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
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
# File lib/bson/document.rb, line 134 def initialize(elements = nil) super() (elements || {}).each_pair{ |key, value| self[key] = value } end
Public Instance Methods
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
# File lib/bson/document.rb, line 52 def [](key) super(convert_key(key)) end
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
# File lib/bson/document.rb, line 67 def []=(key, value) super(convert_key(key), convert_value(value)) end
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
# File lib/bson/document.rb, line 121 def delete(key, &block) super(convert_key(key), &block) end
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
# File lib/bson/document.rb, line 190 def dig(*keys) super(*keys.map{|key| convert_key(key)}) end
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
# File lib/bson/document.rb, line 82 def has_key?(key) super(convert_key(key)) end
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
# File lib/bson/document.rb, line 101 def has_value?(value) super(convert_value(value)) end
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 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
Private Instance Methods
# File lib/bson/document.rb, line 197 def convert_key(key) key.to_bson_normalized_key end
# File lib/bson/document.rb, line 201 def convert_value(value) value.to_bson_normalized_value end