Class: BSON::Document

Inherits:
Hash
  • Object
show all
Defined in:
lib/bson/document.rb

Overview

Note:

The specification is: document ::= int32 e_list “x00”

This module provides behaviour for serializing and deserializing entire BSON documents, according to the BSON specification.

See Also:

Since:

  • 2.0.0

Instance Method Summary collapse

Constructor Details

#initialize(elements = nil) ⇒ Document

Instantiate a new Document. Valid parameters for instantiation is a hash only or nothing.

Examples:

Create the new Document.

BSON::Document.new(name: "Joe", age: 33)

Parameters:

  • elements (Hash) (defaults to: nil)

    The elements of the document.

Since:

  • 3.0.0


211
212
213
214
# File 'lib/bson/document.rb', line 211

def initialize(elements = nil)
  super()
  (elements || {}).each_pair{ |key, value| self[key] = value }
end

Instance Method Details

#[](key) ⇒ Object

Get a value from the document for the provided key. Can use string or symbol access, with string access being the faster of the two.

Examples:

Get an element for the key.

document["field"]

Get an element for the key by symbol.

document[:field]

Parameters:

Returns:

  • (Object)

    The found value, or nil if none found.

Since:

  • 2.0.0


87
88
89
# File 'lib/bson/document.rb', line 87

def [](key)
  super(convert_key(key))
end

#[]=(key, value) ⇒ Object

Stores a key-value pair in the current document.

Since BSON documents provide deep indifferent access (both strings and symbols are accepted as keys, recursively), the value may be converted to facilitate indifferent access. This conversion is performed for built-in Array and Hash classes, and other classes can override to_bson_normalized_value method to provide custom conversion logic. For example:

doc = BSON::Document.new
doc[:a] = {b: {c: 'd'}}
doc['a']['b']['c']
# => "d"

Note that due to this conversion, the object that is stored in the receiver Document may be different from the object supplied as the right hand side of the assignment. In Ruby, the result of assignment is the right hand side, not the return value of []= method. Because of this, modifying the result of assignment generally does not work as intended:

doc = BSON::Document.new
foo = (doc[:a] = {b: {c: 'd'}})
# foo is original Hash with symbol keys
foo['test'] = 'test'
# doc is not modified
doc
# => {"a"=>{"b"=>{"c"=>"d"}}}

This behavior can be encountered when defaulting document contents with []= in a method, such as:

def foo
  # @doc is a BSON::Document
  @doc[:foo] ||= calculation
end

The above method should be written as follows to allow chaining:

def foo
  # @doc is a BSON::Document
  @doc[:foo] ||= calculation and @doc[:foo]
end

Examples:

Set a value on the document.

document[:test] = "value"

Parameters:

Returns:

  • (Object)

    The updated value.

Since:

  • 3.0.0


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

def []=(key, value)
  super(convert_key(key), convert_value(value))
end

#delete(key, &block) ⇒ Object

Deletes the key-value pair and returns the value from the document whose key is equal to key. If the key is not found, returns the default value. If the optional code block is given and the key is not found, pass in the key and return the result of block.

Examples:

Delete a key-value pair

document.delete(:test)

Parameters:

  • key (Object)

    The key of the key-value pair to delete.

Returns:

Since:

  • 4.0.0


198
199
200
# File 'lib/bson/document.rb', line 198

def delete(key, &block)
  super(convert_key(key), &block)
end

#dig(*keys) ⇒ Object, NilClass

Retrieves the value object corresponding to the each key objects repeatedly. Will normalize symbol keys into strings.

Examples:

Get value from nested sub-documents, handling missing levels.

document # => { :key1 => { "key2" => "value"}}
document.dig(:key1, :key2) # => "value"
document.dig("key1", "key2") # => "value"
document.dig("foo", "key2") # => nil

Parameters:

  • *keys (Array<String, Symbol>)

    Keys, which constitute a “path” to the nested value.

Returns:

Since:

  • 3.0.0


