class Erlang::Binary

A `Binary` is a series of bytes.

### Creating Binaries

Erlang::Binary["test"]
# => Erlang::Binary["test"]

Attributes

data[R]

Return the data for this `Erlang::Binary` @return [::String]

Public Class Methods

[](*data) click to toggle source

Create a new `Binary` populated with the given `data`. @param data [::String, Symbol, ::Enumerable, Integer] The content of the `Binary` @return [Binary] @raise [ArgumentError] if `data` cannot be coerced to be a `::String`

# File lib/erlang/binary.rb, line 29
def [](*data)
  return Erlang.iolist_to_binary(data)
end
compare(a, b) click to toggle source

Compares `a` and `b` and returns whether they are less than, equal to, or greater than each other.

@param a [Binary] The left argument @param b [Binary] The right argument @return [-1, 0, 1] @raise [ArgumentError] if `a` or `b` is not a `Binary`

# File lib/erlang/binary.rb, line 48
def compare(a, b)
  return Erlang::Bitstring.compare(a, b)
end
concat(*iodata) click to toggle source

Concatenates list of `Binary` or `Bitstring` items into a single `Binary` or `Bitstring`.

@example

Erlang::Binary.concat(Erlang::Bitstring[1, bits: 2], Erlang::Binary[255])
# => Erlang::Bitstring[127, 3, bits: 2]

@param iodata [Binary, Bitstring] The list of bitstrings @return [Binary, Bitstring]

# File lib/erlang/binary.rb, line 60
def concat(*iodata)
  return iodata.reduce(Erlang::EmptyBinary) { |acc, item| acc.concat(item) }
end
decode_unsigned(subject, endianness = :big) click to toggle source

Returns an unsigned `Integer` which is the `endianness` based version of the `subject`.

@param subject [::String, Binary] The string to decode @param endianness [:big, :little] The endianness of the subject @return [Integer] @raise [ArgumentError] if `subject` is not a string or `endianness` is not `:big` or `:little`

# File lib/erlang/binary.rb, line 70
def decode_unsigned(subject, endianness = :big)
  subject = subject.to_s if subject.kind_of?(Erlang::Binary)
  raise ArgumentError, 'subject must be a String' if not subject.is_a?(::String)
  case endianness
  when :big, :little
    bits = 0
    bytes = subject.unpack(Erlang::Terms::UINT8_SPLAT)
    bytes = bytes.reverse if endianness == :big
    return bytes.inject(0) do |unsigned, n|
      unsigned = unsigned + (n << bits)
      bits += 8
      next unsigned
    end
  else
    raise ArgumentError, 'endianness must be :big or :little'
  end
end
empty() click to toggle source

Return an empty `Binary`. If used on a subclass, returns an empty instance of that class.

@return [Binary]

# File lib/erlang/binary.rb, line 37
def empty
  return @empty ||= self.new
end
encode_unsigned(unsigned, endianness = :big) click to toggle source

Returns a `::String` which is the `endianness` based version of the unsigned `subject`.

@param subject [Integer] The unsigned integer to encode @param endianness [:big, :little] The endianness of the subject @return [::String] @raise [ArgumentError] if `subject` is not an integer or `endianness` is not `:big` or `:little`

# File lib/erlang/binary.rb, line 94
def encode_unsigned(unsigned, endianness = :big)
  raise ArgumentError, 'unsigned must be a non-negative Integer' if not unsigned.is_a?(::Integer) or unsigned < 0
  case endianness
  when :big, :little
    n = unsigned
    bytes = []
    loop do
      bytes << (n & 255)
      break if (n >>= 8) == 0
    end
    bytes = bytes.reverse if endianness == :big
    return bytes.pack(Erlang::Terms::UINT8_SPLAT)
  else
    raise ArgumentError, 'endianness must be :big or :little'
  end
end
new(data = nil) click to toggle source

@private

# File lib/erlang/binary.rb, line 113
def initialize(data = nil)
  data = ::String.new if data.nil?
  data = data.data if data.is_a?(Erlang::Binary)
  raise ArgumentError, 'data must be a String' if not data.is_a?(::String)
  _, data = Erlang::Terms.utf8_encoding(data)
  @printable = Erlang::Terms.printable?(data)
  data = Erlang::Terms.binary_encoding(data) if not @printable
  @data = data.freeze
end

Public Instance Methods

+(*other)
Alias for: concat
==(other)
Alias for: eql?
[](position)
Alias for: at
at(position) click to toggle source

Returns the byte at the provided `position`.

@param position [Integer] The position of the byte @return [Integer] @raise [ArgumentError] if `position` is not an `Integer`

# File lib/erlang/binary.rb, line 133
def at(position)
  raise ArgumentError, 'position must be an Integer' if not position.is_a?(::Integer)
  return @data.getbyte(position)
end
Also aliased as: []
bits() click to toggle source

Return the bits for this `Erlang::Binary` @return [::Integer] @!parse attr_reader :bits

# File lib/erlang/binary.rb, line 20
def bits
  return 8
end
bitsize() click to toggle source

