module BSON::Hash

Injects behaviour for encoding and decoding hashes to and from raw bytes as specified by the BSON spec.

@see bsonspec.org/#/specification

Constants

BSON_TYPE

A hash, also called an embedded document, is type 0x03 in the BSON spec.

Public Instance Methods

as_extended_json(**options) click to toggle source

Converts this object to a representation directly serializable to Extended JSON (github.com/mongodb/specifications/blob/master/source/extended-json.rst).

This method recursively invokes as_extended_json with the provided options on each hash value.

@option opts [ nil | :relaxed | :legacy ] :mode Serialization mode

(default is canonical extended JSON)

@return [ Hash ] This hash converted to extended json representation.

# File lib/bson/hash.rb, line 65
def as_extended_json(**options)
  transform_values { |value| value.as_extended_json(**options) }
end
to_bson(buffer = ByteBuffer.new) click to toggle source

Get the hash as encoded BSON.

@example Get the hash as encoded BSON.

{ "field" => "value" }.to_bson

@return [ BSON::ByteBuffer ] The buffer with the encoded object.

@see bsonspec.org/#/specification

# File lib/bson/hash.rb, line 35
def to_bson(buffer = ByteBuffer.new)
  # If the native buffer version has an optimized version, we'll call
  # it directly. Otherwise, we'll serialize the hash the hard way.
  if buffer.respond_to?(:put_hash)
    buffer.put_hash(self)
  else
    serialize_to_buffer(buffer)
  end
end
to_bson_normalized_value() click to toggle source

Converts the hash to a normalized value in a BSON document.

@example Convert the hash to a normalized value.

hash.to_bson_normalized_value

@return [ BSON::Document ] The normalized hash.

# File lib/bson/hash.rb, line 51
def to_bson_normalized_value
  Document.new(self)
end

Private Instance Methods

serialize_key(buffer, key) click to toggle source

Serialize the key/value pairs in this hash instance to the given buffer.

@param [ ByteBuf ] buffer The buffer to received the serialized

key/value pairs.

@raise [ ArgumentError ] if the string cannot be serialized @raise [ EncodingError ] if the string is not a valid encoding

# File lib/bson/hash.rb, line 111
def serialize_key(buffer, key)
  buffer.put_cstring(key)
rescue ArgumentError => e
  raise ArgumentError, "Error serializing key #{key}: #{e.class}: #{e}"
rescue EncodingError => e
  # Note this may convert exception class from a subclass of
  # EncodingError to EncodingError itself
  raise EncodingError, "Error serializing key #{key}: #{e.class}: #{e}"
end
serialize_key_value_pairs(buffer) click to toggle source

Serialize the key/value pairs in this hash instance to the given buffer.

@param [ ByteBuf ] buffer The buffer to received the serialized

key/value pairs.

@raise [ Error::UnserializableClass ] if a value cannot be serialized

# File lib/bson/hash.rb, line 89
def serialize_key_value_pairs(buffer)
  each do |field, value|
    unless value.respond_to?(:bson_type)
      raise Error::UnserializableClass,
            "Hash value for key '#{field}' does not define its BSON serialized type: #{value}"
    end

    buffer.put_byte(value.bson_type)
    key = field.to_bson_key
    serialize_key(buffer, key)
    value.to_bson(buffer)
  end
end
serialize_to_buffer(buffer) click to toggle source

Serialize this hash instance to the given buffer.

@param [ ByteBuf ] buffer The buffer to receive the serialized hash.

# File lib/bson/hash.rb, line 74
def serialize_to_buffer(buffer)
  position = buffer.length
  buffer.put_int32(0)
  serialize_key_value_pairs(buffer)
  buffer.put_byte(NULL_BYTE)
  buffer.replace_int32(position, buffer.length - position)
end