1 package Scalar::Vec::Util;
10 Scalar::Vec::Util - Utility routines for vec strings.
23 XSLoader::load(__PACKAGE__, $VERSION);
36 use Scalar::Vec::Util qw/vfill vcopy veq/;
39 vfill $s, 0, 100, 1; # Fill with 100 bits 1 starting at 0.
41 vcopy $s, 20, $t, 10, 30; # Copy 30 bits from $s, starting at 20,
42 # to $t, starting at 10.
43 vcopy $t, 10, $t, 20, 30; # Overalapping areas DWIM.
44 if (veq $t, 10, $t, 20, 30) { ... } # Yes, they are equal now.
48 A set of utilities to manipulate bits in vec strings. Highly optimized XS routines are used when available, but straightforward pure perl replacements are also provided for platforms without a C compiler.
50 This module doesn't reimplement bit vectors. It can be used on the very same scalars that C<vec> builds, or actually on any Perl string (C<SVt_PV>).
56 True when pure perl fallbacks are used instead of XS functions.
60 Size in bits of the unit used for moves. The higher this value is, the faster the XS functions are. It's usually C<CHAR_BIT * $Config{alignbytes}>, except on non-little-endian architectures where it currently falls back to C<CHAR_BIT> (e.g. SPARC).
64 =head2 C<vfill $vec, $start, $length, $bit>
66 Starting at C<$start> in C<$vec>, fills C<$length> bits with C<$bit>. Grows C<$vec> if necessary.
71 for (@_) { return 0 unless defined }
76 (undef, my $s, my $l, my $x) = @_;
77 croak "Invalid argument" unless _alldef @_;
80 vec($_[0], $_, 1) = $x for $s .. $s + $l - 1;
83 =head2 C<< vcopy $from => $from_start, $to => $to_start, $length >>
85 Copies C<$length> bits starting at C<$from_start> in C<$from> to C<$to_start> in C<$to>. If C<$from_start + $length> is too long for C<$from>, zeros are copied past C<$length>. Grows C<$to> if necessary.
90 my ($fs, $ts, $l) = @_[1, 3, 4];
91 croak "Invalid argument" unless _alldef @_;
95 vec($_[2], $_ + $step, 1) = vec($_[0], $_, 1) for $fs .. $fs + $l - 1;
96 } else { # There's a risk of overwriting if $_[0] and $_[2] are the same SV.
97 vec($_[2], $_ + $step, 1) = vec($_[0], $_, 1) for reverse $fs .. $fs + $l - 1;
101 =head2 C<< veq $v1 => $v1_start, $v2 => $v2_start, $length >>
103 Returns true if the C<$length> bits starting at C<$v1_start> in C<$v1> and C<$v2_start> in C<$v2> are equal, and false otherwise. If needed, C<$length> is decreased to fit inside C<$v1> and C<$v2> boundaries.
108 my ($s1, $s2, $l) = @_[1, 3, 4];
109 croak "Invalid argument" unless _alldef @_;
112 return 0 if vec($_[0], $s1 + $i, 1) != vec($_[2], $s2 + $i, 1);
120 The functions L</vfill>, L</vcopy> and L</veq> are only exported on request. All of them are exported by the tags C<':funcs'> and C<':all'>.
122 The constants L</SVU_PP> and L</SVU_SIZE> are also only exported on request. They are all exported by the tags C<':consts'> and C<':all'>.
126 use base qw/Exporter/;
130 'funcs' => [ qw/vfill vcopy veq/ ],
131 'consts' => [ qw/SVU_PP SVU_SIZE/ ]
133 our @EXPORT_OK = map { @$_ } values %EXPORT_TAGS;
134 $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
138 The following timings were obtained by running the C<samples/bench.pl> script. The C<_pp> entries are the pure Perl versions, while C<_bv> are L<Bit::Vector> versions.
142 =item This is for perl 5.8.8 on a Core 2 Duo 2.66GHz machine (unit is 64 bits).
144 Filling bits at a given position :
145 Rate vfill_pp vfill_bv vfill
146 vfill_pp 80.3/s -- -100% -100%
147 vfill_bv 1053399/s 1312401% -- -11%
148 vfill 1180792/s 1471129% 12% --
150 Copying bits from a bit vector to a different one :
151 Rate vcopy_pp vcopy_bv vcopy
152 vcopy_pp 112/s -- -100% -100%
153 vcopy_bv 62599/s 55622% -- -89%
154 vcopy 558491/s 497036% 792% --
156 Moving bits in the same bit vector from a given position to a different one :
157 Rate vmove_pp vmove_bv vmove
158 vmove_pp 64.8/s -- -100% -100%
159 vmove_bv 64742/s 99751% -- -88%
160 vmove 547980/s 845043% 746% --
162 Testing bit equality from different positions of different bit vectors :
163 Rate veq_pp veq_bv veq
164 veq_pp 92.7/s -- -100% -100%
165 veq_bv 32777/s 35241% -- -94%
166 veq 505828/s 545300% 1443% --
168 =item This is for perl 5.10.0 on a Pentium 4 3.0GHz (unit is 32 bits).
170 Rate vfill_pp vfill_bv vfill
171 vfill_pp 185/s -- -100% -100%
172 vfill_bv 407979/s 220068% -- -16%
173 vfill 486022/s 262184% 19% --
175 Rate vcopy_pp vcopy_bv vcopy
176 vcopy_pp 61.5/s -- -100% -100%
177 vcopy_bv 32548/s 52853% -- -83%
178 vcopy 187360/s 304724% 476% --
180 Rate vmove_pp vmove_bv vmove
181 vmove_pp 63.1/s -- -100% -100%
182 vmove_bv 32829/s 51933% -- -83%
183 vmove 188572/s 298787% 474% --
185 Rate veq_pp veq_bv veq
186 veq_pp 34.2/s -- -100% -100%
187 veq_bv 17518/s 51190% -- -91%
188 veq 192181/s 562591% 997% --
190 =item This is for perl 5.10.0 on an UltraSPARC-IIi (unit is 8 bits).
192 Rate vfill_pp vfill vfill_bv
193 vfill_pp 4.23/s -- -100% -100%
194 vfill 30039/s 709283% -- -17%
195 vfill_bv 36022/s 850568% 20% --
197 Rate vcopy_pp vcopy_bv vcopy
198 vcopy_pp 2.74/s -- -100% -100%
199 vcopy_bv 8146/s 297694% -- -60%
200 vcopy 20266/s 740740% 149% --
202 Rate vmove_pp vmove_bv vmove
203 vmove_pp 2.66/s -- -100% -100%
204 vmove_bv 8274/s 311196% -- -59%
205 vmove 20287/s 763190% 145% --
207 Rate veq_pp veq_bv veq
208 veq_pp 7.33/s -- -100% -100%
209 veq_bv 2499/s 33978% -- -87%
210 veq 19675/s 268193% 687% --
216 Please report architectures where we can't use the alignment as the move unit. I'll add exceptions for them.
220 L<Carp>, L<Exporter> (core modules since perl 5), L<XSLoader> (since perl 5.006).
224 L<Bit::Vector> gives a complete reimplementation of bit vectors.
228 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
230 You can contact me by mail or on #perl @ FreeNode (vincent or Prof_Vince).
234 Please report any bugs or feature requests to C<bug-scalar-vec-util at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scalar-Vec-Util>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
238 You can find documentation for this module with the perldoc command.
240 perldoc Scalar::Vec::Util
242 Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Scalar-Vec-Util>.
244 =head1 COPYRIGHT & LICENSE
246 Copyright 2008 Vincent Pit, all rights reserved.
248 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
252 1; # End of Scalar::Vec::Util