Class: BSON::ObjectId

Inherits:
Object
  • Object
show all
Defined in:
lib/bson/types/object_id.rb

Overview

Generates MongoDB object ids.

Constant Summary collapse

@@lock = 
Mutex.new
@@index = 
0

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data = nil) ⇒ ObjectId

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.

Parameters:

  • data (Array) (defaults to: nil) —

    should be an array of bytes. If you want to generate a standard MongoDB object id, leave this argument blank.



43
44
45
 
# File 'lib/bson/types/object_id.rb', line 43

def initialize(data=nil)
  @data = data || generate
end

Instance Attribute Details

#data ⇒ Array

Get the array representation without cloning.

Returns:

  • (Array) 


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

def data
  @data
end

Class Method Details

.create_pk(doc) ⇒ Mongo::ObjectId, Object

Adds a primary key to the given document if needed.

Parameters:

  • doc (Hash) —

    a document requiring an _id.

Returns:

  • (Mongo::ObjectId, Object) —

    returns a newly-created or current _id for the given document.



84
85
86
 
# File 'lib/bson/types/object_id.rb', line 84

def self.create_pk(doc)
  doc.has_key?(:_id) || doc.has_key?('_id') ? doc : doc.merge!(:_id => self.new)
end

.from_string(str) ⇒ Mongo::ObjectId

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

Parameters:

  • str (String)

Returns:

  • (Mongo::ObjectId)

Raises:



124
125
126
127
128
129
130
131
 
# File 'lib/bson/types/object_id.rb', line 124

def self.from_string(str)
  raise InvalidObjectId, "illegal ObjectId format" 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) ⇒ Mongo::ObjectId

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.

Examples:

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

Parameters:

  • time (Time) —

    a utc time to encode as an object id.

Returns:

  • (Mongo::ObjectId) 


74
75
76
 
# File 'lib/bson/types/object_id.rb', line 74

def self.from_time(time)
  self.new([time.to_i,0,0].pack("NNN").unpack("C12"))
end

.legal?(str) ⇒ Boolean

Determine if the supplied string is legal. Legal strings will consist of 24 hexadecimal characters.

Parameters:

  • str (String)

Returns:

  • (Boolean) 


55
56
57
58
59
60
 
# File 'lib/bson/types/object_id.rb', line 55

def self.legal?(str)
  len = 24
  str =~ /([0-9a-f]+)/i
  match = $1
  str && str.length == len && match == str
end

Instance Method Details

#eql?(object_id) ⇒ Boolean Also known as: ==

Check equality of this object id with another.

Parameters:

  • object_id (Mongo::ObjectId)

Returns:

  • (Boolean) 


91
92
93
 
# File 'lib/bson/types/object_id.rb', line 91

def eql?(object_id)
  @data == object_id.instance_variable_get("@data")
end

#generation_time ⇒ Time

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.

Returns:

  • (Time) —

    the time at which this object was created.



161
162
163
 
# File 'lib/bson/types/object_id.rb', line 161

def generation_time
  Time.at(@data.pack("C4").unpack("N")[0]).utc
end

#hash ⇒ Integer

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

Returns:

  • (Integer) 


100
101
102
 
# File 'lib/bson/types/object_id.rb', line 100

def hash
  @data.hash
end

#inspect ⇒ Object 



144
145
146
 
# File 'lib/bson/types/object_id.rb', line 144

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

#to_a ⇒ Array

Get an array representation of the object id.

Returns:

  • (Array) 


107
108
109
 
# File 'lib/bson/types/object_id.rb', line 107

def to_a
  @data.dup
end

#to_json(*a) ⇒ String

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.

Returns:

  • (String) —

    the object id represented as MongoDB extended JSON.



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

def to_json(*a)
  "{\"$oid\": \"#{to_s}\"}"
end

#to_s ⇒ String

Get a string representation of this object id.

Returns:

  • (String) 


136
137
138
139
140
141
142
 
# File 'lib/bson/types/object_id.rb', line 136

def to_s
  str = ' ' * 24
  12.times do |i|
    str[i * 2, 2] = '%02x' % @data[i]
  end
  str
end