@return [Integer] the number of bits in this `Binary`

# File lib/erlang/binary.rb, line 140
def bitsize
  return (bytesize * bits)
end
bitslice(*args) click to toggle source

Return specific objects from the `Binary`. All overloads return `nil` if the starting index is out of range.

@overload bitslice(index)

Returns a single bit at the given `index`. If `index` is negative,
count backwards from the end.

@param index [Integer] The index to retrieve. May be negative.
@return [Integer, nil]
@example
  b = Erlang::Binary[1]
  b.bitslice(0)  # => 0
  b.bitslice(7)  # => 1
  b.bitslice(-1) # => 1
  b.bitslice(8)  # => nil

@overload bitslice(index, length)

Return a bitstring starting at `index` and continuing for `length`
bits or until the end of the `Binary`, whichever occurs first.

@param start [Integer] The index to start retrieving bits from. May be
                       negative.
@param length [Integer] The number of bits to retrieve.
@return [Bitstring, Binary]
@example
  b = Erlang::Binary[117]
  b.bitslice(0, 3) # => Erlang::Bitstring[3, bits: 3]
  b.bitslice(3, 5) # => Erlang::Bitstring[21, bits: 5]
  b.bitslice(9, 1) # => nil

@overload bitslice(index..end)

Return a bitstring starting at `index` and continuing to index
`end` or the end of the `Binary`, whichever occurs first.

@param range [Range] The range of bits to retrieve.
@return [Bitstring, Binary]
@example
  b = Erlang::Binary[117]
  b.bitslice(0...3) # => Erlang::Bitstring[3, bits: 3]
  b.bitslice(3...8) # => Erlang::Bitstring[21, bits: 5]
  b.bitslice(9..-1) # => nil

@see Erlang::Bitstring#bitslice

# File lib/erlang/binary.rb, line 187
def bitslice(*args)
  return Erlang::Bitstring.new(@data, 8).bitslice(*args)
end
bytesize() click to toggle source

@return [Integer] the number of bytes in this `Binary`

# File lib/erlang/binary.rb, line 192
def bytesize
  return @data.bytesize
end
Also aliased as: size
concat(*other) click to toggle source

Concatenates list of `Binary` or `Bitstring` items into a single `Binary` or `Bitstring`.

@example

Erlang::Binary["a"].concat(Erlang::Bitstring[3, bits: 3]).concat(Erlang::Bitstring[2, bits: 5])
# => "ab"

@param iodata [Binary, Bitstring] The list of bitstrings @return [Binary, Bitstring]

# File lib/erlang/binary.rb, line 205
def concat(*other)
  if other.size == 1 and (other[0].kind_of?(Erlang::Binary) or other[0].kind_of?(Erlang::Bitstring))
    other = other[0]
  else
    other = Erlang::Binary[*other]
  end
  return other if empty?
  return self if other.empty?
  if other.kind_of?(Erlang::Bitstring) and other.bits != 8
    return Erlang::Bitstring[@data, other.data, bits: other.bits]
  else
    return Erlang::Binary[@data, other.data]
  end
end
Also aliased as: +
copy(n = 1) click to toggle source

Returns a new `Binary` containing `n` copies of itself. `n` must be greater than or equal to 0. @param n [Integer] The number of copies @return [Binary] @raise [ArgumentError] if `n` is less than 0

# File lib/erlang/binary.rb, line 225
def copy(n = 1)
  raise ArgumentError, 'n must be a non-negative Integer' if not n.is_a?(::Integer) or n < 0
  return self if n == 1
  return Erlang::Binary[(@data * n)]
end
decode_unsigned(endianness = :big) click to toggle source

Returns an unsigned `Integer` which is the `endianness` based version of this `Binary`. @param endianness [:big, :little] The endianness of this `Binary` @return [Integer] @see Erlang::Binary.decode_unsigned

# File lib/erlang/binary.rb, line 235
def decode_unsigned(endianness = :big)
  return Erlang::Binary.decode_unsigned(@data, endianness)
end
each_bit() { |bit| ... } click to toggle source

Call the given block once for each bit in the `Binary`, passing each bit from first to last successively to the block. If no block is given, returns an `Enumerator`.

@return [self] @yield [Integer]

# File lib/erlang/binary.rb, line 245
def each_bit
  return enum_for(:each_bit) unless block_given?
  index = 0
  bitsize = self.bitsize
  @data.each_byte do |byte|
    loop do
      break if index == bitsize
      bit = (byte >> (7 - (index & 7))) & 1
      yield bit
      index += 1
      break if (index & 7) == 0
    end
  end
  return self
end
each_bitslice(number, &block) click to toggle source

Split the bits in this `Binary` in groups of `number` bits, and yield each group to the block (as a `List`). If no block is given, returns an `Enumerator`.

@example

b = Erlang::Binary[117]
b.each_bitslice(4).to_a # => [Erlang::Bitstring[7, bits: 4], Erlang::Bitstring[5, bits: 4]]

@return [self, Enumerator] @yield [Binary, Bitstring] Once for each bitstring. @see Erlang::Bitstring#each_bitslice

