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



169
170
171
172
 
# File 'lib/bson/document.rb', line 169

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



87
88
89
 
# File 'lib/bson/document.rb', line 87

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



102
103
104
 
# File 'lib/bson/document.rb', line 102

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



156
157
158
 
# File 'lib/bson/document.rb', line 156

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



225
226
227
 
# File 'lib/bson/document.rb', line 225

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

#fetch(key) ⇒ Object #fetch(key, default) ⇒ Object #fetch(key, &block) ⇒ 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 with a default.

document.fetch(:field, 'foo')

Get an element for the key by symbol with a block default.

document.fetch(:field) { |key| key.upcase }

Overloads:

  • #fetch(key) ⇒ Object

    Returns a value from the hash for the given key. If the key does not exist, raises KeyError exception.

  • #fetch(key, default) ⇒ Object

    Returns a value from the hash for the given key. If the key does not exist, returns default.

  • #fetch(key, &block) ⇒ Object

    Returns a value from the hash for the given key. If the key does not exist, returns the value of the block called with the key.

Parameters:

  • key (String, Symbol) —

    The key to look up.

  • default (Object) —

    Returned value if key does not exist.

Yields:

  • (key) —

    Block returning default value for the given key.

Returns:

  • (Object) —

    The found value. Raises KeyError if none found.

Since:

  • 4.4.0



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

def fetch(key, *args, &block)
  key = convert_key(key)
  super(key, *args, &block)
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



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

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



136
137
138
 
# File 'lib/bson/document.rb', line 136

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



185
186
187
 
# File 'lib/bson/document.rb', line 185

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



200
201
202
203
204
205
206
 
# File 'lib/bson/document.rb', line 200

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



246
247
248
 
# File 'lib/bson/document.rb', line 246

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