class BSON::Document

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

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

@see bsonspec.org/#/specification

@since 2.0.0

Public Class Methods

new(elements = nil) click to toggle source

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

@example Create the new Document.

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

@param [ Hash ] elements The elements of the document.

@since 3.0.0

Calls superclass method
# File lib/bson/document.rb, line 134
def initialize(elements = nil)
  super()
  (elements || {}).each_pair{ |key, value| self[key] = value }
end

Public Instance Methods

[](key) click to toggle source

Get a value from the document for the provided key. Can use string or symbol access, but the fastest will be to always provide a key that is of the same type as the stored keys.

@example Get an element for the key.

document["field"]

@example Get an element for the key by symbol.

document[:field]

@param [ String, Symbol ] key The key to lookup.

@return [ Object ] The found value, or nil if none found.

@since 2.0.0

Calls superclass method
# File lib/bson/document.rb, line 52
def [](key)
  super(convert_key(key))
end
[]=(key, value) click to toggle source

Set a value on the document. Will normalize symbol keys into strings.

@example Set a value on the document.

document[:test] = "value"

@param [ String, Symbol ] key The key to update. @param [ Object ] value The value to update.

@return [ Object ] The updated value.

@since 3.0.0

Calls superclass method
# File lib/bson/document.rb, line 67
def []=(key, value)
  super(convert_key(key), convert_value(value))
end
delete(key, &block) click to toggle source

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.

@example Delete a key-value pair

document.delete(:test)

@param [ Object ] key The key of the key-value pair to delete.

@return [ Object ]

@since 4.0.0

Calls superclass method
# File lib/bson/document.rb, line 121
def delete(key, &block)
  super(convert_key(key), &block)
end
dig(*keys) click to toggle source

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

@example 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

@param [ Array<String, Symbol> ] *keys Keys, which constitute a “path” to the nested value.

@return [ Object, NilClass ] The requested value or nil.

@since 3.0.0

Calls superclass method
# File lib/bson/document.rb, line 190
def dig(*keys)
  super(*keys.map{|key| convert_key(key)})
end
has_key?(key) click to toggle source

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

@example Test if a key exists using a symbol

document.has_key?(:test)

@param [ Object ] key The key to check for.

@return [ true, false]

@since 4.0.0

Calls superclass method
# File lib/bson/document.rb, line 82
def has_key?(key)
  super(convert_key(key))
end
Also aliased as: include?, key?, member?
has_value?(value) click to toggle source

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

@example Test if a key exists using a symbol

document.has_value?(:test)

@param [ Object ] value THe value to check for.

@return [ true, false]

@since 4.0.0

Calls superclass method
# File lib/bson/document.rb, line 101
def has_value?(value)
  super(convert_value(value))
end
Also aliased as: value
include?(key)
Alias for: has_key?
key?(key)
Alias for: has_key?
member?(key)
Alias for: has_key?
merge(other, &block) click to toggle source

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

@example Merge with another document.

document.merge(name: "Bob")

@param [ BSON::Document, Hash ] other The document/hash to merge with.

@return [ BSON::Document ] The result of the merge.

@since 3.0.0

# File lib/bson/document.rb, line 150
def merge(other, &block)
  dup.merge!(other, &block)
end
merge!(other) { |convert_key(key), self, convert_value(value)| ... } click to toggle source

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

@example Merge with another document.

document.merge(name: "Bob")

@param [ BSON::Document, Hash ] other The document/hash to merge with.

@return [ BSON::Document ] The result of the merge.

@since 3.0.0

# File lib/bson/document.rb, line 165
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
Also aliased as: update
update(other)
Alias for: merge!
value(value)
Alias for: has_value?

Private Instance Methods

convert_key(key) click to toggle source
# File lib/bson/document.rb, line 197
def convert_key(key)
  key.to_bson_normalized_key
end
convert_value(value) click to toggle source
# File lib/bson/document.rb, line 201
def convert_value(value)
  value.to_bson_normalized_value
end