class BSON::Binary

@since 2.0.0
@see bsonspec.org/#/specification<br><br>Represents binary data.

def self.from_bson(buffer, **_options)

Other tags:
    Since: - 2.0.0

Other tags:
    See: http://bsonspec.org/#/specification -

Returns:
  • (Binary) - The decoded binary data.

Options Hash: (**options)
  • :mode (nil | :bson) -- Decoding mode to use.

Parameters:
  • buffer (ByteBuffer) -- The byte buffer.
def self.from_bson(buffer, **_options)
  length = buffer.get_int32
  type_byte = buffer.get_byte
  if type_byte.bytes.first < USER_SUBTYPE
    type = TYPES[type_byte]
    if type.nil?
      raise Error::UnsupportedBinarySubtype,
            "BSON data contains unsupported binary subtype #{'0x%02x' % type_byte.ord}"
    end
  else
    type = type_byte
  end
  length = buffer.get_int32 if type == :old
  data = buffer.get_bytes(length)
  new(data, type)
end

def self.from_csharp_legacy_uuid(uuid_binary)

Other tags:
    Api: - private

Returns:
  • (BSON::Binary) - the Binary object

Parameters:
  • uuid_binary (String) -- the UUID data
def self.from_csharp_legacy_uuid(uuid_binary)
  uuid_binary.sub!(/\A(.)(.)(.)(.)(.)(.)(.)(.)(.{8})\z/, '\4\3\2\1\6\5\8\7\9')
  new(uuid_binary, :uuid_old)
end

def self.from_java_legacy_uuid(uuid_binary)

Other tags:
    Api: - private

Returns:
  • (BSON::Binary) - the Binary object

Parameters:
  • uuid_binary (String) -- the UUID data
def self.from_java_legacy_uuid(uuid_binary)
  uuid_binary.sub!(/\A(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)\z/) do
    (::Regexp.last_match[1..8].reverse + ::Regexp.last_match[9..16].reverse).join
  end
  new(uuid_binary, :uuid_old)
end

def self.from_python_legacy_uuid(uuid_binary)

Other tags:
    Api: - private

Returns:
  • (BSON::Binary) - the Binary object

Parameters:
  • uuid_binary (String) -- the UUID data
def self.from_python_legacy_uuid(uuid_binary)
  new(uuid_binary, :uuid_old)
end

def self.from_standard_uuid(uuid_binary)

Other tags:
    Api: - private

Returns:
  • (BSON::Binary) - the Binary object

Parameters:
  • uuid_binary (String) -- the UUID data
def self.from_standard_uuid(uuid_binary)
  new(uuid_binary, :uuid)
end

def self.from_uuid(uuid, representation = nil)

Other tags:
    Api: - experimental

Raises:
  • (ArgumentError) - If invalid representation is requested.

Returns:
  • (Binary) - The binary.

Parameters:
  • representation (Symbol) -- How to interpret the UUID.
  • uuid (String) -- The string representation of the UUID.
def self.from_uuid(uuid, representation = nil)
  raise ArgumentError, "Representation must be given as a symbol: #{representation}" if representation.is_a?(String)
  uuid_binary = uuid.delete('-').scan(/../).map(&:hex).map(&:chr).join
  representation ||= :standard
  handler = :"from_#{representation}_uuid"
  raise ArgumentError, "Invalid representation: #{representation}" unless respond_to?(handler)
  send(handler, uuid_binary)
end

def ==(other)

Other tags:
    Since: - 2.0.0

Returns:
  • (true, false) - If the objects are equal.

Parameters:
  • other (Object) -- The object to compare against.

Other tags:
    Example: Check the binary equality. -
def ==(other)
  return false unless other.is_a?(Binary)
  type == other.type && data == other.data
end

def as_extended_json(**options)

Returns:
  • (Hash) - The extended json representation.

Options Hash: (**opts)
  • :mode (nil | :relaxed | :legacy) -- Serialization mode
