lib/Scalar/Vec/Util.pm

   1 package Scalar::Vec::Util;
   2
   3 use strict;
   4 use warnings;
   5
   6 use Carp qw/croak/;
   7
   8 =head1 NAME
   9
  10 Scalar::Vec::Util - Utility routines for vec strings.
  11
  12 =head1 VERSION
  13
  14 Version 0.02
  15
  16 =cut
  17
  18 our $VERSION;
  19 BEGIN {
  20  $VERSION = '0.02';
  21  eval {
  22   require XSLoader;
  23   XSLoader::load(__PACKAGE__, $VERSION);
  24   1;
  25  } or do {
  26   sub SVU_PP   () { 1 }
  27   sub SVU_SIZE () { 1 }
  28   *vfill = *vfill_pp;
  29   *vcopy = *vcopy_pp;
  30   *veq   = *veq_pp;
  31  }
  32 }
  33
  34 =head1 SYNOPSIS
  35
  36     use Scalar::Vec::Util qw/vfill vcopy veq/;
  37
  38     my $s;
  39     vfill $s, 0, 100, 1; # Fill with 100 bits 1 starting at 0.
  40     my $t;
  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.
  45
  46 =head1 DESCRIPTION
  47
  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.
  49
  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>).
  51
  52 =head1 CONSTANTS
  53
  54 =head2 C<SVU_PP>
  55
  56 True when pure perl fallbacks are used instead of XS functions.
  57
  58 =head2 C<SVU_SIZE>
  59
  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).
  61
  62 =head1 FUNCTIONS
  63
  64 =head2 C<vfill $vec, $start, $length, $bit>
  65
  66 Starting at C<$start> in C<$vec>, fills C<$length> bits with C<$bit>. Grows C<$vec> if necessary.
  67
  68 =cut
  69
  70 sub _alldef {
  71  for (@_) { return 0 unless defined }
  72  return 1;
  73 }
  74
  75 sub vfill_pp {
  76  (undef, my $s, my $l, my $x) = @_;
  77  croak "Invalid argument" unless _alldef @_;
  78  return unless $l;
  79  $x = 1 if $x;
  80  vec($_[0], $_, 1) = $x for $s .. $s + $l - 1;
  81 }
  82
  83 =head2 C<< vcopy $from => $from_start, $to => $to_start, $length >>
  84
  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.
  86
  87 =cut
  88
  89 sub vcopy_pp {
  90  my ($fs, $ts, $l) = @_[1, 3, 4];
  91  croak "Invalid argument" unless _alldef @_;
  92  return unless $l;
  93  my $step = $ts - $fs;
  94  if ($step <= 0) {
  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;
  98  }
  99 }
 100
 101 =head2 C<< veq $v1 => $v1_start, $v2 => $v2_start, $length >>
 102
 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.
 104
 105 =cut
 106
 107 sub veq_pp {
 108  my ($s1, $s2, $l) = @_[1, 3, 4];
 109  croak "Invalid argument" unless _alldef @_;
 110  my $i = 0;
 111  while ($i < $l) {
 112   return 0 if vec($_[0], $s1 + $i, 1) != vec($_[2], $s2 + $i, 1);
 113   ++$i;
 114  }
 115  return 1;
 116 }
 117
 118 =head1 EXPORT
 119
 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'>.
 121
 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'>.
 123
 124 =cut
 125
 126 use base qw/Exporter/;
 127
 128 our @EXPORT         = ();
 129 our %EXPORT_TAGS    = (
 130  'funcs'  => [ qw/vfill vcopy veq/ ],
 131  'consts' => [ qw/SVU_PP SVU_SIZE/ ]
 132 );
 133 our @EXPORT_OK      = map { @$_ } values %EXPORT_TAGS;
 134 $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
 135
 136 =head1 CAVEATS
 137
 138 Please report architectures where we can't use the alignment as the move unit. I'll add exceptions for them.
 139
 140 =head1 DEPENDENCIES
 141
 142 L<Carp>, L<Exporter> (core modules since perl 5), L<XSLoader> (since perl 5.006).
 143
 144 =head1 SEE ALSO
 145
 146 L<Bit::Vector> gives a complete reimplementation of bit vectors.
 147
 148 =head1 AUTHOR
 149
 150 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 151
 152 You can contact me by mail or on #perl @ FreeNode (vincent or Prof_Vince).
 153
 154 =head1 BUGS
 155
 156 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.
 157
 158 =head1 SUPPORT
 159
 160 You can find documentation for this module with the perldoc command.
 161
 162     perldoc Scalar::Vec::Util
 163
 164 Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Scalar-Vec-Util>.
 165
 166 =head1 COPYRIGHT & LICENSE
 167
 168 Copyright 2008 Vincent Pit, all rights reserved.
 169
 170 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
 171
 172 =cut
 173
 174 1; # End of Scalar::Vec::Util