struct BSON
- BSON
- Struct
- Value
- Object
Overview
BSON is a binary format in which zero or more ordered key/value pairs are stored as a single entity.
BSON [bee · sahn], short for Binary JSON, is a binary-encoded serialization of JSON-like documents. Like JSON, BSON supports the embedding of documents and arrays within other documents and arrays. BSON also contains extensions that allow representation of data types that are not part of the JSON spec. For example, BSON has a Date type and a BinData type.
require "bson"
data = BSON.new({
hello: "world",
time: Time.utc,
name: BSON.new({
first_name: "John",
last_name: "Doe",
}),
fruits: ["Orange", "Banana"],
})
puts data.to_json
# => {"hello":"world","time":{"$date":"2020-05-18T07:32:13.621000000Z"},"name":{"first_name":"John","last_name":"Doe"},"fruits":["Orange","Banana"]}
Included Modules
- Comparable(BSON)
- Enumerable({String, BSON | BSON::Code | BSON::DBPointer | BSON::Decimal128 | BSON::MaxKey | BSON::MinKey | BSON::ObjectId | BSON::Symbol | BSON::Timestamp | BSON::Undefined | Bool | Float64 | Int32 | Int64 | Regex | Slice(UInt8) | String | Time | UUID | Nil, BSON::Element, BSON::Binary::SubType?})
- Iterable({String, BSON | BSON::Code | BSON::DBPointer | BSON::Decimal128 | BSON::MaxKey | BSON::MinKey | BSON::ObjectId | BSON::Symbol | BSON::Timestamp | BSON::Undefined | Bool | Float64 | Int32 | Int64 | Regex | Slice(UInt8) | String | Time | UUID | Nil, BSON::Element, BSON::Binary::SubType?})
Defined in:
Constructors
-
.new(data : Bytes? = nil, validate? = false)
Allocate a BSON instance from a byte array.
-
.new(io : IO)
Allocate a BSON instance from an IO
-
.new(tuple : NamedTuple)
Allocate a BSON instance from a NamedTuple.
-
.new(h : Hash)
Allocate a BSON instance from a Hash.
-
.new(bson : BSON)
No-op
-
.new(ary : Array)
Allocate a BSON instance from an Array.
-
.new(serializable : BSON::Serializable)
Allocate a BSON instance from an instance of BSON::Serializable.
Class Method Summary
-
.from_json(json : String)
Allocate a BSON instance from a relaxed extended json representation.
Instance Method Summary
-
#<=>(other : BSON)
Compare with another BSON value.
-
#[](key : String | ::Symbol) : Value
Return the element with the given key.
-
#[]=(key : String | ::Symbol, value)
Append a key/value pair.
-
#[]?(key : String | ::Symbol) : Value?
Return the element with the given key, or
nil
if the key is not present. -
#append(other : BSON)
Append the contents of another BSON instance.
-
#append(**args)
Append one or more key/value pairs.
-
#clear
Clears the BSON instance.
-
#data : Slice(UInt8)
Underlying bytes
-
#each
Returns an Iterator over each key/value pair.
-
#each(&block : Item -> _)
Yield each key/value pair to the block.
-
#empty? : Bool
Returns
true
if the BSON is empty. -
#has_key?(key : String | ::Symbol) : Bool
Returns
true
when key given by key exists, otherwisefalse
. -
#size
Return the size of the BSON instance in bytes.
-
#to_canonical_extjson
Serialize this BSON instance into a canonical extended json representation.
-
#to_h
Returns a Hash representation.
-
#to_json(builder : JSON::Builder, *, array = false)
ameba:disable Metrics/CyclomaticComplexity
-
#validate!
Validate that the BSON is well-formed.
Constructor Detail
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"}
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.
Class Method Detail
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}
Instance Method Detail
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 (Exception)
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"}
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 true
when key given by key exists, otherwise false
.
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}}
Validate that the BSON is well-formed.
bson = BSON.new("140000000461000D0000001030000A0000000000".hexbytes)
bson.validate!
# => Unhandled exception: Invalid BSON (overflow) (Exception)