README

   1 NAME
   2     Scalar::Vec::Util - Utility routines for vec strings.
   3
   4 VERSION
   5     Version 0.06
   6
   7 SYNOPSIS
   8         use Scalar::Vec::Util qw/vfill vcopy veq/;
   9
  10         my $s;
  11         vfill $s, 0, 100, 1; # Fill with 100 bits 1 starting at 0.
  12         my $t;
  13         vcopy $s, 20, $t, 10, 30; # Copy 30 bits from $s, starting at 20,
  14                                   #                to $t, starting at 10.
  15         vcopy $t, 10, $t, 20, 30; # Overalapping areas DWIM.
  16         if (veq $t, 10, $t, 20, 30) { ... } # Yes, they are equal now.
  17
  18 DESCRIPTION
  19     A set of utilities to manipulate bits in vec strings. Highly optimized
  20     XS routines are used when available, but straightforward pure perl
  21     replacements are also provided for platforms without a C compiler.
  22
  23     This module doesn't reimplement bit vectors. It can be used on the very
  24     same scalars that "vec" builds, or actually on any Perl string
  25     ("SVt_PV").
  26
  27 CONSTANTS
  28   "SVU_PP"
  29     True when pure perl fallbacks are used instead of XS functions.
  30
  31   "SVU_SIZE"
  32     Size in bits of the unit used for moves. The higher this value is, the
  33     faster the XS functions are. It's usually "CHAR_BIT *
  34     $Config{alignbytes}", except on non-little-endian architectures where it
  35     currently falls back to "CHAR_BIT" (e.g. SPARC).
  36
  37 FUNCTIONS
  38   "vfill $vec, $start, $length, $bit"
  39     Starting at $start in $vec, fills $length bits with $bit. Grows $vec if
  40     necessary.
  41
  42   "vcopy $from => $from_start, $to => $to_start, $length"
  43     Copies $length bits starting at $from_start in $from to $to_start in
  44     $to. If "$from_start + $length" is too long for $from, zeros are copied
  45     past $length. Grows $to if necessary. Doesn't need to allocate any extra
  46     memory.
  47
  48   "vshift $v, $start, $length => $bits [, $insert ]"
  49     In the area starting at $start and of length $length in $v, shift bits
  50     "abs $bits" positions left if "$bits > 0" and right otherwise. If
  51     $insert is defined, also fills the resulting gap with ones if $insert is
  52     true and zeros if it's false. Bits outside of the specified area are
  53     left untouched. Doesn't need to allocate any extra memory.
  54
  55   "vrot $v, $start, $length, $bits"
  56     In the area starting at $start and of length $length in $v, rotates bits
  57     "abs $bits" positions left if "$bits > 0" and right otherwise. Bits
  58     outside of the specified area are left untouched. Currently allocates an
  59     extra buffer of size "O($bits)".
  60
  61   "veq $v1 => $v1_start, $v2 => $v2_start, $length"
  62     Returns true if the $length bits starting at $v1_start in $v1 and
  63     $v2_start in $v2 are equal, and false otherwise. If needed, $length is
  64     decreased to fit inside $v1 and $v2 boundaries.
  65
  66 EXPORT
  67     The functions "vfill", "vcopy", "vshift", "vrot" and "veq" are only
  68     exported on request. All of them are exported by the tags ':funcs' and
  69     ':all'.
  70
  71     The constants "SVU_PP" and "SVU_SIZE" are also only exported on request.
  72     They are all exported by the tags ':consts' and ':all'.
  73
  74 BENCHMARKS
  75     The following timings were obtained by running the "samples/bench.pl"
  76     script. The "_pp" entries are the pure Perl versions, whereas "_bv" are
  77     Bit::Vector versions.
  78
  79     This is for perl 5.8.8 on a Core 2 Duo 2.66GHz machine (unit is 64
  80     bits).
  81             Filling bits at a given position :
  82                           Rate vfill_pp vfill_bv    vfill
  83             vfill_pp    80.3/s       --    -100%    -100%
  84             vfill_bv 1053399/s 1312401%       --     -11%
  85             vfill    1180792/s 1471129%      12%       --
  86
  87             Copying bits from a bit vector to a different one :
  88                          Rate vcopy_pp vcopy_bv    vcopy
  89             vcopy_pp    112/s       --    -100%    -100%
  90             vcopy_bv  62599/s   55622%       --     -89%
  91             vcopy    558491/s  497036%     792%       --
  92
  93             Moving bits in the same bit vector from a given position to a different one :
  94                          Rate vmove_pp vmove_bv    vmove
  95             vmove_pp   64.8/s       --    -100%    -100%
  96             vmove_bv  64742/s   99751%       --     -88%
  97             vmove    547980/s  845043%     746%       --
  98
  99             Testing bit equality from different positions of different bit vectors :
 100                        Rate  veq_pp  veq_bv     veq
 101             veq_pp   92.7/s      --   -100%   -100%
 102             veq_bv  32777/s  35241%      --    -94%
 103             veq    505828/s 545300%   1443%      --
 104
 105     This is for perl 5.10.0 on a Pentium 4 3.0GHz (unit is 32 bits).
 106                          Rate vfill_pp vfill_bv    vfill
 107             vfill_pp    185/s       --    -100%    -100%
 108             vfill_bv 407979/s  220068%       --     -16%
 109             vfill    486022/s  262184%      19%       --
 110
 111                          Rate vcopy_pp vcopy_bv    vcopy
 112             vcopy_pp   61.5/s       --    -100%    -100%
 113             vcopy_bv  32548/s   52853%       --     -83%
 114             vcopy    187360/s  304724%     476%       --
 115
 116                          Rate vmove_pp vmove_bv    vmove
 117             vmove_pp   63.1/s       --    -100%    -100%
 118             vmove_bv  32829/s   51933%       --     -83%
 119             vmove    188572/s  298787%     474%       --
 120
 121                        Rate  veq_pp  veq_bv     veq
 122             veq_pp   34.2/s      --   -100%   -100%
 123             veq_bv  17518/s  51190%      --    -91%
 124             veq    192181/s 562591%    997%      --
 125
 126     This is for perl 5.10.0 on an UltraSPARC-IIi (unit is 8 bits).
 127                         Rate vfill_pp    vfill vfill_bv
 128             vfill_pp  4.23/s       --    -100%    -100%
 129             vfill    30039/s  709283%       --     -17%
 130             vfill_bv 36022/s  850568%      20%       --
 131
 132                         Rate vcopy_pp vcopy_bv    vcopy
 133             vcopy_pp  2.74/s       --    -100%    -100%
 134             vcopy_bv  8146/s  297694%       --     -60%
 135             vcopy    20266/s  740740%     149%       --
 136
 137                         Rate vmove_pp vmove_bv    vmove
 138             vmove_pp  2.66/s       --    -100%    -100%
 139             vmove_bv  8274/s  311196%       --     -59%
 140             vmove    20287/s  763190%     145%       --
 141
 142                       Rate  veq_pp  veq_bv     veq
 143             veq_pp  7.33/s      --   -100%   -100%
 144             veq_bv  2499/s  33978%      --    -87%
 145             veq    19675/s 268193%    687%      --
 146
 147 CAVEATS
 148     Please report architectures where we can't use the alignment as the move
 149     unit. I'll add exceptions for them.
 150
 151 DEPENDENCIES
 152     Carp, Exporter (core modules since perl 5), XSLoader (since perl 5.006).
 153
 154 SEE ALSO
 155     Bit::Vector gives a complete reimplementation of bit vectors.
 156
 157 AUTHOR
 158     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 159
 160     You can contact me by mail or on "irc.perl.org" (vincent).
 161
 162 BUGS
 163     Please report any bugs or feature requests to "bug-scalar-vec-util at
 164     rt.cpan.org", or through the web interface at
 165     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scalar-Vec-Util>. I will
 166     be notified, and then you'll automatically be notified of progress on
 167     your bug as I make changes.
 168
 169 SUPPORT
 170     You can find documentation for this module with the perldoc command.
 171
 172         perldoc Scalar::Vec::Util
 173
 174     Tests code coverage report is available at
 175     <http://www.profvince.com/perl/cover/Scalar-Vec-Util>.
 176
 177 COPYRIGHT & LICENSE
 178     Copyright 2008-2009 Vincent Pit, all rights reserved.
 179
 180     This program is free software; you can redistribute it and/or modify it
 181     under the same terms as Perl itself.
 182