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



151
152
153
154
 
# File 'lib/bson/document.rb', line 151

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



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

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

#[]=(key, value) ⇒ Object

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

Examples:

Set a value on the document.

document[:test] = "value"

Parameters:

Returns:

  • (Object) —

    The updated value.

Since:

  • 3.0.0



84
85
86
 
# File 'lib/bson/document.rb', line 84

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



138
139
140
 
# File 'lib/bson/document.rb', line 138

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



207
208
209
 
# File 'lib/bson/document.rb', line 207

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

#fetch(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.fetch("field")

Get an element for the key by symbol.

document.fetch(:field)

Parameters:

Returns:

  • (Object) —

    The found value. Raises KeyError if none found.

Since:

  • 4.4.0



51
52
53
 
# File 'lib/bson/document.rb', line 51

def fetch(key)
  super(convert_key(key))
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



99
100
101
 
# File 'lib/bson/document.rb', line 99

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



118
119
120
 
# File 'lib/bson/document.rb', line 118

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



167
168
169
 
# File 'lib/bson/document.rb', line 167

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



182
183
184
185
186
187
188
 
# File 'lib/bson/document.rb', line 182

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



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

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