Bit::Ve...::String(3)

📦
version 7.400.0 · 13 versions
, in opensuse-leap 16.0

💅 Bit::Vector::String(3) — User Contributed Perl Documentation ✨

okay bestie so this is the manual page for Bit::Vector::String(3), and no cap, it's the glow-up your Bit::Vector was waiting for 🫶

🎀 NAME 🎀

Bit::Vector::String — the generic string import/export module for Bit::Vector. it's giving "i speak every format" energy, periodt 💖

✨ SYNOPSIS ✨

like, here's the whole vibe up front:

use Bit::Vector::String;

to_Oct
    $string = $vector->to_Oct();

from_Oct
    $vector->from_Oct($string);

new_Oct
    $vector = Bit::Vector->new_Oct($bits,$string);

String_Export
    $string = $vector->String_Export($type);

String_Import
    $type = $vector->String_Import($string);

new_String
    $vector = Bit::Vector->new_String($bits,$string);
    ($vector,$type) = Bit::Vector->new_String($bits,$string);

🌸 DESCRIPTION 🌸

💜 $string = $vector->to_Oct();

so this one hands you back an octal string representing the bit vector you gave it. cute, right? 🐙

ngl though, heads up: this method is not particularly efficient — it's almost completely realized in Perl, and on top of that it internally operates on a Perl list of individual octal digits, which it then concatenates into the final string using "join('', ...)". so yeah. it's doing the most 😭

a benchmark reveals that this method is about 40 times slower than the method to_Bin() (which is realized in C):

 Benchmark: timing 10000 iterations of to_Bin, to_Hex, to_Oct...
     to_Bin:  1 wallclock secs ( 1.09 usr +  0.00 sys =  1.09 CPU)
     to_Hex:  1 wallclock secs ( 0.53 usr +  0.00 sys =  0.53 CPU)
     to_Oct: 40 wallclock secs (40.16 usr +  0.05 sys = 40.21 CPU)

forty. whole. seconds. 💀 the C methods ate and left no crumbs, and to_Oct is standing there like 🧍‍♀️

also! since an octal digit is always worth three bits, the length of the resulting string is always a multiple of three bits, regardless of the true length (in bits) of the given bit vector. math is mathing 📐

and the LEAST significant octal digit lives at the RIGHT end of the resulting string, while the MOST significant digit is at the LEFT end. respect the orientation bestie ➡️⬅️

finally (last note i promise 🫶): this method does NOT prepend any uniquely identifying format prefix (such as "0o") to the resulting string — which means the result only contains valid octal digits, i.e., [0-7]. pure, unfiltered octal 💅

but like, adding the prefix yourself is literally the easiest thing ever, whenever you need it:

$string = '0o' . $vector->to_Oct();

slay 🎀

💜 $vector->from_Oct($string);

this one lets you read in the contents of a bit vector from an octal string, like the kind returned by to_Oct() (see right above ⬆️).

heads up again: not particularly efficient. almost completely realized in Perl, and it also chops the input string into individual characters using "split(//, $string)". chef's kiss but make it slow 🙈

remember bestie: the least significant bits are always to the right of an octal string, and the most significant bits to the left. so the string actually gets reversed internally before being stored in the given bit vector — it uses the method Chunk_List_Store() to do it, because that method expects the least significant chunks of data at the beginning of a list. flips it like a pancake 🥞

a benchmark reveals that this method is about 40 times slower than the method from_Bin() (which is realized in C):

 Benchmark: timing 10000 iterations of from_Bin, from_Hex, from_Oct...
   from_Bin:  1 wallclock secs ( 1.13 usr +  0.00 sys =  1.13 CPU)
   from_Hex:  1 wallclock secs ( 0.80 usr +  0.00 sys =  0.80 CPU)
   from_Oct: 46 wallclock secs (44.95 usr +  0.00 sys = 44.95 CPU)

46 seconds. the C girlies are thriving and the Perl path is in the group chat typing "omw" for an hour 😭

⚠️ if the given string contains any character which is not an octal digit (i.e., [0-7]), a fatal syntax error ensues ("unknown string type"). no cap, it just dies.

and note especially 👑: this method does NOT accept any uniquely identifying format prefix (such as "0o") in the given string — the mere presence of such a prefix will also lead to the fatal "unknown string type" error. so don't try to be cute with the prefix here, it will not eat 💀

if the given string contains less octal digits than are needed to completely fill the given bit vector, the remaining (most significant) bits all stay cleared (i.e., set to zero). empty space, zero thoughts 🧚

which also means: even if the given string doesn't contain enough digits to completely fill the given bit vector, the previous contents of the bit vector are erased completely. it's a full reset, not a merge. bye to your old data 👋

if the given string is longer than it needs to be to fill the given bit vector, the superfluous characters are simply ignored. extra vibes, discarded ✂️