def as_extended_json(**options)
  subtype = @raw_type.each_byte.map { |c| c.to_s(16) }.join
  subtype = "0#{subtype}" if subtype.length == 1
  value = Base64.encode64(data).strip
  if options[:mode] == :legacy
    { '$binary' => value, '$type' => subtype }
  else
    { '$binary' => { 'base64' => value, 'subType' => subtype } }
  end
end

def as_json(*_args)

Returns:
  • (Hash) - The extended json representation.
def as_json(*_args)
  as_extended_json
end

def from_uuid_old_to_csharp_legacy_uuid(hex)

Returns:
  • (String) - the csharp-legacy-formatted UUID

Parameters:
  • hex (String) -- The hexadecimal string to convert
def from_uuid_old_to_csharp_legacy_uuid(hex)
  hex.sub(/\A(..)(..)(..)(..)(..)(..)(..)(..)(.{16})\z/, '\4\3\2\1\6\5\8\7\9')
end

def from_uuid_old_to_java_legacy_uuid(hex)

Returns:
  • (String) - the java-legacy-formatted UUID

Parameters:
  • hex (String) -- The hexadecimal string to convert
def from_uuid_old_to_java_legacy_uuid(hex)
  hex.sub(/\A(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)(..)\z/) do
    (::Regexp.last_match[1..8].reverse + ::Regexp.last_match[9..16].reverse).join
  end
end

def from_uuid_old_to_python_legacy_uuid(hex)

Returns:
  • (String) - the python-legacy-formatted UUID

Parameters:
  • hex (String) -- The hexadecimal string to convert
def from_uuid_old_to_python_legacy_uuid(hex)
  hex
end

def from_uuid_old_to_standard_uuid(_hex)

Raises:
  • (ArgumentError) - because standard representation is not supported

Parameters:
  • hex (String) -- The hexadecimal string to convert
def from_uuid_old_to_standard_uuid(_hex)
  raise ArgumentError, 'BSON::Binary objects of type :uuid_old cannot be stringified to :standard representation'
end

def from_uuid_old_to_uuid(representation)

Returns:
  • (String) - the UUID as a string

Parameters:
  • representation (Symbol) -- The representation to target
def from_uuid_old_to_uuid(representation)
  if representation.nil?
    raise ArgumentError, 'Representation must be specified for BSON::Binary objects of type :uuid_old'
  end
  hex = data.chars.map { |n| '%02x' % n.ord }.join
  handler = :"from_uuid_old_to_#{representation}_uuid"
  raise ArgumentError, "Invalid representation: #{representation}" unless respond_to?(handler, true)
  send(handler, hex)
    .sub(/\A(.{8})(.{4})(.{4})(.{4})(.{12})\z/, '\1-\2-\3-\4-\5')
end

def from_uuid_to_uuid(representation)

Returns:
  • (String) - the UUID as a string

