# Class RangeCoder

java.lang.Object
htsjdk.samtools.cram.compression.range.RangeCoder

public class RangeCoder extends Object
Arithmetic range coder used by the CRAM 3.1 Range (adaptive arithmetic) codec and FQZComp quality score codec. Implements both encoding and decoding using a 32-bit range with carry propagation for output byte generation.

The range coder maintains a probability interval [low, low+range) and narrows it for each symbol based on cumulative and symbol frequencies. When the range becomes too small (< 2^24), it renormalizes by shifting out the top byte.

Encoding output is written to an internal `byte[]` buffer (set via `setOutput(byte[], int)`) rather than a `ByteBuffer`, eliminating bounds checking and position tracking overhead in the hot encoding loop.

See Also:
  - `ByteModel`
  - CRAM 3.1 specification, Section 3.5

## Constructor Summary

Constructors
Constructor
Description
`RangeCoder()`

## Method Summary

Modifier and Type
Method
Description
`int`
`getOutputPosition()`
Return the current write position in the output buffer.
`protected void`
`rangeDecode(ByteBuffer inBuffer, int cumulativeFrequency, int symbolFrequency)`
Update the decoder state after a symbol has been decoded.
`void`
`rangeDecodeStart(ByteBuffer inBuffer)`
Initialize the decoder by reading the first 5 bytes of the compressed stream into the code register.
`protected void`
`rangeEncode(int cumulativeFrequency, int symbolFrequency, int totalFrequency)`
Encode a symbol by narrowing the range interval and emitting output bytes as needed.
`void`
`rangeEncodeEnd()`
Flush the encoder state by emitting the final 5 bytes.
`protected int`
`rangeGetFrequency(int totalFrequency)`
Compute the scaled frequency for symbol lookup during decoding.
`void`
`setOutput(byte[] buf, int pos)`
Set the output buffer for encoding.

### Methods inherited from class Object

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

## Constructor Details

### RangeCoder

public RangeCoder()

## Method Details

### setOutput

public void setOutput(byte[] buf, int pos)
Set the output buffer for encoding. Must be called before any encode operations.

Parameters:
  `buf` - the byte array to write compressed output to
  `pos` - the starting write position in the buffer

### getOutputPosition

public int getOutputPosition()
Return the current write position in the output buffer. Call after encoding is complete to determine how many bytes were written.

### rangeDecodeStart

public void rangeDecodeStart(ByteBuffer inBuffer)
Initialize the decoder by reading the first 5 bytes of the compressed stream into the code register. Must be called before any calls to `ByteModel.modelDecode(ByteBuffer, RangeCoder)`.

Parameters:
  `inBuffer` - the compressed input stream

### rangeDecode

protected void rangeDecode(ByteBuffer inBuffer, int cumulativeFrequency, int symbolFrequency)
Update the decoder state after a symbol has been decoded.

Parameters:
  `inBuffer` - the compressed input stream (for renormalization reads)
  `cumulativeFrequency` - cumulative frequency of symbols before the decoded symbol
  `symbolFrequency` - frequency of the decoded symbol

### rangeGetFrequency

protected int rangeGetFrequency(int totalFrequency)
Compute the scaled frequency for symbol lookup during decoding.

Parameters:
  `totalFrequency` - the sum of all symbol frequencies
Returns:
  the scaled frequency value used to identify the decoded symbol

### rangeEncode

protected void rangeEncode(int cumulativeFrequency, int symbolFrequency, int totalFrequency)
Encode a symbol by narrowing the range interval and emitting output bytes as needed. Output is written to the internal byte[] buffer (set via `setOutput(byte[], int)`).

Parameters:
  `cumulativeFrequency` - cumulative frequency of all symbols before this one
  `symbolFrequency` - frequency of the symbol being encoded
  `totalFrequency` - sum of all symbol frequencies

### rangeEncodeEnd

public void rangeEncodeEnd()
Flush the encoder state by emitting the final 5 bytes. Must be called after all symbols have been encoded to produce a valid compressed stream.