1Bit::Vector::String(3)User Contributed Perl DocumentationBit::Vector::String(3)
2
3
4

NAME

6       Bit::Vector::String - Generic string import/export for Bit::Vector
7

SYNOPSIS

9         use Bit::Vector::String;
10
11         to_Oct
12             $string = $vector->to_Oct();
13
14         from_Oct
15             $vector->from_Oct($string);
16
17         new_Oct
18             $vector = Bit::Vector->new_Oct($bits,$string);
19
20         String_Export
21             $string = $vector->String_Export($type);
22
23         String_Import
24             $type = $vector->String_Import($string);
25
26         new_String
27             $vector = Bit::Vector->new_String($bits,$string);
28             ($vector,$type) = Bit::Vector->new_String($bits,$string);
29

DESCRIPTION

31       · "$string = $vector->to_Oct();"
32
33         Returns an octal string representing the given bit vector.
34
35         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
40         A benchmark reveals that this method is about 40 times slower than
41         the method ""to_Bin()"" (which is realized in C):
42
43          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
48         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
52         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
56         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
61         However, this can of course most easily be done as needed, as
62         follows:
63
64           $string = '0o' . $vector->to_Oct();
65
66       · "$vector->from_Oct($string);"
67
68         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
71         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
75         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
82         A benchmark reveals that this method is about 40 times slower than
83         the method ""from_Bin()"" (which is realized in C):
84
85          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
90         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
94         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
99         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
103         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
107         If the given string is longer than it needs to fill the given bit
108         vector, the superfluous characters are simply ignored.
109
110         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
114       · "$vector = Bit::Vector->new_Oct($bits,$string);"
115
116         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
120         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
125         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
129         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
135         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
139         In case of an error, the memory occupied by the new bit vector is
140         released again before the exception is actually thrown.
141
142         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
147         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
153       · "$string = $vector->String_Export($type);"
154
155         Returns a string representing the given bit vector in the format
156         specified by "$type":
157
158           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
165         The case (lower/upper/mixed case) of "$type" is ignored.
166
167         If "$type" is omitted or ""undef"" or false ("0" or the empty
168         string), a hexadecimal string is returned as the default format.
169
170         If "$type" does not have any of the values described above, a fatal
171         "unknown string type" will occur.
172
173         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
179           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
187         This is necessary because certain strings can be valid
188         representations in more than one format.
189
190         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
194         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
198         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
203         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
207       · "$type = $vector->String_Import($string);"
208
209         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
214         Beware however that the string must have the correct format;
215         otherwise a fatal "unknown string type" error will occur.
216
217         The correct format is the one returned by ""String_Export()"" (see
218         immediately above).
219
220         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
224         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
228         The method will try to match the format of the given string in the
229         following order:
230
231         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
235         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
239         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
243         If the string consists only of [0-9A-Fa-f], it will be considered to
244         be in hexadecimal format.
245
246         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
250         And if the string starts with ":[0-9]:", the remainder of the string
251         is read in with ""Block_Store()"".
252
253         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
257           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
270         Note that case (lower/upper/mixed case) is not important and will be
271         ignored by this method.
272
273         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
280         The method returns the number of the format that has been recognized:
281
282                         1    =>    binary
283                         2    =>    octal
284                         3    =>    decimal
285                         4    =>    hexadecimal
286                         5    =>    enumeration
287                         6    =>    packed binary
288
289       · "$vector = Bit::Vector->new_String($bits,$string);"
290
291         "($vector,$type) = Bit::Vector->new_String($bits,$string);"
292
293         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
297         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
302         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
308         In case of an error, the memory occupied by the new bit vector is
309         released again before the exception is actually thrown.
310
311         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
315         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
321         The necessary number of bits is calculated as follows:
322
323           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
330         If called in scalar context, the method returns the newly created bit
331         vector object.
332
333         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

SEE ALSO

338       Bit::Vector(3), Bit::Vector::Overload(3).
339

VERSION

341       This man page documents "Bit::Vector::String" version 7.3.
342

AUTHOR

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

LICENSE

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
356       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
360       Please refer to the files "Artistic.txt", "GNU_GPL.txt" and
361       "GNU_LGPL.txt" in this distribution for details!
362

DISCLAIMER

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
368       See the "GNU General Public License" for more details.
369
370
371
372perl v5.16.3                      2013-06-01            Bit::Vector::String(3)
Impressum