Class: Erlang::Binary

Inherits:
Object
  • Object
show all
Defined in:
lib/erlang/binary.rb

Overview

A Binary is a series of bytes.

Creating Binaries

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#bits ⇒ ::Integer (readonly)

Return the bits for this Erlang::Binary

Returns:

  • (::Integer) 


20
21
22
 
# File 'lib/erlang/binary.rb', line 20

def bits
  return 8
end

#data ⇒ ::String (readonly)

Return the data for this Erlang::Binary

Returns:

  • (::String) 


15
16
17
 
# File 'lib/erlang/binary.rb', line 15

def data
  @data
end

Class Method Details

.[](*data) ⇒ Binary

Create a new Binary populated with the given data.

Parameters:

  • data (::String, Symbol, ::Enumerable, Integer) —

    The content of the Binary

Returns:

Raises:

  • (ArgumentError) —

    if data cannot be coerced to be a ::String



29
30
31
 
# File 'lib/erlang/binary.rb', line 29

def [](*data)
  return Erlang.iolist_to_binary(data)
end

.compare(a, b) ⇒ -1, ...

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

Parameters:

  • a (Binary) —

    The left argument

  • b (Binary) —

    The right argument

Returns:

  • (-1, 0, 1)

Raises:

  • (ArgumentError) —

    if a or b is not a Binary



48
49
50
 
# File 'lib/erlang/binary.rb', line 48

def compare(a, b)
  return Erlang::Bitstring.compare(a, b)
end

.concat(*iodata) ⇒ Binary, Bitstring

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

Examples:

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

Parameters:

Returns:



60
61
62
 
# 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) ⇒ Integer

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

Parameters:

  • subject (::String, Binary) —

    The string to decode

  • endianness (:big, :little) (defaults to: :big) —

    The endianness of the subject

Returns:

  • (Integer)

Raises:

  • (ArgumentError) —

    if subject is not a string or endianness is not :big or :little



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# 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 ⇒ Binary

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

Returns:



37
38
39
 
# File 'lib/erlang/binary.rb', line 37

def empty
  return @empty ||= self.new
end

.encode_unsigned(unsigned, endianness = :big) ⇒ ::String

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

Parameters:

  • subject (Integer) —

    The unsigned integer to encode

  • endianness (:big, :little) (defaults to: :big) —

    The endianness of the subject

Returns:

  • (::String)

Raises:

  • (ArgumentError) —

    if subject is not an integer or endianness is not :big or :little



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# 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

Instance Method Details

#at(position) ⇒ Integer Also known as: []

Returns the byte at the provided position.

Parameters:

  • position (Integer) —

    The position of the byte

Returns:

  • (Integer)

Raises:

  • (ArgumentError) —

    if position is not an Integer



133
134
135
136
 
# 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

#bitsize ⇒ Integer

Returns the number of bits in this Binary.

Returns:

  • (Integer) —

    the number of bits in this Binary



140
141
142
 
# File 'lib/erlang/binary.rb', line 140

def bitsize
  return (bytesize * bits)
end

#bitslice(index) ⇒ Integer? #bitslice(index, length) ⇒ Bitstring, Binary #bitslice(index..end) ⇒ Bitstring, Binary

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

Overloads:

  • #bitslice(index) ⇒ Integer?

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

    Examples:

    b = Erlang::Binary[1]
b.bitslice(0)  # => 0
b.bitslice(7)  # => 1
b.bitslice(-1) # => 1
b.bitslice(8)  # => nil

    Parameters:

    • index (Integer) —

      The index to retrieve. May be negative.

    Returns:

    • (Integer, nil)
  • #bitslice(index, length) ⇒ Bitstring, Binary

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

    Examples:

    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

    Parameters:

    • start (Integer) —

      The index to start retrieving bits from. May be negative.

    • length (Integer) —

      The number of bits to retrieve.

    Returns:

  • #bitslice(index..end) ⇒ Bitstring, Binary

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

    Examples:

    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

    Parameters:

    • range (Range) —

      The range of bits to retrieve.

    Returns:

See Also:



187
188
189
 
# File 'lib/erlang/binary.rb', line 187

def bitslice(*args)
  return Erlang::Bitstring.new(@data, 8).bitslice(*args)
end

#bytesize ⇒ Integer Also known as: size

Returns the number of bytes in this Binary.

Returns:

  • (Integer) —

    the number of bytes in this Binary



192
193
194
 
# File 'lib/erlang/binary.rb', line 192

def bytesize
  return @data.bytesize
end

#concat(*other) ⇒ Binary, Bitstring Also known as: +

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

Examples:

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

Parameters:

Returns:



205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# 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

