NAME
Scalar::Vec::Util - Utility routines for vec strings.
VERSION
Version 0.06
SYNOPSIS
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; # Overalapping areas DWIM.
if (veq $t, 10, $t, 20, 30) { ... } # Yes, they are equal now.
DESCRIPTION
A set of utilities to manipulate bits in vec strings. Highly optimized XS routines are used when available, but straightforward pure perl replacements are also provided for platforms without a C compiler.
This module doesn't reimplement bit vectors. It can be used on the very same scalars that "vec" builds, or actually on any Perl string ("SVt_PV").
CONSTANTS
"SVU_PP"
True when pure perl fallbacks are used instead of XS functions.
"SVU_SIZE"
Size in bits of the unit used for moves. The higher this value is, the
faster the XS functions are. It's usually "CHAR_BIT *
$Config{alignbytes}", except on non-little-endian architectures where it
currently falls back to "CHAR_BIT" (e.g. SPARC).
FUNCTIONS
"vfill $vec, $start, $length, $bit"
Starting at $start in $vec, fills $length bits with $bit. Grows $vec if
necessary.
"vcopy $from => $from_start, $to => $to_start, $length" Copies $length bits starting at $from_start in $from to $to_start in $to. If "$from_start + $length" is too long for $from, zeros are copied past $length. Grows $to if necessary. Doesn't need to allocate any extra memory.
"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. If $insert is defined, also fills the resulting gap with ones if $insert is true and zeros if it's false. Bits outside of the specified area are left untouched. Doesn't need to allocate any extra memory.
"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. Bits
outside of the specified area are left untouched. Currently allocates an
extra buffer of size "O($bits)".
"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. If needed, $length is decreased to fit inside $v1 and $v2 boundaries.
EXPORT
The functions "vfill", "vcopy", "vshift", "vrot" and "veq" are only exported on request. All of them are exported by the tags ':funcs' and ':all'.
The constants "SVU_PP" and "SVU_SIZE" are also only exported on request. They are all exported by the tags ':consts' and ':all'.
BENCHMARKS
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.
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% --
CAVEATS
Please report architectures where we can't use the alignment as the move unit. I'll add exceptions for them.
DEPENDENCIES
Carp, Exporter (core modules since perl 5), XSLoader (since perl 5.006).
SEE ALSO
Bit::Vector gives a complete reimplementation of bit vectors.
AUTHOR
Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
You can contact me by mail or on "irc.perl.org" (vincent).
BUGS
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.
SUPPORT
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 & LICENSE
Copyright 2008-2009 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.