org.apache.lucene.util.packed

Class PackedInts

java.lang.Object

org.apache.lucene.util.packed.PackedInts

public class PackedInts
extends Object

Simplistic compression for array of unsigned long values. Each value is >= 0 and <= a specified maximum value. The values are stored as packed ints, with each value consuming a fixed number of bits.

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	PackedInts.Mutable A packed integer array that can be modified.
static interface	PackedInts.Reader A read-only random access array of positive integers.
static class	PackedInts.ReaderImpl A simple base for Readers that keeps track of valueCount and bitsPerValue.
static class	PackedInts.Writer A write-once Writer.

Constructor Summary

Constructors

Constructor and Description
PackedInts()

Method Summary

Methods

Modifier and Type	Method and Description
static int	bitsRequired(long maxValue) Returns how many bits are required to hold values up to and including maxValue
static PackedInts.Mutable	getMutable(int valueCount, int bitsPerValue) Create a packed integer array with the given amount of values initialized to 0.
static int	getNextFixedSize(int bitsPerValue) Rounds bitsPerValue up to 8, 16, 32 or 64.
static PackedInts.Reader	getReader(DataInput in) Retrieve PackedInt data from the DataInput and return a packed int structure based on it.
static int	getRoundedFixedSize(int bitsPerValue) Possibly wastes some storage in exchange for faster lookups
static PackedInts.Writer	getWriter(DataOutput out, int valueCount, int bitsPerValue) Create a packed integer array writer for the given number of values at the given bits/value.
static long	maxValue(int bitsPerValue) Calculates the maximum unsigned long that can be expressed with the given number of bits.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PackedInts

public PackedInts()

Method Detail

getReader

public static PackedInts.Reader getReader(DataInput in)
                                   throws IOException

Retrieve PackedInt data from the DataInput and return a packed int structure based on it.

Parameters:

in - positioned at the beginning of a stored packed int structure.

Returns:

a read only random access capable array of positive integers.

Throws:

IOException - if the structure could not be retrieved.

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

getMutable

public static PackedInts.Mutable getMutable(int valueCount,
                            int bitsPerValue)

Create a packed integer array with the given amount of values initialized to 0. the valueCount and the bitsPerValue cannot be changed after creation. All Mutables known by this factory are kept fully in RAM.

Parameters:

valueCount - the number of elements.

bitsPerValue - the number of bits available for any given value.

Returns:

a mutable packed integer array.

Throws:

IOException - if the Mutable could not be created. With the current implementations, this never happens, but the method signature allows for future persistence-backed Mutables.

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

getWriter

public static PackedInts.Writer getWriter(DataOutput out,
                          int valueCount,
                          int bitsPerValue)
                                   throws IOException

Create a packed integer array writer for the given number of values at the given bits/value. Writers append to the given IndexOutput and has very low memory overhead.

Parameters:

out - the destination for the produced bits.

valueCount - the number of elements.

bitsPerValue - the number of bits available for any given value.

Returns:

a Writer ready for receiving values.

Throws:

IOException - if bits could not be written to out.

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

bitsRequired

public static int bitsRequired(long maxValue)

Returns how many bits are required to hold values up to and including maxValue

Parameters:

maxValue - the maximum value that should be representable.

Returns:

the amount of bits needed to represent values from 0 to maxValue.

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

maxValue

public static long maxValue(int bitsPerValue)

Calculates the maximum unsigned long that can be expressed with the given number of bits.

Parameters:

bitsPerValue - the number of bits available for any given value.

Returns:

the maximum value for the given bits.

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

getNextFixedSize

public static int getNextFixedSize(int bitsPerValue)

Rounds bitsPerValue up to 8, 16, 32 or 64.

getRoundedFixedSize

public static int getRoundedFixedSize(int bitsPerValue)

Possibly wastes some storage in exchange for faster lookups