class BSON::ObjectId

Represents object_id data.

@see bsonspec.org/#/specification

@since 2.0.0

Constants

BSON_TYPE

A object_id is type 0x07 in the BSON spec.

@since 2.0.0

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.

Public Class Methods

_generator() click to toggle source

Accessor for querying the generator directly; used in testing.

@api private

# File lib/bson/object_id.rb, line 231
def self._generator
  @@generator
end
from_bson(buffer, **_) click to toggle source

Deserialize the object id from raw BSON bytes.

@example Get the object id from BSON.

ObjectId.from_bson(bson)

@param [ ByteBuffer ] buffer The byte buffer. @param [ Hash ] _ An optional hash of keyword arguments (unused).

@return [ BSON::ObjectId ] The object id.

@since 2.0.0

# File lib/bson/object_id.rb, line 267
def from_bson(buffer, **_)
  from_data(buffer.get_bytes(12))
end
from_data(data) click to toggle source

Create a new object id from raw bytes.

@example Create an object id from raw bytes.

BSON::ObjectId.from_data(data)

@param [ String ] data The raw bytes.

@return [ ObjectId ] The new object id.

@since 2.0.0

# 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) click to toggle source

Create a new object id from a string.

@example Create an object id from the string.

BSON::ObjectId.from_string(id)

@param [ String ] string The string to create the id from.

@raise [ BSON::Error::InvalidObjectId ] If the provided string is invalid.

@return [ BSON::ObjectId ] The new object id.

@since 2.0.0

# 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 = {}) click to toggle source

Create a new object id from a time.

@example Create an object id from a time.

BSON::ObjectId.from_time(time)

@example Create an object id from a time, ensuring uniqueness.

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

@param [ Time ] time The time to generate from. @param [ Hash ] options The options.

@option options [ true, false ] :unique Whether the id should be

unique.

@return [ ObjectId ] The new object id.

@since 2.0.0

# 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
repair(object) { |object| ... } click to toggle source

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

  1. Used in legacy id repairs.

@example Execute in a repairing block.

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

@param [ String, Array ] object The object to repair.

@raise [ BSON::Error::InvalidObjectId ] If the array is not 12 elements.

@return [ String ] The result of the block.

@since 2.0.0

# 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() click to toggle source

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

@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.

@return [ Integer ] the number of seconds since the Epoch.

# File lib/bson/object_id.rb, line 373
def timestamp
  ::Time.now.to_i % MAX_INTEGER
end

Public Instance Methods

<=>(other) click to toggle source

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

@example Compare the object id with the other object.

object <=> other

@param [ Object ] other The object to compare to.

@return [ Integer ] The result of the comparison.

@since 2.0.0

# File lib/bson/object_id.rb, line 95
def <=>(other)
  generate_data <=> other.to_bson.to_s
end
==(other) click to toggle source

Check equality of the object id with another object.

@example Check if the object id is equal to the other.

object_id == other

@param [ Object ] other The object to check against.

@return [ true, false ] If the objects are equal.

@since 2.0.0

# File lib/bson/object_id.rb, line 42
def ==(other)
  return false unless other.is_a?(ObjectId)

  generate_data == other.send(:generate_data)
end
Also aliased as: eql?
===(other) click to toggle source

Check case equality on the object id.

@example Check case equality.

object_id === other

@param [ Object ] other The object to check against.

@return [ true, false ] If the objects are equal in a case.

@since 2.0.0

Calls superclass method
# 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() click to toggle source

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

@return [ String ] The counter portion of the id.

@api private

# File lib/bson/object_id.rb, line 212
def _counter_part
  to_s[18, 6]
end
_process_part() click to toggle source

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

@return [ String ] The process portion of the id.

@api private

# File lib/bson/object_id.rb, line 202
def _process_part
  to_s[8, 10]
end
as_extended_json(**_) click to toggle source

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

@return [ Hash ] The extended json representation.

# File lib/bson/object_id.rb, line 81
def as_extended_json(**_)
  { '$oid' => to_s }
end
as_json(*_) click to toggle source

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

@example Get the object id as a JSON-serializable object.

object_id.as_json

@return [ String ] The object id as a string.

# File lib/bson/object_id.rb, line 73
def as_json(*_)
  to_s
end
eql?(other)
Alias for: ==
generation_time() click to toggle source

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.

@example Get the generation time.

object_id.generation_time

@return [ Time ] The time the id was generated.

@since 2.0.0

# File lib/bson/object_id.rb, line 109
def generation_time
  ::Time.at(generate_data.unpack1('N')).utc
end
Also aliased as: to_time
hash() click to toggle source

Get the hash value for the object id.

@example Get the hash value.

object_id.hash

@return [ Integer ] The hash value.

@since 2.0.0

# File lib/bson/object_id.rb, line 122
def hash
  generate_data.hash
end
inspect() click to toggle source

Get a nice string for use with object inspection.

@example Inspect the object id.

object_id.inspect

@return [ String ] The object id in form BSON::ObjectId(‘id’)

@since 2.0.0

# File lib/bson/object_id.rb, line 134
def inspect
  "BSON::ObjectId('#{self}')"
end
marshal_dump() click to toggle source

Dump the raw bson when calling Marshal.dump.

@example Dump the raw bson.

Marshal.dump(object_id)

@return [ String ] The raw bson bytes.

@since 2.0.0

# File lib/bson/object_id.rb, line 146
def marshal_dump
  generate_data
end
marshal_load(data) click to toggle source

Unmarshal the data into an object id.

@example Unmarshal the data.

Marshal.load(data)

@param [ String ] data The raw bson bytes.

@return [ String ] The raw bson bytes.

@since 2.0.0

# File lib/bson/object_id.rb, line 160
def marshal_load(data)
  @raw_data = data
end
to_bson(buffer = ByteBuffer.new) click to toggle source

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

@example Get the raw bson bytes.

object_id.to_bson

@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)

@return [ BSON::ByteBuffer ] The buffer with the encoded object.

@see bsonspec.org/#/specification

@since 2.0.0

# File lib/bson/object_id.rb, line 179
def to_bson(buffer = ByteBuffer.new)
  buffer.put_bytes(generate_data)
end
to_s() click to toggle source

Get the string representation of the object id.

@example Get the object id as a string.

object_id.to_s

@return [ String ] The object id as a string.

@since 2.0.0

# File lib/bson/object_id.rb, line 191
def to_s
  generate_data.to_hex_string.force_encoding(UTF8)
end
Also aliased as: to_str
to_str()
Alias for: to_s
to_time()
Alias for: generation_time

Private Instance Methods

generate_data() click to toggle source
# File lib/bson/object_id.rb, line 242
def generate_data
  repair if defined?(@data)

  # rubocop:disable Naming/MemoizedInstanceVariableName
  @raw_data ||= @@generator.next_object_id
  # rubocop:enable Naming/MemoizedInstanceVariableName
end
initialize_copy(other) click to toggle source
# File lib/bson/object_id.rb, line 237
def initialize_copy(other)
  generate_data
  other.instance_variable_set(:@raw_data, @raw_data)
end
repair() click to toggle source
# File lib/bson/object_id.rb, line 250
def repair
  @raw_data = @data.to_bson_object_id
  remove_instance_variable(:@data)
end