Class: BSON::ObjectId

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

Overview

Generates MongoDB object ids.

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (ObjectId) initialize(data = nil, time = nil)

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.

  • opts (Hash)

    a customizable set of options



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

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

Instance Attribute Details

- (Object) data

Returns the value of attribute data



26
27
28
# File 'lib/bson/types/object_id.rb', line 26

def data
  @data
end

Class Method Details

+ (BSON::ObjectId, Object) create_pk(doc)

Adds a primary key to the given document if needed.

Parameters:

  • doc (Hash)

    a document requiring an _id.

Returns:



88
89
90
# File 'lib/bson/types/object_id.rb', line 88

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

+ (BSON::ObjectId) from_string(str)

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

Parameters:

Returns:

Raises:



121
122
123
124
125
126
127
128
# File 'lib/bson/types/object_id.rb', line 121

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

+ (BSON::ObjectId) from_time(time, opts = {})

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.

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • (false) (:unique)

    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.

Returns:



73
74
75
76
77
78
79
80
# File 'lib/bson/types/object_id.rb', line 73

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

+ (Boolean) legal?(str)

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

Parameters:

Returns:

  • (Boolean)


53
54
55
# File 'lib/bson/types/object_id.rb', line 53

def self.legal?(str)
  str =~ /^[0-9a-f]{24}$/i ? true : false
end

+ (Object) machine_id



166
167
168
# File 'lib/bson/types/object_id.rb', line 166

def self.machine_id
  @@machine_id
end

Instance Method Details

- (Hash) as_json(options = {})

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.

Returns:

  • (Hash)

    the hash representation as MongoDB extended JSON



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

def as_json(options ={})
  {"$oid" => to_s}
end

- (Boolean) eql?(object_id) Also known as: ==

Check equality of this object id with another.

Parameters:

Returns:

  • (Boolean)


95
96
97
# File 'lib/bson/types/object_id.rb', line 95

def eql?(object_id)
  object_id.kind_of?(BSON::ObjectId) and self.data == object_id.data
end

- (Time) generation_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.



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

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

- (Integer) hash

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

Returns:

  • (Integer)


104
105
106
# File 'lib/bson/types/object_id.rb', line 104

def hash
  @data.hash
end

- (Object) inspect



137
138
139
# File 'lib/bson/types/object_id.rb', line 137

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

- (Array) to_a

Get an array representation of the object id.

Returns:

  • (Array)


111
112
113
# File 'lib/bson/types/object_id.rb', line 111

def to_a
  @data.dup
end

- (String) to_json(*a)

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.



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

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

- (String) to_s

Get a string representation of this object id.

Returns:



133
134
135
# File 'lib/bson/types/object_id.rb', line 133

def to_s
  @data.map {|e| v=e.to_s(16); v.size == 1 ? "0#{v}" : v }.join
end