Package org.apache.commons.compress.harmony.pack200

# Class BHSDCodec

java.lang.Object
org.apache.commons.compress.harmony.pack200.Codec
org.apache.commons.compress.harmony.pack200.BHSDCodec

public final class BHSDCodec extends Codec
A BHSD codec is a means of encoding integer values as a sequence of bytes or vice versa using a specified "BHSD" encoding mechanism. It uses a variable-length encoding and a modified sign representation such that small numbers are represented as a single byte, whilst larger numbers take more bytes to encode. The number may be signed or unsigned; if it is unsigned, it can be weighted towards positive numbers or equally distributed using a one's complement. The Codec also supports delta coding, where a sequence of numbers is represented as a series of first-order differences. So a delta encoding of the integers [1..10] would be represented as a sequence of 10x1s. This allows the absolute value of a coded integer to fall outside of the 'small number' range, whilst still being encoded as a single byte.

A BHSD codec is configured with four parameters:

B
  The maximum number of bytes that each value is encoded as. B must be a value between [1..5]. For a pass-through coding (where each byte is encoded as itself, aka `Codec.BYTE1`, B is 1 (each byte takes a maximum of 1 byte).
H
  The radix of the integer. Values are defined as a sequence of values, where value `n` is multiplied by `H^<sup>n</sup>`. So the number 1234 may be represented as the sequence 4 3 2 1 with a radix (H) of 10. Note that other permutations are also possible; 43 2 1 will also encode 1234. The co-parameter L is defined as 256-H. This is important because only the last value in a sequence may be < L; all prior values must be > L.
S
  Whether the codec represents signed values (or not). This may have 3 values; 0 (unsigned), 1 (signed, one's complement) or 2 (signed, two's complement)
D
  Whether the codec represents a delta encoding. This may be 0 (no delta) or 1 (delta encoding). A delta encoding of 1 indicates that values are cumulative; a sequence of `1 1 1 1 1` will represent the sequence `1 2 3 4 5`. For this reason, the codec supports two variants of decode; one `with` and one `without` a `last` parameter. If the codec is a non-delta encoding, then the value is ignored if passed. If the codec is a delta encoding, it is a run-time error to call the value without the extra parameter, and the previous value should be returned. (It was designed this way to support multi-threaded access without requiring a new instance of the Codec to be cloned for each use.)

Codecs are notated as (B,H,S,D) and either D or S,D may be omitted if zero. Thus `Codec.BYTE1` is denoted (1,256,0,0) or (1,256). The `toString()` method prints out the condensed form of the encoding. Often, the last character in the name (`Codec.BYTE1`, `Codec.UNSIGNED5`) gives a clue as to the B value. Those that start with U (`Codec.UDELTA5`, `Codec.UNSIGNED5`) are unsigned; otherwise, in most cases, they are signed. The presence of the word Delta (`Codec.DELTA5`, `Codec.UDELTA5`) indicates a delta encoding is used.

- ## Field Summary

  ### Fields inherited from class org.apache.commons.compress.harmony.pack200.Codec

  `BCI5, BRANCH5, BYTE1, CHAR3, DELTA5, lastBandLength, MDELTA5, SIGNED5, UDELTA5, UNSIGNED5`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BHSDCodec(int b, int h)`
  Constructs an unsigned, non-delta Codec with the given B and H values.
  `BHSDCodec(int b, int h, int s)`
  Constructs a non-delta Codec with the given B, H and S values.
  `BHSDCodec(int b, int h, int s, int d)`
  Constructs a Codec with the given B, H, S and D values.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `long`
  `cardinality()`
  Returns the cardinality of this codec; that is, the number of distinct values that it can contain.
  `int`
  `decode(InputStream in)`
  Decodes a sequence of bytes from the given input stream, returning the value as a long.
  `int`
  `decode(InputStream in, long last)`
  Decodes a sequence of bytes from the given input stream, returning the value as a long.
  `int[]`
  `decodeInts(int n, InputStream in)`
  Decodes a sequence of `n` values from `in`.
  `int[]`
  `decodeInts(int n, InputStream in, int firstValue)`
  Decodes a sequence of `n` values from `in`.
  `byte[]`
  `encode(int value)`
  Encodes a single value into a sequence of bytes.
  `byte[]`
  `encode(int value, int last)`
  Encodes a single value into a sequence of bytes.
  `boolean`
  `encodes(long value)`
  True if this encoding can code the given value
  `boolean`
  `equals(Object o)`
  `int`
  `getB()`
  Gets the B.
  `int`
  `getH()`
  Gets the H.
  `int`
  `getL()`
  Gets the L.
  `int`
  `getS()`
  Gets the S.
  `int`
  `hashCode()`
  `boolean`
  `isDelta()`
  Returns true if this codec is a delta codec
  `boolean`
  `isSigned()`
  Returns true if this codec is a signed codec
  `long`
  `largest()`
  Returns the largest value that this codec can represent.
  `long`
  `smallest()`
  Returns the smallest value that this codec can represent.
  `String`
  `toString()`
  Returns the codec in the form (1,256) or (1,64,1,1).

  ### Methods inherited from class org.apache.commons.compress.harmony.pack200.Codec

  `encode`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### BHSDCodec

    public BHSDCodec(int b, int h)
    Constructs an unsigned, non-delta Codec with the given B and H values.
    Parameters:
      `b` - the maximum number of bytes that a value can be encoded as [1..5]
      `h` - the radix of the encoding [1..256]

  - ### BHSDCodec

    public BHSDCodec(int b, int h, int s)
    Constructs a non-delta Codec with the given B, H and S values.
    Parameters:
      `b` - the maximum number of bytes that a value can be encoded as [1..5]
      `h` - the radix of the encoding [1..256]
      `s` - whether the encoding represents signed numbers (s=0 is unsigned; s=1 is signed with 1s complement; s=2 is signed with ?)

  - ### BHSDCodec

    public BHSDCodec(int b, int h, int s, int d)
    Constructs a Codec with the given B, H, S and D values.
    Parameters:
      `b` - the maximum number of bytes that a value can be encoded as [1..5]
      `h` - the radix of the encoding [1..256]
      `s` - whether the encoding represents signed numbers (s=0 is unsigned; s=1 is signed with 1s complement; s=2 is signed with ?)
      `d` - whether this is a delta encoding (d=0 is non-delta; d=1 is delta)

- ## Method Details

  - ### cardinality

    public long cardinality()
    Returns the cardinality of this codec; that is, the number of distinct values that it can contain.
    Returns:
      the cardinality of this codec

  - ### decode

    public int decode(InputStream in) throws IOException, Pack200Exception
    Description copied from class: `Codec`
    Decodes a sequence of bytes from the given input stream, returning the value as a long. Note that this method can only be applied for non-delta encodings.
    Specified by:
      `decode` in class `Codec`
    Parameters:
      `in` - the input stream to read from
    Returns:
      the value as a long
    Throws:
      `IOException` - if there is a problem reading from the underlying input stream
      `Pack200Exception` - if the encoding is a delta encoding

  - ### decode

    public int decode(InputStream in, long last) throws IOException, Pack200Exception
    Description copied from class: `Codec`
    Decodes a sequence of bytes from the given input stream, returning the value as a long. If this encoding is a delta encoding (d=1) then the previous value must be passed in as a parameter. If it is a non-delta encoding, then it does not matter what value is passed in, so it makes sense for the value to be passed in by default using code similar to:

         long last = 0;
         while (condition) {
             last = codec.decode(in, last);
             // do something with last
         }

    Specified by:
      `decode` in class `Codec`
    Parameters:
      `in` - the input stream to read from
      `last` - the previous value read, which must be supplied if the codec is a delta encoding
    Returns:
      the value as a long
    Throws:
      `IOException` - if there is a problem reading from the underlying input stream
      `Pack200Exception` - if there is a problem decoding the value or that the value is invalid

  - ### decodeInts

    public int[] decodeInts(int n, InputStream in) throws IOException, Pack200Exception
    Description copied from class: `Codec`
    Decodes a sequence of `n` values from `in`. This should probably be used in most cases, since some codecs (such as `PopulationCodec`) only work when the number of values to be read is known.
    Overrides:
      `decodeInts` in class `Codec`
    Parameters:
      `n` - the number of values to decode
      `in` - the input stream to read from
    Returns:
      an array of `int` values corresponding to values decoded
    Throws:
      `IOException` - if there is a problem reading from the underlying input stream
      `Pack200Exception` - if there is a problem decoding the value or that the value is invalid

  - ### decodeInts

    public int[] decodeInts(int n, InputStream in, int firstValue) throws IOException, Pack200Exception
    Description copied from class: `Codec`
    Decodes a sequence of `n` values from `in`.
    Overrides:
      `decodeInts` in class `Codec`
    Parameters:
      `n` - the number of values to decode
      `in` - the input stream to read from
      `firstValue` - the first value in the band if it has already been read
    Returns:
      an array of `int` values corresponding to values decoded, with firstValue as the first value in the array.
    Throws:
      `IOException` - if there is a problem reading from the underlying input stream
      `Pack200Exception` - if there is a problem decoding the value or that the value is invalid

  - ### encode

    public byte[] encode(int value) throws Pack200Exception
    Description copied from class: `Codec`
    Encodes a single value into a sequence of bytes. Note that this method can only be used for non-delta encodings.
    Specified by:
      `encode` in class `Codec`
    Parameters:
      `value` - the value to encode
    Returns:
      the encoded bytes
    Throws:
      `Pack200Exception` - TODO

  - ### encode

    public byte[] encode(int value, int last) throws Pack200Exception
    Description copied from class: `Codec`
    Encodes a single value into a sequence of bytes.
    Specified by:
      `encode` in class `Codec`
    Parameters:
      `value` - the value to encode
      `last` - the previous value encoded (for delta encodings)
    Returns:
      the encoded bytes
    Throws:
      `Pack200Exception` - TODO

  - ### encodes

    public boolean encodes(long value)
    True if this encoding can code the given value
    Parameters:
      `value` - the value to check
    Returns:
      `true` if the encoding can encode this value

  - ### equals

    public boolean equals(Object o)
    Overrides:
      `equals` in class `Object`

  - ### getB

    public int getB()
    Gets the B.
    Returns:
      the b

  - ### getH

    public int getH()
    Gets the H.
    Returns:
      the h

  - ### getL

    public int getL()
    Gets the L.
    Returns:
      the l

  - ### getS

    public int getS()
    Gets the S.
    Returns:
      the s

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### isDelta

    public boolean isDelta()
    Returns true if this codec is a delta codec
    Returns:
      true if this codec is a delta codec

  - ### isSigned

    public boolean isSigned()
    Returns true if this codec is a signed codec
    Returns:
      true if this codec is a signed codec

  - ### largest

    public long largest()
    Returns the largest value that this codec can represent.
    Returns:
      the largest value that this codec can represent.

  - ### smallest

    public long smallest()
    Returns the smallest value that this codec can represent.
    Returns:
      the smallest value that this codec can represent.

  - ### toString

    public String toString()
    Returns the codec in the form (1,256) or (1,64,1,1). Note that trailing zero fields are not shown.
    Overrides:
      `toString` in class `Object`