Class: BinData::Array
- Includes:
- DSLMixin, Enumerable
- Defined in:
- lib/bindata/array.rb
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 => lambda { index == 1 })
obj.read(data) #=> [3, 4]
obj = BinData::Array.new(:type => :int8,
:read_until => lambda { element >= 6 })
obj.read(data) #=> [3, 4, 5, 6]
obj = BinData::Array.new(:type => :int8,
:read_until => lambda { 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
Class Method Summary collapse
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
Methods inherited from Base
#==, #=~, arg_extractor, bindata_name, #clear, #debug_name, #eval_parameter, #get_parameter, #has_parameter?, #initialize_with_warning, #inspect, #lazy_evaluator, #new, #num_bytes, #offset, #pretty_print, #read, read, register_subclasses, #rel_offset, #safe_respond_to?, #to_binary_s, #to_s, unregister_self, #write
Methods included from AcceptedParametersPlugin
#accepted_parameters, #default_parameters, #mandatory_parameters, #mutually_exclusive_parameters, #optional_parameters
Methods included from RegisterNamePlugin
Methods included from CheckOrAdjustOffsetPlugin
Methods included from Framework
Class Method Details
.sanitize_parameters!(params) ⇒ Object
:nodoc:
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 |
# File 'lib/bindata/array.rb', line 62 def sanitize_parameters!(params) #:nodoc: unless params.has_parameter?(:initial_length) or params.has_parameter?(:read_until) # ensure one of :initial_length and :read_until exists params[:initial_length] = 0 end params.warn_replacement_parameter(:read_length, :initial_length) params.merge!(dsl_params) if params.needs_sanitizing?(:type) el_type, el_params = params[:type] params[:type] = params.create_sanitized_object_prototype(el_type, el_params) end end |
Instance Method Details
#[](arg1, arg2 = nil) ⇒ Object Also known as: slice
Returns the element at index
.
146 147 148 149 150 151 152 153 154 155 156 157 |
# File 'lib/bindata/array.rb', line 146 def [](arg1, arg2 = nil) if arg1.respond_to?(:to_int) and arg2.nil? slice_index(arg1.to_int) elsif arg1.respond_to?(:to_int) and arg2.respond_to?(:to_int) slice_start_length(arg1.to_int, arg2.to_int) elsif arg1.is_a?(Range) and 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
.
181 182 183 184 |
# File 'lib/bindata/array.rb', line 181 def []=(index, value) extend_array(index) elements[index].assign(value) end |
#assign(array) ⇒ Object
101 102 103 104 105 |
# File 'lib/bindata/array.rb', line 101 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.
176 177 178 |
# File 'lib/bindata/array.rb', line 176 def at(index) elements[index] end |
#clear? ⇒ Boolean
97 98 99 |
# File 'lib/bindata/array.rb', line 97 def clear? @element_list.nil? or elements.all? { |el| el.clear? } end |
#concat(array) ⇒ Object
134 135 136 137 |
# File 'lib/bindata/array.rb', line 134 def concat(array) insert(-1, *array.to_ary) self end |
#debug_name_of(child) ⇒ Object
:nodoc:
230 231 232 233 |
# File 'lib/bindata/array.rb', line 230 def debug_name_of(child) #:nodoc: index = find_index_of(child) "#{debug_name}[#{index}]" end |
#do_num_bytes ⇒ Object
:nodoc:
246 247 248 |
# File 'lib/bindata/array.rb', line 246 def do_num_bytes #:nodoc: sum_num_bytes_for_all_elements end |
#do_write(io) ⇒ Object
:nodoc:
242 243 244 |
# File 'lib/bindata/array.rb', line 242 def do_write(io) #:nodoc: elements.each { |el| el.do_write(io) } end |
#each ⇒ Object
226 227 228 |
# File 'lib/bindata/array.rb', line 226 def each elements.each { |el| yield el } end |
#empty? ⇒ Boolean
217 218 219 |
# File 'lib/bindata/array.rb', line 217 def empty? length.zero? end |
#find_index(obj) ⇒ Object Also known as: index
111 112 113 |
# File 'lib/bindata/array.rb', line 111 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.
119 120 121 |
# File 'lib/bindata/array.rb', line 119 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.
189 190 191 192 193 194 195 196 197 198 |
# File 'lib/bindata/array.rb', line 189 def first(n = nil) if n.nil? and empty? # explicitly return nil as arrays grow automatically nil elsif n.nil? self[0] else self[0, n] end end |
#initialize_instance ⇒ Object
93 94 95 |
# File 'lib/bindata/array.rb', line 93 def initialize_instance @element_list = nil end |
#initialize_shared_instance ⇒ Object
80 81 82 83 84 85 86 87 88 89 90 91 |
# File 'lib/bindata/array.rb', line 80 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
139 140 141 142 143 |
# File 'lib/bindata/array.rb', line 139 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.
203 204 205 206 207 208 209 210 |
# File 'lib/bindata/array.rb', line 203 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
212 213 214 |
# File 'lib/bindata/array.rb', line 212 def length elements.length end |
#offset_of(child) ⇒ Object
:nodoc:
235 236 237 238 239 240 |
# File 'lib/bindata/array.rb', line 235 def offset_of(child) #:nodoc: index = find_index_of(child) sum = sum_num_bytes_below_index(index) child.do_num_bytes.is_a?(Integer) ? sum.ceil : sum.floor end |
#push(*args) ⇒ Object Also known as: <<
123 124 125 126 |
# File 'lib/bindata/array.rb', line 123 def push(*args) insert(-1, *args) self end |
#snapshot ⇒ Object
107 108 109 |
# File 'lib/bindata/array.rb', line 107 def snapshot elements.collect { |el| el.snapshot } end |
#to_ary ⇒ Object
Allow this object to be used in array context.
222 223 224 |
# File 'lib/bindata/array.rb', line 222 def to_ary collect { |el| el } end |
#unshift(*args) ⇒ Object
129 130 131 132 |
# File 'lib/bindata/array.rb', line 129 def unshift(*args) insert(0, *args) self end |