view release on metacpan or  search on metacpan

lib/Bit/Vector/String.pod  view on Meta::CPAN

=head1 NAME

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

=head1 SYNOPSIS

  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);

=head1 DESCRIPTION

=over 2

=item *

C<$string = $vector-E<gt>to_Oct();>

Returns an octal string representing the given bit vector.

Note that this method is not particularly efficient, since it
is almost completely realized in Perl, and moreover internally
operates on a Perl list of individual octal digits which it
concatenates into the final string using "C<join('', ...)>".

A benchmark reveals that this method is about 40 times slower
than the method "C<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)

Note that 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.

Also note that the B<LEAST> significant octal digit is
located at the B<RIGHT> end of the resulting string, and
the B<MOST> significant digit at the B<LEFT> end.

Finally, note that this method does B<NOT> prepend any uniquely
identifying format prefix (such as "0o") to the resulting string
(which means that the result of this method only contains valid
octal digits, i.e., [0-7]).

However, this can of course most easily be done as needed,
as follows:

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

=item *

C<$vector-E<gt>from_Oct($string);>

Allows to read in the contents of a bit vector from an octal string,
such as returned by the method "C<to_Oct()>" (see above).

Note that this method is not particularly efficient, since it is
almost completely realized in Perl, and moreover chops the input
string into individual characters using "C<split(//, $string)>".

Remember also that the least significant bits are always to the
right of an octal string, and the most significant bits to the left.
Therefore, the string is actually reversed internally before storing
it in the given bit vector using the method "C<Chunk_List_Store()>",
which expects the least significant chunks of data at the beginning
of a list.

A benchmark reveals that this method is about 40 times slower than
the method "C<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)

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").

Note especially that this method does B<NOT> accept any uniquely
identifying format prefix (such as "0o") in the given string; the
presence of such a prefix will also lead to the fatal "unknown
string type" error.

If the given string contains less octal digits than are needed to
completely fill the given bit vector, the remaining (most significant)
bits all remain cleared (i.e., set to zero).

This also means that, even if the given string does not contain
enough digits to completely fill the given bit vector, the previous
contents of the bit vector are erased completely.

If the given string is longer than it needs to fill the given bit
vector, the superfluous characters are simply ignored.

This behaviour is intentional so that 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.

=item *

C<$vector = Bit::Vector-E<gt>new_Oct($bits,$string);>

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

The method internally first calls the bit vector constructor method
"C<new()>" and then stores the given string in the newly created
bit vector using the same approach as the method "C<from_Oct()>"
(described above).

Note that this approach is not particularly efficient, since it
is almost completely realized in Perl, and moreover chops the input
string into individual characters using "C<split(//, $string)>".

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

Note especially that this method does B<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.

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 "C<$bits>" given has the value "C<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).