]> git.vpit.fr Git - perl/modules/Scalar-Vec-Util.git/blobdiff - README
Update VPIT::TestHelpers to e8344578
[perl/modules/Scalar-Vec-Util.git] / README
diff --git a/README b/README
index 69aa06bc0b036be56553a43c7ad6eaeb633381a2..a89b0c71c88228f140804c28ed9c3b19c87bab3a 100644 (file)
--- a/README
+++ b/README
@@ -2,10 +2,10 @@ NAME
     Scalar::Vec::Util - Utility routines for vec strings.
 
 VERSION
     Scalar::Vec::Util - Utility routines for vec strings.
 
 VERSION
-    Version 0.02
+    Version 0.07
 
 SYNOPSIS
 
 SYNOPSIS
-        use Scalar::Vec::Util qw/vfill vcopy veq/;
+        use Scalar::Vec::Util qw<vfill vcopy veq>;
 
         my $s;
         vfill $s, 0, 100, 1; # Fill with 100 bits 1 starting at 0.
 
         my $s;
         vfill $s, 0, 100, 1; # Fill with 100 bits 1 starting at 0.
@@ -42,7 +42,21 @@ FUNCTIONS
   "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
   "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.
+    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
 
   "veq $v1 => $v1_start, $v2 => $v2_start, $length"
     Returns true if the $length bits starting at $v1_start in $v1 and
@@ -50,17 +64,96 @@ FUNCTIONS
     decreased to fit inside $v1 and $v2 boundaries.
 
 EXPORT
     decreased to fit inside $v1 and $v2 boundaries.
 
 EXPORT
-    The functions "vfill", "vcopy" and "veq" are only exported on request.
-    All of them are exported by the tags ':funcs' and ':all'.
+    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'.
 
 
     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
 CAVEATS
     Please report architectures where we can't use the alignment as the move
     unit. I'll add exceptions for them.
 
 DEPENDENCIES
+    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.006).
 
 SEE ALSO
     Carp, Exporter (core modules since perl 5), XSLoader (since perl 5.006).
 
 SEE ALSO
@@ -69,8 +162,7 @@ SEE ALSO
 AUTHOR
     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 
 AUTHOR
     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 
-    You can contact me by mail or on #perl @ FreeNode (vincent or
-    Prof_Vince).
+    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
 
 BUGS
     Please report any bugs or feature requests to "bug-scalar-vec-util at
@@ -88,7 +180,7 @@ SUPPORT
     <http://www.profvince.com/perl/cover/Scalar-Vec-Util>.
 
 COPYRIGHT & LICENSE
     <http://www.profvince.com/perl/cover/Scalar-Vec-Util>.
 
 COPYRIGHT & LICENSE
-    Copyright 2008 Vincent Pit, all rights reserved.
+    Copyright 2008,2009,2010,2011,2012 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.
 
     This program is free software; you can redistribute it and/or modify it
     under the same terms as Perl itself.