class BSON::Binary
@since 2.0.0
@see bsonspec.org/#/specification<br><br>Represents binary data.
def self.from_bson(buffer, **_options)
- 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)
- 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)
- 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)
- 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)
- 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)
- 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)
- 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)
-
(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)
-
(Hash)
- The extended json representation.
def as_json(*_args) as_extended_json end
def from_uuid_old_to_csharp_legacy_uuid(hex)
-
(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)
-
(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)
-
(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)
-
(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)
-
(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)
-
(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
- Since: - 2.3.1
Returns:
-
(Fixnum)
-
def hash [ data, type ].hash end
def init_with(coder)
- Api: - private
def init_with(coder) initialize_instance(coder['data'], coder['type']) end
def initialize(data = '', type = :generic)
- 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)
-
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
- 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)
- 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)
- 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)
-
(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)
-
(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)
- 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