267
268
269
# File 'lib/bson/document.rb', line 267

def dig(*keys)
  super(*keys.map{|key| convert_key(key)})
end

#fetch(key) ⇒ Object #fetch(key, default) ⇒ Object #fetch(key, &block) ⇒ Object

Get a value from the document for the provided key. Can use string or symbol access, with string access being the faster of the two.

Examples:

Get an element for the key.

document.fetch("field")

Get an element for the key by symbol with a default.

document.fetch(:field, 'foo')

Get an element for the key by symbol with a block default.

document.fetch(:field) { |key| key.upcase }

Overloads:

  • #fetch(key) ⇒ Object

    Returns a value from the hash for the given key. If the key does not exist, raises KeyError exception.

  • #fetch(key, default) ⇒ Object

    Returns a value from the hash for the given key. If the key does not exist, returns default.

  • #fetch(key, &block) ⇒ Object

    Returns a value from the hash for the given key. If the key does not exist, returns the value of the block called with the key.

Parameters:

  • key (String, Symbol)

    The key to look up.

  • default (Object)

    Returned value if key does not exist.

Yields:

  • (key)

    Block returning default value for the given key.

Returns:

  • (Object)

    The found value. Raises KeyError if none found.

Since:

  • 4.4.0


68
69
70
71
# File 'lib/bson/document.rb', line 68

def fetch(key, *args, &block)
  key = convert_key(key)
  super(key, *args, &block)
end

#has_key?(key) ⇒ true, false Also known as: include?, key?, member?

Returns true if the given key is present in the document. Will normalize symbol keys into strings.

Examples:

Test if a key exists using a symbol

document.has_key?(:test)

Parameters:

  • key (Object)

    The key to check for.

Returns:

  • (true, false)

Since:

  • 4.0.0


159
160
161
# File 'lib/bson/document.rb', line 159

def has_key?(key)
  super(convert_key(key))
end

#has_value?(value) ⇒ true, false Also known as: value

Returns true if the given value is present in the document. Will normalize symbols into strings.

Examples:

Test if a key exists using a symbol

document.has_value?(:test)

Parameters:

  • value (Object)

    THe value to check for.

Returns:

  • (true, false)

Since:

  • 4.0.0


178
179
180
# File 'lib/bson/document.rb', line 178

def has_value?(value)
  super(convert_value(value))
end

#merge(other, &block) ⇒ BSON::Document

Merge this document with another document, returning a new document in the process.

Examples:

Merge with another document.

document.merge(name: "Bob")

Parameters:

Returns:

Since:

  • 3.0.0


227
228
229
# File 'lib/bson/document.rb', line 227

def merge(other, &block)
  dup.merge!(other, &block)
end

#merge!(other) ⇒ BSON::Document Also known as: update

Merge this document with another document, returning the same document in the process.

Examples:

Merge with another document.

document.merge(name: "Bob")

Parameters:

Returns:

Since:

  • 3.0.0


242
243
244
245
246
247
248
# File 'lib/bson/document.rb', line 242

def merge!(other)
  other.each_pair do |key, value|
    value = yield(convert_key(key), self[key], convert_value(value)) if block_given? && self[key]
    self[key] = value
  end
  self
end

#slice(*keys) ⇒ BSON::Document

Slices a document to include only the given keys. Will normalize symbol keys into strings. (this method is backported from ActiveSupport::Hash)

Examples:

Get a document/hash with only the `name` and `age` fields present

document # => { _id: <ObjectId>, :name => 'John', :age => 30, :location => 'Earth' }
document.slice(:name, 'age') # => { name: 'John', age: 30 }
document.slice('name') # => { name: 'John' }
document.slice(:foo) # => nil

Parameters:

  • *keys (Array<String, Symbol>)

    Keys, that will be kept in the resulting document

Returns:

Since:

  • 4.3.1


288
289
290
# File 'lib/bson/document.rb', line 288

def slice(*keys)
  super(*keys.map{|key| convert_key(key)})
end