util
Class PackedArray

java.lang.Object
  extended by util.PackedArray

public class PackedArray
extends java.lang.Object

This is the implementation of a simple packing algorithm, to reduce the size of an integer array with a fixed number of positive elements and where the highest value is known. This implementation allows further extraction and injection of values, with out unpacking and packing the howl array again.

The implementation is based on three simple bit twiddling operations on integer values: PackedArray.ld, PackedArray.extract and PackedArray.inject.
The idea of this algorithm is that if the largest integer is known, we can represent every element by a fixed number of bits (hopefully smaller then the actual size of the integer).
Assume that the number of bits is three and we have a array of 20 elements, we can store the whole array in an array consisting of only two integer values. Each such integer value contains 10 sections (each three bits long). So every element of the original array can be stored in one of the 20 sections. With that we have reduced the size of a 80 Byte array to 8 Byte.

Because we have sliced each integer in a fixed size of peaces it is easy, to access each value in constant time, without unpacking the array.
Note: This implementation can is only applicable if the following constraints hold:

Author:
eden06

Constructor Summary
PackedArray(int[] array, int high)
          Creates a new PackedArray by packing the given integer array to a from where at least values of the given high can be stored.
PackedArray(PackedArray packedArray)
          Creates a new copy of the given packed array.
 
Method Summary
static int extract(int source, int index, int bits)
          This method extracts a section of an integer, by slicing the integer into equal parts of the given size and extracting the part with the given index.
 int get(int index)
          Returns the element at the specified position in the packed array.
static int inject(int source, int index, int bits, int value)
          This method injects the given value into a section of the given integer.
static int ld(int value)
          Computes the logarithm to the base 2 for the given integer value.
 int length()
          Returns the number of elements in this array.
static void main(java.lang.String[] args)
          Method to test the implementation of the packed array.
 int[] packed()
          Returns the internal representation of the integer array.
 void set(int index, int element)
          Replaces the element at the specified position in this list with the specified element.
 int[] unpack()
          Unpacks the internal representation to a full integer array where every value is stored in every element.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PackedArray

public PackedArray(PackedArray packedArray)
Creates a new copy of the given packed array.
Note: Use this constructor to create copies of a PackedArray instance.

Parameters:
packedArray - to copy from

PackedArray

public PackedArray(int[] array,
                   int high)
Creates a new PackedArray by packing the given integer array to a from where at least values of the given high can be stored.

Parameters:
array - to be represented by a packed array
high - the highest value of possible elements in of this array
Method Detail

ld

public static int ld(int value)
Computes the logarithm to the base 2 for the given integer value.

Parameters:
value - for the logarithm
Returns:
the ceiling of the logarithm of the value to the base 2

extract

public static int extract(int source,
                          int index,
                          int bits)
This method extracts a section of an integer, by slicing the integer into equal parts of the given size and extracting the part with the given index.
For example would PackedArray.extract(0x789ABCDE, 3, 4) return 0x0000009 as a result.

Parameters:
source - from which a part has to be extracted
index - of the section holding the result (starting from zero)
bits - the size of each section
Returns:
the extracted value from the source

inject

public static int inject(int source,
                         int index,
                         int bits,
                         int value)
This method injects the given value into a section of the given integer. In detail the integer is sliced into equal parts of the given size. Afterwards the given value is injected into the section with the given index.
For example would PackedArray.extract(0x789ABCDE, 3, 4, 0x00000005) return 0x785ABCDE as a result.

Parameters:
source - where the value should be injected
index - of the section where the value should be placed (starting from zero)
bits - the size of each section
value - to inject into the source
Returns:
the modified source (where the value has been injected).
Throws:
java.lang.IllegalArgumentException - if the value fits not in a section

get

public int get(int index)
Returns the element at the specified position in the packed array.

Parameters:
index - of the element to return
Returns:
the value of the indexed component
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the index is out of range (index < 0 || index >= length())

set

public void set(int index,
                int element)
Replaces the element at the specified position in this list with the specified element.

Parameters:
index - index of the element to replace
element - to be stored at the specified position
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the index is smaller zero or greater then index of the last element

unpack

public int[] unpack()
Unpacks the internal representation to a full integer array where every value is stored in every element.

Returns:
unpacked integer array

length

public int length()
Returns the number of elements in this array.
Note: The actual length of the internal array is different.

Returns:
the length of the array

main

public static void main(java.lang.String[] args)
Method to test the implementation of the packed array.

Parameters:
args - no arguments are processed during execution

packed

public int[] packed()
Returns the internal representation of the integer array.

Returns:
the packed array internaly used