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)

Other tags:
    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)

Other tags:
    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)

Other tags:
    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)

Other tags:
    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)

Other tags:
    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)

Other tags:
    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)

Other tags:
    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)

Other tags:
    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)

Other tags:
    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)

Other tags:
    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)

Other tags:
    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)

Other tags:
    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

Returns:
  • (BSON::Document) - The normalized hash.
def to_bson_normalized_value
  self
end