Generates MongoDB object ids.
@core objectids
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
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
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
Determine if the supplied string is legal. Legal strings will consist of 24 hexadecimal characters.
@param [String] str
@return [Boolean]
# File lib/bson/types/object_id.rb, line 56 def self.legal?(str) str =~ /^[0-9a-f]{24}$/ ? true : false end
# File lib/bson/types/object_id.rb, line 169 def self.machine_id @@machine_id end
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
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
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
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
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
# File lib/bson/types/object_id.rb, line 140 def inspect "BSON::ObjectId('#{to_s}')" end
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
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
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
# 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
# File lib/bson/types/object_id.rb, line 221 def get_inc @@lock.synchronize do @@index = (@@index + 1) % 0xFFFFFF end end