org.apache.lucene.util
Class Vint8

java.lang.Object
  org.apache.lucene.util.Vint8

public class Vint8
extends Object

Variable-length encoding of 32-bit integers, into 8-bit bytes. A number is encoded as follows:

• If it is less than 127 and non-negative (i.e., if the number uses only 7 bits), it is encoded as as single byte: 0bbbbbbb.
• If its highest nonzero bit is greater than bit 6 (0x40), it is represented as a series of bytes, each byte's 7 LSB containing bits from the original value, with the MSB set for all but the last byte. The first encoded byte contains the highest nonzero bits from the original; the second byte contains the next 7 MSB; and so on, with the last byte containing the 7 LSB of the original.

Examples:

1. n = 117 = 1110101: This has fewer than 8 significant bits, and so is encoded as 01110101 = 0x75.
2. n = 100000 = (binary) 11000011010100000. This has 17 significant bits, and so needs three Vint8 bytes. Left-zero-pad it to a multiple of 7 bits, then split it into chunks of 7 and add an MSB, 0 for the last byte, 1 for the others: 1|0000110 1|0001101 0|0100000 = 0x86 0x8D 0x20.

This encoder/decoder will correctly handle any 32-bit integer, but for negative numbers, and positive numbers with more than 28 significant bits, encoding requires 5 bytes; this is not an efficient encoding scheme for large positive numbers or any negative number.

Compatibility:
This class has been used in products that have shipped to customers, and is needed to decode legacy data. Do not modify this class in ways that will break compatibility.

WARNING: This API is experimental and might change in incompatible ways in the next release.

Nested Class Summary

static class

Vint8.Position Because Java lacks call-by-reference, this class boxes the decoding position, which is initially set by the caller, and returned after decoding, incremented by the number of bytes processed.

Field Summary

static int

MAXIMUM_BYTES_NEEDED The maximum number of bytes needed to encode a number using Vint8.

Method Summary

static int	bytesNeeded(int number) Returns the number of bytes needed to encode number.
static int	decode(byte[] bytes, Vint8.Position pos) Decodes a 32-bit integer from bytes, beginning at offset pos.pos.
static int	decode(InputStream in) Decodes a 32-bit integer from bytes read from in.
static int	encode(int number, byte[] dest, int start) Encodes number into dest, starting at offset start from the beginning of the array.
static void	encode(int number, OutputStream out) Encodes number to out.

Methods inherited from class java.lang.Object

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

Field Detail

MAXIMUM_BYTES_NEEDED

public static final int MAXIMUM_BYTES_NEEDED

The maximum number of bytes needed to encode a number using Vint8.

See Also:

Constant Field Values

Method Detail

bytesNeeded

public static int bytesNeeded(int number)

Returns the number of bytes needed to encode number.

Parameters:

number - The number whose encoded length is needed.

Returns:

The number of bytes needed to encode number.

encode

public static void encode(int number,
                          OutputStream out)
                   throws IOException

Encodes number to out.

Parameters:

number - The value to be written in encoded form, to out.

out - The output stream receiving the encoded bytes.

Throws:

IOException - If there is a problem writing to out.

encode

public static int encode(int number,
                         byte[] dest,
                         int start)

Encodes number into dest, starting at offset start from the beginning of the array. This method assumes dest is large enough to hold the required number of bytes.

Parameters:

number - The number to be encoded.

dest - The destination array.

start - The starting offset in the array.

Returns:

The number of bytes used in the array.

decode

public static int decode(byte[] bytes,
                         Vint8.Position pos)

Decodes a 32-bit integer from bytes, beginning at offset pos.pos. The decoded value is returned, and pos.pos is incremented by the number of bytes processed.

Parameters:

bytes - The byte array containing an encoded value.

pos - On entry, the starting position in the array; on return, one greater than the position of the last byte decoded in the call.

Returns:

The decoded value.

decode

public static int decode(InputStream in)
                  throws IOException

Decodes a 32-bit integer from bytes read from in. Bytes are read, one at a time, from in, and it is assumed they represent a 32-bit integer encoded using this class's encoding scheme. The decoded value is returned.

Parameters:

in - The input stream containing the encoded bytes.

Returns:

The decoded value.

Throws:

EOFException - If the stream ends before a value has been decoded.

IOException