Class: BSON::Binary

Inherits:
Object
  • Object
show all
Includes:
Encodable, JSON
Defined in:
lib/bson/binary.rb

Overview

Represents binary data.

See Also:

Since:

  • 2.0.0

Defined Under Namespace

Classes: InvalidType

Constant Summary collapse

BSON_TYPE =

A binary is type 0x05 in the BSON spec.

Since:

  • 2.0.0

5.chr.force_encoding(BINARY).freeze
SUBTYPES =

The mappings of subtypes to their single byte identifiers.

Since:

  • 2.0.0

{
  :generic => 0.chr,
  :function => 1.chr,
  :old =>  2.chr,
  :uuid_old => 3.chr,
  :uuid => 4.chr,
  :md5 => 5.chr,
  :user => 128.chr
}.freeze
TYPES =

The mappings of single byte subtypes to their symbol counterparts.

Since:

  • 2.0.0

SUBTYPES.invert.freeze

Constants included from Encodable

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Encodable

#encode_binary_data_with_placeholder, #encode_with_placeholder_and_null

Methods included from JSON

#to_json

Constructor Details

#initialize(data = "", type = :generic) ⇒ Binary

Instantiate the new binary object.

Examples:

Instantiate a binary.

BSON::Binary.new(data, :md5)

Parameters:

  • data (Object) (defaults to: "") —

    The raw binary data.

  • type (Symbol) (defaults to: :generic) —

    The binary type.

Since:

  • 2.0.0



105
106
107
108
109
 
# File 'lib/bson/binary.rb', line 105

def initialize(data = "", type = :generic)
  validate_type!(type)
  @data = data
  @type = type
end

Instance Attribute Details

#data ⇒ Object

Returns The raw binary data.

Returns:

  • (Object) —

    The raw binary data.

Since:

  • 2.0.0



55
56
57
 
# File 'lib/bson/binary.rb', line 55

def data
  @data
end

#type ⇒ Object

Since:

  • 2.0.0



55
 
# File 'lib/bson/binary.rb', line 55

attr_reader :data, :type

Class Method Details

.from_bson(bson) ⇒ Binary

Deserialize the binary data from BSON.

Parameters:

  • bson (BSON) —

    The bson representing binary data.

Returns:

  • (Binary) —

    The decoded binary data.

See Also:

Since:

  • 2.0.0



150
151
152
153
154
155
156
 
# File 'lib/bson/binary.rb', line 150

def self.from_bson(bson)
  length = Int32.from_bson(bson)
  type = TYPES[bson.read(1)]
  length = Int32.from_bson(bson) if type == :old
  data = bson.read(length)
  new(data, type)
end

Instance Method Details

#==(other) ⇒ true, false Also known as: eql?

Determine if this binary object is equal to another object.

Examples:

Check the binary equality.

binary == other

Parameters:

  • other (Object) —

    The object to compare against.

Returns:

  • (true, false) —

    If the objects are equal.

Since:

  • 2.0.0



67
68
69
70
 
# File 'lib/bson/binary.rb', line 67

def ==(other)
  return false unless other.is_a?(Binary)
  type == other.type && data == other.data
end

#as_json(*args) ⇒ Hash

Get the binary as JSON hash data.

Examples:

Get the binary as a JSON hash.

binary.as_json

Returns:

  • (Hash) —

    The binary as a JSON hash.

Since:

  • 2.0.0



92
93
94
 
# File 'lib/bson/binary.rb', line 92

def as_json(*args)
  { "$binary" => data, "$type" => type }
end

#hash ⇒ Fixnum

Generates a Fixnum hash value for this object.

Allows using Binary as hash keys.

Returns:

  • (Fixnum)

Since:

  • 2.3.1



80
81
82
 
# File 'lib/bson/binary.rb', line 80

def hash
  data.hash + type.hash
end

#inspect ⇒ String

Get a nice string for use with object inspection.

Examples:

Inspect the binary.

object_id.inspect

Returns:

  • (String) —

    The binary in form BSON::Binary:object_id

Since:

  • 2.3.0



119
120
121
 
# File 'lib/bson/binary.rb', line 119

def inspect
  "<BSON::Binary:0x#{object_id} type=#{type} data=0x#{data[0, 8].unpack('H*').first}...>"
end

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

Encode the binary type

Examples:

Encode the binary.

binary.to_bson

Returns:

  • (String) —

    The encoded binary.

See Also:

Since:

  • 2.0.0



133
134
135
136
137
138
139
 
# File 'lib/bson/binary.rb', line 133

def to_bson(encoded = ''.force_encoding(BINARY))
  encode_binary_data_with_placeholder(encoded) do |encoded|
    encoded << SUBTYPES.fetch(type)
    encoded << data.bytesize.to_bson if type == :old
    encoded << data.force_encoding(BINARY)
  end
end