this behaviour is intentional — so you may read in the string representing one bit vector into another bit vector of different size, i.e., as much of it as will fit. flexible queen 🌈

💜 $vector = Bit::Vector->new_Oct($bits,$string);

an alternative constructor which lets you create a new bit vector object (with $bits bits) and initialize it all in one go. one-stop shop, iconic ✨

internally it first calls the bit vector constructor method new() and then stores the given string in the newly created bit vector using the same approach as from_Oct() (described above). same energy, new object 🦋

again: not particularly efficient, almost completely realized in Perl, and it chops the input string into individual characters using "split(//, $string)".

an exception will be raised if the necessary memory cannot be allocated (see the description of the method new() in Bit::Vector(3) for possible causes), or if the given string cannot be converted successfully (see the description of from_Oct() above for details). so many ways to fail, so little time 😮‍💨

⚠️ note especially that this method does NOT accept any uniquely identifying format prefix (such as "0o") in the given string, and that such a prefix will lead to a fatal "unknown string type" error. same rule as before, bestie, the prefix is not invited to this party 🙅‍♀️

in case of an error, the memory occupied by the new bit vector is released again before the exception is actually thrown. it cleans up after itself, we love a responsible icon ♻️

if the number of bits $bits has the value "undef", the method will automatically allocate a bit vector with a size (i.e., number of bits) of three times the length of the given string — since every octal digit is worth three bits. built-in math, no calculator needed 🧮

note that this behaviour is different from that of the methods new_Hex(), new_Bin(), new_Dec() and new_Enum() (which are realized in C, internally): those methods will silently assume a value of 0 bits if "undef" is given (and may warn about the "Use of uninitialized value" if warnings are enabled). so yeah, the C girlies play by different rules 🙈

💜 $string = $vector->String_Export($type);

returns a string representing the given bit vector in the format specified by $type:

  1 | b | bin      =>  binary        (using "to_Bin()")
  2 | o | oct      =>  octal         (using "to_Oct()")
  3 | d | dec      =>  decimal       (using "to_Dec()")
  4 | h | hex | x  =>  hexadecimal   (using "to_Hex()")
  5 | e | enum     =>  enumeration   (using "to_Enum()")
  6 | p | pack     =>  packed binary (using "Block_Read()")

the case (lower/upper/mixed case) of $type is ignored. scream it, whisper it, it doesn't matter 💅

if $type is omitted, or "undef", or false (0 or the empty string), a hexadecimal string is returned as the default format. hex is the default main character 👑

if $type doesn't have any of the values described above, a fatal "unknown string type" will occur. boom, roasted 🔥

🚨 beware that in order to guarantee the strings can be correctly parsed and read in by the methods String_Import() and new_String() (described below), String_Export() provides uniquely identifying prefixes (and, in one case, a suffix) as follows:
  1 | b | bin      =>  '0b' . $vector->to_Bin();
  2 | o | oct      =>  '0o' . $vector->to_Oct();
  3 | d | dec      =>         $vector->to_Dec(); # prefix is [+-]
  4 | h | hex | x  =>  '0x' . $vector->to_Hex();
  5 | e | enum     =>  '{'  . $vector->to_Enum() . '}';
  6 | p | pack     =>  ':'  . $vector->Size() .
                       ':'  . $vector->Block_Read();

this is necessary because certain strings can be valid representations in more than one format. ambiguous much? 😳

  • all strings in binary format, i.e., which only contain "0" and "1", are also valid number representations (of a different value, of course) in octal, decimal and hexadecimal.
  • likewise, a string in octal format is also valid in decimal and hexadecimal.
  • and a string in decimal format is also valid in hexadecimal.

moreover, if the enumeration of set bits (as returned by to_Enum()) only contains one element, this element could be mistaken for a representation of the entire bit vector (instead of just one bit) in decimal. one little number out here causing chaos 🫠

🚨 beware also that the string returned by format 6 (packed binary) will in general NOT BE PRINTABLE, because it will usually consist of many unprintable characters! do not paste it into the group chat, it will look like a glitch in the matrix 💀

💜 $type = $vector->String_Import($string);

lets you read in the contents of a bit vector from a string which has previously been produced by String_Export(), to_Bin(), to_Oct(), to_Dec(), to_Hex(), to_Enum(), Block_Read() — or manually, or by another program. flexible like that 🌈

⚠️ beware however that the string must have the correct format; otherwise a fatal "unknown string type" error will occur.

the correct format is the one returned by String_Export() (see immediately above ⬆️).

the method will also try to automatically recognize formats without an identifying prefix, such as those returned by to_Bin(), to_Oct(), to_Dec(), to_Hex() and to_Enum(). detective mode 🔍

