BSON

Build a document in one pass. Prefer this in Cryomongo instead of many []= calls.

Allocate a BSON instance from a byte array.

NOTE: The byte array is cloned.

data = "160000000378000E0000000261000200000062000000".hexbytes
io = IO::Memory.new(data)
bson = BSON.new(io)
puts bson.to_json # => {"x":{"a":"b"}}

Allocate a BSON instance from an IO

data = "160000000378000E0000000261000200000062000000".hexbytes
bson = BSON.new(data)
puts bson.to_json # => {"x":{"a":"b"}}

Allocate a BSON instance from a NamedTuple.

puts BSON.new({
  hello: "world",
}).to_json # => {"hello":"world"}

Allocate a BSON instance from a Hash.

puts BSON.new({
  "hello" => "world",
}).to_json # => {"hello":"world"}

No-op

Allocate a BSON instance from an Array.

puts BSON.new([1, 2, 3]).to_json # => [1,2,3]

Allocate a BSON instance from an instance of BSON::Serializable.

Read data and walk every field. Raises BSON::Error when the document is invalid.

Create a BSON document over data without copying the bytes.

One heap object. @data is a Slice the GC scans. Do not copy bytes a second time. The slice must stay valid for the life of the document. Nested values decoded from a parent document use this path.

Read a document from io. Returns nil when the bytes are invalid or short.

Allocate a BSON instance from a relaxed extended json representation.

NOTE: see https://github.com/mongodb/specifications/blob/master/source/extended-json.rst

bson = BSON.from_json(%({
  "_id": {
    "$oid": "57e193d7a9cc81b4027498b5"
  },
  "String": "string",
  "Int": 42,
  "Double": -1.0
}))
puts bson.to_json # => {"_id":{"$oid":"57e193d7a9cc81b4027498b5"},"String":"string","Int":42,"Double":-1.0}

Parse Extended JSON. Returns nil when the text is not valid BSON ExtJSON.

Read data and walk every field. Returns nil when the document is invalid.

Compare with another BSON value.

puts BSON.new({a: 1}) <=> BSON.new({a: 1}) # => 0
puts BSON.new({a: 1}) <=> BSON.new({b: 2}) # => -1

Return the element with the given key.

NOTE: Will raise if the key is not found.

bson = BSON.new({ key: "value" })
puts bson["key"] # =>"value"
puts bson["nope"] # => Unhandled exception: Missing bson key: nope (KeyError)

Append a key/value pair.

bson = BSON.new
bson["key"] = "value"
puts bson.to_json # => {"key":"value"}

Return the element with the given key, or nil if the key is not present.

bson = BSON.new({key: "value"})
puts bson["key"]?  # => "value"
puts bson["nope"]? # => nil

Append the contents of another BSON instance.

bson = BSON.new
other_bson = BSON.new({key: "value", key2: "value2"})
bson.append(other_bson)
puts bson.to_json # => {"key":"value","key2":"value2"}

Append one or more key/value pairs.

NOTE: more efficient for appending multiple values than calling []= individually.

bson = BSON.new
bson.append(key: "value", key2: "value2")
puts bson.to_json # => {"key":"value","key2":"value2"}

Append several fields with one rebuild of the document buffer.

Append a key/value pair and declare it as a BSON array.

Re-encode this document from decoded values.

Degenerate array keys become 0, 1, 2, ... and regex options become alphabetical. Used to check native BSON round-trips.

Clears the BSON instance.

Underlying bytes

Traverses the depth of a structure and returns the value, otherwise raises.

Traverses the depth of a structure and returns the value. Returns nil if not found.

Yield each key/value pair to the block.

NOTE: Underlying BSON code as well as the binary subtype are also yielded to the block as additional arguments.

BSON.new({
  a: 1,
  b: "2",
  c: Slice[0_u8, 1_u8, 2_u8],
}).each { |(key, value, code, binary_subtype)|
  puts "#{key} => #{value}, code: #{code}, subtype: #{binary_subtype}"
# a => 1, code: Int32, subtype:
# b => 2, code: String, subtype:
# c => Bytes[0, 1, 2], code: Binary, subtype: Generic
}

Returns an Iterator over each key/value pair.

Returns true if the BSON is empty.

Returns true when key given by key exists, otherwise false.

Return the size of the BSON instance in bytes.

Serialize this BSON instance into a canonical extended json representation.

NOTE: see https://github.com/mongodb/specifications/blob/master/source/extended-json.rst

bson = BSON.from_json(%({
  "Int": 42,
  "Double": -1.0
}))
puts bson.to_canonical_extjson # => {"Int":{"$numberLong":"42"},"Double":{"$numberDouble":"-1.0"}}

Returns a Hash representation.

NOTE: This function is recursive and will convert nested BSON to hash objects.

bson = BSON.new({
  a: 1,
  b: "2",
  c: {
    d: 1,
  },
})
pp bson.to_h # => {"a" => 1, "b" => "2", "c" => { "d" => 1}}

ameba:disable Metrics/CyclomaticComplexity

Validate that the BSON is well-formed.

bson = BSON.new("140000000461000D0000001030000A0000000000".hexbytes)
bson.validate!
# => Unhandled exception: Invalid BSON (overflow) (Exception)