class BSON::Document
@since 2.0.0
@see bsonspec.org/#/specification<br><br>@note The specification is: document ::= int32 e_list “x00”
BSON documents, according to the BSON specification.
This module provides behaviour for serializing and deserializing entire
def [](key)
- Since: - 2.0.0
Returns:
-
(Object)
- The found value, or nil if none found.
Parameters:
-
key
(String, Symbol
) -- The key to look up.
Other tags:
- Example: Get an element for the key by symbol. -
Example: Get an element for the key. -
def [](key) super(convert_key(key)) end
def []=(key, value)
- Since: - 3.0.0
Returns:
-
(Object)
- The updated value.
Parameters:
-
value
(Object
) -- The value to update. -
key
(String, Symbol
) -- The key to update.
Other tags:
- Example: Set a value on the document. -
def []=(key, value) super(convert_key(key), convert_value(value)) end
def convert_key(key)
def convert_key(key) key.to_bson_normalized_key end
def convert_value(value)
def convert_value(value) value.to_bson_normalized_value end
def delete(key, &block)
- Since: - 4.0.0
Returns:
-
(Object)
-
Parameters:
-
key
(Object
) -- The key of the key-value pair to delete.
Other tags:
- Example: Delete a key-value pair -
def delete(key, &block) super(convert_key(key), &block) end
def dig(*keys)
- Since: - 3.0.0
Returns:
-
(Object, NilClass)
- The requested value or nil.
Parameters:
-
*keys
(Array
) -- Keys, which constitute a "path" to the nested value.
Other tags:
- Example: Get value from nested sub-documents, handling missing levels. -
def dig(*keys) super(*keys.map{|key| convert_key(key)}) end
def except(*keys)
- Note: - This method is always defined, even if Hash already contains a
Returns:
-
(BSON::Document)
- The document with the specified keys removed.
Parameters:
-
*keys
(Array
) -- Keys, that will be removed in the resulting document
Other tags:
- Example: Get a document/hash with only the `name` and `age` fields removed -
def except(*keys) copy = dup keys.each {|key| copy.delete(key)} copy end
def fetch(key, *args, &block)
- Since: - 4.4.0
Returns:
-
(Object)
- The found value. Raises KeyError if none found.
Other tags:
- Yield: - Block returning default value for the given key.
Parameters:
-
default
(Object
) -- Returned value if key does not exist. -
key
(String, Symbol
) -- The key to look up.
Other tags:
- Example: Get an element for the key by symbol with a block default. -
Example: Get an element for the key by symbol with a default. -
Example: Get an element for the key. -
Overloads:
-
fetch(key, &block)
-
fetch(key, default)
-
fetch(key)
def fetch(key, *args, &block) key = convert_key(key) super(key, *args, &block) end
def has_key?(key)
- Since: - 4.0.0
Returns:
-
(true, false)
-
Parameters:
-
key
(Object
) -- The key to check for.
Other tags:
- Example: Test if a key exists using a symbol -
def has_key?(key) super(convert_key(key)) end
def has_value?(value)
- Since: - 4.0.0
Returns:
-
(true, false)
-
Parameters:
-
value
(Object
) -- THe value to check for.
Other tags:
- Example: Test if a key exists using a symbol -
def has_value?(value) super(convert_value(value)) end
def initialize(elements = nil)
- Since: - 3.0.0
Parameters:
-
elements
(Hash
) -- The elements of the document.
Other tags:
- Example: Create the new Document. -
def initialize(elements = nil) super() (elements || {}).each_pair{ |key, value| self[key] = value } end
def merge(other, &block)
- Since: - 3.0.0
Returns:
-
(BSON::Document)
- The result of the merge.
Parameters:
-
other
(BSON::Document, Hash
) -- The document/hash to merge with.
Other tags:
- Example: Merge with another document. -
def merge(other, &block) dup.merge!(other, &block) end
def merge!(other)
- Since: - 3.0.0
Returns:
-
(BSON::Document)
- The result of the merge.
Parameters:
-
other
(BSON::Document, Hash
) -- The document/hash to merge with.
Other tags:
- Example: Merge with another document. -
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
def slice(*keys)
- Since: - 4.3.1
Returns:
-
(BSON::Document)
- The document with only the selected keys
Parameters:
-
*keys
(Array
) -- Keys, that will be kept in the resulting document
Other tags:
- Example: Get a document/hash with only the `name` and `age` fields present -
def slice(*keys) keys.each_with_object(self.class.new) do |key, hash| if key?(key) hash[key] = self[key] end end end
def symbolize_keys!
def symbolize_keys! raise ArgumentError, 'symbolize_keys! is not supported on BSON::Document instances. Please convert the document to hash first (using #to_h), then call #symbolize_keys! on the Hash instance' end
def to_bson_normalized_value
-
(BSON::Document)
- The normalized hash.
def to_bson_normalized_value self end