but as explained above for String_Export(), due to the fact that a string may be a valid representation in more than one format, this may lead to unwanted results. it's a vibe check that sometimes fails 😬

the method tries to match the format of the given string in this order:

  • if the string consists only of [01], it will be considered to be in binary format (although it could be in octal, decimal or hexadecimal format, or even be an enumeration with only one element as well).
  • if the string consists only of [0-7], it will be considered to be in octal format (although it could be in decimal or hexadecimal format, or even be an enumeration with only one element as well).
  • if the string consists only of [0-9], it will be considered to be in decimal format (although it could be in hexadecimal format, or even be an enumeration with only one element as well).
  • if the string consists only of [0-9A-Fa-f], it will be considered to be in hexadecimal format.
  • if the string only contains numbers in decimal format, separated by commas (,), or dashes (-), it is considered to be an enumeration (a single decimal number also qualifies).
  • and if the string starts with :[0-9]:, the remainder of the string is read in with Block_Store().

so to avoid misinterpretations, it is therefore recommendable to always either use the method String_Export() or to provide some uniquely identifying prefix (and suffix, in one case) yourself:

the exact prefix roster is giving:

binary         =>  '0b' . $string;
octal          =>  '0o' . $string;
decimal        =>  '+'  . $string; # in case "$string"
               =>  '-'  . $string; # has no sign yet
hexadecimal    =>  '0x' . $string;
               =>  '0h' . $string;
enumeration    =>  '{'  . $string . '}';
               =>  '['  . $string . ']';
               =>  '<'  . $string . '>';
               =>  '('  . $string . ')';
packed binary  =>  ':'  . $vector->Size() .
                   ':'  . $vector->Block_Read();

Lowkey the cutest part? Case (lower/upper/mixed case) is literally not important and gets ignored by this method. Periodt. 💅

Internally, the method uses from_Bin(), from_Oct(), from_Dec(), from_Hex(), from_Enum() and Block_Store() for actually importing the contents of the string into the given bit vector. Peep their descriptions here in this document and in Bit::Vector(3) for any further conditions that must be met and corresponding possible fatal error messages. 🫶

The method returns the number of the format that has been recognized:

1    =>    binary
2    =>    octal
3    =>    decimal
4    =>    hexadecimal
5    =>    enumeration
6    =>    packed binary
  • $vector = Bit::Vector->new_String($bits,$string);

($vector,$type) = Bit::Vector->new_String($bits,$string);

This method is an alternative constructor which allows you to create a new bit vector object (with $bits bits) and to initialize it all in one go. ✨

The method internally first calls the bit vector constructor method new() and then stores the given string in the newly created bit vector using the same approach as the method String_Import() (described immediately above). 🎀

An exception will be raised if the necessary memory cannot be allocated (see the description of the method new() in Bit::Vector(3) for possible causes) or if the given string cannot be converted successfully (see the description of the method String_Import() above for details). 😭

In case of an error, the memory occupied by the new bit vector is released again before the exception is actually thrown. 💀

If the number of bits $bits given has the value undef, the method will automatically determine this value for you and allocate a bit vector of the calculated size. 👑

Note that this behaviour is different from that of the methods new_Hex(), new_Bin(), new_Dec() and new_Enum() (which are realized in C, internally); these methods will silently assume a value of 0 bits if undef is given (and may warn about the "Use of uninitialized value" if warnings are enabled).

The necessary number of bits is calculated as follows:

binary         =>       length($string);
octal          =>   3 * length($string);
decimal        =>  int( length($string) * log(10) / log(2) + 1 );
hexadecimal    =>   4 * length($string);
enumeration    =>  maximum of values found in $string + 1
packed binary  =>  $string =~ /^:(\d+):/;

If called in scalar context, the method returns the newly created bit vector object. 🌟

If called in list context, the method additionally returns the number of the format which has been recognized, as explained above for the method String_Import().

🌈 SEE ALSO

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

💖 VERSION

This man page documents Bit::Vector::String version 7.4.

👑 AUTHOR

Steffen Beyer
mailto:STBEY@cpan.org
http://www.engelschall.com/u/sb/download/

Copyright (c) 2004 - 2013 by Steffen Beyer. All rights reserved.

🦋 LICENSE

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, i.e., under the terms of the "Artistic License" or the "GNU General Public License".

The C library at the core of this Perl module can additionally be redistributed and/or modified under the terms of the "GNU Library General Public License".

Please refer to the files Artistic.txt, GNU_GPL.txt and GNU_LGPL.txt in this distribution for details!

🌸 DISCLAIMER

This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the "GNU General Public License" for more details.

that's the whole vibe bestie — source/version is perl v5.42.0, dated 2025-02-06, and it's documenting Bit::Ve...::String(3) 💜 mwah, go import some strings responsibly ✨

📦 where this page comes from