CommonOperations

Navigation

• Table of Contents
• Prev (Compound Types)
  • Instantiation
  • Reading and writing
  • Manipulating
  • Inspecting
• Next (Advanced Topics)

---

Common Operations

There are operations common to all BinData types, including user defined ones. These are summarised here.

Instantiation

::new(parameters)

Creates a BinData object.

obj = BinData::Array.new(type: :int8, initial_length: 6)

::new(value)

Creates a BinData object with an initial assigned value.

obj = BinData::Stringz.new("hello")

This is equivalent to

obj = BinData::Stringz.new
obj.assign("hello")

::new(value, parameters)

Short cut to instantiate and assign a value in one step

obj = BinData::Array.new([1, 2, 3], type: :int8)

This is equivalent to

obj = BinData::Array.new(type: :int8)
obj.assign([1, 2, 3])

Reading and writing

::read(io)

Creates a BinData object and reads its value from the given string or IO. The newly created object is returned.

obj = BinData::Int8.read("\xff")
obj.snapshot #=> -1

#read(io)

Reads and assigns binary data read from io.

  obj = BinData::Stringz.new
  obj.read("string 1\0string 2\0")
  obj #=> "string 1"

#write(io)

Writes the binary data representation of the object to io.

File.open("...", "wb") do |io|
  obj = BinData::Uint64be.new(568290145640170)
  obj.write(io)
end

#to_binary_s

Returns the binary data representation of this object as a string.

obj = BinData::Uint16be.new(4660)
obj.to_binary_s #=> "\022\064"

#to_hex

Returns the binary data representation of this object as an ascii hexadecimal string.

obj = BinData::Uint16be.new(4660)
obj.to_hex #=> "1234"

Manipulating

#assign(value)

Assigns the given value to this object. value can be of the same format as produced by #snapshot, or it can be a compatible data object.

arr = BinData::Array.new(type: :uint8)
arr.assign([1, 2, 3, 4])
arr.snapshot #=> [1, 2, 3, 4]

#clear

Resets this object to its initial state.

obj = BinData::Int32be.new(initial_value: 42)
obj.assign(50)
obj.clear
obj #=> 42

#clear?

Returns whether this object is in its initial state.

arr = BinData::Array.new(type: :uint16be, initial_length: 5)
arr[3] = 42
arr.clear? #=> false

arr[3].clear
arr.clear? #=> true

Inspecting

#num_bytes

Returns the number of bytes required for the binary data representation of this object.

arr = BinData::Array.new(type: :uint16be, initial_length: 5)
arr[0].num_bytes #=> 2
arr.num_bytes #=> 10

#snapshot

Returns the value of this object as primitive Ruby objects (numerics, strings, arrays and hashs). The output of #snapshot may be useful for serialization or as a reduced memory usage representation.

obj = BinData::Uint8.new(2)
obj.class #=> BinData::Uint8
obj + 3 #=> 5

obj.snapshot #=> 2
obj.snapshot.class #=> Fixnum

#rel_offset

Returns the offset of this object with respect to the parent structure it is contained within.

class Tuple < BinData::Record
  string :name, length: 10
  int8 :a
  int8 :b
end

t = Tuple.new
t.b.rel_offset #=> 11

#abs_offset

Returns the offset of this object with respect to the most distant ancestor structure it is contained within. This is most likely to be used with arrays and records. Compare this to #rel_offset.

class Tuple < BinData::Record
  int8 :a
  int8 :b
end

class MyRecord < BinData::Record
  tuple :t1
  tuple :t2
end

obj = MyRecord.new
obj.t2.b.abs_offset #=> 3
obj.t2.b.rel_offset #=> 1

#inspect

Returns a human readable representation of this object. This is a shortcut to #snapshot.inspect.

---

• Prev (Compound Types)
• Next (Advanced Topics)