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. Doesn't need to allocate any extra
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.
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)".
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.
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
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'.
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
79 This is for perl 5.8.8 on a Core 2 Duo 2.66GHz machine (unit is 64
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% --
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% --
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% --
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% --
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% --
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% --
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% --
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% --
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% --
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% --
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% --
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% --
148 Please report architectures where we can't use the alignment as the move
149 unit. I'll add exceptions for them.
152 Carp, Exporter (core modules since perl 5), XSLoader (since perl 5.006).
155 Bit::Vector gives a complete reimplementation of bit vectors.
158 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
160 You can contact me by mail or on "irc.perl.org" (vincent).
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.
170 You can find documentation for this module with the perldoc command.
172 perldoc Scalar::Vec::Util
174 Tests code coverage report is available at
175 <http://www.profvince.com/perl/cover/Scalar-Vec-Util>.
178 Copyright 2008-2009 Vincent Pit, all rights reserved.
180 This program is free software; you can redistribute it and/or modify it
181 under the same terms as Perl itself.