Class: BinData::Array
Overview
An Array is a list of data objects of the same type.
require 'bindata'
data = "\x03\x04\x05\x06\x07\x08\x09"
obj = BinData::Array.new(type: :int8, initial_length: 6)
obj.read(data) #=> [3, 4, 5, 6, 7, 8]
obj = BinData::Array.new(type: :int8,
read_until: -> { index == 1 })
obj.read(data) #=> [3, 4]
obj = BinData::Array.new(type: :int8,
read_until: -> { element >= 6 })
obj.read(data) #=> [3, 4, 5, 6]
obj = BinData::Array.new(type: :int8,
read_until: -> { array[index] + array[index - 1] == 13 })
obj.read(data) #=> [3, 4, 5, 6, 7]
obj = BinData::Array.new(type: :int8, read_until: :eof)
obj.read(data) #=> [3, 4, 5, 6, 7, 8, 9]
Parameters
Parameters may be provided at initialisation to control the behaviour of an object. These params are:
:type
-
The symbol representing the data type of the array elements. If the type is to have params passed to it, then it should be provided as
[type_symbol, hash_params]
. :initial_length
-
The initial length of the array.
:read_until
-
While reading, elements are read until this condition is true. This is typically used to read an array until a sentinel value is found. The variables
index
,element
andarray
are made available to any lambda assigned to this parameter. If the value of this parameter is the symbol :eof, then the array will read as much data from the stream as possible.
Each data object in an array has the variable index
made available to any lambda evaluated as a parameter of that data object.
Instance Attribute Summary
Attributes inherited from Base
Instance Method Summary collapse
-
#[](arg1, arg2 = nil) ⇒ Object
(also: #slice)
Returns the element at
index
. -
#[]=(index, value) ⇒ Object
Sets the element at
index
. - #assign(array) ⇒ Object
-
#at(index) ⇒ Object
Returns the element at
index
. - #clear? ⇒ Boolean
- #concat(array) ⇒ Object
-
#debug_name_of(child) ⇒ Object
:nodoc:.
-
#do_num_bytes ⇒ Object
:nodoc:.
-
#do_write(io) ⇒ Object
:nodoc:.
- #each ⇒ Object
- #empty? ⇒ Boolean
- #find_index(obj) ⇒ Object (also: #index)
-
#find_index_of(obj) ⇒ Object
Returns the first index of
obj
in self. -
#first(n = nil) ⇒ Object
Returns the first element, or the first
n
elements, of the array. - #initialize_instance ⇒ Object
- #initialize_shared_instance ⇒ Object
- #insert(index, *objs) ⇒ Object
-
#last(n = nil) ⇒ Object
Returns the last element, or the last
n
elements, of the array. - #length ⇒ Object (also: #size)
-
#offset_of(child) ⇒ Object
:nodoc:.
- #push(*args) ⇒ Object (also: #<<)
- #snapshot ⇒ Object
-
#to_ary ⇒ Object
Allow this object to be used in array context.
- #unshift(*args) ⇒ Object
Methods included from DSLMixin
dsl_parser, method_missing, to_str
Methods inherited from Base
#==, #=~, #abs_offset, arg_processor, auto_call_delayed_io, bindata_name, #clear, #debug_name, #eval_parameter, #get_parameter, #has_parameter?, #initialize_with_warning, #inspect, #lazy_evaluator, #new, #num_bytes, #pretty_print, #read, read, register_subclasses, #rel_offset, #safe_respond_to?, #to_binary_s, #to_hex, #to_s, unregister_self, #write
Methods included from AcceptedParametersPlugin
#accepted_parameters, #default_parameters, #mandatory_parameters, #mutually_exclusive_parameters, #optional_parameters
Methods included from CheckOrAdjustOffsetPlugin
Methods included from RegisterNamePlugin
Methods included from Framework
Instance Method Details
#[](arg1, arg2 = nil) ⇒ Object Also known as: slice
Returns the element at index
.
127 128 129 130 131 132 133 134 135 136 137 138 |
# File 'lib/bindata/array.rb', line 127 def [](arg1, arg2 = nil) if arg1.respond_to?(:to_int) && arg2.nil? slice_index(arg1.to_int) elsif arg1.respond_to?(:to_int) && arg2.respond_to?(:to_int) slice_start_length(arg1.to_int, arg2.to_int) elsif arg1.is_a?(Range) && arg2.nil? slice_range(arg1) else raise TypeError, "can't convert #{arg1} into Integer" unless arg1.respond_to?(:to_int) raise TypeError, "can't convert #{arg2} into Integer" unless arg2.respond_to?(:to_int) end end |
#[]=(index, value) ⇒ Object
Sets the element at index
.
162 163 164 165 |
# File 'lib/bindata/array.rb', line 162 def []=(index, value) extend_array(index) elements[index].assign(value) end |
#assign(array) ⇒ Object
82 83 84 85 86 |
# File 'lib/bindata/array.rb', line 82 def assign(array) raise ArgumentError, "can't set a nil value for #{debug_name}" if array.nil? @element_list = to_storage_formats(array.to_ary) end |
#at(index) ⇒ Object
Returns the element at index
. Unlike slice
, if index
is out of range the array will not be automatically extended.
157 158 159 |
# File 'lib/bindata/array.rb', line 157 def at(index) elements[index] end |
#clear? ⇒ Boolean
78 79 80 |
# File 'lib/bindata/array.rb', line 78 def clear? @element_list.nil? || elements.all?(&:clear?) end |
#concat(array) ⇒ Object
115 116 117 118 |
# File 'lib/bindata/array.rb', line 115 def concat(array) insert(-1, *array.to_ary) self end |
#debug_name_of(child) ⇒ Object
:nodoc:
211 212 213 214 |
# File 'lib/bindata/array.rb', line 211 def debug_name_of(child) #:nodoc: index = find_index_of(child) "#{debug_name}[#{index}]" end |
#do_num_bytes ⇒ Object
:nodoc:
227 228 229 |
# File 'lib/bindata/array.rb', line 227 def do_num_bytes #:nodoc: sum_num_bytes_for_all_elements end |
#do_write(io) ⇒ Object
:nodoc:
223 224 225 |
# File 'lib/bindata/array.rb', line 223 def do_write(io) #:nodoc: elements.each { |el| el.do_write(io) } end |
#each ⇒ Object
207 208 209 |
# File 'lib/bindata/array.rb', line 207 def each elements.each { |el| yield el } end |
#empty? ⇒ Boolean
198 199 200 |
# File 'lib/bindata/array.rb', line 198 def empty? length.zero? end |
#find_index(obj) ⇒ Object Also known as: index
92 93 94 |
# File 'lib/bindata/array.rb', line 92 def find_index(obj) elements.index(obj) end |
#find_index_of(obj) ⇒ Object
Returns the first index of obj
in self.
Uses equal? for the comparator.
100 101 102 |
# File 'lib/bindata/array.rb', line 100 def find_index_of(obj) elements.index { |el| el.equal?(obj) } end |
#first(n = nil) ⇒ Object
Returns the first element, or the first n
elements, of the array. If the array is empty, the first form returns nil, and the second form returns an empty array.
170 171 172 173 174 175 176 177 178 179 |
# File 'lib/bindata/array.rb', line 170 def first(n = nil) if n.nil? && empty? # explicitly return nil as arrays grow automatically nil elsif n.nil? self[0] else self[0, n] end end |
#initialize_instance ⇒ Object
74 75 76 |
# File 'lib/bindata/array.rb', line 74 def initialize_instance @element_list = nil end |
#initialize_shared_instance ⇒ Object
61 62 63 64 65 66 67 68 69 70 71 72 |
# File 'lib/bindata/array.rb', line 61 def initialize_shared_instance @element_prototype = get_parameter(:type) if get_parameter(:read_until) == :eof extend ReadUntilEOFPlugin elsif has_parameter?(:read_until) extend ReadUntilPlugin elsif has_parameter?(:initial_length) extend InitialLengthPlugin end super end |
#insert(index, *objs) ⇒ Object
120 121 122 123 124 |
# File 'lib/bindata/array.rb', line 120 def insert(index, *objs) extend_array(index - 1) elements.insert(index, *to_storage_formats(objs)) self end |
#last(n = nil) ⇒ Object
Returns the last element, or the last n
elements, of the array. If the array is empty, the first form returns nil, and the second form returns an empty array.
184 185 186 187 188 189 190 191 |
# File 'lib/bindata/array.rb', line 184 def last(n = nil) if n.nil? self[-1] else n = length if n > length self[-n, n] end end |
#length ⇒ Object Also known as: size
193 194 195 |
# File 'lib/bindata/array.rb', line 193 def length elements.length end |
#offset_of(child) ⇒ Object
:nodoc:
216 217 218 219 220 221 |
# File 'lib/bindata/array.rb', line 216 def offset_of(child) #:nodoc: index = find_index_of(child) sum = sum_num_bytes_below_index(index) child.bit_aligned? ? sum.floor : sum.ceil end |
#push(*args) ⇒ Object Also known as: <<
104 105 106 107 |
# File 'lib/bindata/array.rb', line 104 def push(*args) insert(-1, *args) self end |
#snapshot ⇒ Object
88 89 90 |
# File 'lib/bindata/array.rb', line 88 def snapshot elements.collect(&:snapshot) end |
#to_ary ⇒ Object
Allow this object to be used in array context.
203 204 205 |
# File 'lib/bindata/array.rb', line 203 def to_ary collect { |el| el } end |
#unshift(*args) ⇒ Object
110 111 112 113 |
# File 'lib/bindata/array.rb', line 110 def unshift(*args) insert(0, *args) self end |