#copy(n = 1) ⇒ Binary

Returns a new Binary containing n copies of itself. n must be greater than or equal to 0.

Parameters:

  • n (Integer) (defaults to: 1) —

    The number of copies

Returns:

Raises:

  • (ArgumentError) —

    if n is less than 0



225
226
227
228
229
 
# 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) ⇒ Integer

Returns an unsigned Integer which is the endianness based version of this Binary.

Parameters:

  • endianness (:big, :little) (defaults to: :big) —

    The endianness of this Binary

Returns:

  • (Integer)

See Also:



235
236
237
 
# File 'lib/erlang/binary.rb', line 235

def decode_unsigned(endianness = :big)
  return Erlang::Binary.decode_unsigned(@data, endianness)
end

#each_bit {|Integer| ... } ⇒ self

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.

Yields:

  • (Integer)

Returns:

  • (self) 


245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
 
# 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) {|Binary, Bitstring| ... } ⇒ self, Enumerator

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.

Examples:

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

Yields:

Returns:

  • (self, Enumerator)

See Also:



272
273
274
275
276
277
 
# 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 {|Integer| ... } ⇒ self

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.

Yields:

  • (Integer)

Returns:

  • (self) 


285
286
287
288
289
 
# 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? ⇒ Boolean

Returns true if this Binary is empty.

Returns:

  • (Boolean) 


294
295
296
 
# File 'lib/erlang/binary.rb', line 294

def empty?
  return @data.empty?
end

#eql?(other) ⇒ Boolean Also known as: ==

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

Parameters:

  • other (Object) —

    The object to compare with

Returns:

  • (Boolean) 


302
303
304
305
306
307
308
309
310
311
 
# 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

#erlang_inspect(raw = false) ⇒ ::String

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

Examples:

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>>"

Returns:

  • (::String) 


352
353
354
355
356
357
358
359
360
361
362
 
# 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 ⇒ Integer

Returns the first byte of this Binary.

Returns:

  • (Integer)

Raises:

  • (NotImplementedError) —

    if this Binary is empty



317
318
319
320
 
# File 'lib/erlang/binary.rb', line 317

def first
  raise NotImplementedError if empty?
  return at(0)
end

#inspect ⇒ ::String

Returns the nicely formatted version of the Binary.

Returns:

  • (::String) —

    the nicely formatted version of the Binary



365
366
367
 
# File 'lib/erlang/binary.rb', line 365

def inspect
  return @data.inspect
end

#last ⇒ Integer

Returns the last byte of this Binary.

Returns:

  • (Integer)

Raises:

  • (NotImplementedError) —

    if this Binary is empty



325
326
327
328
 
# File 'lib/erlang/binary.rb', line 325

def last
  raise NotImplementedError if empty?
  return at(-1)
end

#part(position, length) ⇒ Binary

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

Parameters:

  • position (Integer) —

    The starting position

  • length (Integer) —

    The non-negative length

Returns:

Raises:

  • (ArgumentError) —

    if position is not an Integer or length is not a non-negative Integer



336
337
338
339
340
 
# 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

#to_atom ⇒ Atom

Returns the Atom version of the Binary.

Returns:

  • (Atom) —

    the Atom version of the Binary



370
371
372
 
# File 'lib/erlang/binary.rb', line 370

def to_atom
  return Erlang::Atom[@data]
end

#to_binary ⇒ self

Returns the Binary version of the Binary.

Returns:

  • (self) —

    the Binary version of the Binary



375
376
377
 
# File 'lib/erlang/binary.rb', line 375

def to_binary
  return self
end

#to_bitstring(bits = 8) ⇒ Bitstring, self

Returns the Bitstring version of the Binary.

Parameters:

  • bits (Integer) (defaults to: 8) —

    The number of bits to keep for the last byte

Returns:

  • (Bitstring, self) —

    the Bitstring version of the Binary



381
382
383
384
385
386
387
 
# 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 ⇒ List

Returns the List version of the Binary.

Returns:

  • (List) —

    the List version of the Binary



390
391
392
 
# File 'lib/erlang/binary.rb', line 390

def to_list
  return Erlang::List.from_enum(@data.bytes)
end

#to_s ⇒ ::String Also known as: to_str

Returns the string version of the Binary.

Returns:

  • (::String) —

    the string version of the Binary



400
401
402
 
# File 'lib/erlang/binary.rb', line 400

def to_s
  return @data
end

#to_string ⇒ String

Returns the String version of the Binary.

Returns:

  • (String) —

    the String version of the Binary



395
396
397
 
# File 'lib/erlang/binary.rb', line 395

def to_string
  return Erlang::String[@data]
end