2 Scalar::Vec::Util - Utility routines for vec strings.
8 use Scalar::Vec::Util qw/vfill vcopy veq/;
11 vfill $s, 0, 100, 1; # Fill with 100 bits 1 starting at 0.
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.
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.
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
29 True when pure perl fallbacks are used instead of XS functions.
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).
38 "vfill $vec, $start, $length, $bit"
39 Starting at $start in $vec, fills $length bits with $bit. Grows $vec if
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.
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.
53 The functions "vfill", "vcopy" and "veq" are only exported on request.
54 All of them are exported by the tags ':funcs' and ':all'.
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'.
60 The following timings were obtained by running the "samples/bench.pl"
61 script with perl 5.8.8 on a Core 2 Duo 2.66GHz machine. The "_pp"
62 entries are the pure Perl versions, while "_bv" are Bit::Vector
65 Filling bits at a given position :
66 Rate vfill_pp vfill_bv vfill
67 vfill_pp 80.3/s -- -100% -100%
68 vfill_bv 1053399/s 1312401% -- -11%
69 vfill 1180792/s 1471129% 12% --
71 Copying bits from a bit vector to a different one :
72 Rate vcopy_pp vcopy_bv vcopy
73 vcopy_pp 112/s -- -100% -100%
74 vcopy_bv 62599/s 55622% -- -89%
75 vcopy 558491/s 497036% 792% --
77 Moving bits in the same bit vector from a given position to a different
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% --
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% --
91 Please report architectures where we can't use the alignment as the move
92 unit. I'll add exceptions for them.
95 Carp, Exporter (core modules since perl 5), XSLoader (since perl 5.006).
98 Bit::Vector gives a complete reimplementation of bit vectors.
101 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
103 You can contact me by mail or on #perl @ FreeNode (vincent or
107 Please report any bugs or feature requests to "bug-scalar-vec-util at
108 rt.cpan.org", or through the web interface at
109 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scalar-Vec-Util>. I will
110 be notified, and then you'll automatically be notified of progress on
111 your bug as I make changes.
114 You can find documentation for this module with the perldoc command.
116 perldoc Scalar::Vec::Util
118 Tests code coverage report is available at
119 <http://www.profvince.com/perl/cover/Scalar-Vec-Util>.
122 Copyright 2008 Vincent Pit, all rights reserved.
124 This program is free software; you can redistribute it and/or modify it
125 under the same terms as Perl itself.