From 7d49af97e1ada84eee033abd9b808e5d40114103 Mon Sep 17 00:00:00 2001 From: Project Nayuki Date: Fri, 5 Oct 2018 00:21:12 +0000 Subject: [PATCH] Updated documentation comments for three QrSegment members, in all language versions. --- c/qrcodegen.h | 8 ++++---- cpp/QrSegment.hpp | 12 +++++++++--- java/io/nayuki/qrcodegen/QrSegment.java | 12 ++++++++---- javascript/qrcodegen.js | 7 ++++++- python/qrcodegen.py | 9 ++++++++- rust/src/lib.rs | 9 ++++++--- typescript/qrcodegen.ts | 6 +++++- 7 files changed, 46 insertions(+), 17 deletions(-) diff --git a/c/qrcodegen.h b/c/qrcodegen.h index 05b8b8f..7b93ca5 100644 --- a/c/qrcodegen.h +++ b/c/qrcodegen.h @@ -85,10 +85,9 @@ struct qrcodegen_Segment { // The mode indicator for this segment. enum qrcodegen_Mode mode; - // The length of this segment's unencoded data. Always in the range [0, 32767]. - // For numeric, alphanumeric, and kanji modes, this measures in Unicode code points. - // For byte mode, this measures in bytes (raw binary data, text in UTF-8, or other encodings). - // For ECI mode, this is always zero. + // The length of this segment's unencoded data, measured in characters for + // numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode. + // Always zero or positive. int numChars; // The data bits of this segment, packed in bitwise big endian. @@ -97,6 +96,7 @@ struct qrcodegen_Segment { // The number of valid data bits used in the buffer. Requires // 0 <= bitLength <= 32767, and bitLength <= (capacity of data array) * 8. + // The character count (numChars) must agree with the mode and the bit buffer length. int bitLength; }; diff --git a/cpp/QrSegment.hpp b/cpp/QrSegment.hpp index 45918ff..65246bd 100644 --- a/cpp/QrSegment.hpp +++ b/cpp/QrSegment.hpp @@ -109,8 +109,8 @@ class QrSegment final { /* - * Returns a list of zero or more segments to represent the given text string. - * The result may use various segment modes and switch modes to optimize the length of the bit stream. + * Returns a list of zero or more segments to represent the given text string. The result + * may use various segment modes and switch modes to optimize the length of the bit stream. */ public: static std::vector makeSegments(const char *text); @@ -142,7 +142,9 @@ class QrSegment final { /* The mode indicator for this segment. */ private: Mode mode; - /* The length of this segment's unencoded data, measured in characters. Always zero or positive. */ + /* The length of this segment's unencoded data, measured in characters for + * numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode. + * Always zero or positive. */ private: int numChars; /* The data bits of this segment. */ @@ -153,12 +155,16 @@ class QrSegment final { /* * Creates a new QR Code segment with the given parameters and data. + * The character count (numCh) must agree with the mode and the bit buffer length, + * but the constraint isn't checked. The given bit buffer is copied and stored. */ public: QrSegment(Mode md, int numCh, const std::vector &dt); /* * Creates a new QR Code data segment with the given parameters and data. + * The character count (numCh) must agree with the mode and the bit buffer length, + * but the constraint isn't checked. The given bit buffer is moved and stored. */ public: QrSegment(Mode md, int numCh, std::vector &&dt); diff --git a/java/io/nayuki/qrcodegen/QrSegment.java b/java/io/nayuki/qrcodegen/QrSegment.java index 927ebaf..b9409b9 100644 --- a/java/io/nayuki/qrcodegen/QrSegment.java +++ b/java/io/nayuki/qrcodegen/QrSegment.java @@ -106,10 +106,10 @@ public final class QrSegment { /** - * Returns a new mutable list of zero or more segments to represent the specified Unicode text string. + * Returns a list of zero or more segments to represent the specified Unicode text string. * The result may use various segment modes and switch modes to optimize the length of the bit stream. * @param text the text to be encoded, which can be any Unicode string - * @return a list of segments containing the text + * @return a new mutable list of segments containing the text * @throws NullPointerException if the text is {@code null} */ public static List makeSegments(String text) { @@ -159,7 +159,9 @@ public final class QrSegment { /** The mode indicator for this segment. Never {@code null}. */ public final Mode mode; - /** The length of this segment's unencoded data, measured in characters. Always zero or positive. */ + /** The length of this segment's unencoded data, measured in characters for + * numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode. + * Always zero or positive. */ public final int numChars; /** The data bits of this segment. Accessed through {@link getBits()}. Not {@code null}. */ @@ -170,8 +172,10 @@ public final class QrSegment { /** * Constructs a QR Code segment with the specified parameters and data. + * The character count (numCh) must agree with the mode and the bit buffer length, + * but the constraint isn't checked. The specified bit buffer is cloned and stored. * @param md the mode, which is not {@code null} - * @param numCh the data length in characters, which is non-negative + * @param numCh the data length in characters or bytes, which is non-negative * @param data the data bits of this segment, which is not {@code null} * @throws NullPointerException if the mode or data is {@code null} * @throws IllegalArgumentException if the character count is negative diff --git a/javascript/qrcodegen.js b/javascript/qrcodegen.js index 4f7a296..97754fa 100644 --- a/javascript/qrcodegen.js +++ b/javascript/qrcodegen.js @@ -698,6 +698,9 @@ var qrcodegen = new function() { * This segment class imposes no length restrictions, but QR Codes have restrictions. * Even in the most favorable conditions, a QR Code can only hold 7089 characters of data. * Any segment longer than this is meaningless for the purpose of generating QR Codes. + * This constructor creates a QR Code segment with the given parameters and data. + * The character count (numChars) must agree with the mode and the bit buffer length, + * but the constraint isn't checked. The given bit buffer is cloned and stored. */ this.QrSegment = function(mode, numChars, bitData) { /*---- Constructor (low level) ----*/ @@ -708,7 +711,9 @@ var qrcodegen = new function() { // The mode indicator for this segment. Object.defineProperty(this, "mode", {value:mode}); - // The length of this segment's unencoded data, measured in characters. Always zero or positive. + // The length of this segment's unencoded data, measured in characters for + // numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode. + // Always zero or positive. Object.defineProperty(this, "numChars", {value:numChars}); // Returns a copy of all bits, which is an array of 0s and 1s. diff --git a/python/qrcodegen.py b/python/qrcodegen.py index c4bc172..bfa9369 100644 --- a/python/qrcodegen.py +++ b/python/qrcodegen.py @@ -678,11 +678,18 @@ class QrSegment(object): # ---- Constructor (low level) ---- def __init__(self, mode, numch, bitdata): - """Creates a new QR Code segment with the given parameters and data.""" + """Creates a new QR Code segment with the given parameters and data. + The character count (numch) must agree with the mode and the bit buffer length, + but the constraint isn't checked. The given bit buffer is cloned and stored.""" if numch < 0 or not isinstance(mode, QrSegment.Mode): raise ValueError() self._mode = mode + + # The length of this segment's unencoded data, measured in characters for + # numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode. + # Always zero or positive. self._numchars = numch + self._bitdata = list(bitdata) # Make defensive copy diff --git a/rust/src/lib.rs b/rust/src/lib.rs index 1db6288..05b96ee 100644 --- a/rust/src/lib.rs +++ b/rust/src/lib.rs @@ -832,7 +832,8 @@ pub struct QrSegment { // The mode indicator for this segment. mode: QrSegmentMode, - // The length of this segment's unencoded data, measured in characters. + // The length of this segment's unencoded data, measured in characters for + // numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode. numchars: usize, // The bits of this segment. @@ -905,8 +906,8 @@ impl QrSegment { } - // Returns a new mutable list of zero or more segments to represent the given Unicode text string. - // The result may use various segment modes and switch modes to optimize the length of the bit stream. + // Returns a list of zero or more segments to represent the given Unicode text string. The result + // may use various segment modes and switch modes to optimize the length of the bit stream. pub fn make_segments(text: &[char]) -> Vec { if text.is_empty() { vec![] @@ -943,6 +944,8 @@ impl QrSegment { /*---- Constructor (low level) ----*/ // Creates a new QR Code segment with the given parameters and data. + // The character count (numchars) must agree with the mode and + // the bit buffer length, but the constraint isn't checked. pub fn new(mode: QrSegmentMode, numchars: usize, data: Vec) -> Self { Self { mode: mode, diff --git a/typescript/qrcodegen.ts b/typescript/qrcodegen.ts index 470324e..6deaaea 100644 --- a/typescript/qrcodegen.ts +++ b/typescript/qrcodegen.ts @@ -738,11 +738,15 @@ namespace qrcodegen { /*-- Constructor (low level) and fields --*/ // Creates a new QR Code segment with the given parameters and data. + // The character count (numChars) must agree with the mode and the bit buffer length, + // but the constraint isn't checked. The given bit buffer is cloned and stored. public constructor( // The mode indicator for this segment. public readonly mode: QrSegment.Mode, - // The length of this segment's unencoded data, measured in characters. Always zero or positive. + // The length of this segment's unencoded data, measured in characters for + // numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode. + // Always zero or positive. public readonly numChars: int, private readonly bitData: Array) {