Package io.github.mahmoudimus.quic

Class VarInt

java.lang.Object
io.github.mahmoudimus.quic.VarInt
public final class VarInt extends Object
QUIC variable-length integers (RFC 9000 section 16): values below 262, encoded in 1, 2, 4 or 8 bytes with the length in the two most significant bits of the first byte.

Values are carried as longs. The writers always use the shortest encoding; the reader accepts any encoding, as RFC 9000 requires, so callers that need the shortest form (frame types) compare size(long) with the bytes consumed.

All methods are static and thread-safe.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final long
    MAX
    The largest encodable value, 262-1.
    static final int
    MAX_SIZE
    The longest encoding, in bytes.

  • Method Summary

    Modifier and Type
    Method
    Description
    static byte[]
    encode(long value)
    The shortest encoding of a value.
    static long
    maxForSize(int size)
    The largest value that encodes in at most size bytes.
    static long
    read(ByteBuffer in)
    Reads a value at the buffer's position, in any of the four encodings.
    static int
    size(long value)
    The length of the shortest encoding of a value.
    static int
    sizeOf(byte firstByte)
    The length of an encoding, read from its first byte.
    static int
    write(byte[] out, int offset, long value)
    Writes a value in its shortest encoding into an array.
    static void
    write(ByteBuffer out, long value)
    Writes a value in its shortest encoding.
    static void
    writeWithSize(ByteBuffer out, long value, int size)
    Writes a value in a chosen encoding length, which may be longer than necessary (as the two-byte Length field of a long header is, so that it can be patched once the payload is known).

    Methods inherited from class java.lang.Object

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

  • Field Details

    • MAX

      public static final long MAX
      The largest encodable value, 262-1.
      See Also:

    • MAX_SIZE

      public static final int MAX_SIZE
      The longest encoding, in bytes.
      See Also:

  • Method Details

    • size

      public static int size(long value)
      The length of the shortest encoding of a value.
      Parameters:
      value - the value, from 0 to MAX
      Returns:
      1, 2, 4 or 8
      Throws:
      IllegalArgumentException - if the value is negative or above MAX

    • sizeOf

      public static int sizeOf(byte firstByte)
      The length of an encoding, read from its first byte.
      Parameters:
      firstByte - the first byte of the encoding
      Returns:
      1, 2, 4 or 8

    • maxForSize

      public static long maxForSize(int size)
      The largest value that encodes in at most size bytes.
      Parameters:
      size - 1, 2, 4 or 8
      Returns:
      the largest value of that size
      Throws:
      IllegalArgumentException - for any other size

    • write

      public static void write(ByteBuffer out, long value)
      Writes a value in its shortest encoding.
      Parameters:
      out - the buffer, written at its position
      value - the value, from 0 to MAX
      Throws:
      IllegalArgumentException - if the value is out of range
      BufferOverflowException - if the buffer has too little room

    • writeWithSize

      public static void writeWithSize(ByteBuffer out, long value, int size)
      Writes a value in a chosen encoding length, which may be longer than necessary (as the two-byte Length field of a long header is, so that it can be patched once the payload is known).
      Parameters:
      out - the buffer, written at its position
      value - the value
      size - the encoding length: 1, 2, 4 or 8, at least size(long)
      Throws:
      IllegalArgumentException - if the value does not fit in size bytes
      BufferOverflowException - if the buffer has too little room

    • write

      public static int write(byte[] out, int offset, long value)
      Writes a value in its shortest encoding into an array.
      Parameters:
      out - the array
      offset - where to write
      value - the value, from 0 to MAX
      Returns:
      the offset just past the encoding
      Throws:
      IllegalArgumentException - if the value is out of range
      IndexOutOfBoundsException - if the array has too little room

    • encode

      public static byte[] encode(long value)
      The shortest encoding of a value.
      Parameters:
      value - the value, from 0 to MAX
      Returns:
      a new array of size(long) bytes
      Throws:
      IllegalArgumentException - if the value is out of range

    • read

      public static long read(ByteBuffer in)
      Reads a value at the buffer's position, in any of the four encodings.
      Parameters:
      in - the buffer; its position moves past the encoding
      Returns:
      the value, from 0 to MAX
      Throws:
      BufferUnderflowException - if the buffer ends inside the encoding (the position is then unchanged)