README

   1 NAME
   2     Scalar::Vec::Util - Utility routines for vec strings.
   3
   4 VERSION
   5     Version 0.02
   6
   7 SYNOPSIS
   8         use Scalar::Vec::Util qw/vfill vcopy veq/;
   9
  10         my $s;
  11         vfill $s, 0, 100, 1; # Fill with 100 bits 1 starting at 0.
  12         my $t;
  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.
  17
  18 DESCRIPTION
  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.
  22
  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
  25     ("SVt_PV").
  26
  27 CONSTANTS
  28   "SVU_PP"
  29     True when pure perl fallbacks are used instead of XS functions.
  30
  31   "SVU_SIZE"
  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).
  36
  37 FUNCTIONS
  38   "vfill $vec, $start, $length, $bit"
  39     Starting at $start in $vec, fills $length bits with $bit. Grows $vec if
  40     necessary.
  41
  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.
  46
  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.
  51
  52 EXPORT
  53     The functions "vfill", "vcopy" and "veq" are only exported on request.
  54     All of them are exported by the tags ':funcs' and ':all'.
  55
  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'.
  58
  59 CAVEATS
  60     Please report architectures where we can't use the alignment as the move
  61     unit. I'll add exceptions for them.
  62
  63 DEPENDENCIES
  64     Carp, Exporter (core modules since perl 5), XSLoader (since perl 5.006).
  65
  66 SEE ALSO
  67     Bit::Vector gives a complete reimplementation of bit vectors.
  68
  69 AUTHOR
  70     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
  71
  72     You can contact me by mail or on #perl @ FreeNode (vincent or
  73     Prof_Vince).
  74
  75 BUGS
  76     Please report any bugs or feature requests to "bug-scalar-vec-util at
  77     rt.cpan.org", or through the web interface at
  78     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scalar-Vec-Util>. I will
  79     be notified, and then you'll automatically be notified of progress on
  80     your bug as I make changes.
  81
  82 SUPPORT
  83     You can find documentation for this module with the perldoc command.
  84
  85         perldoc Scalar::Vec::Util
  86
  87     Tests code coverage report is available at
  88     <http://www.profvince.com/perl/cover/Scalar-Vec-Util>.
  89
  90 COPYRIGHT & LICENSE
  91     Copyright 2008 Vincent Pit, all rights reserved.
  92
  93     This program is free software; you can redistribute it and/or modify it
  94     under the same terms as Perl itself.
  95