NAME

Tie::IntegerArray - provides a tied array of packed integers of any bit length

SYNOPSIS

  use Tie::IntegerArray;

  # an array of signed 16-bit integers with no undef support and
  # starting room for 100,000 items.  You can expect this to consume a
  # bit more than 200K of memory versus more than 800K for a normal
  # Perl array.
  my @integer_array;
  tie @integer_array, 'Tie::IntegerArray',
     bits => 16,
     signed => 1,
     undef => 0,
     size => 100_000;
  
  # put a value in
  $integer_array[0] = 10;

  # and print it out
  print "Int 0: $integer_array[0]\n";     

  # the full range of array operations are available

DESCRIPTION

This module provides an array interface to packed array of integers. A packed array of integers is useful in situations where you need to store a large set of integers in as small a space as possible. Access to the packed array will be significantly slower than access to a normal array but for many applications the reduction in memory usage makes this a good trade-off.

USAGE

To create an IntegerArray you call tie with a number of optional arguements. These arguements let you fine-tune the storage of your integers. The simplest tie call uses no options:

  my @integer_array;
  tie @integer_array, 'Tie::IntegerArray';

This will create an array of signed integers with the same size as native ints on your platform. By default the array does not support undef - values are 0 by default. This may be ideal for many applications - read below for other options.

OPTIONS

• bits (defaults to your machine's int size)

  This option specifies how many bits to use to store the integer value. This setting determines the possible range of your integers. If you specify unsigned integers (see below) then the maximum range on your integers is simply 2^bits. For example, 8 bits provides an unsigned range of 0 - 255.

  Since the integers are stored in a packed array you can calculate the size of your array by multiplying the number of items by the number of bits.

  Attempting to store a value into the array that is too large or too small for the available bit size will cause an error.

• signed (defaults to 1)

  If you set signed to 1 then your integers will be signed. This reduces their positive range by a power of 2 but provides equal negative range. For example, an 8 bit signed integer has a range from -128 - 127.

• undef (defaults to 0)

  By default IntegerArrays do not support undef. This means that array values will be 0 until they are set to some value. Calling defined() on an array value will return true if exists() will. You can change this by setting undef to 1. This requires extra memory - 1 bit per array entry.

• size (defaults to 1)

  IntegerArrays grow automatically as you add items but you can specify a size arguement to pre-allocate space. This will improve performance for large arrays.

FUTURE PLANS

This module is functionally complete but not yet fully optimized. It relies on Tie::Array for the more advanced array functions (push, pop, etc) and a native implementation could be faster. If this module proves at all popular then I will definitely move in that direction.

CREDITS

Steffen Beyer - Bit::Vector is pure magic.

AUTHOR

Sam Tregar, sam@tregar.com

LICENSE

HTML::Template : A module for using HTML Templates with Perl Copyright (C) 2000 Sam Tregar (sam@tregar.com)

This module is free software; you can redistribute it and/or modify it under the terms of either:

a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

b) the "Artistic License" which comes with this module.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this module, in the file ARTISTIC. If not, I'll be glad to provide one.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

SEE ALSO

Bit::Vector