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

Private Class Methods

from_bson(buffer, **options) 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.

@option options [ nil | :bson ] :mode Decoding mode to use.

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

@since 2.0.0

# File lib/bson/object_id.rb, line 238
def from_bson(buffer, **options)
  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 252
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::ObjectId::Invalid ] If the provided string is invalid.

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

@since 2.0.0

# File lib/bson/object_id.rb, line 270
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 = {}) 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 294
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 [ Invalid ] 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 325
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

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 101
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 46
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 62
def ===(other)
  return to_str === other.to_str if other.respond_to?(:to_str)
  super
end
as_extended_json(**options) 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).

@option opts [ nil | :relaxed | :legacy ] :mode Serialization mode

(default is canonical extended JSON)

@return [ Hash ] The extended json representation.

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

Return the object id as a JSON hash representation.

@example Get the object id as JSON.

object_id.as_json

@return [ Hash ] The object id as a JSON hash.

@since 2.0.0 @deprecated Use as_extended_json instead.

# File lib/bson/object_id.rb, line 76
def as_json(*args)
  as_extended_json
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 115
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 128
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 140
def inspect
  "BSON::ObjectId('#{to_s}')"
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 152
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 166
def marshal_load(data)
  @raw_data = data
end
to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?) 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 185
def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
  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 197
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 214
def generate_data
  repair if defined?(@data)
  @raw_data ||= @@generator.next_object_id
end
initialize_copy(other) click to toggle source
# File lib/bson/object_id.rb, line 209
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 219
def repair
  @raw_data = @data.to_bson_object_id
  remove_instance_variable(:@data)
end