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,
50 regardless 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
57 identifying format prefix (such as "0o") to the resulting string
58 (which means that the result of this method only contains valid octal
59 digits, i.e., [0-7]).
60 However, this can of course most easily be done as needed, as
62 follows:
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
95 identifying format prefix (such as "0o") in the given string; the
96 presence of such a prefix will also lead to the fatal "unknown string
97 type" error.
98 If the given string contains less octal digits than are needed to
100 completely fill the given bit vector, the remaining (most
101 significant) 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
111 representing one bit vector into another bit vector of different
112 size, 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
130 allocated (see the description of the method ""new()"" in
131 Bit::Vector(3) for possible causes) or if the given string cannot be
132 converted successfully (see the description of the method
133 ""from_Oct()"" above for details).
134 Note especially that this method does NOT accept any uniquely
136 identifying format prefix (such as "0o") in the given string and that
137 such 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
188 representations 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
195 hexadecimal, and a string in decimal format is also valid in
196 hexadecimal.
197 Moreover, if the enumeration of set bits (as returned by
199 ""to_Enum()"") only contains one element, this element could be
200 mistaken for a representation of the entire bit vector (instead of
201 just one bit) in decimal.
202 Beware also that the string returned by format "6" ("packed binary")
204 will in general NOT BE PRINTABLE, because it will usually consist of
205 many unprintable characters!
206 · "$type = $vector->String_Import($string);"
208 Allows to read in the contents of a bit vector from a string which
210 has previously been produced by ""String_Export()"", ""to_Bin()"",
211 ""to_Oct()"", ""to_Dec()"", ""to_Hex()"", ""to_Enum()"",
212 ""Block_Read()"" or manually or by another program.
213 Beware however that the string must have the correct format;
215 otherwise a fatal "unknown string type" error will occur.
216 The correct format is the one returned by ""String_Export()"" (see
218 immediately above).
219 The method will also try to automatically recognize formats without
221 identifying prefix such as returned by the methods ""to_Bin()"",
222 ""to_Oct()"", ""to_Dec()"", ""to_Hex()"" and ""to_Enum()"".
223 However, as explained above for the method ""String_Export()"", due
225 to the fact that a string may be a valid representation in more than
226 one format, this may lead to unwanted results.
227 The method will try to match the format of the given string in the
229 following order:
230 If the string consists only of [01], it will be considered to be in
232 binary format (although it could be in octal, decimal or hexadecimal
233 format or even be an enumeration with only one element as well).
234 If the string consists only of [0-7], it will be considered to be in
236 octal format (although it could be in decimal or hexadecimal format
237 or even be an enumeration with only one element as well).
238 If the string consists only of [0-9], it will be considered to be in
240 decimal format (although it could be in hexadecimal format or even be
241 an enumeration with only one element as well).
242 If the string consists only of [0-9A-Fa-f], it will be considered to
244 be in hexadecimal format.
245 If the string only contains numbers in decimal format, separated by
247 commas (",") or dashes ("-"), it is considered to be an enumeration
248 (a single decimal number also qualifies).
249 And if the string starts with ":[0-9]:", the remainder of the string
251 is read in with ""Block_Store()"".
252 To avoid misinterpretations, it is therefore recommendable to always
254 either use the method ""String_Export()"" or to provide some uniquely
255 identifying prefix (and suffix, in one case) yourself:
256 binary => '0b' . $string;
258 octal => '0o' . $string;
259 decimal => '+' . $string; # in case "$string"
260 => '-' . $string; # has no sign yet
261 hexadecimal => '0x' . $string;
262 => '0h' . $string;
263 enumeration => '{' . $string . '}';
264 => '[' . $string . ']';
265 => '<' . $string . '>';
266 => '(' . $string . ')';
267 packed binary => ':' . $vector->Size() .
268 ':' . $vector->Block_Read();
269 Note that case (lower/upper/mixed case) is not important and will be
271 ignored by this method.
272 Internally, the method uses the methods ""from_Bin()"",
274 ""from_Oct()"", ""from_Dec()"", ""from_Hex()"", ""from_Enum()"" and
275 ""Block_Store()"" for actually importing the contents of the string
276 into the given bit vector. See their descriptions here in this
277 document and in Bit::Vector(3) for any further conditions that must
278 be met and corresponding possible fatal error messages.
279 The method returns the number of the format that has been recognized:
281 1 => binary
283 2 => octal
284 3 => decimal
285 4 => hexadecimal
286 5 => enumeration
287 6 => packed binary
288 · "$vector = Bit::Vector->new_String($bits,$string);"
290 "($vector,$type) = Bit::Vector->new_String($bits,$string);"
292 This method is an alternative constructor which allows you to create
294 a new bit vector object (with "$bits" bits) and to initialize it all
295 in one go.
296 The method internally first calls the bit vector constructor method
298 ""new()"" and then stores the given string in the newly created bit
299 vector using the same approach as the method ""String_Import()""
300 (described immediately above).
301 An exception will be raised if the necessary memory cannot be
303 allocated (see the description of the method ""new()"" in
304 Bit::Vector(3) for possible causes) or if the given string cannot be
305 converted successfully (see the description of the method
306 ""String_Import()"" above for details).
307 In case of an error, the memory occupied by the new bit vector is
309 released again before the exception is actually thrown.
310 If the number of bits "$bits" given has the value ""undef"", the
312 method will automatically determine this value for you and allocate a
313 bit vector of the calculated size.
314 Note that this behaviour is different from that of the methods
316 ""new_Hex()"", ""new_Bin()"", ""new_Dec()"" and ""new_Enum()"" (which
317 are realized in C, internally); these methods will silently assume a
318 value of 0 bits if ""undef"" is given (and may warn about the "Use of
319 uninitialized value" if warnings are enabled).
320 The necessary number of bits is calculated as follows:
322 binary => length($string);
324 octal => 3 * length($string);
325 decimal => int( length($string) * log(10) / log(2) + 1 );
326 hexadecimal => 4 * length($string);
327 enumeration => maximum of values found in $string + 1
328 packed binary => $string =~ /^:(\d+):/;
329 If called in scalar context, the method returns the newly created bit
331 vector object.
332 If called in list context, the method additionally returns the number
334 of the format which has been recognized, as explained above for the
335 method ""String_Import()"".
336
338 Bit::Vector(3), Bit::Vector::Overload(3).
339
341 This man page documents "Bit::Vector::String" version 7.4.
342
344 Steffen Beyer
345 mailto:STBEY@cpan.org
346 http://www.engelschall.com/u/sb/download/
347
349 Copyright (c) 2004 - 2013 by Steffen Beyer. All rights reserved.
350
352 This package is free software; you can redistribute it and/or modify it
353 under the same terms as Perl itself, i.e., under the terms of the
354 "Artistic License" or the "GNU General Public License".
355 The C library at the core of this Perl module can additionally be
357 redistributed and/or modified under the terms of the "GNU Library
358 General Public License".
359 Please refer to the files "Artistic.txt", "GNU_GPL.txt" and
361 "GNU_LGPL.txt" in this distribution for details!
362
364 This package is distributed in the hope that it will be useful, but
365 WITHOUT ANY WARRANTY; without even the implied warranty of
366 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
367 See the "GNU General Public License" for more details.
369perl v5.30.1 2020-02-10 Bit::Vector::String(3)