Updated and synchronized documentation comments for QrCode class's constructor and static factory functions, in all languages.

pull/39/merge
Project Nayuki 7 years ago
parent fe2c384e97
commit 76f97dd0b8

@ -256,8 +256,8 @@ struct qrcodegen_Segment qrcodegen_makeEci(long assignVal, uint8_t buf[]);
* QR Code creation succeeded, or false if the data is too long to fit in any version. The ECC level * QR Code creation succeeded, or false if the data is too long to fit in any version. The ECC level
* of the result may be higher than the ecl argument if it can be done without increasing the version. * of the result may be higher than the ecl argument if it can be done without increasing the version.
* This function allows the user to create a custom sequence of segments that switches * This function allows the user to create a custom sequence of segments that switches
* between modes (such as alphanumeric and binary) to encode text more efficiently. * between modes (such as alphanumeric and byte) to encode text in less space.
* This function is considered to be lower level than simply encoding text or binary data. * This is a low-level API; the high-level API is qrcodegen_encodeText() and qrcodegen_encodeBinary().
* To save memory, the segments' data buffers can alias/overlap tempBuffer, and will * To save memory, the segments' data buffers can alias/overlap tempBuffer, and will
* result in them being clobbered, but the QR Code output will still be correct. * result in them being clobbered, but the QR Code output will still be correct.
* But the qrcode array must not overlap tempBuffer or any segment's data buffer. * But the qrcode array must not overlap tempBuffer or any segment's data buffer.
@ -269,10 +269,14 @@ bool qrcodegen_encodeSegments(const struct qrcodegen_Segment segs[], size_t len,
/* /*
* Renders a QR Code representing the given segments with the given encoding parameters. * Renders a QR Code representing the given segments with the given encoding parameters.
* Returns true if QR Code creation succeeded, or false if the data is too long to fit in the range of versions. * Returns true if QR Code creation succeeded, or false if the data is too long to fit in the range of versions.
* The smallest possible QR Code version within the given range is automatically chosen for the output. * The smallest possible QR Code version within the given range is automatically
* chosen for the output. Iff boostEcl is true, then the ECC level of the result
* may be higher than the ecl argument if it can be done without increasing the
* version. The mask number is either between 0 to 7 (inclusive) to force that
* mask, or -1 to automatically choose an appropriate mask (which may be slow).
* This function allows the user to create a custom sequence of segments that switches * This function allows the user to create a custom sequence of segments that switches
* between modes (such as alphanumeric and binary) to encode text more efficiently. * between modes (such as alphanumeric and byte) to encode text in less space.
* This function is considered to be lower level than simply encoding text or binary data. * This is a low-level API; the high-level API is qrcodegen_encodeText() and qrcodegen_encodeBinary().
* To save memory, the segments' data buffers can alias/overlap tempBuffer, and will * To save memory, the segments' data buffers can alias/overlap tempBuffer, and will
* result in them being clobbered, but the QR Code output will still be correct. * result in them being clobbered, but the QR Code output will still be correct.
* But the qrcode array must not overlap tempBuffer or any segment's data buffer. * But the qrcode array must not overlap tempBuffer or any segment's data buffer.

@ -80,7 +80,7 @@ class QrCode final {
/* /*
* Returns a QR Code representing the given binary data string at the given error correction level. * Returns a QR Code representing the given binary data at the given error correction level.
* This function always encodes using the binary segment mode, not any text mode. The maximum number of * This function always encodes using the binary segment mode, not any text mode. The maximum number of
* bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output. * bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output.
* The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version. * The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version.
@ -92,10 +92,14 @@ class QrCode final {
/* /*
* Returns a QR Code representing the given segments with the given encoding parameters. * Returns a QR Code representing the given segments with the given encoding parameters.
* The smallest possible QR Code version within the given range is automatically chosen for the output. * The smallest possible QR Code version within the given range is automatically
* chosen for the output. Iff boostEcl is true, then the ECC level of the result
* may be higher than the ecl argument if it can be done without increasing the
* version. The mask number is either between 0 to 7 (inclusive) to force that
* mask, or -1 to automatically choose an appropriate mask (which may be slow).
* This function allows the user to create a custom sequence of segments that switches * This function allows the user to create a custom sequence of segments that switches
* between modes (such as alphanumeric and binary) to encode text more efficiently. * between modes (such as alphanumeric and byte) to encode text in less space.
* This function is considered to be lower level than simply encoding text or binary data. * This is a mid-level API; the high-level API is encodeText() and encodeBinary().
*/ */
public: static QrCode encodeSegments(const std::vector<QrSegment> &segs, Ecc ecl, public: static QrCode encodeSegments(const std::vector<QrSegment> &segs, Ecc ecl,
int minVersion=1, int maxVersion=40, int mask=-1, bool boostEcl=true); // All optional parameters int minVersion=1, int maxVersion=40, int mask=-1, bool boostEcl=true); // All optional parameters
@ -135,9 +139,10 @@ class QrCode final {
/*---- Constructor (low level) ----*/ /*---- Constructor (low level) ----*/
/* /*
* Creates a new QR Code with the given version number, error correction level, binary data array, * Creates a new QR Code with the given version number,
* and mask number. This is a cumbersome low-level constructor that should not be invoked directly by the user. * error correction level, data codeword bytes, and mask number.
* To go one level up, see the encodeSegments() function. * This is a low-level API that most users should not use directly.
* A mid-level API is the encodeSegments() function.
*/ */
public: QrCode(int ver, Ecc ecl, const std::vector<std::uint8_t> &dataCodewords, int mask); public: QrCode(int ver, Ecc ecl, const std::vector<std::uint8_t> &dataCodewords, int mask);

@ -75,7 +75,7 @@ public final class QrCode {
/** /**
* Returns a QR Code representing the specified binary data string at the specified error correction level. * Returns a QR Code representing the specified binary data at the specified error correction level.
* This function always encodes using the binary segment mode, not any text mode. The maximum number of * This function always encodes using the binary segment mode, not any text mode. The maximum number of
* bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output. * bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output.
* The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version. * The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version.
@ -101,8 +101,9 @@ public final class QrCode {
* level. The smallest possible QR Code version is automatically chosen for the output. The ECC level * level. The smallest possible QR Code version is automatically chosen for the output. The ECC level
* of the result may be higher than the ecl argument if it can be done without increasing the version. * of the result may be higher than the ecl argument if it can be done without increasing the version.
* <p>This function allows the user to create a custom sequence of segments that switches * <p>This function allows the user to create a custom sequence of segments that switches
* between modes (such as alphanumeric and binary) to encode text more efficiently. * between modes (such as alphanumeric and byte) to encode text in less space.
* This function is considered to be lower level than simply encoding text or binary data.</p> * This is a mid-level API; the high-level API is {@link #encodeText(String,Ecc)}
* and {@link #encodeBinary(byte[],Ecc)}.</p>
* @param segs the segments to encode * @param segs the segments to encode
* @param ecl the error correction level to use (will be boosted) * @param ecl the error correction level to use (will be boosted)
* @return a QR Code representing the segments * @return a QR Code representing the segments
@ -117,10 +118,15 @@ public final class QrCode {
/** /**
* Returns a QR Code representing the specified segments with the specified encoding parameters. * Returns a QR Code representing the specified segments with the specified encoding parameters.
* The smallest possible QR Code version within the specified range is automatically chosen for the output. * The smallest possible QR Code version within the specified range is automatically
* chosen for the output. Iff boostEcl is {@code true}, then the ECC level of the
* result may be higher than the ecl argument if it can be done without increasing
* the version. The mask number is either between 0 to 7 (inclusive) to force that
* mask, or &#x2212;1 to automatically choose an appropriate mask (which may be slow).
* <p>This function allows the user to create a custom sequence of segments that switches * <p>This function allows the user to create a custom sequence of segments that switches
* between modes (such as alphanumeric and binary) to encode text more efficiently. * between modes (such as alphanumeric and byte) to encode text in less space.
* This function is considered to be lower level than simply encoding text or binary data.</p> * This is a mid-level API; the high-level API is {@link #encodeText(String,Ecc)}
* and {@link #encodeBinary(byte[],Ecc)}.</p>
* @param segs the segments to encode * @param segs the segments to encode
* @param ecl the error correction level to use (may be boosted) * @param ecl the error correction level to use (may be boosted)
* @param minVersion the minimum allowed version of the QR symbol (at least 1) * @param minVersion the minimum allowed version of the QR symbol (at least 1)
@ -216,9 +222,10 @@ public final class QrCode {
/*---- Constructor (low level) ----*/ /*---- Constructor (low level) ----*/
/** /**
* Constructs a QR Code with the specified version number, error correction level, binary data array, and mask number. * Constructs a QR Code with the specified version number,
* <p>This is a cumbersome low-level constructor that should not be invoked directly by the user. * error correction level, data codeword bytes, and mask number.
* To go one level up, see the {@link #encodeSegments(List,Ecc,int,int,int,boolean)} function.</p> * <p>This is a low-level API that most users should not use directly. A mid-level
* API is the {@link #encodeSegments(List,Ecc,int,int,int,boolean)} function.</p>
* @param ver the version number to use, which must be in the range 1 to 40 (inclusive) * @param ver the version number to use, which must be in the range 1 to 40 (inclusive)
* @param ecl the error correction level to use * @param ecl the error correction level to use
* @param dataCodewords the bytes representing segments to encode (without ECC) * @param dataCodewords the bytes representing segments to encode (without ECC)

@ -75,9 +75,10 @@ var qrcodegen = new function() {
* supply the appropriate version number, and call the QrCode() constructor. * supply the appropriate version number, and call the QrCode() constructor.
* (Note that all ways require supplying the desired error correction level.) * (Note that all ways require supplying the desired error correction level.)
* *
* This constructor creates a new QR Code with the given version number, error correction level, binary data array, * This constructor creates a new QR Code with the given version number,
* and mask number. mask = -1 is for automatic choice, or 0 to 7 for fixed choice. This is a cumbersome low-level constructor * error correction level, data codeword bytes, and mask number.
* that should not be invoked directly by the user. To go one level up, see the QrCode.encodeSegments() function. * This is a low-level API that most users should not use directly.
* A mid-level API is the encodeSegments() function.
*/ */
this.QrCode = function(version, errCorLvl, dataCodewords, mask) { this.QrCode = function(version, errCorLvl, dataCodewords, mask) {
@ -541,7 +542,7 @@ var qrcodegen = new function() {
/* /*
* Returns a QR Code representing the given binary data string at the given error correction level. * Returns a QR Code representing the given binary data at the given error correction level.
* This function always encodes using the binary segment mode, not any text mode. The maximum number of * This function always encodes using the binary segment mode, not any text mode. The maximum number of
* bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output. * bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output.
* The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version. * The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version.
@ -556,10 +557,14 @@ var qrcodegen = new function() {
/* /*
* Returns a QR Code representing the given segments with the given encoding parameters. * Returns a QR Code representing the given segments with the given encoding parameters.
* The smallest possible QR Code version within the given range is automatically chosen for the output. * The smallest possible QR Code version within the given range is automatically
* chosen for the output. Iff boostEcl is true, then the ECC level of the result
* may be higher than the ecl argument if it can be done without increasing the
* version. The mask number is either between 0 to 7 (inclusive) to force that
* mask, or -1 to automatically choose an appropriate mask (which may be slow).
* This function allows the user to create a custom sequence of segments that switches * This function allows the user to create a custom sequence of segments that switches
* between modes (such as alphanumeric and binary) to encode text more efficiently. * between modes (such as alphanumeric and byte) to encode text in less space.
* This function is considered to be lower level than simply encoding text or binary data. * This is a mid-level API; the high-level API is encodeText() and encodeBinary().
*/ */
this.QrCode.encodeSegments = function(segs, ecl, minVersion, maxVersion, mask, boostEcl) { this.QrCode.encodeSegments = function(segs, ecl, minVersion, maxVersion, mask, boostEcl) {
if (minVersion == undefined) minVersion = MIN_VERSION; if (minVersion == undefined) minVersion = MIN_VERSION;

@ -91,7 +91,7 @@ class QrCode(object):
@staticmethod @staticmethod
def encode_binary(data, ecl): def encode_binary(data, ecl):
"""Returns a QR Code representing the given binary data string at the given error correction level. """Returns a QR Code representing the given binary data at the given error correction level.
This function always encodes using the binary segment mode, not any text mode. The maximum number of This function always encodes using the binary segment mode, not any text mode. The maximum number of
bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output. bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output.
The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version.""" The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version."""
@ -105,10 +105,14 @@ class QrCode(object):
@staticmethod @staticmethod
def encode_segments(segs, ecl, minversion=1, maxversion=40, mask=-1, boostecl=True): def encode_segments(segs, ecl, minversion=1, maxversion=40, mask=-1, boostecl=True):
"""Returns a QR Code representing the given segments with the given encoding parameters. """Returns a QR Code representing the given segments with the given encoding parameters.
The smallest possible QR Code version within the given range is automatically chosen for the output. The smallest possible QR Code version within the given range is automatically
chosen for the output. Iff boostecl is true, then the ECC level of the result
may be higher than the ecl argument if it can be done without increasing the
version. The mask number is either between 0 to 7 (inclusive) to force that
mask, or -1 to automatically choose an appropriate mask (which may be slow).
This function allows the user to create a custom sequence of segments that switches This function allows the user to create a custom sequence of segments that switches
between modes (such as alphanumeric and binary) to encode text more efficiently. between modes (such as alphanumeric and byte) to encode text in less space.
This function is considered to be lower level than simply encoding text or binary data.""" This is a mid-level API; the high-level API is encode_text() and encode_binary()."""
if not (QrCode.MIN_VERSION <= minversion <= maxversion <= QrCode.MAX_VERSION) or not (-1 <= mask <= 7): if not (QrCode.MIN_VERSION <= minversion <= maxversion <= QrCode.MAX_VERSION) or not (-1 <= mask <= 7):
raise ValueError("Invalid value") raise ValueError("Invalid value")
@ -157,9 +161,10 @@ class QrCode(object):
# ---- Constructor (low level) ---- # ---- Constructor (low level) ----
def __init__(self, version, errcorlvl, datacodewords, mask): def __init__(self, version, errcorlvl, datacodewords, mask):
"""Creates a new QR Code with the given version number, error correction level, binary data array, """Creates a new QR Code with the given version number,
and mask number. mask = -1 is for automatic choice, or 0 to 7 for fixed choice. This is a cumbersome low-level constructor error correction level, data codeword bytes, and mask number.
that should not be invoked directly by the user. To go one level up, see the QrCode.encode_segments() function.""" This is a low-level API that most users should not use directly.
A mid-level API is the encode_segments() function."""
# Check scalar arguments and set fields # Check scalar arguments and set fields
if not (QrCode.MIN_VERSION <= version <= QrCode.MAX_VERSION): if not (QrCode.MIN_VERSION <= version <= QrCode.MAX_VERSION):

@ -90,7 +90,7 @@ impl QrCode {
} }
// Returns a QR Code representing the given binary data string at the given error correction level. // Returns a QR Code representing the given binary data at the given error correction level.
// This function always encodes using the binary segment mode, not any text mode. The maximum number of // This function always encodes using the binary segment mode, not any text mode. The maximum number of
// bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output. // bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output.
// The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version. // The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version.
@ -107,8 +107,8 @@ impl QrCode {
// The smallest possible QR Code version is automatically chosen for the output. The ECC level // The smallest possible QR Code version is automatically chosen for the output. The ECC level
// of the result may be higher than the ecl argument if it can be done without increasing the version. // of the result may be higher than the ecl argument if it can be done without increasing the version.
// This function allows the user to create a custom sequence of segments that switches // This function allows the user to create a custom sequence of segments that switches
// between modes (such as alphanumeric and binary) to encode text more efficiently. // between modes (such as alphanumeric and byte) to encode text in less space.
// This function is considered to be lower level than simply encoding text or binary data. // This is a mid-level API; the high-level API is encode_text() and encode_binary().
// Returns a wrapped QrCode if successful, or None if the data is too long to fit in any version at the given ECC level. // Returns a wrapped QrCode if successful, or None if the data is too long to fit in any version at the given ECC level.
pub fn encode_segments(segs: &[QrSegment], ecl: QrCodeEcc) -> Option<Self> { pub fn encode_segments(segs: &[QrSegment], ecl: QrCodeEcc) -> Option<Self> {
QrCode::encode_segments_advanced(segs, ecl, QrCode_MIN_VERSION, QrCode_MAX_VERSION, None, true) QrCode::encode_segments_advanced(segs, ecl, QrCode_MIN_VERSION, QrCode_MAX_VERSION, None, true)
@ -116,10 +116,14 @@ impl QrCode {
// Returns a QR Code representing the given segments with the given encoding parameters. // Returns a QR Code representing the given segments with the given encoding parameters.
// The smallest possible QR Code version within the given range is automatically chosen for the output. // The smallest possible QR Code version within the given range is automatically
// chosen for the output. Iff boostecl is true, then the ECC level of the result
// may be higher than the ecl argument if it can be done without increasing the
// version. The mask number is either between 0 to 7 (inclusive) to force that
// mask, or -1 to automatically choose an appropriate mask (which may be slow).
// This function allows the user to create a custom sequence of segments that switches // This function allows the user to create a custom sequence of segments that switches
// between modes (such as alphanumeric and binary) to encode text more efficiently. // between modes (such as alphanumeric and byte) to encode text in less space.
// This function is considered to be lower level than simply encoding text or binary data. // This is a mid-level API; the high-level API is encodeText() and encodeBinary().
// Returns a wrapped QrCode if successful, or None if the data is too long to fit // Returns a wrapped QrCode if successful, or None if the data is too long to fit
// in any version in the given range at the given ECC level. // in any version in the given range at the given ECC level.
pub fn encode_segments_advanced(segs: &[QrSegment], mut ecl: QrCodeEcc, pub fn encode_segments_advanced(segs: &[QrSegment], mut ecl: QrCodeEcc,
@ -189,9 +193,10 @@ impl QrCode {
/*---- Constructor (low level) ----*/ /*---- Constructor (low level) ----*/
// Creates a new QR Code with the given version number, error correction level, // Creates a new QR Code with the given version number,
// binary data array, and mask number. This is a cumbersome low-level constructor that // error correction level, data codeword bytes, and mask number.
// should not be invoked directly by the user. To go one level up, see the encode_segments() function. // This is a low-level API that most users should not use directly.
// A mid-level API is the encode_segments() function.
pub fn encode_codewords(ver: Version, ecl: QrCodeEcc, datacodewords: &[u8], mask: Option<Mask>) -> Self { pub fn encode_codewords(ver: Version, ecl: QrCodeEcc, datacodewords: &[u8], mask: Option<Mask>) -> Self {
// Initialize fields // Initialize fields
let size: usize = (ver.value() as usize) * 4 + 17; let size: usize = (ver.value() as usize) * 4 + 17;

@ -64,7 +64,7 @@ namespace qrcodegen {
} }
// Returns a QR Code representing the given binary data string at the given error correction level. // Returns a QR Code representing the given binary data at the given error correction level.
// This function always encodes using the binary segment mode, not any text mode. The maximum number of // This function always encodes using the binary segment mode, not any text mode. The maximum number of
// bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output. // bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output.
// The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version. // The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version.
@ -77,10 +77,14 @@ namespace qrcodegen {
/*-- Static factory functions (mid level) --*/ /*-- Static factory functions (mid level) --*/
// Returns a QR Code representing the given segments with the given encoding parameters. // Returns a QR Code representing the given segments with the given encoding parameters.
// The smallest possible QR Code version within the given range is automatically chosen for the output. // The smallest possible QR Code version within the given range is automatically
// chosen for the output. Iff boostEcl is true, then the ECC level of the result
// may be higher than the ecl argument if it can be done without increasing the
// version. The mask number is either between 0 to 7 (inclusive) to force that
// mask, or -1 to automatically choose an appropriate mask (which may be slow).
// This function allows the user to create a custom sequence of segments that switches // This function allows the user to create a custom sequence of segments that switches
// between modes (such as alphanumeric and binary) to encode text more efficiently. // between modes (such as alphanumeric and byte) to encode text in less space.
// This function is considered to be lower level than simply encoding text or binary data. // This is a mid-level API; the high-level API is encodeText() and encodeBinary().
public static encodeSegments(segs: Array<QrSegment>, ecl: QrCode.Ecc, public static encodeSegments(segs: Array<QrSegment>, ecl: QrCode.Ecc,
minVersion: int = 1, maxVersion: int = 40, minVersion: int = 1, maxVersion: int = 40,
mask: int = -1, boostEcl: boolean = true): QrCode { mask: int = -1, boostEcl: boolean = true): QrCode {
@ -153,9 +157,10 @@ namespace qrcodegen {
/*-- Constructor (low level) and fields --*/ /*-- Constructor (low level) and fields --*/
// Creates a new QR Code with the given version number, error correction level, binary data array, // Creates a new QR Code with the given version number,
// and mask number. mask = -1 is for automatic choice, or 0 to 7 for fixed choice. This is a cumbersome low-level constructor // error correction level, data codeword bytes, and mask number.
// that should not be invoked directly by the user. To go one level up, see the QrCode.encodeSegments() function. // This is a low-level API that most users should not use directly.
// A mid-level API is the encodeSegments() function.
public constructor( public constructor(
// The version number of this QR Code, which is between 1 and 40 (inclusive). // The version number of this QR Code, which is between 1 and 40 (inclusive).
// This determines the size of this barcode. // This determines the size of this barcode.

Loading…
Cancel
Save