Parameters:
  • representation (Symbol) -- The representation to target (must be
def from_uuid_to_uuid(representation)
  if representation != :standard
    raise ArgumentError,
          'Binary of type :uuid can only be stringified to :standard representation, ' \
          "requested: #{representation.inspect}"
  end
  data
    .chars
    .map { |n| '%02x' % n.ord }
    .join
    .sub(/\A(.{8})(.{4})(.{4})(.{4})(.{12})\z/, '\1-\2-\3-\4-\5')
end

def hash

Other tags:
    Since: - 2.3.1

Returns:
  • (Fixnum) -
def hash
  [ data, type ].hash
end

def init_with(coder)

Other tags:
    Api: - private
def init_with(coder)
  initialize_instance(coder['data'], coder['type'])
end

def initialize(data = '', type = :generic)

Other tags:
    Since: - 2.0.0

Parameters:
  • type (Symbol) -- The binary type.
  • data (String) -- The raw binary data.

Other tags:
    Example: Instantiate a binary. -
def initialize(data = '', type = :generic)
  initialize_instance(data, type)
end

def initialize_instance(data, type)

Parameters:
  • type (Symbol) -- the type to assign the binary object
  • data (String) -- the data to initialize the object with
def initialize_instance(data, type)
  @type = validate_type!(type)
  # The Binary class used to force encoding to BINARY when serializing to
  # BSON. Instead of doing that during serialization, perform this
  # operation during Binary construction to make it clear that once
  # the string is given to the Binary, the data is treated as a binary
  # string and not a text string in any encoding.
  data = data.dup.force_encoding('BINARY') unless data.encoding == Encoding.find('BINARY')
  @data = data
end

def inspect

Other tags:
    Since: - 2.3.0

Returns:
  • (String) - The binary in form BSON::Binary:object_id

Other tags:
    Example: Inspect the binary. -
def inspect
  "<BSON::Binary:0x#{object_id} type=#{type} data=0x#{data[0, 8].unpack1('H*')}...>"
end

def to_bson(buffer = ByteBuffer.new)

Other tags:
    Since: - 2.0.0

Other tags:
    See: http://bsonspec.org/#/specification -

Returns:
  • (BSON::ByteBuffer) - The buffer with the encoded object.

Other tags:
    Example: Encode the binary. -
def to_bson(buffer = ByteBuffer.new)
  position = buffer.length
  buffer.put_int32(0)
  buffer.put_byte(@raw_type)
  buffer.put_int32(data.bytesize) if type == :old
  buffer.put_bytes(data)
  buffer.replace_int32(position, buffer.length - position - 5)
end

def to_uuid(representation = nil)

Other tags:
    Api: - experimental

Raises:
  • (ArgumentError) - If the representation other than :standard
  • (TypeError) - If the subtype of Binary is not :uuid nor :uuid_old.

Returns:
  • (String) - The string representation of the UUID.

Parameters:
  • representation (Symbol) -- How to interpret the UUID.
def to_uuid(representation = nil)
  if representation.is_a?(String)
    raise ArgumentError,
          "Representation must be given as a symbol: #{representation.inspect}"
  end
  case type
  when :uuid
    from_uuid_to_uuid(representation || :standard)
  when :uuid_old
    from_uuid_old_to_uuid(representation)
  else
    raise TypeError, "The type of Binary must be :uuid or :uuid_old, this object is: #{type.inspect}"
  end
end

def validate_integer_type!(type)

Raises:
  • (BSON::Error::InvalidBinaryType) - if the type is invalid.

Returns:
  • (Symbol) - the symbolic type corresponding to the argument.

Parameters:
  • type (Integer) -- the provided type
def validate_integer_type!(type)
  @raw_type = type.chr.force_encoding('BINARY').freeze
  if type < USER_SUBTYPE
    raise BSON::Error::InvalidBinaryType, type unless TYPES.key?(@raw_type)
    return TYPES[@raw_type]
  end
  :user
end

def validate_symbol_type!(type)

Raises:
  • (BSON::Error::InvalidBinaryType) - if the type is invalid.

Returns:
  • (Symbol) - the symbolic type corresponding to the argument.

Parameters:
  • type (Symbol) -- the provided type
def validate_symbol_type!(type)
  raise BSON::Error::InvalidBinaryType, type unless SUBTYPES.key?(type)
  @raw_type = SUBTYPES[type]
  type
end

def validate_type!(type)

Other tags:
    Since: - 2.0.0

Raises:
  • (BSON::Error::InvalidBinaryType) - The the type is invalid.

Returns:
  • (Symbol) - the symbolic type corresponding to the argument.

Parameters:
  • type (Symbol | String | Integer) -- The provided type.

Other tags:
    Example: Validate the type. -

Other tags:
    Api: - private
def validate_type!(type)
  case type
  when Integer then validate_integer_type!(type)
  when String
    if type.length > 1
      validate_symbol_type!(type.to_sym)
    else
      validate_integer_type!(type.bytes.first)
    end
  when Symbol then validate_symbol_type!(type)
  else raise BSON::Error::InvalidBinaryType, type
  end
end