1Bit::Vector::String(3)User Contributed Perl DocumentationBit::Vector::String(3)
2
6 Bit::Vector::String - Generic string import/export for Bit::Vector
7
9 use Bit::Vector::String;
10 to_Oct
12 $string = $vector->to_Oct();
13 from_Oct
15 $vector->from_Oct($string);
16 new_Oct
18 $vector = Bit::Vector->new_Oct($bits,$string);
19 String_Export
21 $string = $vector->String_Export($type);
22 String_Import
24 $type = $vector->String_Import($string);
25 new_String
27 $vector = Bit::Vector->new_String($bits,$string);
28 ($vector,$type) = Bit::Vector->new_String($bits,$string);
29
31 · "$string = $vector->to_Oct();"
32 Returns an octal string representing the given bit vector.
34 Note that this method is not particularly efficient, since it is
36 almost completely realized in Perl, and moreover internally operates
37 on a Perl list of individual octal digits which it concatenates into
38 the final string using ""join('', ...)"".
39 A benchmark reveals that this method is about 40 times slower than
41 the method ""to_Bin()"" (which is realized in C):
42 Benchmark: timing 10000 iterations of to_Bin, to_Hex, to_Oct...
44 to_Bin: 1 wallclock secs ( 1.09 usr + 0.00 sys = 1.09 CPU)
45 to_Hex: 1 wallclock secs ( 0.53 usr + 0.00 sys = 0.53 CPU)
46 to_Oct: 40 wallclock secs (40.16 usr + 0.05 sys = 40.21 CPU)
47 Note that since an octal digit is always worth three bits, the length
49 of the resulting string is always a multiple of three bits, regard‐
50 less of the true length (in bits) of the given bit vector.
51 Also note that the LEAST significant octal digit is located at the
53 RIGHT end of the resulting string, and the MOST significant digit at
54 the LEFT end.
55 Finally, note that this method does NOT prepend any uniquely identi‐
57 fying format prefix (such as "0o") to the resulting string (which
58 means that the result of this method only contains valid octal dig‐
59 its, i.e., [0-7]).
60 However, this can of course most easily be done as needed, as fol‐
62 lows:
63 $string = '0o' . $vector->to_Oct();
65 · "$vector->from_Oct($string);"
67 Allows to read in the contents of a bit vector from an octal string,
69 such as returned by the method ""to_Oct()"" (see above).
70 Note that this method is not particularly efficient, since it is
72 almost completely realized in Perl, and moreover chops the input
73 string into individual characters using ""split(//, $string)"".
74 Remember also that the least significant bits are always to the right
76 of an octal string, and the most significant bits to the left.
77 Therefore, the string is actually reversed internally before storing
78 it in the given bit vector using the method ""Chunk_List_Store()"",
79 which expects the least significant chunks of data at the beginning
80 of a list.
81 A benchmark reveals that this method is about 40 times slower than
83 the method ""from_Bin()"" (which is realized in C):
84 Benchmark: timing 10000 iterations of from_Bin, from_Hex, from_Oct...
86 from_Bin: 1 wallclock secs ( 1.13 usr + 0.00 sys = 1.13 CPU)
87 from_Hex: 1 wallclock secs ( 0.80 usr + 0.00 sys = 0.80 CPU)
88 from_Oct: 46 wallclock secs (44.95 usr + 0.00 sys = 44.95 CPU)
89 If the given string contains any character which is not an octal
91 digit (i.e., [0-7]), a fatal syntax error ensues ("unknown string
92 type").
93 Note especially that this method does NOT accept any uniquely identi‐
95 fying format prefix (such as "0o") in the given string; the presence
96 of such a prefix will also lead to the fatal "unknown string type"
97 error.
98 If the given string contains less octal digits than are needed to
100 completely fill the given bit vector, the remaining (most signifi‐
101 cant) bits all remain cleared (i.e., set to zero).
102 This also means that, even if the given string does not contain
104 enough digits to completely fill the given bit vector, the previous
105 contents of the bit vector are erased completely.
106 If the given string is longer than it needs to fill the given bit
108 vector, the superfluous characters are simply ignored.
109 This behaviour is intentional so that you may read in the string rep‐
111 resenting one bit vector into another bit vector of different size,
112 i.e., as much of it as will fit.
113 · "$vector = Bit::Vector->new_Oct($bits,$string);"
115 This method is an alternative constructor which allows you to create
117 a new bit vector object (with "$bits" bits) and to initialize it all
118 in one go.
119 The method internally first calls the bit vector constructor method
121 ""new()"" and then stores the given string in the newly created bit
122 vector using the same approach as the method ""from_Oct()""
123 (described above).
124 Note that this approach is not particularly efficient, since it is
126 almost completely realized in Perl, and moreover chops the input
127 string into individual characters using ""split(//, $string)"".
128 An exception will be raised if the necessary memory cannot be allo‐
130 cated (see the description of the method ""new()"" in Bit::Vector(3)
131 for possible causes) or if the given string cannot be converted suc‐
132 cessfully (see the description of the method ""from_Oct()"" above for
133 details).
134 Note especially that this method does NOT accept any uniquely identi‐
136 fying format prefix (such as "0o") in the given string and that such
137 a prefix will lead to a fatal "unknown string type" error.
138 In case of an error, the memory occupied by the new bit vector is
140 released again before the exception is actually thrown.
141 If the number of bits "$bits" given has the value ""undef"", the
143 method will automatically allocate a bit vector with a size (i.e.,
144 number of bits) of three times the length of the given string (since
145 every octal digit is worth three bits).
146 Note that this behaviour is different from that of the methods
148 ""new_Hex()"", ""new_Bin()"", ""new_Dec()"" and ""new_Enum()"" (which
149 are realized in C, internally); these methods will silently assume a
150 value of 0 bits if ""undef"" is given (and may warn about the "Use of
151 uninitialized value" if warnings are enabled).
152 · "$string = $vector->String_Export($type);"
154 Returns a string representing the given bit vector in the format
156 specified by "$type":
157 1 ⎪ b ⎪ bin => binary (using "to_Bin()")
159 2 ⎪ o ⎪ oct => octal (using "to_Oct()")
160 3 ⎪ d ⎪ dec => decimal (using "to_Dec()")
161 4 ⎪ h ⎪ hex ⎪ x => hexadecimal (using "to_Hex()")
162 5 ⎪ e ⎪ enum => enumeration (using "to_Enum()")
163 6 ⎪ p ⎪ pack => packed binary (using "Block_Read()")
164 The case (lower/upper/mixed case) of "$type" is ignored.
166 If "$type" is omitted or ""undef"" or false ("0" or the empty
168 string), a hexadecimal string is returned as the default format.
169 If "$type" does not have any of the values described above, a fatal
171 "unknown string type" will occur.
172 Beware that in order to guarantee that the strings can be correctly
174 parsed and read in by the methods ""String_Import()"" and
175 ""new_String()"" (described below), the method ""String_Export()""
176 provides uniquely identifying prefixes (and, in one case, a suffix)
177 as follows:
178 1 ⎪ b ⎪ bin => '0b' . $vector->to_Bin();
180 2 ⎪ o ⎪ oct => '0o' . $vector->to_Oct();
181 3 ⎪ d ⎪ dec => $vector->to_Dec(); # prefix is [+-]
182 4 ⎪ h ⎪ hex ⎪ x => '0x' . $vector->to_Hex();
183 5 ⎪ e ⎪ enum => '{' . $vector->to_Enum() . '}';
184 6 ⎪ p ⎪ pack => ':' . $vector->Size() .
185 ':' . $vector->Block_Read();
186 This is necessary because certain strings can be valid representa‐
188 tions in more than one format.
189 All strings in binary format, i.e., which only contain "0" and "1",
191 are also valid number representations (of a different value, of
192 course) in octal, decimal and hexadecimal.
193 Likewise, a string in octal format is also valid in decimal and hexa‐
195 decimal, and a string in decimal format is also valid in hexadecimal.
196 Moreover, if the enumeration of set bits (as returned by
198 ""to_Enum()"") only contains one element, this element could be mis‐
199 taken for a representation of the entire bit vector (instead of just
200 one bit) in decimal.
201 Beware also that the string returned by format "6" ("packed binary")
203 will in general NOT BE PRINTABLE, because it will usually consist of
204 many unprintable characters!
205 · "$type = $vector->String_Import($string);"
207 Allows to read in the contents of a bit vector from a string which
209 has previously been produced by ""String_Export()"", ""to_Bin()"",
210 ""to_Oct()"", ""to_Dec()"", ""to_Hex()"", ""to_Enum()"",
211 ""Block_Read()"" or manually or by another program.
212 Beware however that the string must have the correct format; other‐
214 wise a fatal "unknown string type" error will occur.
215 The correct format is the one returned by ""String_Export()"" (see
217 immediately above).
218 The method will also try to automatically recognize formats without
220 identifying prefix such as returned by the methods ""to_Bin()"",
221 ""to_Oct()"", ""to_Dec()"", ""to_Hex()"" and ""to_Enum()"".
222 However, as explained above for the method ""String_Export()"", due
224 to the fact that a string may be a valid representation in more than
225 one format, this may lead to unwanted results.
226 The method will try to match the format of the given string in the
228 following order:
229 If the string consists only of [01], it will be considered to be in
231 binary format (although it could be in octal, decimal or hexadecimal
232 format or even be an enumeration with only one element as well).
233 If the string consists only of [0-7], it will be considered to be in
235 octal format (although it could be in decimal or hexadecimal format
236 or even be an enumeration with only one element as well).
237 If the string consists only of [0-9], it will be considered to be in
239 decimal format (although it could be in hexadecimal format or even be
240 an enumeration with only one element as well).
241 If the string consists only of [0-9A-Fa-f], it will be considered to
243 be in hexadecimal format.
244 If the string only contains numbers in decimal format, separated by
246 commas (",") or dashes ("-"), it is considered to be an enumeration
247 (a single decimal number also qualifies).
248 And if the string starts with ":[0-9]:", the remainder of the string
250 is read in with ""Block_Store()"".
251 To avoid misinterpretations, it is therefore recommendable to always
253 either use the method ""String_Export()"" or to provide some uniquely
254 identifying prefix (and suffix, in one case) yourself:
255 binary => '0b' . $string;
257 octal => '0o' . $string;
258 decimal => '+' . $string; # in case "$string"
259 => '-' . $string; # has no sign yet
260 hexadecimal => '0x' . $string;
261 => '0h' . $string;
262 enumeration => '{' . $string . '}';
263 => '[' . $string . ']';
264 => '<' . $string . '>';
265 => '(' . $string . ')';
266 packed binary => ':' . $vector->Size() .
267 ':' . $vector->Block_Read();
268 Note that case (lower/upper/mixed case) is not important and will be
270 ignored by this method.
271 Internally, the method uses the methods ""from_Bin()"",
273 ""from_Oct()"", ""from_Dec()"", ""from_Hex()"", ""from_Enum()"" and
274 ""Block_Store()"" for actually importing the contents of the string
275 into the given bit vector. See their descriptions here in this docu‐
276 ment and in Bit::Vector(3) for any further conditions that must be
277 met and corresponding possible fatal error messages.
278 The method returns the number of the format that has been recognized:
280 1 => binary
282 2 => octal
283 3 => decimal
284 4 => hexadecimal
285 5 => enumeration
286 6 => packed binary
287 · "$vector = Bit::Vector->new_String($bits,$string);"
289 "($vector,$type) = Bit::Vector->new_String($bits,$string);"
291 This method is an alternative constructor which allows you to create
293 a new bit vector object (with "$bits" bits) and to initialize it all
294 in one go.
295 The method internally first calls the bit vector constructor method
297 ""new()"" and then stores the given string in the newly created bit
298 vector using the same approach as the method ""String_Import()""
299 (described immediately above).
300 An exception will be raised if the necessary memory cannot be allo‐
302 cated (see the description of the method ""new()"" in Bit::Vector(3)
303 for possible causes) or if the given string cannot be converted suc‐
304 cessfully (see the description of the method ""String_Import()""
305 above for details).
306 In case of an error, the memory occupied by the new bit vector is
308 released again before the exception is actually thrown.
309 If the number of bits "$bits" given has the value ""undef"", the
311 method will automatically determine this value for you and allocate a
312 bit vector of the calculated size.
313 Note that this behaviour is different from that of the methods
315 ""new_Hex()"", ""new_Bin()"", ""new_Dec()"" and ""new_Enum()"" (which
316 are realized in C, internally); these methods will silently assume a
317 value of 0 bits if ""undef"" is given (and may warn about the "Use of
318 uninitialized value" if warnings are enabled).
319 The necessary number of bits is calculated as follows:
321 binary => length($string);
323 octal => 3 * length($string);
324 decimal => int( length($string) * log(10) / log(2) + 1 );
325 hexadecimal => 4 * length($string);
326 enumeration => maximum of values found in $string + 1
327 packed binary => $string =~ /^:(\d+):/;
328 If called in scalar context, the method returns the newly created bit
330 vector object.
331 If called in list context, the method additionally returns the number
333 of the format which has been recognized, as explained above for the
334 method ""String_Import()"".
335
337 Bit::Vector(3), Bit::Vector::Overload(3).
338
340 This man page documents "Bit::Vector::String" version 6.4.
341
343 Steffen Beyer
344 mailto:sb@engelschall.com
345 http://www.engelschall.com/u/sb/download/
346
348 Copyright (c) 2004 by Steffen Beyer. All rights reserved.
349
351 This package is free software; you can redistribute it and/or modify it
352 under the same terms as Perl itself, i.e., under the terms of the
353 "Artistic License" or the "GNU General Public License".
354 The C library at the core of this Perl module can additionally be
356 redistributed and/or modified under the terms of the "GNU Library Gen‐
357 eral Public License".
358 Please refer to the files "Artistic.txt", "GNU_GPL.txt" and
360 "GNU_LGPL.txt" in this distribution for details!
361
363 This package is distributed in the hope that it will be useful, but
364 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
365 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
366 See the "GNU General Public License" for more details.
368perl v5.8.8 2004-10-03 Bit::Vector::String(3)