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.
| constant | type | note |
|---|---|---|
| FASTEST | float | At most 700% memory overhead, always select a direct implementation. |
| FAST | float | At most 50% memory overhead, always select a reasonably fast implementation. |
| DEFAULT | float | At most 25% memory overhead. |
| COMPACT | float | No memory overhead at all, but the returned implementation may be slow. |
| DEFAULT_BUFFER_SIZE | int | Default amount of memory to use for bulk operations. |
| CODEC_NAME | String | |
| VERSION_MONOTONIC_WITHOUT_ZIGZAG | int | |
| VERSION_START | int | |
| VERSION_CURRENT | int |
<init>()bitsRequired(long maxValue)Returns how many bits are required to hold values up to and including maxValue NOTE: This method returns at least 1.
| name | type | description |
|---|---|---|
| max_value | long | the maximum value that should be representable. |
Returns: the amount of bits needed to represent values from 0 to maxValue.
bitsRequired(int maxValue)Returns how many bits are required to hold values up to and including maxValue NOTE: This method returns at least 1.
| name | type | description |
|---|---|---|
| max_value | int | the maximum int value that should be representable. |
Returns: the amount of bits needed to represent values from 0 to maxValue.
checkVersion(int version)Check the validity of a version number.
copy(org.apache.lucene.util.packed.PackedInts.Reader src, int srcPos, org.apache.lucene.util.packed.PackedInts.Mutable dest, int destPos, int len, int mem)Copy src[srcPos:srcPos+len] into dest[destPos:destPos+len] using at
most mem bytes.
fastestFormatAndBits(int valueCount, int bitsPerValue, float acceptableOverheadRatio)Try to find the Format and number of bits per value that would restore from disk the
fastest reader whose overhead is less than acceptableOverheadRatio.
The acceptableOverheadRatio parameter makes sense for random-access Readers. In case you only plan to perform sequential access on this stream later on, you
should probably use PackedInts#COMPACT.
If you don't know how many values you are going to write, use valueCount = -1.
getDecoder(org.apache.lucene.util.packed.PackedInts.Format format, int version, int bitsPerValue)Get a Decoder.
| name | type | description |
|---|---|---|
| format | org.apache.lucene.util.packed.PackedInts.Format | the format used to store packed ints |
| version | int | the compatibility version |
| bits_per_value | int | the number of bits per value |
Returns: a decoder
getEncoder(org.apache.lucene.util.packed.PackedInts.Format format, int version, int bitsPerValue)Get an Encoder.
| name | type | description |
|---|---|---|
| format | org.apache.lucene.util.packed.PackedInts.Format | the format used to store packed ints |
| version | int | the compatibility version |
| bits_per_value | int | the number of bits per value |
Returns: an encoder
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 PackedInts#COMPACT will make sure that the most
memory-efficient implementation is selected whereas PackedInts#FASTEST will make sure
that the fastest implementation is selected.
| name | type | description |
|---|---|---|
| value_count | int | the number of elements |
| bits_per_value | int | the number of bits available for any given value |
| acceptable_overhead_ratio | float | an acceptable overhead ratio per value |
Returns: a mutable packed integer array
getMutable(int valueCount, int bitsPerValue, org.apache.lucene.util.packed.PackedInts.Format format)Same as #getMutable(int, int, float) with a pre-computed number of bits per value and
format.
getReaderIteratorNoHeader(org.apache.lucene.store.DataInput in, org.apache.lucene.util.packed.PackedInts.Format format, int version, int valueCount, int bitsPerValue, int mem)Expert: Restore a ReaderIterator from a stream without reading metadata at the
beginning of the stream. This method is useful to restore data from streams which have been
created using PackedInts#getWriterNoHeader(DataOutput, Format, int, int, int).
| name | type | description |
|---|---|---|
| in | org.apache.lucene.store.DataInput | the stream to read data from, positioned at the beginning of the packed values |
| format | org.apache.lucene.util.packed.PackedInts.Format | the format used to serialize |
| version | int | the version used to serialize the data |
| value_count | int | how many values the stream holds |
| bits_per_value | int | the number of bits per value |
| mem | int | how much memory the iterator is allowed to use to read-ahead (likely to speed up iteration) |
Returns: a ReaderIterator
getWriterNoHeader(org.apache.lucene.store.DataOutput out, org.apache.lucene.util.packed.PackedInts.Format format, int valueCount, int bitsPerValue, int mem)Expert: Create a packed integer array writer for the given output, format, value count, and number of bits per value.
The resulting stream will be long-aligned. This means that depending on the format which is
used, up to 63 bits will be wasted. An easy way to make sure that no space is lost is to always
use a valueCount that is a multiple of 64.
This method does not write any metadata to the stream, meaning that it is your responsibility to store it somewhere else in order to be able to recover data from the stream later on:
format (using Format#getId()),
valueCount,
bitsPerValue,
#VERSION_CURRENT.
It is possible to start writing values without knowing how many of them you are actually
going to write. To do this, just pass -1 as valueCount. On the other
hand, for any positive value of valueCount, the returned writer will make sure
that you don't write more values than expected and pad the end of stream with zeros in case you
have written less than valueCount when calling Writer#finish().
The mem parameter lets you control how much memory can be used to buffer
changes in memory before flushing to disk. High values of mem are likely to
improve throughput. On the other hand, if speed is not that important to you, a value of
0 will use as little memory as possible and should already offer reasonable throughput.
| name | type | description |
|---|---|---|
| out | org.apache.lucene.store.DataOutput | the data output |
| format | org.apache.lucene.util.packed.PackedInts.Format | the format to use to serialize the values |
| value_count | int | the number of values |
| bits_per_value | int | the number of bits per value |
| mem | int | how much memory (in bytes) can be used to speed up serialization |
Returns: a Writer
maxValue(int bitsPerValue)Calculates the maximum unsigned long that can be expressed with the given number of bits.
| name | type | description |
|---|---|---|
| bits_per_value | int | the number of bits available for any given value. |
Returns: the maximum value for the given bits.
unsignedBitsRequired(long bits)Returns how many bits are required to store bits, interpreted as an unsigned
value. NOTE: This method returns at least 1.
unsignedBitsRequired(int bits)Returns how many bits are required to store bits, interpreted as an unsigned
value. NOTE: This method returns at least 1.
| name | type | description |
|---|---|---|
| bits | int | the int value to be stored, interpreted as unsigned. |
Returns: the amount of bits needed to represent the unsigned value.