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

Returns:

Since:

  • 2.0.0


223
224
225
# File 'lib/bson/object_id.rb', line 223

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


237
238
239
240
241
# File 'lib/bson/object_id.rb', line 237

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


255
256
257
258
259
260
# File 'lib/bson/object_id.rb', line 255

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_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


279
280
281
# File 'lib/bson/object_id.rb', line 279

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


293
294
295
# File 'lib/bson/object_id.rb', line 293

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


310
311
312
313
314
315
316
# File 'lib/bson/object_id.rb', line 310

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


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

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


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_timeTime 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


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

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

#hashInteger

Get the hash value for the object id.

Examples:

Get the hash value.

object_id.hash

Returns:

Since:

  • 2.0.0


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

def hash
  generate_data.hash
end

#inspectString

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


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

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

#marshal_dumpString

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


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

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


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

def marshal_load(data)
  @raw_data = data
end

#to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?) ⇒ 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:

  • (BSON::ByteBuffer)

    The buffer with the encoded object.

See Also:

Since:

  • 2.0.0


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

def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
  buffer.put_bytes(generate_data)
end

#to_sString 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


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

def to_s
  generate_data.to_hex_string.force_encoding(UTF8)
end