diff --git a/cpp/BitBuffer.hpp b/cpp/BitBuffer.hpp index 2e6e673..be00ee4 100644 --- a/cpp/BitBuffer.hpp +++ b/cpp/BitBuffer.hpp @@ -30,7 +30,7 @@ namespace qrcodegen { /* - * An appendable sequence of bits. Bits are packed in big endian within a byte. + * An appendable sequence of bits (0's and 1's). */ class BitBuffer final : public std::vector { @@ -43,12 +43,13 @@ class BitBuffer final : public std::vector { /*---- Methods ----*/ - // Returns a copy of all bytes, padding up to the nearest byte. Bits are packed in big endian within a byte. + // Packs this buffer's bits into bytes in big endian, + // padding with '0' bit values, and returns the new vector. public: std::vector getBytes() const; - // Appends the given number of bits of the given value to this sequence. - // If 0 <= len <= 31, then this requires 0 <= val < 2^len. + // Appends the given number of low bits of the given value + // to this sequence. Requires 0 <= val < 2^len. public: void appendBits(std::uint32_t val, int len); }; diff --git a/java/io/nayuki/qrcodegen/BitBuffer.java b/java/io/nayuki/qrcodegen/BitBuffer.java index fad2e67..f43cc12 100644 --- a/java/io/nayuki/qrcodegen/BitBuffer.java +++ b/java/io/nayuki/qrcodegen/BitBuffer.java @@ -28,20 +28,23 @@ import java.util.Objects; /** - * An appendable sequence of bits. Bits are packed in big endian within a byte. + * An appendable sequence of bits (0's and 1's). */ public final class BitBuffer implements Cloneable { /*---- Fields ----*/ private BitSet data; + private int bitLength; /*---- Constructor ----*/ - // Creates an empty bit buffer (length 0). + /** + * Constructs an empty bit buffer (length 0). + */ public BitBuffer() { data = new BitSet(); bitLength = 0; @@ -51,13 +54,21 @@ public final class BitBuffer implements Cloneable { /*---- Methods ----*/ - // Returns the number of bits in the buffer, which is a non-negative value. + /** + * Returns the length of this sequence, which is a non-negative value. + * @return the length of this sequence + */ public int bitLength() { return bitLength; } - // Returns the bit at the given index, yielding 0 or 1, or throwing IndexOutOfBoundsException. + /** + * Returns the bit at the specified index, yielding 0 or 1. + * @param index the index to get the bit at + * @return the bit at the specified index + * @throws IndexOutOfBoundsException if index < 0 or index ≥ bitLength + */ public int getBit(int index) { if (index < 0 || index >= bitLength) throw new IndexOutOfBoundsException(); @@ -65,7 +76,11 @@ public final class BitBuffer implements Cloneable { } - // Returns a copy of all bytes, padding up to the nearest byte. Bits are packed in big endian within a byte. + /** + * Packs this buffer's bits into bytes in big endian, + * padding with '0' bit values, and returns the new array. + * @return this sequence as a new array of bytes (not {@code null}) + */ public byte[] getBytes() { byte[] result = new byte[(bitLength + 7) / 8]; for (int i = 0; i < bitLength; i++) @@ -74,8 +89,12 @@ public final class BitBuffer implements Cloneable { } - // Appends the given number of bits of the given value to this sequence. - // If 0 <= len <= 31, then this requires 0 <= val < 2^len. + /** + * Appends the specified number of low bits of the specified value + * to this sequence. Requires 0 ≤ val < 2len. + * @param val the value to append + * @param len the number of low bits in the value to take + */ public void appendBits(int val, int len) { if (len < 0 || len > 31 || val >>> len != 0) throw new IllegalArgumentException("Value out of range"); @@ -84,7 +103,11 @@ public final class BitBuffer implements Cloneable { } - // Appends the data of the given segment to this bit buffer. + /** + * Appends the bit data of the specified segment to this bit buffer. + * @param seg the segment whose data to append (not {@code null}) + * @throws NullPointerException if the segment is {@code null} + */ public void appendData(QrSegment seg) { Objects.requireNonNull(seg); BitBuffer bb = seg.data; @@ -93,7 +116,10 @@ public final class BitBuffer implements Cloneable { } - // Returns a copy of this bit buffer object. + /** + * Returns a copy of this bit buffer object. + * @return a copy of this bit buffer object + */ public BitBuffer clone() { try { BitBuffer result = (BitBuffer)super.clone(); diff --git a/javascript/qrcodegen.js b/javascript/qrcodegen.js index d7fa3a5..94031f1 100644 --- a/javascript/qrcodegen.js +++ b/javascript/qrcodegen.js @@ -736,7 +736,7 @@ var qrcodegen = new function() { this.QrSegment = function(mode, numChars, bitData) { if (numChars < 0 || !(mode instanceof Mode)) throw "Invalid argument"; - bitData = bitData.slice(); + bitData = bitData.slice(); // Make defensive copy // The mode indicator for this segment. Object.defineProperty(this, "mode", {value:mode}); @@ -746,7 +746,7 @@ var qrcodegen = new function() { // Returns a copy of all bits, which is an array of 0s and 1s. this.getBits = function() { - return bitData.slice(); + return bitData.slice(); // Make defensive copy }; }; @@ -992,7 +992,8 @@ var qrcodegen = new function() { */ function BitBuffer() { - // Returns a copy of all bytes, padding up to the nearest byte. + // Packs this buffer's bits into bytes in big endian, + // padding with '0' bit values, and returns the new array. this.getBytes = function() { var result = []; while (result.length * 8 < this.length) @@ -1003,8 +1004,8 @@ var qrcodegen = new function() { return result; }; - // Appends the given number of bits of the given value to this sequence. - // If 0 <= len <= 31, then this requires 0 <= val < 2^len. + // Appends the given number of low bits of the given value + // to this sequence. Requires 0 <= val < 2^len. this.appendBits = function(val, len) { if (len < 0 || len > 31 || val >>> len != 0) throw "Value out of range"; diff --git a/python/qrcodegen.py b/python/qrcodegen.py index 97b8f5f..d149a67 100644 --- a/python/qrcodegen.py +++ b/python/qrcodegen.py @@ -696,7 +696,7 @@ class QrSegment(object): raise ValueError() self._mode = mode self._numchars = numch - self._bitdata = list(bitdata) # Defensive copy + self._bitdata = list(bitdata) # Make defensive copy # ---- Accessor methods ---- @@ -708,7 +708,7 @@ class QrSegment(object): return self._numchars def get_bits(self): - return list(self._bitdata) # Defensive copy + return list(self._bitdata) # Make defensive copy # Package-private helper function. @@ -833,14 +833,16 @@ class _BitBuffer(list): """An appendable sequence of bits (0's and 1's).""" def get_bytes(self): - """Returns a copy of all bytes, padding up to the nearest byte. Bits are packed in big endian within a byte.""" + """Packs this buffer's bits into bytes in big endian, + padding with '0' bit values, and returns the new list.""" result = [0] * ((len(self) + 7) // 8) for (i, bit) in enumerate(self): result[i >> 3] |= bit << (7 - (i & 7)) return result def append_bits(self, val, n): - """Appends the given number of bits of the given value to this sequence. This requires 0 <= val < 2^n.""" + """Appends the given number of low bits of the given value + to this sequence. Requires 0 <= val < 2^n.""" if n < 0 or val >> n != 0: raise ValueError("Value out of range") self.extend(((val >> i) & 1) for i in reversed(range(n)))