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

Constant Summary collapse

BSON_TYPE =

A object_id is type 0x07 in the BSON spec.

Since:

  • 2.0.0

::String.new(7.chr, encoding: BINARY).freeze
MAX_INTEGER =

The largest numeric value that can be converted to an integer by MRI’s NUM2UINT. Further, the spec dictates that the time component of an ObjectID must be no more than 4 bytes long, so the spec itself is constrained in this regard.

Since:

  • 2.0.0

2 ** 32
@@generator =

We keep one global generator for object ids.

Since:

  • 2.0.0

Generator.new

Class Method Summary collapse

Instance Method Summary collapse

Methods included from JSON

#to_json

Class Method Details

._generator ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Accessor for querying the generator directly; used in testing.

Since:

  • 2.0.0



231
232
233
 
# File 'lib/bson/object_id.rb', line 231

def self._generator
  @@generator
end

.from_bson(buffer, **_) ⇒ BSON::ObjectId

Deserialize the object id from raw BSON bytes.

Examples:

Get the object id from BSON.

ObjectId.from_bson(bson)

Parameters:

  • buffer (ByteBuffer) —

    The byte buffer.

  • _ (Hash) —

    An optional hash of keyword arguments (unused).

Returns:

Since:

  • 2.0.0



267
268
269
 
# File 'lib/bson/object_id.rb', line 267

def from_bson(buffer, **_)
  from_data(buffer.get_bytes(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



281
282
283
284
285
 
# File 'lib/bson/object_id.rb', line 281

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



299
300
301
302
303
 
# File 'lib/bson/object_id.rb', line 299

def from_string(string)
  raise Error::InvalidObjectId, "'#{string}' is an invalid ObjectId." unless legal?(string)

  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_time(time)

Create an object id from a time, ensuring uniqueness.

BSON::ObjectId.from_time(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



322
323
324
 
# File 'lib/bson/object_id.rb', line 322

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:

  • string (String) —

    The string to check.

Returns:

  • (true, false) —

    If the string is legal.

Since:

  • 2.0.0



336
337
338
 
# File 'lib/bson/object_id.rb', line 336

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:

Since:

  • 2.0.0



353
354
355
356
357
 
# File 'lib/bson/object_id.rb', line 353

def repair(object)
  raise Error::InvalidObjectId, "#{object.inspect} is not a valid object id." if object.size != 12

  block_given? ? yield(object) : object
end

.timestamp ⇒ Integer

Note:

This value is guaranteed to be no more than 4 bytes in length. A time value far enough in the future to require a larger integer than 4 bytes will be truncated to 4 bytes.

Returns an integer timestamp (seconds since the Epoch). Primarily used by the generator to produce object ids.

Returns:

  • (Integer) —

    the number of seconds since the Epoch.

Since:

  • 2.0.0



373
374
375
 
# File 'lib/bson/object_id.rb', line 373

def timestamp
  ::Time.now.to_i % MAX_INTEGER
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



95
96
97
 
# File 'lib/bson/object_id.rb', line 95

def <=>(other)
  generate_data <=> other.to_bson.to_s
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



42
43
44
45
46
 
# File 'lib/bson/object_id.rb', line 42

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

  generate_data == other.send(:generate_data)
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



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

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

  super
end

#_counter_part ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Extract the counter-specific part of the object id. This is used only internally, for testing, and should not be used elsewhere.

Returns:

  • (String) —

    The counter portion of the id.

Since:

  • 2.0.0



212
213
214
 
# File 'lib/bson/object_id.rb', line 212

def _counter_part
  to_s[18, 6]
end

#_process_part ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Extract the process-specific part of the object id. This is used only internally, for testing, and should not be used elsewhere.

Returns:

  • (String) —

    The process portion of the id.

Since:

  • 2.0.0



202
203
204
 
# File 'lib/bson/object_id.rb', line 202

def _process_part
  to_s[8, 10]
end

#as_extended_json(**_) ⇒ Hash

Converts this object to a representation directly serializable to Extended JSON (github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).

Returns:

  • (Hash) —

    The extended json representation.

Since:

  • 2.0.0



81
82
83
 
# File 'lib/bson/object_id.rb', line 81

def as_extended_json(**_)
  { '$oid' => to_s }
end

#as_json(*_) ⇒ String

Return a string representation of the object id for use in application-level JSON serialization. This method is intentionally different from #as_extended_json.

Examples:

Get the object id as a JSON-serializable object.

object_id.as_json

Returns:

  • (String) —

    The object id as a string.

Since:

  • 2.0.0



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

def as_json(*_)
  to_s
end

#generation_time ⇒ Time Also known as: to_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



109
110
111
 
# File 'lib/bson/object_id.rb', line 109

def generation_time
  ::Time.at(generate_data.unpack1('N')).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



122
123
124
 
# File 'lib/bson/object_id.rb', line 122

def hash
  generate_data.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



134
135
136
 
# File 'lib/bson/object_id.rb', line 134

def inspect
  "BSON::ObjectId('#{self}')"
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



146
147
148
 
# File 'lib/bson/object_id.rb', line 146

def marshal_dump
  generate_data
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



160
161
162
 
# File 'lib/bson/object_id.rb', line 160

def marshal_load(data)
  @raw_data = data
end

#to_bson(buffer = ByteBuffer.new) ⇒ BSON::ByteBuffer

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



179
180
181
 
# File 'lib/bson/object_id.rb', line 179

def to_bson(buffer = ByteBuffer.new)
  buffer.put_bytes(generate_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



191
192
193
 
# File 'lib/bson/object_id.rb', line 191

def to_s
  generate_data.to_hex_string.force_encoding(UTF8)
end