org.apache.lucene.util.packed
Class PackedInts

java.lang.Object
  extended by 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
static interface PackedInts.Mutable
          A packed integer array that can be modified.
static class PackedInts.MutableImpl
           
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 interface PackedInts.ReaderIterator
          Run-once iterator interface, to decode previously saved PackedInts.
static class PackedInts.Writer
          A write-once Writer.
 
Field Summary
static float COMPACT
          No memory overhead at all, but the returned implementation may be slow.
static float DEFAULT
          At most 20% memory overhead.
static int DEFAULT_BUFFER_SIZE
          Default amount of memory to use for bulk operations.
static float FAST
          At most 50% memory overhead, always select a reasonably fast implementation.
static float FASTEST
          At most 700% memory overhead, always select a direct implementation.
 
Constructor Summary
PackedInts()
           
 
Method Summary
static int bitsRequired(long maxValue)
          Returns how many bits are required to hold values up to and including maxValue
static void copy(PackedInts.Reader src, int srcPos, PackedInts.Mutable dest, int destPos, int len, int mem)
          Copy src[srcPos:srcPos+len] into dest[destPos:destPos+len] using at most mem bytes.
static PackedInts.Reader getDirectReader(IndexInput in)
          Retrieve PackedInts.Reader that does not load values into RAM but rather accesses all values via the provided IndexInput.
static PackedInts.Mutable getMutable(int valueCount, int bitsPerValue, float acceptableOverheadRatio)
          Create a packed integer array with the given amount of values initialized to 0.
static PackedInts.Reader getReader(DataInput in)
          Retrieve PackedInt data from the DataInput and return a packed int structure based on it.
static PackedInts.ReaderIterator getReaderIterator(IndexInput in)
          Retrieve PackedInts as a PackedInts.ReaderIterator
static PackedInts.Writer getWriter(DataOutput out, int valueCount, int bitsPerValue, float acceptableOverheadRatio)
          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
 

Field Detail

FASTEST

public static final float FASTEST
At most 700% memory overhead, always select a direct implementation.

See Also:
Constant Field Values

FAST

public static final float FAST
At most 50% memory overhead, always select a reasonably fast implementation.

See Also:
Constant Field Values

DEFAULT

public static final float DEFAULT
At most 20% memory overhead.

See Also:
Constant Field Values

COMPACT

public static final float COMPACT
No memory overhead at all, but the returned implementation may be slow.

See Also:
Constant Field Values

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE
Default amount of memory to use for bulk operations.

See Also:
Constant Field Values
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.

getReaderIterator

public static PackedInts.ReaderIterator getReaderIterator(IndexInput in)
                                                   throws IOException
Retrieve PackedInts as a PackedInts.ReaderIterator

Parameters:
in - positioned at the beginning of a stored packed int structure.
Returns:
an iterator to access the values
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.

getDirectReader

public static PackedInts.Reader getDirectReader(IndexInput in)
                                         throws IOException
Retrieve PackedInts.Reader that does not load values into RAM but rather accesses all values via the provided IndexInput.

Parameters:
in - positioned at the beginning of a stored packed int structure.
Returns:
an Reader to access the values
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,
                                            float acceptableOverheadRatio)
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. Positive values of acceptableOverheadRatio will trade space for speed by selecting a faster but potentially less memory-efficient implementation. An acceptableOverheadRatio of COMPACT will make sure that the most memory-efficient implementation is selected whereas FASTEST will make sure that the fastest implementation is selected.

Parameters:
valueCount - the number of elements
bitsPerValue - the number of bits available for any given value
acceptableOverheadRatio - an acceptable overhead ratio per 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,
                                          float acceptableOverheadRatio)
                                   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. Positive values of acceptableOverheadRatio will trade space for speed by selecting a faster but potentially less memory-efficient implementation. An acceptableOverheadRatio of COMPACT will make sure that the most memory-efficient implementation is selected whereas FASTEST will make sure that the fastest implementation is selected.

Parameters:
out - the destination for the produced bits.
valueCount - the number of elements.
bitsPerValue - the number of bits available for any given value.
acceptableOverheadRatio - an acceptable overhead ratio per 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.

copy

public static void copy(PackedInts.Reader src,
                        int srcPos,
                        PackedInts.Mutable dest,
                        int destPos,
                        int len,
                        int mem)
Copy src[srcPos:srcPos+len] into dest[destPos:destPos+len] using at most mem bytes.



Copyright © 2000-2012 Apache Software Foundation. All Rights Reserved.