Document Data Format: BSON

Raw Bytes

To write raw bytes to the byte buffer with no transformations, use the put_byte and put_bytes methods. Each method takes a byte string as its argument and copies this string into the buffer. The put_byte method enforces that the argument is a string of length 1. put_bytes accepts any length of strings. The strings can contain null bytes.

The following code demonstrates how to write raw bytes to a byte buffer:

buffer.put_byte("\x00")
buffer.put_bytes("\xff\xfe\x00\xfd")

Typed Byte Write Methods

The write methods described in the following sections write objects of particular types in the BSON specification. The type indicated by the method name takes precedence over the type of the argument. For example, if a floating-point value is passed to put_int32, it is coerced into an integer, and the driver writes the resulting integer to the byte buffer.

Strings

To write a UTF-8 string (BSON type 0x02) to the byte buffer, use the put_string method:

buffer.put_string("hello, world")

BSON strings are always encoded in UTF-8. This means that the argument to put_string must be either in UTF-8 or in an encoding convertable to UTF-8 (not binary). If the argument is in an encoding other than UTF-8, the string is first converted to UTF-8 and then the UTF-8 encoded version is written to the buffer. The string must be valid in its claimed encoding. The string can contain null bytes.

The BSON specification also defines a CString type, which is used, for example, for document keys. To write CStrings to the buffer, use put_cstring:

buffer.put_cstring("hello, world")

As with regular strings, CStrings in BSON must be UTF-8 encoded. If the argument is not in UTF-8, it is converted to UTF-8 and the resulting string is written to the buffer. Unlike put_string, the UTF-8 encoding of the argument given to put_cstring cannot have any null bytes, since the CString serialization format in BSON is null-terminated.

Unlike put_string, put_cstring also accepts symbols and integers. In all cases the argument is stringified prior to being written to the buffer:

buffer.put_cstring(:hello)
buffer.put_cstring(42)

Numbers

To write a 32-bit or a 64-bit integer to the byte buffer, use put_int32 and put_int64 methods, respectively. Note that Ruby integers can be arbitrarily large; if the value being written exceeds the range of a 32-bit or a 64-bit integer, put_int32 and put_int64 raise a RangeError error.

The following code demonstrates how to write integer values to a byte buffer:

buffer.put_int32(12345)
buffer.put_int64(123456789012345)

To write a 64-bit floating point value to the byte buffer, use put_double:

buffer.put_double(3.14159)

Convert Bytes to Strings

To retrieve the serialized data as a byte string, call to_s on the buffer:

buffer = BSON::ByteBuffer.new
buffer.put_string('testing')
socket.write(buffer.to_s)

UUID Methods

To create a UUID BSON::Binary (binary subtype 4) from its RFC 4122-compliant string representation, use the from_uuid method:

uuid_str = "00112233-4455-6677-8899-aabbccddeeff"
BSON::Binary.from_uuid(uuid_str)
# => <BSON::Binary:0x46986653612880 type=uuid data=0x0011223344556677...>

To stringify a UUID BSON::Binary to an RFC 4122-compliant representation, use the to_uuid method:

binary = BSON::Binary.new("\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF".force_encoding('BINARY'), :uuid)
# => <BSON::Binary:0x46942046606480 type=uuid data=0x0011223344556677...>
binary.to_uuid
# => "00112233-4455-6677-8899aabbccddeeff"

You can explicitly specify standard UUID representation in the from_uuid and to_uuid methods:

binary = BSON::Binary.from_uuid(uuid_str, :standard)
binary.to_uuid(:standard)

You can use the :standard representation only with a Binary value of subtype :uuid, not :uuid_old.

Legacy UUIDs

Data stored in BSON::Binary objects of subtype 3 (:uuid_old) can be persisted in one of three different byte orders depending on the driver that created the data. The byte orders are CSharp legacy, Java legacy, and Python legacy. The Python legacy byte order is the same as the standard RFC 4122 byte order. The CSharp legacy and Java legacy byte orders have some of the bytes in different locations.

The Binary object containing a legacy UUID does not encode which format the UUID is stored in. Therefore, methods that convert to and from the legacy UUID format take the desired format, or representation, as their argument. An application may copy legacy UUID Binary objects without knowing which byte order they store their data in.

The following methods for working with legacy UUIDs are provided for interoperability with existing deployments storing data in legacy UUID formats. In new applications, use the :uuid (subtype 4) format only, which is compliant with RFC 4122.

To stringify a legacy UUID BSON::Binary, use the to_uuid method and specify the desired representation. Accepted representations are :csharp_legacy, :java_legacy and :python_legacy. A legacy UUID BSON::Binary cannot be stringified without specifying a representation.

