Vincent Pit > Scalar-Vec-Util > Scalar::Vec::Util

Download:
Scalar-Vec-Util-0.08.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.08   Source  

NAME ^

Scalar::Vec::Util - Utility routines for vec strings.

VERSION ^

Version 0.08

SYNOPSIS ^

    use Scalar::Vec::Util qw<vfill vcopy veq>;

    my $s;
    vfill $s, 0, 100, 1; # Fill with 100 bits 1 starting at 0.
    my $t;
    vcopy $s, 20, $t, 10, 30; # Copy 30 bits from $s, starting at 20,
                              #                to $t, starting at 10.
    vcopy $t, 10, $t, 20, 30; # Overlapping areas DWIM.
    if (veq $t, 10, $t, 20, 30) { ... } # Yes, they are equal now.

DESCRIPTION ^

This module provides a set of utility routines that efficiently manipulate bits in vec strings. Highly optimized XS functions are used whenever possible, but straightforward pure Perl replacements are also available for platforms without a C compiler.

Note that this module does not aim at reimplementing bit vectors : all its functions can be used on any Perl string, just like "vec" in perlfunc.

CONSTANTS ^

SVU_PP

True when pure Perl fallbacks are used instead of XS functions.

SVU_SIZE

The size (in bits) of the unit used for bit operations. The higher this value is, the faster the XS functions are. It is usually CHAR_BIT * $Config{alignbytes}, except on non-little-endian architectures where it currently falls back to CHAR_BIT (e.g. SPARC).

FUNCTIONS ^

vfill

    vfill $vec, $start, $length, $bit;

Starting at $start in $vec, fills $length bits with ones if $bit is true and with zeros if $bit is false.

$vec is upgraded to a string and extended if necessary. Bits that are outside of the specified area are left untouched.

vcopy

    vcopy $from => $from_start, $to => $to_start, $length;

Copies $length bits starting at $from_start in $from to $to_start in $to.

$from and $to are allowed to be the same scalar, and the given areas can rightfully overlap.

$from is upgraded to a string if it isn't one already. If $from_start + $length goes out of the bounds of $from, then the extra bits are treated as zeros. $to is upgraded to a string and extended if necessary. The content of $from is not modified, except when it is equal to $to. Bits that are outside of the specified area are left untouched.

This function does not need to allocate any extra memory.

vshift

    vshift $v, $start, $length => $bits, $insert;

In the area starting at $start and of length $length in $v, shift bits abs $bits positions left if $bits > 0 and right otherwise.

When $insert is defined, the resulting gap is also filled with ones if $insert is true and with zeros if $insert is false.

$v is upgraded to a string if it isn't one already. If $start + $length goes out of the bounds of $v, then the extra bits are treated as zeros. Bits that are outside of the specified area are left untouched.

This function does not need to allocate any extra memory.

vrot

    vrot $v, $start, $length, $bits;

In the area starting at $start and of length $length in $v, rotates bits abs $bits positions left if $bits > 0 and right otherwise.

$v is upgraded to a string if it isn't one already. If $start + $length goes out of the bounds of $v, then the extra bits are treated as zeros. Bits that are outside of the specified area are left untouched.

This function currently allocates an extra buffer of size O($bits).

veq

    veq $v1 => $v1_start, $v2 => $v2_start, $length;

Returns true if the $length bits starting at $v1_start in $v1 and $v2_start in $v2 are equal, and false otherwise.

$v1 and $v2 are upgraded to strings if they aren't already, but their contents are never modified. If $v1_start + $length (respectively $v2_start + $length) goes out of the bounds of $v1 (respectively $v2), then the extra bits are treated as zeros.

This function does not need to allocate any extra memory.

EXPORT ^

The functions "vfill", "vcopy", "vshift", "vrot" and "veq" are only exported on request. All of them are exported by the tags ':funcs' and ':all'.

The constants "SVU_PP" and "SVU_SIZE" are also only exported on request. They are all exported by the tags ':consts' and ':all'.

BENCHMARKS ^

The following timings were obtained by running the samples/bench.pl script. The _pp entries are the pure Perl versions, whereas _bv are Bit::Vector versions.

CAVEATS ^

Please report architectures where we can't use the alignment as the move unit. I'll add exceptions for them.

DEPENDENCIES ^

perl 5.6.

A C compiler. This module may happen to build with a C++ compiler as well, but don't rely on it, as no guarantee is made in this regard.

Carp, Exporter (core modules since perl 5), XSLoader (since perl 5.6.0).

SEE ALSO ^

Bit::Vector gives a complete reimplementation of bit vectors.

AUTHOR ^

Vincent Pit, <perl at profvince.com>, http://www.profvince.com.

You can contact me by mail or on irc.perl.org (vincent).

BUGS ^

Please report any bugs or feature requests to bug-scalar-vec-util at rt.cpan.org, or through the web interface at 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.

SUPPORT ^

You can find documentation for this module with the perldoc command.

    perldoc Scalar::Vec::Util

Tests code coverage report is available at http://www.profvince.com/perl/cover/Scalar-Vec-Util.

COPYRIGHT & LICENSE ^

Copyright 2008,2009,2010,2011,2012,2013 Vincent Pit, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: