Package org.apache.lucene.util

Class 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

      Nested Classes 
      Modifier and Type Class Description
      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

      Fields 
      Modifier and Type Field Description
      static int MAXIMUM_BYTES_NEEDED
      The maximum number of bytes needed to encode a number using Vint8.

    • 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