class BSON::ObjectId

Generates MongoDB object ids.

@core objectids

Attributes

data[RW]

Public Class Methods

create_pk(doc) click to toggle source

Adds a primary key to the given document if needed.

@param [Hash] doc a document requiring an _id.

@return [BSON::ObjectId, Object] returns a newly-created or

current _id for the given document.
# File lib/bson/types/object_id.rb, line 91
def self.create_pk(doc)
  doc.has_key?(:_id) || doc.has_key?('_id') ? doc : doc.merge!(:_id => self.new)
end
from_string(str) click to toggle source

Given a string representation of an ObjectId, return a new ObjectId with that value.

@param [String] str

@return [BSON::ObjectId]

# File lib/bson/types/object_id.rb, line 124
def self.from_string(str)
  raise InvalidObjectId, "illegal ObjectId format: #{str}" unless legal?(str)
  data = []
  12.times do |i|
    data[i] = str[i * 2, 2].to_i(16)
  end
  self.new(data)
end
from_time(time, opts={}) click to toggle source

Create an object id from the given time. This is useful for doing range queries; it works because MongoDB's object ids begin with a timestamp.

@param [Time] time a utc time to encode as an object id.

@option opts [:unique] (false) If false, the object id's bytes

succeeding the timestamp will be zeroed; if true, they'll
consist of the standard machine id, pid, and counter.

@return [BSON::ObjectId]

@example Return all document created before Jan 1, 2010.

time = Time.utc(2010, 1, 1)
time_id = ObjectId.from_time(time)
collection.find({'_id' => {'$lt' => time_id}})
# File lib/bson/types/object_id.rb, line 76
def self.from_time(time, opts={})
  unique = opts.fetch(:unique, false)
  if unique
    self.new(nil, time)
  else
    self.new([time.to_i,0,0].pack("NNN").unpack("C12"))
  end
end
machine_id() click to toggle source
# File lib/bson/types/object_id.rb, line 169
def self.machine_id
  @@machine_id
end
new(data=nil, time=nil) click to toggle source

Create a new object id. If no parameter is given, an id corresponding to the ObjectId BSON data type will be created. This is a 12-byte value consisting of a 4-byte timestamp, a 3-byte machine id, a 2-byte process id, and a 3-byte counter.

@param [Array] data should be an array of bytes. If you want

to generate a standard MongoDB object id, leave this argument blank.

@option opts :data (nil) An array of bytes to use as the object id. @option opts :time (nil) The value of this object ids timestamp. Note that

the remaining bytes will consist of the standard machine id, pid, and counter. If
you need a zeroed timestamp, used ObjectId.from_time.
# File lib/bson/types/object_id.rb, line 43
def initialize(data=nil, time=nil)
  if data && (!data.is_a?(Array) || data.size != 12)
    raise InvalidObjectId, 'ObjectId requires 12 byte array'
  end
  @data = data || generate(time)
end

Public Instance Methods

==(object_id)
Alias for: eql?
as_json(options ={}) click to toggle source

Create the JSON hash structure convert to MongoDB extended format. Rails 2.3.3 introduced #as_json to create the needed hash structure to encode objects into JSON.

@return [Hash] the hash representation as MongoDB extended JSON

# File lib/bson/types/object_id.rb, line 156
def as_json(options ={})
  {"$oid" => to_s}
end
eql?(object_id) click to toggle source

Check equality of this object id with another.

@param [BSON::ObjectId] object_id

# File lib/bson/types/object_id.rb, line 98
def eql?(object_id)
  object_id.kind_of?(BSON::ObjectId) and self.data == object_id.data
end
Also aliased as: ==
generation_time() click to toggle source

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

@return [Time] the time at which this object was created.

# File lib/bson/types/object_id.rb, line 165
def generation_time
  Time.at(@data.pack("C4").unpack("N")[0]).utc
end
hash() click to toggle source

Get a unique hashcode for this object. This is required since we've defined an eql? method.

@return [Integer]

# File lib/bson/types/object_id.rb, line 107
def hash
  @data.hash
end
inspect() click to toggle source
# File lib/bson/types/object_id.rb, line 140
def inspect
  "BSON::ObjectId('#{to_s}')"
end
to_a() click to toggle source

Get an array representation of the object id.

@return [Array]

# File lib/bson/types/object_id.rb, line 114
def to_a
  @data.dup
end
to_json(*a) click to toggle source

Convert to MongoDB extended JSON format. Since JSON includes type information, but lacks an ObjectId type, this JSON format encodes the type using an $oid key.

@return [String] the object id represented as MongoDB extended JSON.

# File lib/bson/types/object_id.rb, line 148
def to_json(*a)
  "{\"$oid\": \"#{to_s}\"}"
end
to_s() click to toggle source

Get a string representation of this object id.

@return [String]

# File lib/bson/types/object_id.rb, line 136
def to_s
  @data.map {|e| v=e.to_s(16); v.size == 1 ? "0#{v}" : v }.join
end

Private Instance Methods

generate(oid_time=nil) click to toggle source
# File lib/bson/types/object_id.rb, line 179
def generate(oid_time=nil)
  data = (oid_time ? @@generator.new(oid_time) : @@generator.new)

  oid = ''
  oid += [data.timeSecond].pack("N")
  oid += [data._machine].pack("N")
  oid += [data._inc].pack("N")
  oid.unpack("C12")
end
get_inc() click to toggle source
# File lib/bson/types/object_id.rb, line 221
def get_inc
  @@lock.synchronize do
    @@index = (@@index + 1) % 0xFFFFFF
  end
end