# File lib/erlang/binary.rb, line 272
def each_bitslice(number, &block)
  return enum_for(:each_bitslice, number) unless block_given?
  bitstring = Erlang::Bitstring.new(@data, 8)
  bitstring.each_bitslice(number, &block)
  return self
end
each_byte(&block) click to toggle source

Call the given block once for each byte in the `Binary`, passing each byte from first to last successively to the block. If no block is given, returns an `Enumerator`.

@return [self] @yield [Integer]

# File lib/erlang/binary.rb, line 285
def each_byte(&block)
  return enum_for(:each_byte) unless block_given?
  @data.each_byte(&block)
  return self
end
empty?() click to toggle source

Returns true if this `Binary` is empty.

@return [Boolean]

# File lib/erlang/binary.rb, line 294
def empty?
  return @data.empty?
end
eql?(other) click to toggle source

Return true if `other` has the same type and contents as this `Binary`.

@param other [Object] The object to compare with @return [Boolean]

# File lib/erlang/binary.rb, line 302
def eql?(other)
  return true if other.equal?(self)
  if instance_of?(other.class)
    return @data.eql?(other.data)
  elsif other.kind_of?(Erlang::Bitstring)
    return !!(Erlang::Bitstring.compare(other, self) == 0)
  else
    return !!(Erlang.compare(other, self) == 0)
  end
end
Also aliased as: ==
erlang_inspect(raw = false) click to toggle source

Return the contents of this `Binary` as a Erlang-readable `::String`.

@example

Erlang::Binary["test"].erlang_inspect
# => "<<\"test\"/utf8>>"
# Pass `raw` as `true` for the decimal version
Erlang::Binary["test"].erlang_inspect(true)
# => "<<116,101,115,116>>"

@return [::String]

# File lib/erlang/binary.rb, line 352
def erlang_inspect(raw = false)
  result = '<<'
  if raw == false and @printable
    result << @data.inspect
    result << '/utf8'
  else
    result << @data.bytes.join(',')
  end
  result << '>>'
  return result
end
first() click to toggle source

Returns the first byte of this `Binary`. @return [Integer] @raise [NotImplementedError] if this `Binary` is empty

# File lib/erlang/binary.rb, line 317
def first
  raise NotImplementedError if empty?
  return at(0)
end
hash() click to toggle source

@private

# File lib/erlang/binary.rb, line 124
def hash
  return @data.hash
end
inspect() click to toggle source

@return [::String] the nicely formatted version of the `Binary`

# File lib/erlang/binary.rb, line 365
def inspect
  return @data.inspect
end
last() click to toggle source

Returns the last byte of this `Binary`. @return [Integer] @raise [NotImplementedError] if this `Binary` is empty

# File lib/erlang/binary.rb, line 325
def last
  raise NotImplementedError if empty?
  return at(-1)
end
marshal_dump() click to toggle source

@return [::String] @private

# File lib/erlang/binary.rb, line 407
def marshal_dump
  return @data
end
marshal_load(data) click to toggle source

@private

# File lib/erlang/binary.rb, line 412
def marshal_load(data)
  initialize(data)
  __send__(:immutable!)
  return self
end
part(position, length) click to toggle source

Returns the section of this `Binary` starting at `position` of `length`.

@param position [Integer] The starting position @param length [Integer] The non-negative length @return [Binary] @raise [ArgumentError] if `position` is not an `Integer` or `length` is not a non-negative `Integer`

# File lib/erlang/binary.rb, line 336
def part(position, length)
  raise ArgumentError, 'position must be an Integer' if not position.is_a?(::Integer)
  raise ArgumentError, 'length must be a non-negative Integer' if not length.is_a?(::Integer) or length < 0
  return Erlang::Binary[@data.byteslice(position, length)]
end
size()
Alias for: bytesize
to_atom() click to toggle source

@return [Atom] the `Atom` version of the `Binary`

# File lib/erlang/binary.rb, line 370
def to_atom
  return Erlang::Atom[@data]
end
to_binary() click to toggle source

@return [self] the `Binary` version of the `Binary`

# File lib/erlang/binary.rb, line 375
def to_binary
  return self
end
to_bitstring(bits = 8) click to toggle source

@param bits [Integer] The number of bits to keep for the last byte @return [Bitstring, self] the `Bitstring` version of the `Binary`

# File lib/erlang/binary.rb, line 381
def to_bitstring(bits = 8)
  if bits == 8
    return self
  else
    return Erlang::Bitstring[@data, bits: bits]
  end
end
to_list() click to toggle source

@return [List] the `List` version of the `Binary`

# File lib/erlang/binary.rb, line 390
def to_list
  return Erlang::List.from_enum(@data.bytes)
end
to_s() click to toggle source

@return [::String] the string version of the `Binary`

# File lib/erlang/binary.rb, line 400
def to_s
  return @data
end
Also aliased as: to_str
to_str()
Alias for: to_s
to_string() click to toggle source

@return [String] the `String` version of the `Binary`

# File lib/erlang/binary.rb, line 395
def to_string
  return Erlang::String[@data]
end