README

   1 NAME
   2     Scalar::Vec::Util - Utility routines for vec strings.
   3
   4 VERSION
   5     Version 0.05
   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.
  46
  47   "veq $v1 => $v1_start, $v2 => $v2_start, $length"
  48     Returns true if the $length bits starting at $v1_start in $v1 and
  49     $v2_start in $v2 are equal, and false otherwise. If needed, $length is
  50     decreased to fit inside $v1 and $v2 boundaries.
  51
  52 EXPORT
  53     The functions "vfill", "vcopy" and "veq" are only exported on request.
  54     All of them are exported by the tags ':funcs' and ':all'.
  55
  56     The constants "SVU_PP" and "SVU_SIZE" are also only exported on request.
  57     They are all exported by the tags ':consts' and ':all'.
  58
  59 BENCHMARKS
  60     The following timings were obtained by running the "samples/bench.pl"
  61     script. The "_pp" entries are the pure Perl versions, while "_bv" are
  62     Bit::Vector versions.
  63
  64     This is for perl 5.8.8 on a Core 2 Duo 2.66GHz machine (unit is 64
  65     bits).
  66             Filling bits at a given position :
  67                           Rate vfill_pp vfill_bv    vfill
  68             vfill_pp    80.3/s       --    -100%    -100%
  69             vfill_bv 1053399/s 1312401%       --     -11%
  70             vfill    1180792/s 1471129%      12%       --
  71
  72             Copying bits from a bit vector to a different one :
  73                          Rate vcopy_pp vcopy_bv    vcopy
  74             vcopy_pp    112/s       --    -100%    -100%
  75             vcopy_bv  62599/s   55622%       --     -89%
  76             vcopy    558491/s  497036%     792%       --
  77
  78             Moving bits in the same bit vector from a given position to a different one :
  79                          Rate vmove_pp vmove_bv    vmove
  80             vmove_pp   64.8/s       --    -100%    -100%
  81             vmove_bv  64742/s   99751%       --     -88%
  82             vmove    547980/s  845043%     746%       --
  83
  84             Testing bit equality from different positions of different bit vectors :
  85                        Rate  veq_pp  veq_bv     veq
  86             veq_pp   92.7/s      --   -100%   -100%
  87             veq_bv  32777/s  35241%      --    -94%
  88             veq    505828/s 545300%   1443%      --
  89
  90     This is for perl 5.10.0 on a Pentium 4 3.0GHz (unit is 32 bits).
  91                          Rate vfill_pp vfill_bv    vfill
  92             vfill_pp    185/s       --    -100%    -100%
  93             vfill_bv 407979/s  220068%       --     -16%
  94             vfill    486022/s  262184%      19%       --
  95
  96                          Rate vcopy_pp vcopy_bv    vcopy
  97             vcopy_pp   61.5/s       --    -100%    -100%
  98             vcopy_bv  32548/s   52853%       --     -83%
  99             vcopy    187360/s  304724%     476%       --
 100
 101                          Rate vmove_pp vmove_bv    vmove
 102             vmove_pp   63.1/s       --    -100%    -100%
 103             vmove_bv  32829/s   51933%       --     -83%
 104             vmove    188572/s  298787%     474%       --
 105
 106                        Rate  veq_pp  veq_bv     veq
 107             veq_pp   34.2/s      --   -100%   -100%
 108             veq_bv  17518/s  51190%      --    -91%
 109             veq    192181/s 562591%    997%      --
 110
 111     This is for perl 5.10.0 on an UltraSPARC-IIi (unit is 8 bits).
 112                         Rate vfill_pp    vfill vfill_bv
 113             vfill_pp  4.23/s       --    -100%    -100%
 114             vfill    30039/s  709283%       --     -17%
 115             vfill_bv 36022/s  850568%      20%       --
 116
 117                         Rate vcopy_pp vcopy_bv    vcopy
 118             vcopy_pp  2.74/s       --    -100%    -100%
 119             vcopy_bv  8146/s  297694%       --     -60%
 120             vcopy    20266/s  740740%     149%       --
 121
 122                         Rate vmove_pp vmove_bv    vmove
 123             vmove_pp  2.66/s       --    -100%    -100%
 124             vmove_bv  8274/s  311196%       --     -59%
 125             vmove    20287/s  763190%     145%       --
 126
 127                       Rate  veq_pp  veq_bv     veq
 128             veq_pp  7.33/s      --   -100%   -100%
 129             veq_bv  2499/s  33978%      --    -87%
 130             veq    19675/s 268193%    687%      --
 131
 132 CAVEATS
 133     Please report architectures where we can't use the alignment as the move
 134     unit. I'll add exceptions for them.
 135
 136 DEPENDENCIES
 137     Carp, Exporter (core modules since perl 5), XSLoader (since perl 5.006).
 138
 139 SEE ALSO
 140     Bit::Vector gives a complete reimplementation of bit vectors.
 141
 142 AUTHOR
 143     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 144
 145     You can contact me by mail or on #perl @ FreeNode (vincent or
 146     Prof_Vince).
 147
 148 BUGS
 149     Please report any bugs or feature requests to "bug-scalar-vec-util at
 150     rt.cpan.org", or through the web interface at
 151     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scalar-Vec-Util>. I will
 152     be notified, and then you'll automatically be notified of progress on
 153     your bug as I make changes.
 154
 155 SUPPORT
 156     You can find documentation for this module with the perldoc command.
 157
 158         perldoc Scalar::Vec::Util
 159
 160     Tests code coverage report is available at
 161     <http://www.profvince.com/perl/cover/Scalar-Vec-Util>.
 162
 163 COPYRIGHT & LICENSE
 164     Copyright 2008 Vincent Pit, all rights reserved.
 165
 166     This program is free software; you can redistribute it and/or modify it
 167     under the same terms as Perl itself.
 168