Class: BSON::ObjectId

Inherits:
Object
  • Object
show all
Includes:
JSON, Comparable
Defined in:
lib/bson/object_id.rb

Overview

Represents object_id data.

See Also:

Since:

  • 2.0.0

Defined Under Namespace

Classes: Generator, Invalid

Constant Summary collapse

BSON_TYPE =

A object_id is type 0x07 in the BSON spec.

Since:

  • 2.0.0

7.chr.force_encoding(BINARY).freeze

Class Method Summary collapse

Instance Method Summary collapse

Methods included from JSON

#to_json

Class Method Details

.from_bson(bson) ⇒ BSON::ObjectId

Deserialize the object id from raw BSON bytes.

Examples:

Get the object id from BSON.

ObjectId.from_bson(bson)

Parameters:

  • bson (String) —

    The raw BSON bytes.

Returns:

Since:

  • 2.0.0



214
215
216
 
# File 'lib/bson/object_id.rb', line 214

def from_bson(bson)
  from_data(bson.read(12))
end

.from_data(data) ⇒ ObjectId

Create a new object id from raw bytes.

Examples:

Create an object id from raw bytes.

BSON::ObjectId.from_data(data)

Parameters:

  • data (String) —

    The raw bytes.

Returns:

Since:

  • 2.0.0



228
229
230
231
232
 
# File 'lib/bson/object_id.rb', line 228

def from_data(data)
  object_id = allocate
  object_id.instance_variable_set(:@raw_data, data)
  object_id
end

.from_string(string) ⇒ BSON::ObjectId

Create a new object id from a string.

Examples:

Create an object id from the string.

BSON::ObjectId.from_string(id)

Parameters:

  • string (String) —

    The string to create the id from.

Returns:

Raises:

Since:

  • 2.0.0



246
247
248
249
250
251
 
# File 'lib/bson/object_id.rb', line 246

def from_string(string)
  unless legal?(string)
    raise Invalid.new("'#{string}' is an invalid ObjectId.")
  end
  from_data([ string ].pack("H*"))
end

.from_time(time, options = {}) ⇒ ObjectId

Create a new object id from a time.

Examples:

Create an object id from a time.

BSON::ObjectId.from_id(time)

Create an object id from a time, ensuring uniqueness.

BSON::ObjectId.from_id(time, unique: true)

Parameters:

  • time (Time) —

    The time to generate from.

  • options (Hash) (defaults to: {}) —

    The options.

Options Hash (options):

  • :unique (true, false) —

    Whether the id should be unique.

Returns:

Since:

  • 2.0.0



270
271
272
 
# File 'lib/bson/object_id.rb', line 270

def from_time(time, options = {})
  from_data(options[:unique] ? @@generator.next_object_id(time.to_i) : [ time.to_i ].pack("Nx8"))
end

.legal?(string) ⇒ true, false

Determine if the provided string is a legal object id.

Examples:

Is the string a legal object id?

BSON::ObjectId.legal?(string)

Parameters:

  • The (String) —

    string to check.

Returns:

  • (true, false) —

    If the string is legal.

Since:

  • 2.0.0



284
285
286
 
# File 'lib/bson/object_id.rb', line 284

def legal?(string)
  string.to_s =~ /\A[0-9a-f]{24}\z/i ? true : false
end

.repair(object) ⇒ String

Executes the provided block only if the size of the provided object is

  1. Used in legacy id repairs.

Examples:

Execute in a repairing block.

BSON::ObjectId.repair("test") { obj }

Parameters:

Returns:

  • (String) —

    The result of the block.

Raises:

  • (Invalid) —

    If the array is not 12 elements.

Since:

  • 2.0.0



301
302
303
304
305
306
307
 
# File 'lib/bson/object_id.rb', line 301

def repair(object)
  if object.size == 12
    block_given? ? yield(object) : object
  else
    raise Invalid.new("#{object.inspect} is not a valid object id.")
  end
end

Instance Method Details

#<=>(other) ⇒ Integer

Compare this object id with another object for use in sorting.

Examples:

Compare the object id with the other object.

object <=> other

Parameters:

  • other (Object) —

    The object to compare to.

Returns:

  • (Integer) —

    The result of the comparison.

Since:

  • 2.0.0



88
89
90
 
# File 'lib/bson/object_id.rb', line 88

