Scalar::Vec::Util - Utility routines for vec strings.
Version 0.08
use Scalar::Vec::Util qw<vfill vcopy veq>; my $s; vfill $s, 0, 100, 1; # Fill with 100 bits 1 starting at 0. my $t; vcopy $s, 20, $t, 10, 30; # Copy 30 bits from $s, starting at 20, # to $t, starting at 10. vcopy $t, 10, $t, 20, 30; # Overlapping areas DWIM. if (veq $t, 10, $t, 20, 30) { ... } # Yes, they are equal now.
This module provides a set of utility routines that efficiently manipulate bits in vec strings. Highly optimized XS functions are used whenever possible, but straightforward pure Perl replacements are also available for platforms without a C compiler.
Note that this module does not aim at reimplementing bit vectors : all its functions can be used on any Perl string, just like "vec" in perlfunc.
SVU_PP
True when pure Perl fallbacks are used instead of XS functions.
SVU_SIZE
The size (in bits) of the unit used for bit operations. The higher this value is, the faster the XS functions are. It is usually CHAR_BIT * $Config{alignbytes}, except on non-little-endian architectures where it currently falls back to CHAR_BIT (e.g. SPARC).
CHAR_BIT * $Config{alignbytes}
CHAR_BIT
vfill
vfill $vec, $start, $length, $bit;
Starting at $start in $vec, fills $length bits with ones if $bit is true and with zeros if $bit is false.
$start
$vec
$length
$bit
$vec is upgraded to a string and extended if necessary. Bits that are outside of the specified area are left untouched.
vcopy
vcopy $from => $from_start, $to => $to_start, $length;
Copies $length bits starting at $from_start in $from to $to_start in $to.
$from_start
$from
$to_start
$to
$from and $to are allowed to be the same scalar, and the given areas can rightfully overlap.
$from is upgraded to a string if it isn't one already. If $from_start + $length goes out of the bounds of $from, then the extra bits are treated as zeros. $to is upgraded to a string and extended if necessary. The content of $from is not modified, except when it is equal to $to. Bits that are outside of the specified area are left untouched.
$from_start + $length
This function does not need to allocate any extra memory.
vshift
vshift $v, $start, $length => $bits, $insert;
In the area starting at $start and of length $length in $v, shift bits abs $bits positions left if $bits > 0 and right otherwise.
$v
abs $bits
$bits > 0
When $insert is defined, the resulting gap is also filled with ones if $insert is true and with zeros if $insert is false.
$insert
$v is upgraded to a string if it isn't one already. If $start + $length goes out of the bounds of $v, then the extra bits are treated as zeros. Bits that are outside of the specified area are left untouched.
$start + $length
vrot
vrot $v, $start, $length, $bits;
In the area starting at $start and of length $length in $v, rotates bits abs $bits positions left if $bits > 0 and right otherwise.
This function currently allocates an extra buffer of size O($bits).
O($bits)
veq
veq $v1 => $v1_start, $v2 => $v2_start, $length;
Returns true if the $length bits starting at $v1_start in $v1 and $v2_start in $v2 are equal, and false otherwise.
$v1_start
$v1
$v2_start
$v2
$v1 and $v2 are upgraded to strings if they aren't already, but their contents are never modified. If $v1_start + $length (respectively $v2_start + $length) goes out of the bounds of $v1 (respectively $v2), then the extra bits are treated as zeros.
$v1_start + $length
$v2_start + $length
The functions "vfill", "vcopy", "vshift", "vrot" and "veq" are only exported on request. All of them are exported by the tags ':funcs' and ':all'.
':funcs'
':all'
The constants "SVU_PP" and "SVU_SIZE" are also only exported on request. They are all exported by the tags ':consts' and ':all'.
':consts'
The following timings were obtained by running the samples/bench.pl script. The _pp entries are the pure Perl versions, whereas _bv are Bit::Vector versions.
samples/bench.pl
_pp
_bv
This is for perl 5.8.8 on a Core 2 Duo 2.66GHz machine (unit is 64 bits).
Filling bits at a given position : Rate vfill_pp vfill_bv vfill vfill_pp 80.3/s -- -100% -100% vfill_bv 1053399/s 1312401% -- -11% vfill 1180792/s 1471129% 12% -- Copying bits from a bit vector to a different one : Rate vcopy_pp vcopy_bv vcopy vcopy_pp 112/s -- -100% -100% vcopy_bv 62599/s 55622% -- -89% vcopy 558491/s 497036% 792% -- Moving bits in the same bit vector from a given position to a different one : Rate vmove_pp vmove_bv vmove vmove_pp 64.8/s -- -100% -100% vmove_bv 64742/s 99751% -- -88% vmove 547980/s 845043% 746% -- Testing bit equality from different positions of different bit vectors : Rate veq_pp veq_bv veq veq_pp 92.7/s -- -100% -100% veq_bv 32777/s 35241% -- -94% veq 505828/s 545300% 1443% --
This is for perl 5.10.0 on a Pentium 4 3.0GHz (unit is 32 bits).
Rate vfill_pp vfill_bv vfill vfill_pp 185/s -- -100% -100% vfill_bv 407979/s 220068% -- -16% vfill 486022/s 262184% 19% -- Rate vcopy_pp vcopy_bv vcopy vcopy_pp 61.5/s -- -100% -100% vcopy_bv 32548/s 52853% -- -83% vcopy 187360/s 304724% 476% -- Rate vmove_pp vmove_bv vmove vmove_pp 63.1/s -- -100% -100% vmove_bv 32829/s 51933% -- -83% vmove 188572/s 298787% 474% -- Rate veq_pp veq_bv veq veq_pp 34.2/s -- -100% -100% veq_bv 17518/s 51190% -- -91% veq 192181/s 562591% 997% --
This is for perl 5.10.0 on an UltraSPARC-IIi (unit is 8 bits).
Rate vfill_pp vfill vfill_bv vfill_pp 4.23/s -- -100% -100% vfill 30039/s 709283% -- -17% vfill_bv 36022/s 850568% 20% -- Rate vcopy_pp vcopy_bv vcopy vcopy_pp 2.74/s -- -100% -100% vcopy_bv 8146/s 297694% -- -60% vcopy 20266/s 740740% 149% -- Rate vmove_pp vmove_bv vmove vmove_pp 2.66/s -- -100% -100% vmove_bv 8274/s 311196% -- -59% vmove 20287/s 763190% 145% -- Rate veq_pp veq_bv veq veq_pp 7.33/s -- -100% -100% veq_bv 2499/s 33978% -- -87% veq 19675/s 268193% 687% --
Please report architectures where we can't use the alignment as the move unit. I'll add exceptions for them.
perl 5.6.
A C compiler. This module may happen to build with a C++ compiler as well, but don't rely on it, as no guarantee is made in this regard.
Carp, Exporter (core modules since perl 5), XSLoader (since perl 5.6.0).
Bit::Vector gives a complete reimplementation of bit vectors.
Vincent Pit, <perl at profvince.com>, http://www.profvince.com.
<perl at profvince.com>
You can contact me by mail or on irc.perl.org (vincent).
irc.perl.org
Please report any bugs or feature requests to bug-scalar-vec-util at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scalar-Vec-Util. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-scalar-vec-util at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Scalar::Vec::Util
Tests code coverage report is available at http://www.profvince.com/perl/cover/Scalar-Vec-Util.
Copyright 2008,2009,2010,2011,2012,2013 Vincent Pit, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Scalar::Vec::Util, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Scalar::Vec::Util
CPAN shell
perl -MCPAN -e shell install Scalar::Vec::Util
For more information on module installation, please visit the detailed CPAN module installation guide.