Class: BSON::ByteBuffer

Inherits:
Object
  • Object
show all
Defined in:
ext/bson/init.c,
ext/bson/init.c

Overview

Stores BSON-serialized data and provides efficient serialization and deserialization of common Ruby classes using native code.

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Object

Instance Method Details

#get_array(**options) ⇒ Array

Reads an array from the byte buffer.

Returns:

Returns:

  • (Array) —

    The decoded array.

#get_byte ⇒ Object

#get_bytes ⇒ Object

#get_cstring ⇒ Object

#get_decimal128_bytes ⇒ Object

#get_double ⇒ Object

#get_hash(**options) ⇒ Hash

Reads a document from the byte buffer and returns it as a BSON::Document.

Returns:

Returns:

#get_int32 ⇒ Object

#get_int64 ⇒ Object

#get_string ⇒ Object

#get_uint32(buffer) ⇒ Fixnum

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Reads an unsigned 32 bit number from the byte buffer.

Returns:

  • (Fixnum)

Returns:

  • (Fixnum) —

    The unsigned 32 bits integer from the buffer

#length ⇒ Fixnum

Returns the number of bytes available to be read in the buffer.

When a buffer is being written to, each added byte increases its length. When a buffer is being read from, each read byte decreases its length.

Returns:

  • (Fixnum)

#put_array(array) ⇒ ByteBuffer

Writes an Array into the byte buffer.

Returns the modified self.

Returns:

#put_byte(binary_str) ⇒ ByteBuffer

Writes the specified byte string, which must be of length 1, to the byte buffer.

Returns the modified self.

Returns:

#put_bytes(binary_str) ⇒ ByteBuffer

Writes the specified byte string to the byte buffer.

This method writes exactly the provided byte string - in particular, it does not prepend the length, and does not append a null byte at the end.

Returns the modified self.

Returns:

#put_cstring(obj) ⇒ ByteBuffer

Converts obj to a string, which must not contain any null bytes, and which must be valid UTF-8, and writes the string to the buffer as a BSON cstring. obj can be an instance of String, Symbol or Fixnum.

If the string serialization of obj contains null bytes, this method raises ArgumentError. If obj is of an unsupported type, this method raises TypeError.

BSON cstring serialization contains no length of the string (relying instead on the null terminator), unlike the BSON string serialization.

Returns:

#put_decimal128(low_64bit, high_64bit) ⇒ ByteBuffer

Writes a 128-bit Decimal128 value to the buffer.

low_64bit and high_64bit are Fixnum objects containing the low and the high parts of the 128-bit Decimal128 value, respectively.

Returns the modified self.

Returns:

#put_double(double) ⇒ ByteBuffer

Writes a 64-bit floating point value to the buffer.

Returns the modified self.

Returns:

#put_hash(hash) ⇒ ByteBuffer

Writes a Hash into the byte buffer.

Returns the modified self.

Returns:

#put_int32(fixnum) ⇒ ByteBuffer

Writes a 32-bit integer value to the buffer.

If the argument cannot be represented in 32 bits, raises RangeError.

Returns the modified self.

Returns:

#put_int64(fixnum) ⇒ ByteBuffer

Writes a 64-bit integer value to the buffer.

If the argument cannot be represented in 64 bits, raises RangeError.

Returns the modified self.

Returns:

#put_string(str) ⇒ ByteBuffer

Writes the specified string to the byte buffer as a BSON string.

Unlike #put_bytes, this method writes the provided byte string as a “BSON string” - the string is prefixed with its length and suffixed with a null byte. The byte string may contain null bytes itself thus the null terminator is redundant, but it is required by the BSON specification.

str must either already be in UTF-8 encoding or be a string encodable to UTF-8. In particular, a string in BINARY/ASCII-8BIT encoding is generally not suitable for this method. EncodingError will be raised if str cannot be encoded in UTF-8, or if str claims to be encoded in UTF-8 but contains bytes/byte sequences which are not valid in UTF-8. Use #put_bytes to write arbitrary byte strings to the buffer.

Returns the modified self.

Returns:

#put_symbol(sym) ⇒ ByteBuffer

Converts sym to a string and writes the resulting string to the byte buffer.

The symbol may contain null bytes.

The symbol value is assumed to be encoded in UTF-8. If the symbol value contains bytes or byte sequences that are not valid in UTF-8, this method raises EncodingError.

Note: due to the string conversion, a symbol written to the buffer becomes indistinguishable from a string with the same value written to the buffer.

Returns:

#put_uint32(fixnum) ⇒ ByteBuffer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Writes an unsigned 32-bit integer value to the buffer.

If the argument cannot be represented in 32 bits, raises RangeError.

Returns the modified self.

Returns:

#read_position ⇒ Fixnum

Returns the read position in the buffer.

Returns:

  • (Fixnum)

#replace_int32(position, fixnum) ⇒ ByteBuffer

Replaces a 32-bit integer value at the specified position in the buffer.

The position must be a non-negative integer, and must be completely contained within the data already written. For example, if the buffer has the write position of 12, the acceptable range of positions for this method is 0..8.

If the argument cannot be represented in 32 bits, raises RangeError.

Returns the modified self.

Returns:

#rewind! ⇒ ByteBuffer

Resets the read position to the beginning of the byte buffer.

Note: rewind! does not change the buffer’s write position.

Returns the modified self.

Returns:

#to_s ⇒ String

Returns the contents of the buffer as a binary string.

If the buffer is used for reading, the returned contents is the data that was not yet read. If the buffer is used for writing, the returned contents is the complete data that has been written so far.

Note: this method copies the buffer’s contents into a newly allocated String instance. It does not return a reference to the data stored in the buffer itself.

Returns:

#write_position ⇒ Fixnum

Returns the write position in the buffer.

Returns:

  • (Fixnum)