From d4085a443a680aa4acfbe067de2a3226f3b909b6 Mon Sep 17 00:00:00 2001 From: Project Nayuki Date: Fri, 3 Dec 2021 05:56:54 +0000 Subject: [PATCH] Revamped documentation comments about argument arrays in the C and Rust-no-heap ports. --- c/qrcodegen.h | 33 ++++++++++++++++++++++++--------- rust-no-heap/src/lib.rs | 25 ++++++++++++++++++------- 2 files changed, 42 insertions(+), 16 deletions(-) diff --git a/c/qrcodegen.h b/c/qrcodegen.h index b9e73eb..922f764 100644 --- a/c/qrcodegen.h +++ b/c/qrcodegen.h @@ -154,9 +154,17 @@ struct qrcodegen_Segment { * - The input text must be encoded in UTF-8 and contain no NULs. * - The variables ecl and mask must correspond to enum constant values. * - Requires 1 <= minVersion <= maxVersion <= 40. - * - The arrays tempBuffer and qrcode must each have a length of at least - * qrcodegen_BUFFER_LEN_FOR_VERSION(maxVersion), and cannot overlap. - * - After the function returns, tempBuffer contains no useful data. + * - About the arrays, letting len = qrcodegen_BUFFER_LEN_FOR_VERSION(maxVersion): + * - Before calling the function: + * - The array ranges tempBuffer[0 : len] and qrcode[0 : len] must allow + * reading and writing; hence each array must have a length of at least len. + * - The two ranges must not overlap (aliasing). + * - The initial state of both ranges can be uninitialized + * because the function always writes before reading. + * - After the function returns: + * - Both ranges have no guarantee on which elements are initialized and what values are stored. + * - tempBuffer contains no useful data and should be treated as entirely uninitialzed. + * - If successful, qrcode can be passed into qrcodegen_getSize() and qrcodegen_getModule(). * - If successful, the resulting QR Code may use numeric, * alphanumeric, or byte mode to encode the text. * - In the most optimistic case, a QR Code at version 40 with low ECC @@ -174,14 +182,21 @@ bool qrcodegen_encodeText(const char *text, uint8_t tempBuffer[], uint8_t qrcode * Encodes the given binary data to a QR Code, returning true if encoding succeeded. * If the data is too long to fit in any version in the given range * at the given ECC level, then false is returned. - * - The input array range dataAndTemp[0 : dataLen] should normally be - * valid UTF-8 text, but is not required by the QR Code standard. * - The variables ecl and mask must correspond to enum constant values. * - Requires 1 <= minVersion <= maxVersion <= 40. - * - The arrays dataAndTemp and qrcode must each have a length of at least - * qrcodegen_BUFFER_LEN_FOR_VERSION(maxVersion), and cannot overlap. - * - After the function returns, the contents of dataAndTemp may have changed, - * and does not represent useful data anymore. + * - About the arrays, letting len = qrcodegen_BUFFER_LEN_FOR_VERSION(maxVersion): + * - Before calling the function: + * - The array ranges dataAndTemp[0 : len] and qrcode[0 : len] must allow + * reading and writing; hence each array must have a length of at least len. + * - The two ranges must not overlap (aliasing). + * - The input array range dataAndTemp[0 : dataLen] should normally be + * valid UTF-8 text, but is not required by the QR Code standard. + * - The initial state of dataAndTemp[dataLen : len] and qrcode[0 : len] + * can be uninitialized because the function always writes before reading. + * - After the function returns: + * - Both ranges have no guarantee on which elements are initialized and what values are stored. + * - dataAndTemp contains no useful data and should be treated as entirely uninitialzed. + * - If successful, qrcode can be passed into qrcodegen_getSize() and qrcodegen_getModule(). * - If successful, the resulting QR Code will use byte mode to encode the data. * - In the most optimistic case, a QR Code at version 40 with low ECC can hold any byte * sequence up to length 2953. This is the hard upper limit of the QR Code standard. diff --git a/rust-no-heap/src/lib.rs b/rust-no-heap/src/lib.rs index c05d419..bef9a5f 100644 --- a/rust-no-heap/src/lib.rs +++ b/rust-no-heap/src/lib.rs @@ -139,7 +139,14 @@ impl<'a> QrCode<'a> { /// version. The mask number is either between 0 to 7 (inclusive) to force that /// mask, or `None` to automatically choose an appropriate mask (which may be slow). /// - /// The arrays tempbuffer and outbuffer must each have a length of at least maxversion.buffer_len(). + /// About the slices, letting len = maxversion.buffer_len(): + /// - Before calling the function: + /// - The slices tempbuffer and outbuffer each must have a length of at least len. + /// - If a slice is longer than len, then the function will not + /// read from or write to the suffix array[len .. array.len()]. + /// - The initial values of both slices can be arbitrary + /// because the function always writes before reading. + /// - After the function returns, both slices have no guarantee on what values are stored. /// /// In the most optimistic case, a QR Code at version 40 with low ECC /// can hold any UTF-8 string up to 2953 bytes, or any alphanumeric string @@ -149,8 +156,6 @@ impl<'a> QrCode<'a> { /// Please consult the QR Code specification for information on /// data capacities per version, ECC level, and text encoding mode. /// - /// After the function returns, tempbuffer contains no useful data. - /// /// If successful, the resulting QR Code may use numeric, alphanumeric, or byte mode to encode the text. /// /// Returns a wrapped `QrCode` if successful, or `Err` if the @@ -185,7 +190,16 @@ impl<'a> QrCode<'a> { /// Returns a QR Code representing the given binary data with the given encoding parameters. /// - /// The arrays dataandtemp and outbuffer must each have a length of at least maxversion.buffer_len(). + /// About the slices, letting len = maxversion.buffer_len(): + /// - Before calling the function: + /// - The slices dataandtempbuffer and outbuffer each must have a length of at least len. + /// - If a slice is longer than len, then the function will not + /// read from or write to the suffix array[len .. array.len()]. + /// - The input slice range dataandtempbuffer[0 .. datalen] should normally be + /// valid UTF-8 text, but is not required by the QR Code standard. + /// - The initial values of dataandtempbuffer[datalen .. len] and outbuffer[0 .. len] + /// can be arbitrary because the function always writes before reading. + /// - After the function returns, both slices have no guarantee on what values are stored. /// /// In the most optimistic case, a QR Code at version 40 with low ECC can hold any byte /// sequence up to length 2953. This is the hard upper limit of the QR Code standard. @@ -193,9 +207,6 @@ impl<'a> QrCode<'a> { /// Please consult the QR Code specification for information on /// data capacities per version, ECC level, and text encoding mode. /// - /// After the function returns, the contents of dataandtemp may have changed, - /// and does not represent useful data anymore. - /// /// If successful, the resulting QR Code will use byte mode to encode the data. /// /// Returns a wrapped `QrCode` if successful, or `Err` if the