class BitStruct::Vector
A Vector
is, like a BitStruct
, a String. It retains all of the String methods, except for []
, []=
, and each
. These methods operate on entries instead of chars. Other methods, including length and slice, are unchanged. Hence a Vector
can be used directly with sockets, binary files, etc.
Note that Vector
is not a subclass of BitStruct
. It cannot be used in a nest declaration in a BitStruct
. Instead, use the vector declaration. See BitStruct::VectorField
.
Different instances of the same Vector
class may have different lengths, and a single instance can change its length. The length should always be a multiple of the struct size.
Public Class Methods
Get or set the hash of default options for the class, which apply to all fields in the entries. If h
is provided, update the default options with that hash. Default options are inherited.
This is especially useful with the :endian => val
option.
# File lib/bit-struct/vector.rb 63 def default_options h = nil 64 @default_options ||= superclass.default_options.dup 65 if h 66 @default_options.merge! h 67 if @struct_class 68 @struct_class.default_options h 69 end 70 end 71 @default_options 72 end
# File lib/bit-struct/vector.rb 74 def describe(*args) 75 fmt = args[0] || BitStruct.describe_format 76 if block_given? 77 struct_class.describe(*args){|desc| yield desc} 78 yield ["..."]*5 79 else 80 struct_class.describe(*args) + [fmt % (["..."]*5)] 81 end 82 end
# File lib/bit-struct/vector.rb 20 def inherited cl 21 cl.instance_eval do 22 @struct_class = nil 23 end 24 end
arg
can be an integer (number of entries) or a string (binary data, such as another Vector
of the same size).
# File lib/bit-struct/vector.rb 99 def initialize arg # :yields: instance 100 case arg 101 when Integer 102 super(struct_class.initial_value * arg) 103 104 else 105 begin 106 super arg 107 rescue NameError 108 raise ArgumentError, "must be string or integer: #{arg.inspect}" 109 end 110 end 111 112 yield self if block_given? 113 end
Called as a class method with a single argument in a user-defined subclass to specify a particular BitStruct
class to use for each entry, instead of generating an anonymous class. Called without arguments to access the struct class, generating an anonymous one if needed. The struct_class
inherits from the struct_class
of the parent Vector
class.
# File lib/bit-struct/vector.rb 32 def struct_class cl = nil 33 if cl 34 if @struct_class 35 warn "changing struct_class in #{self} to #{cl}" 36 end 37 @struct_class = cl 38 @struct_class.default_options default_options 39 else 40 unless @struct_class 41 @struct_class = self == BitStruct::Vector ? BitStruct : 42 Class.new(superclass.struct_class) 43 @struct_class.default_options default_options 44 end 45 end 46 @struct_class 47 end
Public Instance Methods
Get the i
-th entry. Returns a copy of the entry. If you want to use this copy to modify the entry, you must modify the copy and then use []=
to replace the entry with the copy.
# File lib/bit-struct/vector.rb 118 def [](i) 119 sc = self.class.struct_class 120 entry_length = sc.round_byte_length 121 122 unless (0...(length / entry_length)).include? i 123 raise ArgumentError, "index out of range: #{i}" 124 end 125 126 sc.new slice(entry_length * i, entry_length) 127 end
Set the i
-th entry to val
.
# File lib/bit-struct/vector.rb 132 def []=(i,val) 133 entry_length = struct_class_length 134 135 unless (0...(length / entry_length)).include? i 136 raise ArgumentError, "index out of range: #{i}" 137 end 138 139 unless val.length == entry_length 140 raise ArgumentError, "wrong entry length: #{val.length} != #{entry_length}" 141 end 142 143 _old_replace_substr(entry_length * i, entry_length, val) 144 end
Iterate over entries.
# File lib/bit-struct/vector.rb 149 def each 150 entry_length = struct_class_length 151 (length / entry_length).times do |i| 152 yield self[i] 153 end 154 end
# File lib/bit-struct/vector.rb 172 def inspect_detailed 173 inspect(BitStruct::DETAILED_INSPECT_OPTS) 174 end
# File lib/bit-struct/vector.rb 156 def inspect_with_options(opts = BitStruct::DEFAULT_INSPECT_OPTS) 157 if opts[:include_class] 158 opts = opts.dup 159 opts[:include_class] = false 160 s = self.class.inspect + ": " 161 else 162 s = "" 163 end 164 165 s << entries.map{|entry| entry.inspect(opts)}.join(opts[:separator]) 166 lb, rb = opts[:brackets] 167 [lb, s, rb].join 168 end
Convenience method for instances. Returns the BitStruct
class that describes each entry.
# File lib/bit-struct/vector.rb 87 def struct_class 88 self.class.struct_class 89 end
Convenience method for instances. Returns the string length in bytes of each entry in the vector.
# File lib/bit-struct/vector.rb 93 def struct_class_length 94 self.class.struct_class.round_byte_length 95 end