Renamed field ArithmeticCoderBase.STATE_SIZE to numStateBits/num_state_bits (including mentions in comments), in all languages.

Author: nayuki

cpp/ArithmeticCoder.cpp

@@ -17,8 +17,8 @@ using std::uint64_t;
 ArithmeticCoderBase::ArithmeticCoderBase(int stateSize) {
 	if (stateSize < 1 || stateSize > 63)
 		throw std::domain_error("State size out of range");
-	STATE_SIZE = stateSize;
-	MAX_RANGE = static_cast<decltype(MAX_RANGE)>(1) << STATE_SIZE;
+	numStateBits = stateSize;
+	MAX_RANGE = static_cast<decltype(MAX_RANGE)>(1) << numStateBits;
 	TOP_MASK = MAX_RANGE >> 1;
 	SECOND_MASK = TOP_MASK >> 1;
 	MIN_RANGE = (MAX_RANGE >> 2) + 2;
@@ -75,7 +75,7 @@ ArithmeticDecoder::ArithmeticDecoder(int stateSize, BitInputStream &in) :
 		ArithmeticCoderBase(stateSize),
 		input(in),
 		code(0) {
-	for (int i = 0; i < STATE_SIZE; i++)
+	for (int i = 0; i < numStateBits; i++)
 		code = code << 1 | readCodeBit();
 }
 
@@ -151,7 +151,7 @@ void ArithmeticEncoder::finish() {
 
 
 void ArithmeticEncoder::shift() {
-	int bit = static_cast<int>(low >> (STATE_SIZE - 1));
+	int bit = static_cast<int>(low >> (numStateBits - 1));
 	output.write(bit);
 
 	// Write out the saved underflow bits

cpp/ArithmeticCoder.hpp

@@ -29,19 +29,19 @@ class ArithmeticCoderBase {
 	// - But for state sizes greater than the midpoint, because intermediate computations are limited
 	//   to the long integer type's 63-bit unsigned precision, larger state sizes will decrease the
 	//   maximum frequency total, which might constrain the user-supplied probability model.
-	// - Therefore STATE_SIZE=32 is recommended as the most versatile setting
+	// - Therefore numStateBits=32 is recommended as the most versatile setting
 	//   because it maximizes MAX_TOTAL (which ends up being slightly over 2^30).
-	// - Note that STATE_SIZE=63 is legal but useless because it implies MAX_TOTAL=1,
+	// - Note that numStateBits=63 is legal but useless because it implies MAX_TOTAL=1,
 	//   which means a frequency table can only support one symbol with non-zero frequency.
-	protected: int STATE_SIZE;
+	protected: int numStateBits;
 
-	// Maximum range (high+1-low) during coding (trivial), which is 2^STATE_SIZE = 1000...000.
+	// Maximum range (high+1-low) during coding (trivial), which is 2^numStateBits = 1000...000.
 	protected: std::uint64_t MAX_RANGE;
 
-	// The top bit at width STATE_SIZE, which is 0100...000.
+	// The top bit at width numStateBits, which is 0100...000.
 	protected: std::uint64_t TOP_MASK;
 
-	// The second highest bit at width STATE_SIZE, which is 0010...000. This is zero when STATE_SIZE=1.
+	// The second highest bit at width numStateBits, which is 0010...000. This is zero when numStateBits=1.
 	protected: std::uint64_t SECOND_MASK;
 
 	// Minimum range (high+1-low) during coding (non-trivial), which is 0010...010.
@@ -50,7 +50,7 @@ class ArithmeticCoderBase {
 	// Maximum allowed total from a frequency table at all times during coding.
 	protected: std::uint64_t MAX_TOTAL;
 
-	// Bit mask of STATE_SIZE ones, which is 0111...111.
+	// Bit mask of numStateBits ones, which is 0111...111.
 	protected: std::uint64_t MASK;
 
 
@@ -77,14 +77,14 @@ class ArithmeticCoderBase {
 	// Updates the code range (low and high) of this arithmetic coder as a result
 	// of processing the given symbol with the given frequency table.
 	// Invariants that are true before and after encoding/decoding each symbol:
-	// * 0 <= low <= code <= high < 2^STATE_SIZE. ('code' exists only in the decoder.)
-	//   Therefore these variables are unsigned integers of STATE_SIZE bits.
-	// * (low < 1/2 * 2^STATE_SIZE) && (high >= 1/2 * 2^STATE_SIZE).
+	// * 0 <= low <= code <= high < 2^numStateBits. ('code' exists only in the decoder.)
+	//   Therefore these variables are unsigned integers of numStateBits bits.
+	// * (low < 1/2 * 2^numStateBits) && (high >= 1/2 * 2^numStateBits).
 	//   In other words, they are in different halves of the full range.
-	// * (low < 1/4 * 2^STATE_SIZE) || (high >= 3/4 * 2^STATE_SIZE).
+	// * (low < 1/4 * 2^numStateBits) || (high >= 3/4 * 2^numStateBits).
 	//   In other words, they are not both in the middle two quarters.
 	// * Let range = high - low + 1, then MAX_RANGE/4 < MIN_RANGE <= range
-	//   <= MAX_RANGE = 2^STATE_SIZE. These invariants for 'range' essentially dictate the maximum
+	//   <= MAX_RANGE = 2^numStateBits. These invariants for 'range' essentially dictate the maximum
 	//   total that the incoming frequency table can have, such that intermediate calculations don't overflow.
 	protected: virtual void update(const FrequencyTable &freqs, std::uint32_t symbol);
 

java/src/ArithmeticCoderBase.java

@@ -28,21 +28,21 @@ public abstract class ArithmeticCoderBase {
 	 *   <li>But for state sizes greater than the midpoint, because intermediate computations are limited
 	 *   to the long integer type's 63-bit unsigned precision, larger state sizes will decrease the
 	 *   maximum frequency total, which might constrain the user-supplied probability model.</li>
-	 *   <li>Therefore STATE_SIZE=32 is recommended as the most versatile setting
+	 *   <li>Therefore numStateBits=32 is recommended as the most versatile setting
 	 *   because it maximizes MAX_TOTAL (which ends up being slightly over 2^30).</li>
-	 *   <li>Note that STATE_SIZE=62 is legal but useless because it implies MAX_TOTAL=1,
+	 *   <li>Note that numStateBits=62 is legal but useless because it implies MAX_TOTAL=1,
 	 *   which means a frequency table can only support one symbol with non-zero frequency.</li>
 	 * </ul>
 	 */
-	protected final int STATE_SIZE;
+	protected final int numStateBits;
 
-	/** Maximum range (high+1-low) during coding (trivial), which is 2^STATE_SIZE = 1000...000. */
+	/** Maximum range (high+1-low) during coding (trivial), which is 2^numStateBits = 1000...000. */
 	protected final long MAX_RANGE;
 
-	/** The top bit at width STATE_SIZE, which is 0100...000. */
+	/** The top bit at width numStateBits, which is 0100...000. */
 	protected final long TOP_MASK;
 
-	/** The second highest bit at width STATE_SIZE, which is 0010...000. This is zero when STATE_SIZE=1. */
+	/** The second highest bit at width numStateBits, which is 0010...000. This is zero when numStateBits=1. */
 	protected final long SECOND_MASK;
 
 	/** Minimum range (high+1-low) during coding (non-trivial), which is 0010...010. */
@@ -51,7 +51,7 @@ public abstract class ArithmeticCoderBase {
 	/** Maximum allowed total from a frequency table at all times during coding. */
 	protected final long MAX_TOTAL;
 
-	/** Bit mask of STATE_SIZE ones, which is 0111...111. */
+	/** Bit mask of numStateBits ones, which is 0111...111. */
 	protected final long MASK;
 
 
@@ -80,8 +80,8 @@ public abstract class ArithmeticCoderBase {
 	public ArithmeticCoderBase(int stateSize) {
 		if (stateSize < 1 || stateSize > 62)
 			throw new IllegalArgumentException("State size out of range");
-		STATE_SIZE = stateSize;
-		MAX_RANGE = 1L << STATE_SIZE;
+		numStateBits = stateSize;
+		MAX_RANGE = 1L << numStateBits;
 		TOP_MASK = MAX_RANGE >>> 1;
 		SECOND_MASK = TOP_MASK >>> 1;
 		MIN_RANGE = (MAX_RANGE >>> 2) + 2;
@@ -101,14 +101,14 @@ public ArithmeticCoderBase(int stateSize) {
 	 * of processing the specified symbol with the specified frequency table.
 	 * <p>Invariants that are true before and after encoding/decoding each symbol:</p>
 	 * <ul>
-	 *   <li>0 &le; low &le; code &le; high &lt; 2<sup>STATE_SIZE</sup>. ('code' exists only in the decoder.)
-	 *   Therefore these variables are unsigned integers of STATE_SIZE bits.</li>
-	 *   <li>(low &lt; 1/2 * 2<sup>STATE_SIZE</sup>) && (high &ge; 1/2 * 2<sup>STATE_SIZE</sup>).
+	 *   <li>0 &le; low &le; code &le; high &lt; 2<sup>numStateBits</sup>. ('code' exists only in the decoder.)
+	 *   Therefore these variables are unsigned integers of numStateBits bits.</li>
+	 *   <li>(low &lt; 1/2 * 2<sup>numStateBits</sup>) && (high &ge; 1/2 * 2<sup>numStateBits</sup>).
 	 *   In other words, they are in different halves of the full range.</li>
-	 *   <li>(low &lt; 1/4 * 2<sup>STATE_SIZE</sup>) || (high &ge; 3/4 * 2<sup>STATE_SIZE</sup>).
+	 *   <li>(low &lt; 1/4 * 2<sup>numStateBits</sup>) || (high &ge; 3/4 * 2<sup>numStateBits</sup>).
 	 *   In other words, they are not both in the middle two quarters.</li>
 	 *   <li>Let range = high &minus; low + 1, then MAX_RANGE/4 &lt; MIN_RANGE &le; range
-	 *   &le; MAX_RANGE = 2<sup>STATE_SIZE</sup>. These invariants for 'range' essentially dictate the maximum
+	 *   &le; MAX_RANGE = 2<sup>numStateBits</sup>. These invariants for 'range' essentially dictate the maximum
 	 *   total that the incoming frequency table can have, such that intermediate calculations don't overflow.</li>
 	 * </ul>
 	 * @param freqs the frequency table to use

java/src/ArithmeticDecoder.java

@@ -41,7 +41,7 @@ public ArithmeticDecoder(int stateSize, BitInputStream in) throws IOException {
 		super(stateSize);
 		input = Objects.requireNonNull(in);
 		code = 0;
-		for (int i = 0; i < STATE_SIZE; i++)
+		for (int i = 0; i < numStateBits; i++)
 			code = code << 1 | readCodeBit();
 	}
 

java/src/ArithmeticEncoder.java

@@ -88,7 +88,7 @@ public void finish() throws IOException {
 
 
 	protected void shift() throws IOException {
-		int bit = (int)(low >>> (STATE_SIZE - 1));
+		int bit = (int)(low >>> (numStateBits - 1));
 		output.write(bit);
 
 		// Write out the saved underflow bits

python/arithmeticcoding.py

@@ -30,20 +30,20 @@ def __init__(self, statesize):
 		#   and compression gains beyond ~30 bits essentially zero in real-world applications.
 		# - Python has native bigint arithmetic, so there is no upper limit to the state size.
 		#   For Java and C++ where using native machine-sized integers makes the most sense,
-		#   they have a recommended value of STATE_SIZE=32 as the most versatile setting.
-		self.STATE_SIZE = statesize
-		# Maximum range (high+1-low) during coding (trivial), which is 2^STATE_SIZE = 1000...000.
-		self.MAX_RANGE = 1 << self.STATE_SIZE
-		# The top bit at width STATE_SIZE, which is 0100...000.
+		#   they have a recommended value of num_state_bits=32 as the most versatile setting.
+		self.num_state_bits = statesize
+		# Maximum range (high+1-low) during coding (trivial), which is 2^num_state_bits = 1000...000.
+		self.MAX_RANGE = 1 << self.num_state_bits
+		# The top bit at width num_state_bits, which is 0100...000.
 		self.TOP_MASK = self.MAX_RANGE >> 1
-		# The second highest bit at width STATE_SIZE, which is 0010...000. This is zero when STATE_SIZE=1.
+		# The second highest bit at width num_state_bits, which is 0010...000. This is zero when num_state_bits=1.
 		self.SECOND_MASK = self.TOP_MASK >> 1
 		# Minimum range (high+1-low) during coding (non-trivial), which is 0010...010.
 		self.MIN_RANGE = (self.MAX_RANGE >> 2) + 2
 		# Maximum allowed total from a frequency table at all times during coding. This differs from Java
 		# and C++ because Python's native bigint avoids constraining the size of intermediate computations.
 		self.MAX_TOTAL = self.MIN_RANGE
-		# Bit mask of STATE_SIZE ones, which is 0111...111.
+		# Bit mask of num_state_bits ones, which is 0111...111.
 		self.MASK = self.MAX_RANGE - 1
 
 		# -- State fields --
@@ -56,14 +56,14 @@ def __init__(self, statesize):
 	# Updates the code range (low and high) of this arithmetic coder as a result
 	# of processing the given symbol with the given frequency table.
 	# Invariants that are true before and after encoding/decoding each symbol:
-	# - 0 <= low <= code <= high < 2^STATE_SIZE. ('code' exists only in the decoder.)
-	#   Therefore these variables are unsigned integers of STATE_SIZE bits.
-	# - (low < 1/2 * 2^STATE_SIZE) && (high >= 1/2 * 2^STATE_SIZE).
+	# - 0 <= low <= code <= high < 2^num_state_bits. ('code' exists only in the decoder.)
+	#   Therefore these variables are unsigned integers of num_state_bits bits.
+	# - (low < 1/2 * 2^num_state_bits) && (high >= 1/2 * 2^num_state_bits).
 	#   In other words, they are in different halves of the full range.
-	# - (low < 1/4 * 2^STATE_SIZE) || (high >= 3/4 * 2^STATE_SIZE).
+	# - (low < 1/4 * 2^num_state_bits) || (high >= 3/4 * 2^num_state_bits).
 	#   In other words, they are not both in the middle two quarters.
 	# - Let range = high - low + 1, then MAX_RANGE/4 < MIN_RANGE <= range
-	#   <= MAX_RANGE = 2^STATE_SIZE. These invariants for 'range' essentially
+	#   <= MAX_RANGE = 2^num_state_bits. These invariants for 'range' essentially
 	#   dictate the maximum total that the incoming frequency table can have.
 	def update(self, freqs, symbol):
 		# State check
@@ -142,7 +142,7 @@ def finish(self):
 
 
 	def shift(self):
-		bit = self.low >> (self.STATE_SIZE - 1)
+		bit = self.low >> (self.num_state_bits - 1)
 		self.output.write(bit)
 
 		# Write out the saved underflow bits
@@ -167,7 +167,7 @@ def __init__(self, statesize, bitin):
 		self.input = bitin
 		# The current raw code bits being buffered, which is always in the range [low, high].
 		self.code = 0
-		for _ in range(self.STATE_SIZE):
+		for _ in range(self.num_state_bits):
 			self.code = self.code << 1 | self.read_code_bit()