Vint8 (Lucene 3.6.2 API)
Keywords: org.apache.lucene.util.Vint8 class

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD