Module: BSON::String

Includes:
Encodable
Defined in:
lib/bson/string.rb

Overview

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

See Also:

Since:

  • 2.0.0

Defined Under Namespace

Modules: ClassMethods

Constant Summary collapse

BSON_TYPE =

A string is type 0x02 in the BSON spec.

Since:

  • 2.0.0

2.chr.force_encoding(BINARY).freeze

Constants included from Encodable

Encodable::BSON_ADJUST, Encodable::PLACEHOLDER, Encodable::STRING_ADJUST

Instance Method Summary collapse

Methods included from Encodable

#encode_binary_data_with_placeholder, #encode_with_placeholder_and_null

Instance Method Details

#from_bson_string ⇒ String

Take the binary string and return a UTF-8 encoded string.

Examples:

Convert from a BSON string.

"\x00".from_bson_string

Returns:

  • (String) —

    The UTF-8 string.

Raises:

  • (EncodingError) —

    If the string is not UTF-8.

Since:

  • 2.0.0



143
144
145
 
# File 'lib/bson/string.rb', line 143

def from_bson_string
  force_encoding(UTF8)
end

#set_int32(pos, int32) ⇒ String

Set four bytes for int32 in a binary string and return it.

Examples:

Set int32 in a BSON string.

"".set_int32(pos, int32)

Parameters:

  • The (Fixnum) —

    position to set.

  • The (Fixnum) —

    int32 value.

Returns:

  • (String) —

    The binary string.

Since:

  • 2.0.0



158
159
160
 
# File 'lib/bson/string.rb', line 158

def set_int32(pos, int32)
  self[pos, 4] = [ int32 ].pack(Int32::PACK)
end

#to_bson(encoded = ''.force_encoding(BINARY)) ⇒ String

Get the string as encoded BSON.

Examples:

Get the string as encoded BSON.

"test".to_bson

Returns:

  • (String) —

    The encoded string.

Raises:

  • (EncodingError) —

    If the string is not UTF-8.

See Also:

Since:

  • 2.0.0



44
45
46
47
48
 
# File 'lib/bson/string.rb', line 44

def to_bson(encoded = ''.force_encoding(BINARY))
  encode_with_placeholder_and_null(STRING_ADJUST, encoded) do |encoded|
    to_bson_string(encoded)
  end
end

#to_bson_cstring(encoded = ''.force_encoding(BINARY)) ⇒ String

Get the string as an encoded C string.

Examples:

Get the string as an encoded C string.

"test".to_bson_cstring

Returns:

  • (String) —

    The encoded string.

Raises:

  • (EncodingError) —

    If the string is not UTF-8.

See Also:

Since:

  • 2.0.0



78
79
80
81
 
# File 'lib/bson/string.rb', line 78

def to_bson_cstring(encoded = ''.force_encoding(BINARY))
  check_for_illegal_characters!
  to_bson_string(encoded) << NULL_BYTE
end

#to_bson_key(encoded = ''.force_encoding(BINARY)) ⇒ String

Get the string as a BSON key name encoded C string with checking for special characters.

Examples:

Get the string as key name.

"test".to_bson_key

Returns:

  • (String) —

    The encoded string.

Raises:

  • (EncodingError) —

    If the string is not UTF-8.

See Also:

Since:

  • 2.0.0



62
63
64
 
# File 'lib/bson/string.rb', line 62

def to_bson_key(encoded = ''.force_encoding(BINARY))
  to_bson_cstring(encoded)
end

#to_bson_object_id ⇒ String

Note:

This is used for repairing legacy bson data.

Convert the string to an object id. This will only work for strings of size 12.

Examples:

Convert the string to an object id.

string.to_bson_object_id

Returns:

  • (String) —

    The raw object id bytes.

Raises:

  • (InvalidObjectId) —

    If the string is not 12 elements.

Since:

  • 2.0.0



96
97
98
 
# File 'lib/bson/string.rb', line 96

def to_bson_object_id
  ObjectId.repair(self)
end

#to_bson_string(encoded = ''.force_encoding(BINARY)) ⇒ String

Convert the string to a UTF-8 string then force to binary. This is so we get errors for strings that are not UTF-8 encoded.

Examples:

Convert to valid BSON string.

"Straße".to_bson_string

Returns:

  • (String) —

    The binary string.

Raises:

  • (EncodingError) —

    If the string is not UTF-8.

Since:

  • 2.0.0



111
112
113
114
115
116
117
118
119
 
# File 'lib/bson/string.rb', line 111

def to_bson_string(encoded = ''.force_encoding(BINARY))
  begin
    to_utf8_binary(encoded)
  rescue EncodingError
    data = dup.force_encoding(UTF8)
    raise unless data.valid_encoding?
    encoded << data.force_encoding(BINARY)
  end
end

#to_hex_string ⇒ String

Convert the string to a hexidecimal representation.

Examples:

Convert the string to hex.

"\x01".to_hex_string

Returns:

  • (String) —

    The string as hex.

Since:

  • 2.0.0



129
130
131
 
# File 'lib/bson/string.rb', line 129

def to_hex_string
  unpack("H*")[0]
end