def <=>(other)
  to_bson <=> other.to_bson
end

#==(other) ⇒ true, false Also known as: eql?

Check equality of the object id with another object.

Examples:

Check if the object id is equal to the other.

object_id == other

Parameters:

  • other (Object) —

    The object to check against.

Returns:

  • (true, false) —

    If the objects are equal.

Since:

  • 2.0.0



45
46
47
48
 
# File 'lib/bson/object_id.rb', line 45

def ==(other)
  return false unless other.is_a?(ObjectId)
  to_bson == other.to_bson
end

#===(other) ⇒ true, false

Check case equality on the object id.

Examples:

Check case equality.

object_id === other

Parameters:

  • other (Object) —

    The object to check against.

Returns:

  • (true, false) —

    If the objects are equal in a case.

Since:

  • 2.0.0



61
62
63
64
 
# File 'lib/bson/object_id.rb', line 61

def ===(other)
  return to_str === other.to_str if other.respond_to?(:to_str)
  super
end

#as_json(*args) ⇒ Hash

Return the object id as a JSON hash representation.

Examples:

Get the object id as JSON.

object_id.as_json

Returns:

  • (Hash) —

    The object id as a JSON hash.

Since:

  • 2.0.0



74
75
76
 
# File 'lib/bson/object_id.rb', line 74

def as_json(*args)
  { "$oid" => to_s }
end

#generation_time ⇒ Time

Return the UTC time at which this ObjectId was generated. This may be used instread of a created_at timestamp since this information is always encoded in the object id.

Examples:

Get the generation time.

object_id.generation_time

Returns:

  • (Time) —

    The time the id was generated.

Since:

  • 2.0.0



102
103
104
 
# File 'lib/bson/object_id.rb', line 102

def generation_time
  ::Time.at(to_bson.unpack("N")[0]).utc
end

#hash ⇒ Integer

Get the hash value for the object id.

Examples:

Get the hash value.

object_id.hash

Returns:

Since:

  • 2.0.0



114
115
116
 
# File 'lib/bson/object_id.rb', line 114

def hash
  to_bson.hash
end

#inspect ⇒ String

Get a nice string for use with object inspection.

Examples:

Inspect the object id.

object_id.inspect

Returns:

  • (String) —

    The object id in form BSON::ObjectId(‘id’)

Since:

  • 2.0.0



126
127
128
 
# File 'lib/bson/object_id.rb', line 126

def inspect
  "BSON::ObjectId('#{to_s}')"
end

#marshal_dump ⇒ String

Dump the raw bson when calling Marshal.dump.

Examples:

Dump the raw bson.

Marshal.dump(object_id)

Returns:

  • (String) —

    The raw bson bytes.

Since:

  • 2.0.0



138
139
140
 
# File 'lib/bson/object_id.rb', line 138

def marshal_dump
  to_bson
end

#marshal_load(data) ⇒ String

Unmarshal the data into an object id.

Examples:

Unmarshal the data.

Marshal.load(data)

Parameters:

  • data (String) —

    The raw bson bytes.

Returns:

  • (String) —

    The raw bson bytes.

Since:

  • 2.0.0



152
153
154
 
# File 'lib/bson/object_id.rb', line 152

def marshal_load(data)
  @raw_data = data
end

#to_bson(encoded = ''.force_encoding(BINARY)) ⇒ String

Note:

Since Moped’s BSON and MongoDB BSON before 2.0.0 have different internal representations, we will attempt to repair the data for cases where the object was instantiated in a non-standard way. (Like a Marshal.load)

Get the object id as it’s raw BSON data.

Examples:

Get the raw bson bytes.

object_id.to_bson

Returns:

See Also:

Since:

  • 2.0.0



171
172
173
174
175
 
# File 'lib/bson/object_id.rb', line 171

def to_bson(encoded = ''.force_encoding(BINARY))
  repair if defined?(@data)
  @raw_data ||= @@generator.next_object_id
  encoded << @raw_data
end

#to_s ⇒ String Also known as: to_str

Get the string representation of the object id.

Examples:

Get the object id as a string.

object_id.to_s

Returns:

  • (String) —

    The object id as a string.

Since:

  • 2.0.0



185
186
187
 
# File 'lib/bson/object_id.rb', line 185

def to_s
  to_bson.to_hex_string.force_encoding(UTF8)
end