binary = BSON::Binary.new("\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF".force_encoding('BINARY'), :uuid_old)
# => <BSON::Binary:0x46942046606480 type=uuid data=0x0011223344556677...>
binary.to_uuid
# => ArgumentError (Representation must be specified for BSON::Binary objects of type :uuid_old)
binary.to_uuid(:csharp_legacy)
# => "33221100-5544-7766-8899aabbccddeeff"
binary.to_uuid(:java_legacy)
# => "77665544-3322-1100-ffeeddccbbaa9988"
binary.to_uuid(:python_legacy)
# => "00112233-4455-6677-8899aabbccddeeff"

To create a legacy UUID BSON::Binary from the string representation of the UUID, use the from_uuid method and specify the desired representation:

uuid_str = "00112233-4455-6677-8899-aabbccddeeff"
BSON::Binary.from_uuid(uuid_str, :csharp_legacy)
# => <BSON::Binary:0x46986653650480 type=uuid_old data=0x3322110055447766...>
BSON::Binary.from_uuid(uuid_str, :java_legacy)
# => <BSON::Binary:0x46986653663960 type=uuid_old data=0x7766554433221100...>
BSON::Binary.from_uuid(uuid_str, :python_legacy)
# => <BSON::Binary:0x46986653686300 type=uuid_old data=0x0011223344556677...>

You can use these methods to convert from one representation to another:

BSON::Binary.from_uuid('77665544-3322-1100-ffeeddccbbaa9988',:java_legacy).to_uuid(:csharp_legacy)
# => "33221100-5544-7766-8899aabbccddeeff"

BSON::Decimal128 and BigDecimal

The BigDecimal#from_bson and BigDecimal#to_bson methods use the equivalent BSON::Decimal128 methods internally. This leads to some limitations on BigDecimal values that can be serialized to BSON and those that can be deserialized from existing decimal128 BSON values.

Serializing BigDecimal instances as BSON::Decimal128 instances allows for more flexibility when querying and performing aggregations in MongoDB. The following list describes the limitations on BigDecimal:

• Decimal128 has a limited range and precision, while BigDecimal has no restrictions in terms of range and precision. Decimal128 has a max value of approximately 10^6145 and a min value of approximately -10^6145, and has a maximum of 34 bits of precision.

• Decimal128 is able to accept signed NaN values, while BigDecimal is not. All signed NaN values that are deserialized into BigDecimal instances will be unsigned.

• Decimal128 maintains trailing zeroes when serializing to and deserializing from BSON. BigDecimal, however, does not maintain trailing zeroes and therefore using BigDecimal may result in a lack of precision.

Options, Flags, and Modifiers

Both Ruby and PCRE regular expressions support modifiers. These are also called "options" in Ruby contexts and "flags" in PCRE contexts. The meaning of s and m modifiers differs in Ruby and PCRE in the following ways:

• Ruby does not have the s modifier. Instead, the Ruby m modifier performs the same function as the PCRE s modifier, which is to make the period (.) match any character including newlines. The Ruby documentation refers to the m modifier as enabling multi-line mode.

• Ruby always operates in the equivalent of PCRE's multi-line mode, enabled by the m modifier in PCRE regular expressions. In Ruby the ^ anchor always refers to the beginning of line and the $ anchor always refers to the end of line.

When writing regular expressions intended to be used in both Ruby and PCRE environments, including MongoDB Server and most other MongoDB drivers, avoid using the ^ and $ anchors. The following sections provide workarounds and recommendations for authoring portable regular expressions that can be used in multiple contexts.

^ Anchor

In Ruby regular expressions, the ^ anchor always refers to the beginning of line. In PCRE regular expressions, the ^ anchor refers to the beginning of input by default, and the m flag changes its meaning to the beginning of line.

Both Ruby and PCRE regular expressions support the \A anchor to refer to the beginning of input, regardless of modifiers. The following suggestions allow you to write portable regular expressions:

• Use the \A anchor to refer to the beginning of input.

• Use the ^ anchor to refer to the beginning of line if you set the m flag in PCRE regular expressions. Alternatively, use one of the following constructs which work regardless of modifiers:

  • (?:\A|(?<=\n)): handles LF and CR+LF line ends

  • (?:\A|(?<=[\r\n])): handles CR, LF and CR+LF line ends

$ Anchor

In Ruby regular expressions, the $ anchor always refers to the end of line. In PCRE regular expressions, the $ anchor refers to the end of input by default and the m flag changes its meaning to the end of line.

Both Ruby and PCRE regular expressions support the \z anchor to refer to the end of input, regardless of modifiers.

The following suggestions allow you to write portable regular expressions:

• Use the \z anchor to refer to the end of input.

• Use the $ anchor to refer to the beginning of line if you set the m flag in PCRE regular expressions. Alternatively, use one of the following constructs which work regardless of modifiers:

  • (?:\z|(?=\n)): handles LF and CR+LF line ends

  • (?:\z|(?=[\n\n])): handles CR, LF and CR+LF line ends