kastet/zint
1
0
Fork 0
mirror of https://github.com/woo-j/zint.git synced 2025-03-12 00:58:25 +03:00
Code Issues Projects Releases Wiki Activity

Add convenience API funcs ZBarcode_UTF8_To_ECI() and

Browse Source 
`ZBarcode_Dest_Len_ECI()`, primarily for ZXingC++ but also useful
  in general
This commit is contained in:
gitlost 2025-03-02 20:50:55 +00:00
parent 99f94b1027
commit d0465375bb
12 changed files with 647 additions and 167 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
ChangeLog
View File

@ -1,4 +1,4 @@
Version 2.15.0.9 (dev) not released yet (2025-02-28)
Version 2.15.0.9 (dev) not released yet (2025-03-02)
====================================================
Changes
@ -7,6 +7,10 @@ Changes
- Add new `BARCODE_RAW_TEXT` option for `output_options` and new warning
`ZINT_WARN_HRT_RAW_TEXT` for when set when outputting HRT
Changes
-------
- Add API funcs `ZBarcode_UTF8_To_ECI()` and `ZBarcode_Dest_Len_ECI()`
Bugs
----
- AZTEC: fix GS1 mode with Structured Append (wasn't outputting initial FNC1)

42
backend/eci.c
View File

@ -1,7 +1,7 @@
/* eci.c - Extended Channel Interpretations */
/*
libzint - the open source barcode library
Copyright (C) 2009-2024 Robin Stuart <rstuart114@gmail.com>
Copyright (C) 2009-2025 Robin Stuart <rstuart114@gmail.com>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
@ -43,6 +43,30 @@
/* Single-byte stuff */
/* ECI 2 (bottom half ASCII, top half CP437), included for libzueci compatibility - assumes valid Unicode */
static int u_cp437(const unsigned int u, unsigned char *dest) {
int s, e;
if (u < 0x80) {
*dest = (unsigned char) u;
return 1;
}
s = 0;
e = ARRAY_SIZE(cp437_u) - 1;
while (s <= e) {
const int m = (s + e) >> 1;
if (cp437_u[m] < u) {
s = m + 1;
} else if (cp437_u[m] > u) {
e = m - 1;
} else {
*dest = cp437_sb[m];
return 1;
}
}
return 0;
}
/* Base ISO/IEC 8859 routine to convert Unicode codepoint `u` */
static int u_iso8859(const unsigned int u, const unsigned short *tab_s, const unsigned short *tab_u,
const unsigned char *tab_sb, int e, unsigned char *dest) {
@ -181,6 +205,15 @@ static int u_utf32le(const unsigned int u, unsigned char *dest) {
return 4;
}
/* ECI 899 Binary, included for libzueci compatibility - assumes valid Unicode */
static int u_binary(const unsigned int u, unsigned char *dest) {
if (u <= 0xFF) {
*dest = (unsigned char) u;
return 1;
}
return 0;
}
/* Multibyte stuff */
/* Acknowledgements to Bruno Haible <bruno@clisp.org> for a no. of techniques used here */
@ -701,7 +734,7 @@ typedef int (*eci_func_t)(const unsigned int u, unsigned char *dest);
INTERNAL int utf8_to_eci(const int eci, const unsigned char source[], unsigned char dest[], int *p_length) {
static const eci_func_t eci_funcs[36] = {
NULL, NULL, NULL, NULL, u_iso8859_2, /*0-4*/
NULL, NULL, u_cp437, NULL, u_iso8859_2, /*0-4*/
u_iso8859_3, u_iso8859_4, u_iso8859_5, u_iso8859_6, u_iso8859_7, /*5-9*/
u_iso8859_8, u_iso8859_9, u_iso8859_10, u_iso8859_11, NULL, /*10-14*/
u_iso8859_13, u_iso8859_14, u_iso8859_15, u_iso8859_16, NULL, /*15-19*/
@ -717,7 +750,8 @@ INTERNAL int utf8_to_eci(const int eci, const unsigned char source[], unsigned c
int length = *p_length;
/* Special case ISO/IEC 8859-1 */
if (eci == 0 || eci == 3) { /* Default ECI 0 to ISO/IEC 8859-1 */
/* Default ECI 0 to ISO/IEC 8859-1 (and ECI 1 for libzueci compatibility) */
if (eci == 0 || eci == 3 || eci == 1) {
while (in_posn < length) {
do {
decode_utf8(&state, &codepoint, source[in_posn++]);
@ -737,6 +771,8 @@ INTERNAL int utf8_to_eci(const int eci, const unsigned char source[], unsigned c
if (eci == 170) { /* ASCII Invariant (archaic subset) */
eci_func = u_ascii_inv;
} else if (eci == 899) { /* Binary, for libzueci compatibility */
eci_func = u_binary;
} else {
eci_func = eci_funcs[eci];
if (eci_func == NULL) {

47
backend/eci_sb.h
View File

@ -1,9 +1,10 @@
/* eci_sb.h - Extended Channel Interpretations single-byte, generated by "backend/tools/gen_eci_sb_h.php"
from "https://unicode.org/Public/MAPPINGS/ISO8859/8859-*.TXT"
and "https://unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WINDOWS/CP125*.TXT" */
/* eci_sb.h - Extended Channel Interpretations single-byte, generated by "backend/tools/gen_eci_sb_h.php" from
"https://unicode.org/Public/MAPPINGS/VENDORS/MICSFT/PC/CP437.TXT" (for libzueci compatibility) and
"https://unicode.org/Public/MAPPINGS/ISO8859/8859-*.TXT" and
"https://unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WINDOWS/CP125*.TXT" */
/*
libzint - the open source barcode library
Copyright (C) 2021-2022 Robin Stuart <rstuart114@gmail.com>
Copyright (C) 2021-2025 Robin Stuart <rstuart114@gmail.com>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
@ -35,6 +36,44 @@
#ifndef Z_ECI_SB_H
#define Z_ECI_SB_H
/* Tables for ECI 2 CP437 (for libzueci compatibility) */
static const unsigned short cp437_u[128] = { /* Unicode codepoints sorted */
0x00A0, 0x00A1, 0x00A2, 0x00A3, 0x00A5, 0x00AA, 0x00AB, 0x00AC,
0x00B0, 0x00B1, 0x00B2, 0x00B5, 0x00B7, 0x00BA, 0x00BB, 0x00BC,
0x00BD, 0x00BF, 0x00C4, 0x00C5, 0x00C6, 0x00C7, 0x00C9, 0x00D1,
0x00D6, 0x00DC, 0x00DF, 0x00E0, 0x00E1, 0x00E2, 0x00E4, 0x00E5,
0x00E6, 0x00E7, 0x00E8, 0x00E9, 0x00EA, 0x00EB, 0x00EC, 0x00ED,
0x00EE, 0x00EF, 0x00F1, 0x00F2, 0x00F3, 0x00F4, 0x00F6, 0x00F7,
0x00F9, 0x00FA, 0x00FB, 0x00FC, 0x00FF, 0x0192, 0x0393, 0x0398,
0x03A3, 0x03A6, 0x03A9, 0x03B1, 0x03B4, 0x03B5, 0x03C0, 0x03C3,
0x03C4, 0x03C6, 0x207F, 0x20A7, 0x2219, 0x221A, 0x221E, 0x2229,
0x2248, 0x2261, 0x2264, 0x2265, 0x2310, 0x2320, 0x2321, 0x2500,
0x2502, 0x250C, 0x2510, 0x2514, 0x2518, 0x251C, 0x2524, 0x252C,
0x2534, 0x253C, 0x2550, 0x2551, 0x2552, 0x2553, 0x2554, 0x2555,
0x2556, 0x2557, 0x2558, 0x2559, 0x255A, 0x255B, 0x255C, 0x255D,
0x255E, 0x255F, 0x2560, 0x2561, 0x2562, 0x2563, 0x2564, 0x2565,
0x2566, 0x2567, 0x2568, 0x2569, 0x256A, 0x256B, 0x256C, 0x2580,
0x2584, 0x2588, 0x258C, 0x2590, 0x2591, 0x2592, 0x2593, 0x25A0,
};
static const unsigned char cp437_sb[128] = { /* Single-byte in Unicode order */
0xFF, 0xAD, 0x9B, 0x9C, 0x9D, 0xA6, 0xAE, 0xAA,
0xF8, 0xF1, 0xFD, 0xE6, 0xFA, 0xA7, 0xAF, 0xAC,
0xAB, 0xA8, 0x8E, 0x8F, 0x92, 0x80, 0x90, 0xA5,
0x99, 0x9A, 0xE1, 0x85, 0xA0, 0x83, 0x84, 0x86,
0x91, 0x87, 0x8A, 0x82, 0x88, 0x89, 0x8D, 0xA1,
0x8C, 0x8B, 0xA4, 0x95, 0xA2, 0x93, 0x94, 0xF6,
0x97, 0xA3, 0x96, 0x81, 0x98, 0x9F, 0xE2, 0xE9,
0xE4, 0xE8, 0xEA, 0xE0, 0xEB, 0xEE, 0xE3, 0xE5,
0xE7, 0xED, 0xFC, 0x9E, 0xF9, 0xFB, 0xEC, 0xEF,
0xF7, 0xF0, 0xF3, 0xF2, 0xA9, 0xF4, 0xF5, 0xC4,
0xB3, 0xDA, 0xBF, 0xC0, 0xD9, 0xC3, 0xB4, 0xC2,
0xC1, 0xC5, 0xCD, 0xBA, 0xD5, 0xD6, 0xC9, 0xB8,
0xB7, 0xBB, 0xD4, 0xD3, 0xC8, 0xBE, 0xBD, 0xBC,
0xC6, 0xC7, 0xCC, 0xB5, 0xB6, 0xB9, 0xD1, 0xD2,
0xCB, 0xCF, 0xD0, 0xCA, 0xD8, 0xD7, 0xCE, 0xDF,
0xDC, 0xDB, 0xDD, 0xDE, 0xB0, 0xB1, 0xB2, 0xFE,
};
/* Forward reference to base ISO/IEC 8859 routine - see "eci.c" */
static int u_iso8859(const unsigned int u, const unsigned short *tab_s, const unsigned short *tab_u,
const unsigned char *tab_sb, int e, unsigned char *dest);

63
backend/library.c
View File

@ -979,7 +979,7 @@ static int map_invalid_symbology(struct zint_symbol *symbol) {
return warn_number;
}
/* Encode a barcode. If `length` is 0, `source` must be NUL-terminated */
/* Encode a barcode. If `length` is 0 or negative, `source` must be NUL-terminated */
int ZBarcode_Encode(struct zint_symbol *symbol, const unsigned char *source, int length) {
struct zint_seg segs[1];
@ -2070,6 +2070,67 @@ float ZBarcode_XdimDp_From_Scale(int symbol_id, float scale, float xdim_mm_or_dp
return xdim_mm_or_dpmm;
}
/* Whether `eci` is valid character set ECI */
static int is_valid_char_set_eci(const int eci) {
/* Allowing ECI 1 and ECI 2 for libzueci compatibility (and ECI 0, which is mapped to ECI 2) */
return (eci <= 35 && eci >= 0 && eci != 14 && eci != 19) || eci == 170 || eci == 899;
}
/* Convert UTF-8 `source` of length `length` to `eci`-encoded `dest`, setting `p_dest_length` to length of `dest`
on output. If `length` is 0 or negative, `source` must be NUL-terminated. Returns 0 on success, else
ZINT_ERROR_INVALID_OPTION or ZINT_ERROR_INVALID_DATA. Compatible with libzueci `zueci_utf8_to_eci()` */
int ZBarcode_UTF8_To_ECI(int eci, const unsigned char *source, int length, unsigned char dest[], int *p_dest_length) {
int error_number;
/* Map ECI 0 to ECI 2 (CP437) for libzueci compatibility */
if (eci == 0) {
eci = 2;
}
if (!is_valid_char_set_eci(eci) || !source || !p_dest_length) {
return ZINT_ERROR_INVALID_OPTION;
}
if (length <= 0) {
length = (int) ustrlen(source); /* Note `zueci_utf8_to_eci()` doesn't do this */
}
if (!is_valid_utf8(source, length)) {
return ZINT_ERROR_INVALID_DATA;
}
if (eci == 26) { /* UTF-8 - no change */
memcpy(dest, source, length);
*p_dest_length = length;
return 0;
}
/* Only set `p_dest_length` on success, for libzueci compatibility */
if ((error_number = utf8_to_eci(eci, source, dest, &length)) == 0) {
*p_dest_length = length;
}
return error_number; /* 0 or ZINT_ERROR_INVALID_DATA */
}
/* Calculate sufficient length needed to convert UTF-8 `source` of length `length` from UTF-8 to `eci`, and place
in `p_dest_length`. If `length` is 0 or negative, `source` must be NUL-terminated. Returns 0 on success, else
ZINT_ERROR_INVALID_OPTION or ZINT_ERROR_INVALID_DATA. Compatible with libzueci `zueci_dest_len_eci()` */
int ZBarcode_Dest_Len_ECI(int eci, const unsigned char *source, int length, int *p_dest_length) {
/* Map ECI 0 to ECI 2 (CP437) for libzueci compatibility */
if (eci == 0) {
eci = 2;
}
if (!is_valid_char_set_eci(eci) || !source || !p_dest_length) {
return ZINT_ERROR_INVALID_OPTION;
}
if (length <= 0) {
length = (int) ustrlen(source); /* Note `zueci_dest_len_eci()` doesn't do this */
}
if (!is_valid_utf8(source, length)) {
return ZINT_ERROR_INVALID_DATA;
}
*p_dest_length = get_eci_length(eci, source, length);
return 0;
}
/* Whether Zint built without PNG support */
int ZBarcode_NoPng(void) {
#ifdef ZINT_NO_PNG

18
backend/tests/test_eci.c
View File

@ -647,6 +647,19 @@ static const unsigned short int windows_1256[] = {
0x064b, 0x064c, 0x064d, 0x064e, 0x00f4, 0x064f, 0x0650, 0x00f7, 0x0651, 0x00f9, 0x0652, 0x00fb, 0x00fc, 0x200e, 0x200f, 0x06d2
};
/* Taken from https://unicode.org/Public/MAPPINGS/VENDORS/MICSFT/PC/CP437.TXT */
static const unsigned short int cp437[] = {
0x00c7, 0x00fc, 0x00e9, 0x00e2, 0x00e4, 0x00e0, 0x00e5, 0x00e7, 0x00ea, 0x00eb, 0x00e8, 0x00ef, 0x00ee, 0x00ec, 0x00c4, 0x00c5,
0x00c9, 0x00e6, 0x00c6, 0x00f4, 0x00f6, 0x00f2, 0x00fb, 0x00f9, 0x00ff, 0x00d6, 0x00dc, 0x00a2, 0x00a3, 0x00a5, 0x20a7, 0x0192,
0x00e1, 0x00ed, 0x00f3, 0x00fa, 0x00f1, 0x00d1, 0x00aa, 0x00ba, 0x00bf, 0x2310, 0x00ac, 0x00bd, 0x00bc, 0x00a1, 0x00ab, 0x00bb,
0x2591, 0x2592, 0x2593, 0x2502, 0x2524, 0x2561, 0x2562, 0x2556, 0x2555, 0x2563, 0x2551, 0x2557, 0x255d, 0x255c, 0x255b, 0x2510,
0x2514, 0x2534, 0x252c, 0x251c, 0x2500, 0x253c, 0x255e, 0x255f, 0x255a, 0x2554, 0x2569, 0x2566, 0x2560, 0x2550, 0x256c, 0x2567,
0x2568, 0x2564, 0x2565, 0x2559, 0x2558, 0x2552, 0x2553, 0x256b, 0x256a, 0x2518, 0x250c, 0x2588, 0x2584, 0x258c, 0x2590, 0x2580,
0x03b1, 0x00df, 0x0393, 0x03c0, 0x03a3, 0x03c3, 0x00b5, 0x03c4, 0x03a6, 0x0398, 0x03a9, 0x03b4, 0x221e, 0x03c6, 0x03b5, 0x2229,
0x2261, 0x00b1, 0x2265, 0x2264, 0x2320, 0x2321, 0x00f7, 0x2248, 0x00b0, 0x2219, 0x00b7, 0x221a, 0x207f, 0x00b2, 0x25a0, 0x00a0
};
static void test_utf8_to_eci_sb(const testCtx *const p_ctx) {
struct item {
@ -674,6 +687,7 @@ static void test_utf8_to_eci_sb(const testCtx *const p_ctx) {
/* 16*/ { 22, windows_1251 },
/* 17*/ { 23, windows_1252 },
/* 18*/ { 24, windows_1256 },
/* 19*/ { 2, cp437 },
};
int data_size = ARRAY_SIZE(data);
int i, length, ret;
@ -749,8 +763,8 @@ static void test_utf8_to_eci_ascii(const testCtx *const p_ctx) {
/* 16*/ { 170, "~", -1, ZINT_ERROR_INVALID_DATA },
/* 17*/ { 170, "\302\200", -1, ZINT_ERROR_INVALID_DATA },
/* 18*/ { 170, "~", -1, ZINT_ERROR_INVALID_DATA },
/* 19*/ { 1, "A", -1, ZINT_ERROR_INVALID_DATA },
/* 20*/ { 2, "A", -1, ZINT_ERROR_INVALID_DATA },
/* 19*/ { 1, "A", -1, 0 }, /* Now succeeds (maps to ISO/ECI 8859-1 for libzueci compatibility) */
/* 20*/ { 2, "A", -1, 0 }, /* Now succeeds (maps to CP437 for libzueci compatibility) */
/* 21*/ { 14, "A", -1, ZINT_ERROR_INVALID_DATA },
/* 22*/ { 19, "A", -1, ZINT_ERROR_INVALID_DATA },
/* 23*/ { 26, "A", -1, ZINT_ERROR_INVALID_DATA },

33
backend/tests/test_ksx1001_tab.h
View File

@ -1,3 +1,34 @@
/*
libzint - the open source barcode library
Copyright (C) 2021-2025 Robin Stuart <rstuart114@gmail.com>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither the name of the project nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
*/
/* SPDX-License-Identifier: BSD-3-Clause */
/* Generated by gen_test_tab.php from KSX1001.TXT */
static const unsigned int test_ksx1001_tab[] = {
0x222E, 0x00A1,
@ -8292,3 +8323,5 @@ static const unsigned int test_ksx1001_tab_ind[] = {
15712,
16248,
};
/* vim: set ts=4 sw=4 et : */

111
backend/tests/test_library.c
View File

@ -2177,6 +2177,116 @@ static void test_xdimdp_from_scale(const testCtx *const p_ctx) {
testFinish();
}
static void test_utf8_to_eci(const testCtx *const p_ctx) {
struct item {
int eci;
const char *data;
int length;
int ret_dest;
int expected_dest_length;
int ret;
const char *expected;
int expected_length;
};
/* s/\/\*[ 0-9]*\*\//\=printf("\/\*%3d*\/", line(".") - line("'<")): */
static const struct item data[] = {
/* 0*/ { 3, "1234", -1, 0, 4, 0, "1234", -1 },
/* 1*/ { 3, "1234", 0, 0, 4, 0, "1234", -1 }, /* Zero length allowed */
/* 2*/ { 3, "1234", -2, 0, 4, 0, "1234", -1 }, /* Negative length allowed */
/* 3*/ { 3, "", -1, 0, 0, 0, "", 0 }, /* Empty allowed */
/* 4*/ { 3, NULL, -1, ZINT_ERROR_INVALID_OPTION, 0, -1, "", -1 },
/* 5*/ { -1, "1234", -1, ZINT_ERROR_INVALID_OPTION, 0, -1, "", -1 },
/* 6*/ { 0, "1234", -1, 0, 4, 0, "1234", -1 },
/* 7*/ { 1, "1234", -1, 0, 4, 0, "1234", -1 },
/* 8*/ { 2, "1234", -1, 0, 4, 0, "1234", -1 },
/* 9*/ { 0, "1234é", -1, 0, 6, 0, "1234\202", 5 }, /* CP437 */
/* 10*/ { 1, "1234é", -1, 0, 6, 0, "1234\351", 5 }, /* Same as ISO/IEC 8859-1 */
/* 11*/ { 2, "1234é", -1, 0, 6, 0, "1234\202", 5 }, /* CP437 */
/* 12*/ { 3, "1234é", -1, 0, 6, 0, "1234\351", 5 },
/* 13*/ { 4, "1234˘", -1, 0, 6, 0, "1234\242", 5 }, /* ISO/IEC 8859-2 */
/* 14*/ { 5, "1234Ħ", -1, 0, 6, 0, "1234\241", 5 }, /* ISO/IEC 8859-3 */
/* 15*/ { 6, "1234ĸ", -1, 0, 6, 0, "1234\242", 5 }, /* ISO/IEC 8859-4 */
/* 16*/ { 7, "1234Ё", -1, 0, 6, 0, "1234\241", 5 }, /* ISO/IEC 8859-5 */
/* 17*/ { 8, "1234ء", -1, 0, 6, 0, "1234\301", 5 }, /* ISO/IEC 8859-6 */
/* 18*/ { 9, "1234π", -1, 0, 6, 0, "1234\360", 5 }, /* ISO/IEC 8859-7 */
/* 19*/ { 11, "1234ğ", -1, 0, 6, 0, "1234\360", 5 }, /* ISO/IEC 8859-9 */
/* 20*/ { 12, "1234Ŋ", -1, 0, 6, 0, "1234\257", 5 }, /* ISO/IEC 8859-10 */
/* 21*/ { 13, "1234๐", -1, 0, 7, 0, "1234\360", 5 }, /* ISO/IEC 8859-11 */
/* 22*/ { 14, "1234", -1, ZINT_ERROR_INVALID_OPTION, 0, -1, "", -1 },
/* 23*/ { 15, "1234š", -1, 0, 6, 0, "1234\360", 5 }, /* ISO/IEC 8859-13 */
/* 24*/ { 16, "1234ŵ", -1, 0, 6, 0, "1234\360", 5 }, /* ISO/IEC 8859-14 */
/* 25*/ { 17, "1234œ", -1, 0, 6, 0, "1234\275", 5 }, /* ISO/IEC 8859-15 */
/* 26*/ { 18, "1234Ł", -1, 0, 6, 0, "1234\243", 5 }, /* ISO/IEC 8859-16 */
/* 27*/ { 19, "1234", -1, ZINT_ERROR_INVALID_OPTION, 0, -1, "", -1 },
/* 28*/ { 20, "1234点", -1, 0, 7, 0, "1234\223\137", 6 }, /* Shift JIS */
/* 29*/ { 20, "1234¥", -1, 0, 6, 0, "1234\\", 5 }, /* Shift JIS - Yen sign -> backslash */
/* 30*/ { 20, "1234~", -1, 0, 5, ZINT_ERROR_INVALID_DATA, "", -1 }, /* Shift JIS - no mapping for tilde */
/* 31*/ { 20, "1234\\", -1, 0, 6, 0, "1234\201\137", -1 }, /* Shift JIS - backslash -> full-width reverse solidus */
/* 32*/ { 21, "1234Ą", -1, 0, 6, 0, "1234\245", 5 }, /* Windows-1250 */
/* 33*/ { 22, "1234ѓ", -1, 0, 6, 0, "1234\203", 5 }, /* Windows-1251 */
/* 34*/ { 23, "1234ƒ", -1, 0, 6, 0, "1234\203", 5 }, /* Windows-1252 */
/* 35*/ { 24, "1234پ", -1, 0, 6, 0, "1234\201", 5 }, /* Windows-1256 */
/* 36*/ { 25, "1234é", -1, 0, 10, 0, "\0001\0002\0003\0004\000\351", 10 }, /* UTF-16BE */
/* 37*/ { 26, "1234é", -1, 0, 6, 0, "1234é", 6 }, /* UTF-8 */
/* 38*/ { 27, "1234é", -1, 0, 6, ZINT_ERROR_INVALID_DATA, "", -1 }, /* ASCII */
/* 39*/ { 27, "1234", -1, 0, 4, 0, "1234", -1 }, /* ASCII */
/* 40*/ { 28, "1234＿", -1, 0, 7, 0, "1234\241\304", 6 }, /* Big5 */
/* 41*/ { 29, "1234崂", -1, 0, 7, 0, "1234\341\300", 6 }, /* GB 2312 */
/* 42*/ { 30, "1234가", -1, 0, 7, 0, "1234\260\241", 6 }, /* EUC-KR */
/* 43*/ { 31, "1234郎", -1, 0, 7, 0, "1234\375\234", 6 }, /* GBK */
/* 44*/ { 32, "1234崂", -1, 0, 14, 0, "1234\341\300", 6 }, /* GB 18030 */
/* 45*/ { 33, "1234é", -1, 0, 10, 0, "1\0002\0003\0004\000\351\000", 10 }, /* UTF-16LE */
/* 46*/ { 34, "1234é", -1, 0, 20, 0, "\000\000\0001\000\000\0002\000\000\0003\000\000\0004\000\000\000\351", 20 }, /* UTF-16BE */
/* 47*/ { 35, "1234é", -1, 0, 20, 0, "1\000\000\0002\000\000\0003\000\000\0004\000\000\000\351\000\000\000", 20 }, /* UTF-16LE */
/* 48*/ { 170, "1234", -1, 0, 4, 0, "1234", 4 }, /* ISO 646 Invariant */
/* 49*/ { 170, "1234#", -1, 0, 5, ZINT_ERROR_INVALID_DATA, "", -1 }, /* ISO 646 Invariant */
/* 50*/ { 899, "1234\000\127\302\200ÿ", 10, 0, 10, 0, "1234\000\127\200\377", 8 }, /* Binary */
};
const int data_size = ARRAY_SIZE(data);
int i, length, ret;
int expected_length;
testStart("test_utf8_to_eci");
for (i = 0; i < data_size; i++) {
int ret_dest;
unsigned char dest[1024];
int dest_length;
if (testContinue(p_ctx, i)) continue;
length = data[i].length == -1 && data[i].data ? (int) strlen(data[i].data) : data[i].length;
ret_dest = ZBarcode_Dest_Len_ECI(data[i].eci, TCU(data[i].data), length, &dest_length);
assert_equal(ret_dest, data[i].ret_dest, "i:%d ZBarcode_Dest_Len_ECI(%d, %s) ret_dest %d != %d\n",
i, data[i].eci, data[i].data, ret_dest, data[i].ret_dest);
if (ret_dest < ZINT_ERROR) {
assert_equal(dest_length, data[i].expected_dest_length,
"i:%d ZBarcode_Dest_Len_ECI dest_length %d != expected_dest_length %d\n",
i, dest_length, data[i].expected_dest_length);
expected_length = data[i].expected_length == -1 ? (int) strlen(data[i].expected) : data[i].expected_length;
ret = ZBarcode_UTF8_To_ECI(data[i].eci, TCU(data[i].data), length, dest, &dest_length);
assert_equal(ret, data[i].ret, "i:%d ZBarcode_UTF8_To_ECI(%d, %s) ret %d != %d\n",
i, data[i].eci, data[i].data, ret, data[i].ret);
if (ret < ZINT_ERROR) {
assert_equal(dest_length, expected_length,
"i:%d ZBarcode_UTF8_To_ECI dest_length %d != expected_length %d\n",
i, dest_length, expected_length);
#if 0
printf("dest_length %d\n", dest_length); debug_print_escape(TCU(dest), dest_length, NULL); printf("\n");
#endif
assert_zero(memcmp(dest, data[i].expected, expected_length), "i:%d memcmp(\"%s\", \"%s\", %d) != 0\n",
i, dest, data[i].expected, expected_length);
}
}
}
testFinish();
}
int main(int argc, char *argv[]) {
testFunction funcs[] = { /* name, func */
@ -2205,6 +2315,7 @@ int main(int argc, char *argv[]) {
{ "test_reset", test_reset },
{ "test_scale_from_xdimdp", test_scale_from_xdimdp },
{ "test_xdimdp_from_scale", test_xdimdp_from_scale },
{ "test_utf8_to_eci", test_utf8_to_eci },
};
testRun(argc, argv, funcs, ARRAY_SIZE(funcs));

100
backend/tools/gen_eci_sb_h.php
View File

@ -2,7 +2,7 @@
/* Generate ECI single-byte tables & routines from unicode.org mapping files */
/*
libzint - the open source barcode library
Copyright (C) 2022-2023 Robin Stuart <rstuart114@gmail.com>
Copyright (C) 2022-2025 Robin Stuart <rstuart114@gmail.com>
*/
/* SPDX-License-Identifier: BSD-3-Clause */
/*
@ -20,12 +20,13 @@ $out_dirname = isset($opts['o']) ? $opts['o'] : ($dirname . '/..'); // Where to
$out = array();
$head = <<<'EOD'
/* eci_sb.h - Extended Channel Interpretations single-byte, generated by "backend/tools/gen_eci_sb_h.php"
from "https://unicode.org/Public/MAPPINGS/ISO8859/8859-*.TXT"
and "https://unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WINDOWS/CP125*.TXT" */
/* eci_sb.h - Extended Channel Interpretations single-byte, generated by "backend/tools/gen_eci_sb_h.php" from
"https://unicode.org/Public/MAPPINGS/VENDORS/MICSFT/PC/CP437.TXT" (for libzueci compatibility) and
"https://unicode.org/Public/MAPPINGS/ISO8859/8859-*.TXT" and
"https://unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WINDOWS/CP125*.TXT" */
/*
libzint - the open source barcode library
Copyright (C) 2021-2022 Robin Stuart <rstuart114@gmail.com>
Copyright (C) 2021-2025 Robin Stuart <rstuart114@gmail.com>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
@ -60,6 +61,95 @@ EOD;
$out = explode("\n", $head);
// Read the CP437 file
$tot_cp437 = 0;
//$file = $data_dirname . '/' . 'CP437.TXT';
$file = 'https://unicode.org/Public/MAPPINGS/VENDORS/MICSFT/PC/CP437.TXT';
if (($get = file_get_contents($file)) === false) {
error_log($error = "$basename: ERROR: Could not read mapping file \"$file\"");
exit($error . PHP_EOL);
}
$lines = explode("\n", $get);
// Parse the file.
$sort = array();
$sb = array();
foreach ($lines as $line) {
$line = trim($line);
if ($line === '' || strncmp($line, '0x', 2) !== 0 || strpos($line, "*** NO MAPPING ***") !== false) {
continue;
}
$matches = array();
if (preg_match('/^0x([0-9a-f]{2})[ \t]+0x([0-9a-f]{4})[ \t].*$/', $line, $matches)) {
$mb = hexdec($matches[1]);
$unicode = hexdec($matches[2]);
if ($unicode >= 0x80) {
$sort[] = $unicode;
$sb[] = $mb;
}
}
}
array_multisort($sort, $sb);
// Output.
$out[] = '';
$out[] = '/* Tables for ECI 2 CP437 (for libzueci compatibility) */';
$cnt = count($sort);
$out[] = 'static const unsigned short cp437_u[' . $cnt . '] = { /* Unicode codepoints sorted */';
$line = ' ';
for ($i = 0; $i < $cnt; $i++) {
if ($i && $i % 8 === 0) {
$out[] = $line;
$line = ' ';
}
$line .= sprintf(' 0x%04X,', $sort[$i]);
}
if ($line !== ' ') {
$out[] = $line;
}
$out[] = '};';
$tot_cp437 += $cnt * 2;
$cnt = count($sb);
$out[] = 'static const unsigned char cp437_sb[' . $cnt . '] = { /* Single-byte in Unicode order */';
$line = ' ';
for ($i = 0; $i < $cnt; $i++) {
if ($i && $i % 8 === 0) {
$out[] = $line;
$line = ' ';
}
$line .= sprintf(' 0x%02X,', $sb[$i]);
}
if ($line !== ' ') {
$out[] = $line;
}
$out[] = '};';
$tot_cp437 += $cnt;
$u_sb = array_flip($sb);
$b = 0x80;
$cnt = 256 - $b;
$max_idx = -1;
for ($i = 0; $i < $cnt; $i++) {
if (isset($u_sb[$i + $b])) {
$max_idx = $i;
}
}
$cnt = $max_idx + 1;
$tot_cp437 += $cnt;
if (0) {
$out[] = '';
$out[] = '/* Total CP437 bytes: ' . $tot_cp437 . ' */';
}
$u_iso8859 = <<<'EOD'
/* Forward reference to base ISO/IEC 8859 routine - see "eci.c" */

16
backend/zint.h
View File

@ -141,7 +141,7 @@ extern "C" {
/* Segment for use with `ZBarcode_Encode_Segs()` below */
struct zint_seg {
unsigned char *source; /* Data to encode */
int length; /* Length of `source`. If 0, `source` must be NUL-terminated */
int length; /* Length of `source`. If 0 or negative, `source` must be NUL-terminated */
int eci; /* Extended Channel Interpretation */
};
@ -405,7 +405,7 @@ extern "C" {
ZINT_EXTERN void ZBarcode_Delete(struct zint_symbol *symbol);
/* Encode a barcode. If `length` is 0, `source` must be NUL-terminated */
/* Encode a barcode. If `length` is 0 or negative, `source` must be NUL-terminated */
ZINT_EXTERN int ZBarcode_Encode(struct zint_symbol *symbol, const unsigned char *source, int length);
/* Encode a barcode with multiple ECI segments */
@ -488,6 +488,18 @@ extern "C" {
const char *filetype);
/* Convert UTF-8 `source` of length `length` to `eci`-encoded `dest`, setting `p_dest_length` to length of `dest`
on output. If `length` is 0 or negative, `source` must be NUL-terminated. Returns 0 on success, else
ZINT_ERROR_INVALID_OPTION or ZINT_ERROR_INVALID_DATA. Compatible with libzueci `zueci_utf8_to_eci()` */
ZINT_EXTERN int ZBarcode_UTF8_To_ECI(int eci, const unsigned char *source, int length, unsigned char dest[],
int *p_dest_length);
/* Calculate sufficient length needed to convert UTF-8 `source` of length `length` from UTF-8 to `eci`, and place
in `p_dest_length`. If `length` is 0 or negative, `source` must be NUL-terminated. Returns 0 on success, else
ZINT_ERROR_INVALID_OPTION or ZINT_ERROR_INVALID_DATA. Compatible with libzueci `zueci_dest_len_eci()` */
ZINT_EXTERN int ZBarcode_Dest_Len_ECI(int eci, const unsigned char *source, int length, int *p_dest_length);
/* Whether Zint built without PNG support */
ZINT_EXTERN int ZBarcode_NoPng(void);

295
docs/manual.html
View File

@ -488,7 +488,10 @@ Availability</a></li>
<li><a href="#checking-symbology-capabilities"
id="toc-checking-symbology-capabilities">5.15 Checking Symbology
Capabilities</a></li>
<li><a href="#zint-version" id="toc-zint-version">5.16 Zint
<li><a href="#utf-8-to-eci-convenience-functions"
id="toc-utf-8-to-eci-convenience-functions">5.16 UTF-8 to ECI
convenience functions</a></li>
<li><a href="#zint-version" id="toc-zint-version">5.17 Zint
Version</a></li>
</ul></li>
<li><a href="#types-of-symbology" id="toc-types-of-symbology">6. Types
@ -4105,8 +4108,8 @@ segments and <code>seg_count</code> being the number of elements it
contains. The zint_seg structure is of the form:</p>
<div class="sourceCode" id="cb76"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb76-1"><a href="#cb76-1" aria-hidden="true" tabindex="-1"></a><span class="kw">struct</span> zint_seg <span class="op">{</span></span>
<span id="cb76-2"><a href="#cb76-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">unsigned</span> <span class="dt">char</span> <span class="op">*</span>source<span class="op">;</span> <span class="co">/* Data to encode */</span></span>
<span id="cb76-3"><a href="#cb76-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">int</span> length<span class="op">;</span> <span class="co">/* Length of `source`. If 0, `source` must be</span></span>
<span id="cb76-4"><a href="#cb76-4" aria-hidden="true" tabindex="-1"></a><span class="co"> NUL-terminated */</span></span>
<span id="cb76-3"><a href="#cb76-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">int</span> length<span class="op">;</span> <span class="co">/* Length of `source`. If 0 or negative, `source`</span></span>
<span id="cb76-4"><a href="#cb76-4" aria-hidden="true" tabindex="-1"></a><span class="co"> must be NUL-terminated */</span></span>
<span id="cb76-5"><a href="#cb76-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">int</span> eci<span class="op">;</span> <span class="co">/* Extended Channel Interpretation */</span></span>
<span id="cb76-6"><a href="#cb76-6" aria-hidden="true" tabindex="-1"></a><span class="op">};</span></span></code></pre></div>
<p>The symbology must support ECIs (see Table <a
@ -4299,13 +4302,34 @@ defined?</td>
<span id="cb85-10"><a href="#cb85-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span> <span class="cf">else</span> <span class="op">{</span></span>
<span id="cb85-11"><a href="#cb85-11" aria-hidden="true" tabindex="-1"></a> printf<span class="op">(</span><span class="st">&quot;PDF417 does not support ECI</span><span class="sc">\n</span><span class="st">&quot;</span><span class="op">);</span></span>
<span id="cb85-12"><a href="#cb85-12" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div>
<h2 id="zint-version">5.16 Zint Version</h2>
<h2 id="utf-8-to-eci-convenience-functions">5.16 UTF-8 to ECI
convenience functions</h2>
<p>As a convenience the conversion done by Zint from UTF-8 to ECIs is
exposed in two helper functions (compatible with the
<code>libzueci</code><a href="#fn18" class="footnote-ref" id="fnref18"
role="doc-noteref"><sup>18</sup></a> functions
<code>zueci_utf8_to_eci()</code> and
<code>zueci_dest_len_eci()</code>):</p>
<div class="sourceCode" id="cb86"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb86-1"><a href="#cb86-1" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> ZBarcode_UTF8_To_ECI<span class="op">(</span><span class="dt">int</span> eci<span class="op">,</span> <span class="dt">const</span> <span class="dt">unsigned</span> <span class="dt">char</span> <span class="op">*</span>source<span class="op">,</span> <span class="dt">int</span> length<span class="op">,</span></span>
<span id="cb86-2"><a href="#cb86-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">unsigned</span> <span class="dt">char</span> dest<span class="op">[],</span> <span class="dt">int</span> <span class="op">*</span>p_dest_length<span class="op">);</span></span>
<span id="cb86-3"><a href="#cb86-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb86-4"><a href="#cb86-4" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> ZBarcode_Dest_Len_ECI<span class="op">(</span><span class="dt">int</span> eci<span class="op">,</span> <span class="dt">const</span> <span class="dt">unsigned</span> <span class="dt">char</span> <span class="op">*</span>source<span class="op">,</span> <span class="dt">int</span> length<span class="op">,</span></span>
<span id="cb86-5"><a href="#cb86-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">int</span> <span class="op">*</span>p_dest_length<span class="op">);</span></span></code></pre></div>
<p>Call <code>ZBarcode_Dest_Len_ECI()</code> to get the size of buffer
sufficient to accommodate the conversion, then call
<code>ZBarcode_UTF8_To_ECI()</code> with an appropriately sized buffer
to do the conversion. The final destination length, returned in
<code>p_dest_length</code>, may be smaller than the estimate given by
<code>ZBarcode_Dest_Len_ECI()</code>. If <code>length</code> is zero or
less, <code>source</code> must be NUL-terminated. The destination buffer
is not NUL-terminated. The obsolete ECIs 0, 1 and 2 are supported.</p>
<h2 id="zint-version">5.17 Zint Version</h2>
<p>Whether the Zint library linked to was built with PNG support may be
determined with:</p>
<div class="sourceCode" id="cb86"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb86-1"><a href="#cb86-1" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> ZBarcode_NoPng<span class="op">();</span></span></code></pre></div>
<div class="sourceCode" id="cb87"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb87-1"><a href="#cb87-1" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> ZBarcode_NoPng<span class="op">();</span></span></code></pre></div>
<p>which returns 1 if no PNG support is available, else zero.</p>
<p>Lastly, the version of the Zint library linked to is returned by:</p>
<div class="sourceCode" id="cb87"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb87-1"><a href="#cb87-1" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> ZBarcode_Version<span class="op">();</span></span></code></pre></div>
<div class="sourceCode" id="cb88"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb88-1"><a href="#cb88-1" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> ZBarcode_Version<span class="op">();</span></span></code></pre></div>
<p>The version parts are separated by hundreds. For instance, version
<code>"2.9.1"</code> is returned as <code>"20901"</code>.</p>
<h1 id="types-of-symbology">6. Types of Symbology</h1>
@ -4453,12 +4477,12 @@ calculated by Zint. In addition EAN-2 and EAN-5 add-on symbols can be
added using the <code>+</code> character. For example, to draw a UPC-A
symbol with the data 72527270270 with an EAN-5 add-on showing the data
12345 use the command:</p>
<div class="sourceCode" id="cb88"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb88-1"><a href="#cb88-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> UPCA <span class="at">-d</span> <span class="st">&quot;72527270270+12345&quot;</span></span></code></pre></div>
<div class="sourceCode" id="cb89"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb89-1"><a href="#cb89-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> UPCA <span class="at">-d</span> <span class="st">&quot;72527270270+12345&quot;</span></span></code></pre></div>
<p>or using the API encode a data string with the <code>+</code>
character included:</p>
<div class="sourceCode" id="cb89"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb89-1"><a href="#cb89-1" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>symbology <span class="op">=</span> BARCODE_UPCA<span class="op">;</span></span>
<span id="cb89-2"><a href="#cb89-2" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Encode_and_Print<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;72527270270+12345&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span></code></pre></div>
<div class="sourceCode" id="cb90"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb90-1"><a href="#cb90-1" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>symbology <span class="op">=</span> BARCODE_UPCA<span class="op">;</span></span>
<span id="cb90-2"><a href="#cb90-2" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Encode_and_Print<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;72527270270+12345&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span></code></pre></div>
<figure>
<img src="images/upca_5.svg" title="fig:" class="upcean"
alt="zint -b UPCA --compliantheight -d &quot;72527270270+12345&quot;" />
@ -4472,12 +4496,12 @@ input and validates the check digit before encoding.</p>
<code>--guardwhitespace</code> (API
<code>output_options |= EANUPC_GUARD_WHITESPACE</code>). For UPC, this
is only relevant when there is add-on:</p>
<div class="sourceCode" id="cb90"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb90-1"><a href="#cb90-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> UPCA <span class="at">-d</span> <span class="st">&quot;72527270270+12345&quot;</span> <span class="at">--guardwhitespace</span></span></code></pre></div>
<div class="sourceCode" id="cb91"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb91-1"><a href="#cb91-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> UPCA <span class="at">-d</span> <span class="st">&quot;72527270270+12345&quot;</span> <span class="at">--guardwhitespace</span></span></code></pre></div>
<p>or using the API:</p>
<div class="sourceCode" id="cb91"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb91-1"><a href="#cb91-1" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>symbology <span class="op">=</span> BARCODE_UPCA<span class="op">;</span></span>
<span id="cb91-2"><a href="#cb91-2" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>output_options <span class="op">|=</span> EANUPC_GUARD_WHITESPACE<span class="op">;</span></span>
<span id="cb91-3"><a href="#cb91-3" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Encode_and_Print<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;72527270270+12345&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span></code></pre></div>
<div class="sourceCode" id="cb92"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb92-1"><a href="#cb92-1" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>symbology <span class="op">=</span> BARCODE_UPCA<span class="op">;</span></span>
<span id="cb92-2"><a href="#cb92-2" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>output_options <span class="op">|=</span> EANUPC_GUARD_WHITESPACE<span class="op">;</span></span>
<span id="cb92-3"><a href="#cb92-3" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Encode_and_Print<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;72527270270+12345&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span></code></pre></div>
<figure>
<img src="images/upca_5_gws.svg" title="fig:" class="upcean"
alt="zint -b UPCA --compliantheight -d &quot;72527270270+12345&quot; --guardwhitespace" />
@ -4504,19 +4528,19 @@ check digit is calculated by Zint. EAN-2 and EAN-5 add-on symbols can be
added using the + character as with UPC-A. In addition Zint also
supports Number System 1 encoding by entering a 7-digit article number
starting with the digit 1. For example:</p>
<div class="sourceCode" id="cb92"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb92-1"><a href="#cb92-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> UPCE <span class="at">-d</span> <span class="st">&quot;1123456&quot;</span></span></code></pre></div>
<div class="sourceCode" id="cb93"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb93-1"><a href="#cb93-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> UPCE <span class="at">-d</span> <span class="st">&quot;1123456&quot;</span></span></code></pre></div>
<p>or</p>
<div class="sourceCode" id="cb93"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb93-1"><a href="#cb93-1" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>symbology <span class="op">=</span> BARCODE_UPCE<span class="op">;</span></span>
<span id="cb93-2"><a href="#cb93-2" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Encode_and_Print<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;1123456&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span></code></pre></div>
<div class="sourceCode" id="cb94"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb94-1"><a href="#cb94-1" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>symbology <span class="op">=</span> BARCODE_UPCE<span class="op">;</span></span>
<span id="cb94-2"><a href="#cb94-2" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Encode_and_Print<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;1123456&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span></code></pre></div>
<p>If your input data already includes the check digit symbology
<code>BARCODE_UPCE_CHK</code> (38) can be used which takes a 7 or
8-digit input and validates the check digit before encoding.</p>
<p>As with UPC-A, a quiet zone indicator can be added when there is an
add-on by setting <code>--guardwhitespace</code> (API
<code>output_options |= EANUPC_GUARD_WHITESPACE</code>):</p>
<div class="sourceCode" id="cb94"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb94-1"><a href="#cb94-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> UPCE <span class="at">-d</span> <span class="st">&quot;1123456+12&quot;</span> <span class="at">--guardwhitespace</span></span></code></pre></div>
<div class="sourceCode" id="cb95"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb95-1"><a href="#cb95-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> UPCE <span class="at">-d</span> <span class="st">&quot;1123456+12&quot;</span> <span class="at">--guardwhitespace</span></span></code></pre></div>
<figure>
<img src="images/upce_2_gws.svg" title="fig:" class="upcean"
alt="zint -b UPCE --compliantheight -d &quot;1123456+12&quot; --guardwhitespace" />
@ -4546,8 +4570,8 @@ numbers respectively. Zint will decide which symbology to use depending
on the length of the input data. In addition EAN-2 and EAN-5 add-on
symbols can be added to EAN-8 and EAN-13 symbols using the
<code>+</code> character as with UPC symbols. For example:</p>
<div class="sourceCode" id="cb95"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb95-1"><a href="#cb95-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> EANX <span class="at">-d</span> <span class="st">&quot;54321&quot;</span></span></code></pre></div>
<div class="sourceCode" id="cb96"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb96-1"><a href="#cb96-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> EANX <span class="at">-d</span> <span class="st">&quot;54321&quot;</span></span></code></pre></div>
<figure>
<img src="images/eanx5.svg" title="fig:" class="upcean"
alt="zint -b EANX --compliantheight -d &quot;54321&quot;" />
@ -4555,15 +4579,15 @@ alt="zint -b EANX --compliantheight -d &quot;54321&quot;" />
aria-hidden="true"><code>zint -b EANX --compliantheight -d "54321"</code></figcaption>
</figure>
<p>will encode a stand-alone EAN-5, whereas</p>
<div class="sourceCode" id="cb96"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb96-1"><a href="#cb96-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> EANX <span class="at">-d</span> <span class="st">&quot;7432365+54321&quot;</span></span></code></pre></div>
<div class="sourceCode" id="cb97"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb97-1"><a href="#cb97-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> EANX <span class="at">-d</span> <span class="st">&quot;7432365+54321&quot;</span></span></code></pre></div>
<p>will encode an EAN-8 symbol with an EAN-5 add-on. As before these
results can be achieved using the API:</p>
<div class="sourceCode" id="cb97"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb97-1"><a href="#cb97-1" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>symbology <span class="op">=</span> BARCODE_EANX<span class="op">;</span></span>
<span id="cb97-2"><a href="#cb97-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb97-3"><a href="#cb97-3" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Encode_and_Print<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;54321&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
<span id="cb97-4"><a href="#cb97-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb97-5"><a href="#cb97-5" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Encode_and_Print<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;7432365+54321&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span></code></pre></div>
<div class="sourceCode" id="cb98"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb98-1"><a href="#cb98-1" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>symbology <span class="op">=</span> BARCODE_EANX<span class="op">;</span></span>
<span id="cb98-2"><a href="#cb98-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb98-3"><a href="#cb98-3" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Encode_and_Print<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;54321&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
<span id="cb98-4"><a href="#cb98-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb98-5"><a href="#cb98-5" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Encode_and_Print<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;7432365+54321&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span></code></pre></div>
<figure>
<img src="images/eanx8_5.svg" title="fig:" class="upcean"
alt="zint -b EANX --compliantheight -d &quot;7432365+54321&quot;" />
@ -4579,8 +4603,8 @@ and validates the check digit before encoding.</p>
<p>Options to add quiet zone indicators and to adjust the add-on gap and
the guard bar descent height are the same as for <a
href="#upc-version-e">6.1.3.2 UPC Version E</a>. For instance:</p>
<div class="sourceCode" id="cb98"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb98-1"><a href="#cb98-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> EANX_CHK <span class="at">-d</span> <span class="st">&quot;74323654&quot;</span> <span class="at">--guardwhitespace</span></span></code></pre></div>
<div class="sourceCode" id="cb99"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb99-1"><a href="#cb99-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> EANX_CHK <span class="at">-d</span> <span class="st">&quot;74323654&quot;</span> <span class="at">--guardwhitespace</span></span></code></pre></div>
<figure>
<img src="images/eanx8_gws.svg" title="fig:" class="upcean"
alt="zint -b EANX_CHK --compliantheight -d &quot;74323654&quot; –guardwhitespace" />
@ -4872,21 +4896,21 @@ escapes <code>\^A</code>, <code>\^B</code>, <code>\^C</code> and
<code>\^@</code> (the latter turns off manual Code Set selection). For
instance the following will force switching to Code Set B for the data
<code>"5678"</code> (normally Code Set C would be used throughout):</p>
<div class="sourceCode" id="cb99"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb99-1"><a href="#cb99-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> CODE128 <span class="at">-d</span> <span class="st">&quot;1234\^B5678&quot;</span> <span class="at">--extraesc</span></span></code></pre></div>
<div class="sourceCode" id="cb100"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb100-1"><a href="#cb100-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> CODE128 <span class="at">-d</span> <span class="st">&quot;1234\^B5678&quot;</span> <span class="at">--extraesc</span></span></code></pre></div>
<p>The manually selected Code Set will apply until the next Code Set
escape sequence or until a <code>\^@</code>, with the exception that
data that cannot be represented in that Code Set will be switched as
appropriate. If the data contains an extra escape sequence, it can be
escaped by doubling the caret (<code>^</code>). For instance</p>
<div class="sourceCode" id="cb100"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb100-1"><a href="#cb100-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> CODE128 <span class="at">-d</span> <span class="st">&quot;\^AABC\^^BDEF&quot;</span> <span class="at">--extraesc</span></span></code></pre></div>
<div class="sourceCode" id="cb101"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb101-1"><a href="#cb101-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> CODE128 <span class="at">-d</span> <span class="st">&quot;\^AABC\^^BDEF&quot;</span> <span class="at">--extraesc</span></span></code></pre></div>
<p>will encode the data <code>"ABC\^BDEF"</code> in Code Set A.</p>
<p>There is also the extra escape <code>\^1</code>, which will encode a
special Function Code 1 character (<code>FNC1</code>) anywhere you chose
in the data, for instance</p>
<div class="sourceCode" id="cb101"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb101-1"><a href="#cb101-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> CODE128 <span class="at">-d</span> <span class="st">&quot;A\^1BC\^1DEF&quot;</span> <span class="at">--extraesc</span></span></code></pre></div>
<div class="sourceCode" id="cb102"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb102-1"><a href="#cb102-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> CODE128 <span class="at">-d</span> <span class="st">&quot;A\^1BC\^1DEF&quot;</span> <span class="at">--extraesc</span></span></code></pre></div>
<p>Zint can encode a maximum of 102 symbol characters, which allows for
e.g. 202 all-numeric or 101 all-uppercase characters. Sizes above 120
digits (60 alphanumerics) are not recommended.</p>
@ -4900,8 +4924,8 @@ aria-hidden="true"><code>zint -b CODE128AB -d "130170X178"</code></figcaption>
</figure>
<p>It is sometimes advantageous to stop Code 128 from using Code Set C
which compresses numerical data. The <code>BARCODE_CODE128AB</code><a
href="#fn18" class="footnote-ref" id="fnref18"
role="doc-noteref"><sup>18</sup></a> variant (symbology 60) suppresses
href="#fn19" class="footnote-ref" id="fnref19"
role="doc-noteref"><sup>19</sup></a> variant (symbology 60) suppresses
Code Set C in favour of Code Sets A and B.</p>
<p>Note that the special extra escapes mentioned above are not available
for this variant (nor for any other).</p>
@ -4927,11 +4951,11 @@ correct encoding. GS1-128 does not support extended ASCII (ISO/IEC
8859-1) characters. Check digits for GTIN data AI (01) are not generated
and need to be included in the input data. The following is an example
of a valid GS1-128 input:</p>
<div class="sourceCode" id="cb102"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb102-1"><a href="#cb102-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> 16 <span class="at">-d</span> <span class="st">&quot;[01]98898765432106[3202]012345[15]991231&quot;</span></span></code></pre></div>
<p>or using the <code>--gs1parens</code> option:</p>
<div class="sourceCode" id="cb103"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb103-1"><a href="#cb103-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> 16 <span class="at">--gs1parens</span> <span class="at">-d</span> <span class="st">&quot;(01)98898765432106(3202)012345(15)991231&quot;</span></span></code></pre></div>
class="sourceCode bash"><code class="sourceCode bash"><span id="cb103-1"><a href="#cb103-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> 16 <span class="at">-d</span> <span class="st">&quot;[01]98898765432106[3202]012345[15]991231&quot;</span></span></code></pre></div>
<p>or using the <code>--gs1parens</code> option:</p>
<div class="sourceCode" id="cb104"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb104-1"><a href="#cb104-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> 16 <span class="at">--gs1parens</span> <span class="at">-d</span> <span class="st">&quot;(01)98898765432106(3202)012345(15)991231&quot;</span></span></code></pre></div>
<h4 id="ean-14">6.1.10.4 EAN-14</h4>
<figure>
<img src="images/ean14.svg" title="fig:" class="lin"
@ -5103,8 +5127,8 @@ href="#gs1-128">6.1.10.3 GS1-128</a>.</p>
not calculated by Zint when this symbology is encoded. Fixed length data
should be entered at the appropriate length for correct encoding. The
following is an example of a valid GS1 DataBar Expanded input:</p>
<div class="sourceCode" id="cb104"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb104-1"><a href="#cb104-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> 31 <span class="at">-d</span> <span class="st">&quot;[01]98898765432106[3202]012345[15]991231&quot;</span></span></code></pre></div>
<div class="sourceCode" id="cb105"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb105-1"><a href="#cb105-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> 31 <span class="at">-d</span> <span class="st">&quot;[01]98898765432106[3202]012345[15]991231&quot;</span></span></code></pre></div>
<h3 id="korea-post-barcode">6.1.12 Korea Post Barcode</h3>
<figure>
<img src="images/koreapost.svg" title="fig:" class="lin"
@ -5193,20 +5217,20 @@ position. Lowercase input is automatically made uppercase.</p>
primarily in the vehicle industry, is to simply stack one-dimensional
codes on top of each other. This can be achieved at the command prompt
by giving more than one set of input data. For example</p>
<div class="sourceCode" id="cb105"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb105-1"><a href="#cb105-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-d</span> <span class="st">&quot;This&quot;</span> <span class="at">-d</span> <span class="st">&quot;That&quot;</span></span></code></pre></div>
<div class="sourceCode" id="cb106"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb106-1"><a href="#cb106-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-d</span> <span class="st">&quot;This&quot;</span> <span class="at">-d</span> <span class="st">&quot;That&quot;</span></span></code></pre></div>
<p>will draw two Code 128 symbols, one on top of the other. The same
result can be achieved using the API by executing the
<code>ZBarcode_Encode()</code> function more than once on a symbol. For
example:</p>
<div class="sourceCode" id="cb106"><pre
class="sourceCode c"><code class="sourceCode c"><span id="cb106-1"><a href="#cb106-1" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>symbology <span class="op">=</span> BARCODE_CODE128<span class="op">;</span></span>
<span id="cb106-2"><a href="#cb106-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb106-3"><a href="#cb106-3" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Encode<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;This&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
<span id="cb106-4"><a href="#cb106-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb106-5"><a href="#cb106-5" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Encode<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;That&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
<span id="cb106-6"><a href="#cb106-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb106-7"><a href="#cb106-7" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Print<span class="op">(</span>my_symbol<span class="op">);</span></span></code></pre></div>
<div class="sourceCode" id="cb107"><pre
class="sourceCode c"><code class="sourceCode c"><span id="cb107-1"><a href="#cb107-1" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>symbology <span class="op">=</span> BARCODE_CODE128<span class="op">;</span></span>
<span id="cb107-2"><a href="#cb107-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb107-3"><a href="#cb107-3" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Encode<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;This&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
<span id="cb107-4"><a href="#cb107-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb107-5"><a href="#cb107-5" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Encode<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;That&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
<span id="cb107-6"><a href="#cb107-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb107-7"><a href="#cb107-7" aria-hidden="true" tabindex="-1"></a>error <span class="op">=</span> ZBarcode_Print<span class="op">(</span>my_symbol<span class="op">);</span></span></code></pre></div>
<figure>
<img src="images/code128_stacked.svg" title="fig:" class="lin"
alt="zint -d &quot;This&quot; -d &quot;That&quot;" />
@ -5222,8 +5246,8 @@ specifying <code>--bind</code> (API
separator bars in integral multiples of the X-dimension (minimum and
default 1, maximum 4) can be set by <code>--separator</code> (API
<code>option_3</code>):</p>
<div class="sourceCode" id="cb107"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb107-1"><a href="#cb107-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">--bind</span> <span class="at">--notext</span> <span class="at">--separator</span><span class="op">=</span>2 <span class="at">-d</span> <span class="st">&quot;This&quot;</span> <span class="at">-d</span> <span class="st">&quot;That&quot;</span></span></code></pre></div>
<div class="sourceCode" id="cb108"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb108-1"><a href="#cb108-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">--bind</span> <span class="at">--notext</span> <span class="at">--separator</span><span class="op">=</span>2 <span class="at">-d</span> <span class="st">&quot;This&quot;</span> <span class="at">-d</span> <span class="st">&quot;That&quot;</span></span></code></pre></div>
<figure>
<img src="images/code128_stacked_sep2.svg" title="fig:" class="lin"
alt="zint --notext --bind --separator=2 -d &quot;This&quot; -d &quot;That&quot;" />
@ -5501,21 +5525,21 @@ should be entered into a primary string with the data for the 2D
component being entered in the normal way. To do this at the command
prompt use the <code>--primary</code> switch (API <code>primary</code>).
For example:</p>
<div class="sourceCode" id="cb108"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb108-1"><a href="#cb108-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> EANX_CC <span class="at">--mode</span><span class="op">=</span>1 <span class="at">--primary</span><span class="op">=</span>331234567890 <span class="at">-d</span> <span class="st">&quot;[99]1234-abcd&quot;</span></span></code></pre></div>
<div class="sourceCode" id="cb109"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb109-1"><a href="#cb109-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> EANX_CC <span class="at">--mode</span><span class="op">=</span>1 <span class="at">--primary</span><span class="op">=</span>331234567890 <span class="at">-d</span> <span class="st">&quot;[99]1234-abcd&quot;</span></span></code></pre></div>
<p>This creates an EAN-13 linear component with the data
<code>"331234567890"</code> and a 2D CC-A (see <a
href="#cc-a">below</a>) component with the data
<code>"(99)1234-abcd"</code>. The same results can be achieved using the
API as shown below:</p>
<div class="sourceCode" id="cb109"><pre
class="sourceCode c"><code class="sourceCode c"><span id="cb109-1"><a href="#cb109-1" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>symbology <span class="op">=</span> BARCODE_EANX_CC<span class="op">;</span></span>
<span id="cb109-2"><a href="#cb109-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb109-3"><a href="#cb109-3" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>option_1 <span class="op">=</span> <span class="dv">1</span><span class="op">;</span></span>
<span id="cb109-4"><a href="#cb109-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb109-5"><a href="#cb109-5" aria-hidden="true" tabindex="-1"></a>strcpy<span class="op">(</span>my_symbol<span class="op">-&gt;</span>primary<span class="op">,</span> <span class="st">&quot;331234567890&quot;</span><span class="op">);</span></span>
<span id="cb109-6"><a href="#cb109-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb109-7"><a href="#cb109-7" aria-hidden="true" tabindex="-1"></a>ZBarcode_Encode_and_Print<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;[99]1234-abcd&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span></code></pre></div>
<div class="sourceCode" id="cb110"><pre
class="sourceCode c"><code class="sourceCode c"><span id="cb110-1"><a href="#cb110-1" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>symbology <span class="op">=</span> BARCODE_EANX_CC<span class="op">;</span></span>
<span id="cb110-2"><a href="#cb110-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb110-3"><a href="#cb110-3" aria-hidden="true" tabindex="-1"></a>my_symbol<span class="op">-&gt;</span>option_1 <span class="op">=</span> <span class="dv">1</span><span class="op">;</span></span>
<span id="cb110-4"><a href="#cb110-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb110-5"><a href="#cb110-5" aria-hidden="true" tabindex="-1"></a>strcpy<span class="op">(</span>my_symbol<span class="op">-&gt;</span>primary<span class="op">,</span> <span class="st">&quot;331234567890&quot;</span><span class="op">);</span></span>
<span id="cb110-6"><a href="#cb110-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb110-7"><a href="#cb110-7" aria-hidden="true" tabindex="-1"></a>ZBarcode_Encode_and_Print<span class="op">(</span>my_symbol<span class="op">,</span> <span class="st">&quot;[99]1234-abcd&quot;</span><span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span></code></pre></div>
<p>EAN-2 and EAN-5 add-on data can be used with EAN and UPC symbols
using the + symbol as described in sections <a
href="#upc-universal-product-code-iso-15420">6.1.3 UPC (Universal
@ -5641,8 +5665,8 @@ the 6-digit version the first and last digit are ignored, leaving a
2047. The second format <code>"NNN-NN"</code> represents the DX Extract
as two numbers separated by a dash (<code>-</code>), the first number
being 1 to 3 digits (range 1 to 127) and the second 1 to 2 digits (range
0 to 15).<a href="#fn19" class="footnote-ref" id="fnref19"
role="doc-noteref"><sup>19</sup></a></p>
0 to 15).<a href="#fn20" class="footnote-ref" id="fnref20"
role="doc-noteref"><sup>20</sup></a></p>
<p>The optional frame number is a number in the range 0 to 63, and may
have a half frame indicator <code>"A"</code> appended. Special character
sequences (with or without a half frame indicator appended) may also be
@ -5907,13 +5931,13 @@ size to full height can be given in thousandths (permille) using the
<code>--vers</code> option (API <code>option_2</code>). The default
value is 250 (25%).</p>
<p>For example the following</p>
<div class="sourceCode" id="cb110"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb110-1"><a href="#cb110-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> DAFT <span class="at">-d</span> AAFDTTDAFADTFTTFFFDATFTADTTFFTDAFAFDTF <span class="at">--height</span><span class="op">=</span>8.494 <span class="at">--vers</span><span class="op">=</span>256</span></code></pre></div>
<div class="sourceCode" id="cb111"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb111-1"><a href="#cb111-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> DAFT <span class="at">-d</span> AAFDTTDAFADTFTTFFFDATFTADTTFFTDAFAFDTF <span class="at">--height</span><span class="op">=</span>8.494 <span class="at">--vers</span><span class="op">=</span>256</span></code></pre></div>
<p>produces the same barcode (see <a
href="#royal-mail-4-state-customer-code-rm4scc">6.5.3 Royal Mail 4-State
Customer Code (RM4SCC)</a>) as</p>
<div class="sourceCode" id="cb111"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb111-1"><a href="#cb111-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> RM4SCC <span class="at">--compliantheight</span> <span class="at">-d</span> <span class="st">&quot;W1J0TR01&quot;</span></span></code></pre></div>
<div class="sourceCode" id="cb112"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb112-1"><a href="#cb112-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> RM4SCC <span class="at">--compliantheight</span> <span class="at">-d</span> <span class="st">&quot;W1J0TR01&quot;</span></span></code></pre></div>
<h2 id="matrix-symbols">6.6 Matrix Symbols</h2>
<h3 id="data-matrix-iso-16022">6.6.1 Data Matrix (ISO 16022)</h3>
<figure>
@ -6554,8 +6578,8 @@ be manually specified by using the <code>--mask</code> switch with
values 0-7, or in the API by setting
<code>option_3 = (N + 1) &lt;&lt; 8</code> where N is 0-7. To use with
<code>ZINT_FULL_MULTIBYTE</code> set</p>
<div class="sourceCode" id="cb112"><pre
class="sourceCode c"><code class="sourceCode c"><span id="cb112-1"><a href="#cb112-1" aria-hidden="true" tabindex="-1"></a>option_3 <span class="op">=</span> ZINT_FULL_MULTIBYTE <span class="op">|</span> <span class="op">(</span>N <span class="op">+</span> <span class="dv">1</span><span class="op">)</span> <span class="op">&lt;&lt;</span> <span class="dv">8</span></span></code></pre></div>
<div class="sourceCode" id="cb113"><pre
class="sourceCode c"><code class="sourceCode c"><span id="cb113-1"><a href="#cb113-1" aria-hidden="true" tabindex="-1"></a>option_3 <span class="op">=</span> ZINT_FULL_MULTIBYTE <span class="op">|</span> <span class="op">(</span>N <span class="op">+</span> <span class="dv">1</span><span class="op">)</span> <span class="op">&lt;&lt;</span> <span class="dv">8</span></span></code></pre></div>
<p>The <code>--fast</code> option (API
<code>input_mode |= FAST_MODE</code>) may be used when leaving Zint to
automatically select a mask to reduce the number of masks to try to four
@ -6691,8 +6715,8 @@ be manually specified by using the <code>--mask</code> switch with
values 0-3, or in the API by setting
<code>option_3 = (N + 1) &lt;&lt; 8</code> where N is 0-3. To use with
<code>ZINT_FULL_MULTIBYTE</code> set</p>
<div class="sourceCode" id="cb113"><pre
class="sourceCode c"><code class="sourceCode c"><span id="cb113-1"><a href="#cb113-1" aria-hidden="true" tabindex="-1"></a>option_3 <span class="op">=</span> ZINT_FULL_MULTIBYTE <span class="op">|</span> <span class="op">(</span>N <span class="op">+</span> <span class="dv">1</span><span class="op">)</span> <span class="op">&lt;&lt;</span> <span class="dv">8</span></span></code></pre></div>
<div class="sourceCode" id="cb114"><pre
class="sourceCode c"><code class="sourceCode c"><span id="cb114-1"><a href="#cb114-1" aria-hidden="true" tabindex="-1"></a>option_3 <span class="op">=</span> ZINT_FULL_MULTIBYTE <span class="op">|</span> <span class="op">(</span>N <span class="op">+</span> <span class="dv">1</span><span class="op">)</span> <span class="op">&lt;&lt;</span> <span class="dv">8</span></span></code></pre></div>
<h3 id="rectangular-micro-qr-code-rmqr-iso-23941">6.6.5 Rectangular
Micro QR Code (rMQR) (ISO 23941)</h3>
<figure>
@ -6959,8 +6983,8 @@ Latin-2 formatted use the <code>--binary</code> switch (API
<code>input_mode = DATA_MODE</code>).</p>
<p>The following example creates a symbol from data saved as a Latin-2
file:</p>
<div class="sourceCode" id="cb114"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb114-1"><a href="#cb114-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-o</span> upnqr.png <span class="at">-b</span> 143 <span class="at">--scale</span><span class="op">=</span>3 <span class="at">--binary</span> <span class="at">-i</span> upn.txt</span></code></pre></div>
<div class="sourceCode" id="cb115"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb115-1"><a href="#cb115-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-o</span> upnqr.png <span class="at">-b</span> 143 <span class="at">--scale</span><span class="op">=</span>3 <span class="at">--binary</span> <span class="at">-i</span> upn.txt</span></code></pre></div>
<p>A mask may be manually specified or the <code>--fast</code> option
used as with QRCODE.</p>
<h3 id="maxicode-iso-16023">6.6.7 MaxiCode (ISO 16023)</h3>
@ -7019,9 +7043,9 @@ your parcel courier.</td>
<p>The primary message can be set at the command prompt using the
<code>--primary</code> switch (API <code>primary</code>). The secondary
message uses the normal data entry method. For example:</p>
<div class="sourceCode" id="cb115"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb115-1"><a href="#cb115-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-o</span> test.eps <span class="at">-b</span> 57 <span class="at">--primary</span><span class="op">=</span><span class="st">&quot;999999999840012&quot;</span> <span class="dt">\</span></span>
<span id="cb115-2"><a href="#cb115-2" aria-hidden="true" tabindex="-1"></a> <span class="at">-d</span> <span class="st">&quot;Secondary Message Here&quot;</span></span></code></pre></div>
<div class="sourceCode" id="cb116"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb116-1"><a href="#cb116-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-o</span> test.eps <span class="at">-b</span> 57 <span class="at">--primary</span><span class="op">=</span><span class="st">&quot;999999999840012&quot;</span> <span class="dt">\</span></span>
<span id="cb116-2"><a href="#cb116-2" aria-hidden="true" tabindex="-1"></a> <span class="at">-d</span> <span class="st">&quot;Secondary Message Here&quot;</span></span></code></pre></div>
<p>When using the API the primary message must be placed in the
<code>primary</code> string. The secondary is entered in the same way as
described in <a href="#encoding-and-saving-to-file">5.2 Encoding and
@ -7034,9 +7058,9 @@ to be prefixed by the ISO/IEC 15434 Format <code>"01"</code>
<code>vv</code> is a 2-digit version, by using the <code>--scmvv</code>
switch (API <code>option_2 = vv + 1</code>). For example to use the
common version <code>"96"</code> (ASC MH10/SC 8):</p>
<div class="sourceCode" id="cb116"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb116-1"><a href="#cb116-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> 57 <span class="at">--primary</span><span class="op">=</span><span class="st">&quot;152382802840001&quot;</span> <span class="at">--scmvv</span><span class="op">=</span>96 <span class="at">--esc</span> <span class="at">-d</span> <span class="dt">\</span></span>
<span id="cb116-2"><a href="#cb116-2" aria-hidden="true" tabindex="-1"></a> <span class="st">&quot;1Z00004951\GUPSN\G06X610\G159\G1234567\G1/1\G\GY\G1 MAIN ST\GNY\GNY\R\E&quot;</span></span></code></pre></div>
<div class="sourceCode" id="cb117"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb117-1"><a href="#cb117-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> 57 <span class="at">--primary</span><span class="op">=</span><span class="st">&quot;152382802840001&quot;</span> <span class="at">--scmvv</span><span class="op">=</span>96 <span class="at">--esc</span> <span class="at">-d</span> <span class="dt">\</span></span>
<span id="cb117-2"><a href="#cb117-2" aria-hidden="true" tabindex="-1"></a> <span class="st">&quot;1Z00004951\GUPSN\G06X610\G159\G1234567\G1/1\G\GY\G1 MAIN ST\GNY\GNY\R\E&quot;</span></span></code></pre></div>
<p>will prefix <code>"[)&gt;\R01\G96"</code> to the secondary message.
(<code>\R</code>, <code>\G</code> and <code>\E</code> are the escape
sequences for Record Separator, Group Separator and End of Transmission
@ -7045,8 +7069,8 @@ Sequences</a>.)</p>
<p>Modes 4 to 6 can be accessed using the <code>--mode</code> switch
(API <code>option_1</code>). Modes 4 to 6 do not have a primary message.
For example:</p>
<div class="sourceCode" id="cb117"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb117-1"><a href="#cb117-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-o</span> test.eps <span class="at">-b</span> 57 <span class="at">--mode</span><span class="op">=</span>4 <span class="at">-d</span> <span class="st">&quot;A MaxiCode Message in Mode 4&quot;</span></span></code></pre></div>
<div class="sourceCode" id="cb118"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb118-1"><a href="#cb118-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-o</span> test.eps <span class="at">-b</span> 57 <span class="at">--mode</span><span class="op">=</span>4 <span class="at">-d</span> <span class="st">&quot;A MaxiCode Message in Mode 4&quot;</span></span></code></pre></div>
<p>Mode 6 is reserved for the maintenance of scanner hardware and should
not be used to encode user data.</p>
<p>This symbology uses Latin-1 character encoding by default but also
@ -7970,8 +7994,8 @@ be manually specified by using the <code>--mask</code> switch with
values 0-3, or in the API by setting
<code>option_3 = (N + 1) &lt;&lt; 8</code> where N is 0-3. To use with
<code>ZINT_FULL_MULTIBYTE</code> set</p>
<div class="sourceCode" id="cb118"><pre
class="sourceCode c"><code class="sourceCode c"><span id="cb118-1"><a href="#cb118-1" aria-hidden="true" tabindex="-1"></a>option_3 <span class="op">=</span> ZINT_FULL_MULTIBYTE <span class="op">|</span> <span class="op">(</span>N <span class="op">+</span> <span class="dv">1</span><span class="op">)</span> <span class="op">&lt;&lt;</span> <span class="dv">8</span></span></code></pre></div>
<div class="sourceCode" id="cb119"><pre
class="sourceCode c"><code class="sourceCode c"><span id="cb119-1"><a href="#cb119-1" aria-hidden="true" tabindex="-1"></a>option_3 <span class="op">=</span> ZINT_FULL_MULTIBYTE <span class="op">|</span> <span class="op">(</span>N <span class="op">+</span> <span class="dv">1</span><span class="op">)</span> <span class="op">&lt;&lt;</span> <span class="dv">8</span></span></code></pre></div>
<h3 id="ultracode">6.6.14 Ultracode</h3>
<figure>
<img src="images/ultra.svg" title="fig:" class="ultra"
@ -8031,8 +8055,8 @@ data-tag=": Ultracode Error Correction Values">
</div>
<p>Zint does not currently implement data compression by default, but
this can be initiated through the API by setting</p>
<div class="sourceCode" id="cb119"><pre
class="sourceCode c"><code class="sourceCode c"><span id="cb119-1"><a href="#cb119-1" aria-hidden="true" tabindex="-1"></a>symbol<span class="op">-&gt;</span>option_3 <span class="op">=</span> ULTRA_COMPRESSION<span class="op">;</span></span></code></pre></div>
<div class="sourceCode" id="cb120"><pre
class="sourceCode c"><code class="sourceCode c"><span id="cb120-1"><a href="#cb120-1" aria-hidden="true" tabindex="-1"></a>symbol<span class="op">-&gt;</span>option_3 <span class="op">=</span> ULTRA_COMPRESSION<span class="op">;</span></span></code></pre></div>
<p>With compression, up to 504 digits, 375 alphanumerics or 252 bytes
can be encoded.</p>
<p>Revision 2 of Ultracode (2023) may be specified using
@ -8117,12 +8141,13 @@ not include a check digit.</p>
<h1 id="legal-and-version-information">7. Legal and Version
Information</h1>
<h2 id="license">7.1 License</h2>
<p>Zint, libzint and Zint Barcode Studio are Copyright © 2025 Robin
Stuart. All historical versions are distributed under the GNU General
Public License version 3 or later. Versions 2.5 and later are released
under a dual license: the encoding library is released under the BSD (3
clause) license whereas the GUI, Zint Barcode Studio, and the CLI are
released under the GNU General Public License version 3 or later.</p>
<p>Zint, <code>libzint</code> and Zint Barcode Studio are Copyright ©
2025 Robin Stuart. All historical versions are distributed under the GNU
General Public License version 3 or later. Versions 2.5 and later are
released under a dual license: the encoding library is released under
the BSD (3 clause) license whereas the GUI, Zint Barcode Studio, and the
CLI are released under the GNU General Public License version 3 or
later.</p>
<p>Telepen is a trademark of SB Electronic Systems Ltd.</p>
<p>QR Code is a registered trademark of Denso Wave Incorporated.</p>
<p>Mailmark is a registered trademark of Royal Mail Group Ltd.</p>
@ -8685,28 +8710,28 @@ properties that correspond to the <code>zint_symbol</code> structure
method <code>render()</code> which takes a Qt <code>QPainter</code> to
paint with, and a <code>QRectF</code> rectangular area specifying where
to paint into:</p>
<div class="sourceCode" id="cb120"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb120-1"><a href="#cb120-1" aria-hidden="true" tabindex="-1"></a><span class="co">/* Encode and display barcode in `paintRect` using `painter`.</span></span>
<span id="cb120-2"><a href="#cb120-2" aria-hidden="true" tabindex="-1"></a><span class="co"> Note: legacy argument `mode` is not used */</span></span>
<span id="cb120-3"><a href="#cb120-3" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> render<span class="op">(</span><span class="ex">QPainter</span><span class="op">&amp;</span> painter<span class="op">,</span> <span class="at">const</span> <span class="ex">QRectF</span><span class="op">&amp;</span> paintRect<span class="op">,</span></span>
<span id="cb120-4"><a href="#cb120-4" aria-hidden="true" tabindex="-1"></a> AspectRatioMode mode <span class="op">=</span> IgnoreAspectRatio<span class="op">);</span></span></code></pre></div>
<div class="sourceCode" id="cb121"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb121-1"><a href="#cb121-1" aria-hidden="true" tabindex="-1"></a><span class="co">/* Encode and display barcode in `paintRect` using `painter`.</span></span>
<span id="cb121-2"><a href="#cb121-2" aria-hidden="true" tabindex="-1"></a><span class="co"> Note: legacy argument `mode` is not used */</span></span>
<span id="cb121-3"><a href="#cb121-3" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> render<span class="op">(</span><span class="ex">QPainter</span><span class="op">&amp;</span> painter<span class="op">,</span> <span class="at">const</span> <span class="ex">QRectF</span><span class="op">&amp;</span> paintRect<span class="op">,</span></span>
<span id="cb121-4"><a href="#cb121-4" aria-hidden="true" tabindex="-1"></a> AspectRatioMode mode <span class="op">=</span> IgnoreAspectRatio<span class="op">);</span></span></code></pre></div>
<p><code>render()</code> will emit one of two Qt signals -
<code>encoded</code> on successful encoding and drawing, or
<code>errored</code> on failure. The client can connect and act
appropriately, for instance:</p>
<div class="sourceCode" id="cb121"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb121-1"><a href="#cb121-1" aria-hidden="true" tabindex="-1"></a><span class="fu">connect</span><span class="op">(</span>qzint<span class="op">,</span> <span class="ex">SIGNAL</span><span class="op">(</span>encoded<span class="op">()),</span> <span class="ex">SLOT</span><span class="op">(</span>on_encoded<span class="op">()));</span></span>
<span id="cb121-2"><a href="#cb121-2" aria-hidden="true" tabindex="-1"></a><span class="fu">connect</span><span class="op">(</span>qzint<span class="op">,</span> <span class="ex">SIGNAL</span><span class="op">(</span>errored<span class="op">()),</span> <span class="ex">SLOT</span><span class="op">(</span>on_errored<span class="op">()));</span></span></code></pre></div>
<div class="sourceCode" id="cb122"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb122-1"><a href="#cb122-1" aria-hidden="true" tabindex="-1"></a><span class="fu">connect</span><span class="op">(</span>qzint<span class="op">,</span> <span class="ex">SIGNAL</span><span class="op">(</span>encoded<span class="op">()),</span> <span class="ex">SLOT</span><span class="op">(</span>on_encoded<span class="op">()));</span></span>
<span id="cb122-2"><a href="#cb122-2" aria-hidden="true" tabindex="-1"></a><span class="fu">connect</span><span class="op">(</span>qzint<span class="op">,</span> <span class="ex">SIGNAL</span><span class="op">(</span>errored<span class="op">()),</span> <span class="ex">SLOT</span><span class="op">(</span>on_errored<span class="op">()));</span></span></code></pre></div>
<p>where <code>qzint</code> is an instance of <code>Zint::QZint</code>
and <code>on_encoded()</code> and <code>on_error()</code> are Qt slot
methods provided by the caller. On error, the error value and message
can be retrieved by the methods <code>getError()</code> and
<code>lastError()</code> respectively.</p>
<p>The other main method is <code>save_to_file()</code>:</p>
<div class="sourceCode" id="cb122"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb122-1"><a href="#cb122-1" aria-hidden="true" tabindex="-1"></a><span class="co">/* Encode and print barcode to file `filename`.</span></span>
<span id="cb122-2"><a href="#cb122-2" aria-hidden="true" tabindex="-1"></a><span class="co"> Only sets `getError()` on error, not on warning */</span></span>
<span id="cb122-3"><a href="#cb122-3" aria-hidden="true" tabindex="-1"></a><span class="dt">bool</span> save_to_file<span class="op">(</span><span class="at">const</span> <span class="ex">QString</span><span class="op">&amp;</span> filename<span class="op">);</span> <span class="co">// `ZBarcode_Print()`</span></span></code></pre></div>
<div class="sourceCode" id="cb123"><pre
class="sourceCode cpp"><code class="sourceCode cpp"><span id="cb123-1"><a href="#cb123-1" aria-hidden="true" tabindex="-1"></a><span class="co">/* Encode and print barcode to file `filename`.</span></span>
<span id="cb123-2"><a href="#cb123-2" aria-hidden="true" tabindex="-1"></a><span class="co"> Only sets `getError()` on error, not on warning */</span></span>
<span id="cb123-3"><a href="#cb123-3" aria-hidden="true" tabindex="-1"></a><span class="dt">bool</span> save_to_file<span class="op">(</span><span class="at">const</span> <span class="ex">QString</span><span class="op">&amp;</span> filename<span class="op">);</span> <span class="co">// `ZBarcode_Print()`</span></span></code></pre></div>
<p>which takes a <code>filename</code> to output to. It too will emit an
<code>errored</code> signal on failure, returning <code>false</code>
(but nothing on success, which just returns <code>true</code>). Note
@ -8721,12 +8746,12 @@ symbology capabilities, and utility methods such as
<h1 id="annex-c.-tcl-backend-binding">Annex C. Tcl Backend Binding</h1>
<p>A Tcl binding is available in the <code>"backend_tcl</code>”
sub-directory. To make on Unix:</p>
<div class="sourceCode" id="cb123"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb123-1"><a href="#cb123-1" aria-hidden="true" tabindex="-1"></a><span class="bu">cd</span> backend_tcl</span>
<span id="cb123-2"><a href="#cb123-2" aria-hidden="true" tabindex="-1"></a><span class="fu">autoconf</span></span>
<span id="cb123-3"><a href="#cb123-3" aria-hidden="true" tabindex="-1"></a><span class="ex">./configure</span></span>
<span id="cb123-4"><a href="#cb123-4" aria-hidden="true" tabindex="-1"></a><span class="fu">make</span></span>
<span id="cb123-5"><a href="#cb123-5" aria-hidden="true" tabindex="-1"></a><span class="fu">sudo</span> make install</span></code></pre></div>
<div class="sourceCode" id="cb124"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb124-1"><a href="#cb124-1" aria-hidden="true" tabindex="-1"></a><span class="bu">cd</span> backend_tcl</span>
<span id="cb124-2"><a href="#cb124-2" aria-hidden="true" tabindex="-1"></a><span class="fu">autoconf</span></span>
<span id="cb124-3"><a href="#cb124-3" aria-hidden="true" tabindex="-1"></a><span class="ex">./configure</span></span>
<span id="cb124-4"><a href="#cb124-4" aria-hidden="true" tabindex="-1"></a><span class="fu">make</span></span>
<span id="cb124-5"><a href="#cb124-5" aria-hidden="true" tabindex="-1"></a><span class="fu">sudo</span> make install</span></code></pre></div>
<p>For Windows, a Microsoft Visual C++ project file is available at
<code>"backend_tcl\zint_tcl.vcxproj"</code>. Note that this assumes that
Tcl/Tk is available in <code>"C:\Tcl"</code> and that the libraries are
@ -8737,21 +8762,21 @@ to match your setup. There is also a Visual Studio makefile available at
<code>"backend_tcl\win\README.txt"</code>.</p>
<p>Once built and installed, invoke the Tcl/Tk CLI
<code>"wish"</code>:</p>
<div class="sourceCode" id="cb124"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb124-1"><a href="#cb124-1" aria-hidden="true" tabindex="-1"></a><span class="ex">wish</span></span></code></pre></div>
<div class="sourceCode" id="cb125"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb125-1"><a href="#cb125-1" aria-hidden="true" tabindex="-1"></a><span class="ex">wish</span></span></code></pre></div>
<p>and ignoring the Tk window click back to the command prompt
<code>"%"</code> and type:</p>
<div class="sourceCode" id="cb125"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb125-1"><a href="#cb125-1" aria-hidden="true" tabindex="-1"></a><span class="ex">package</span> require zint</span>
<span id="cb125-2"><a href="#cb125-2" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> help</span></code></pre></div>
<div class="sourceCode" id="cb126"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb126-1"><a href="#cb126-1" aria-hidden="true" tabindex="-1"></a><span class="ex">package</span> require zint</span>
<span id="cb126-2"><a href="#cb126-2" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> help</span></code></pre></div>
<p>which will show the usage message, with options very similiar to the
Zint CLI. (One notable difference is that boolean options such as
<code>-bold</code> take a <code>1</code> or <code>0</code> as an
argument.)</p>
<p>A demonstration Tcl/Tk program which is also useful in itself is
available at <code>"backend_tcl/demo/demo.tcl"</code>. To run type:</p>
<div class="sourceCode" id="cb126"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb126-1"><a href="#cb126-1" aria-hidden="true" tabindex="-1"></a><span class="ex">wish</span> demo/demo.tcl</span></code></pre></div>
<div class="sourceCode" id="cb127"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb127-1"><a href="#cb127-1" aria-hidden="true" tabindex="-1"></a><span class="ex">wish</span> demo/demo.tcl</span></code></pre></div>
<p>which will display the following window.</p>
<figure>
<img src="images/tcl_demo.png" title="fig:" class="pop"
@ -9471,17 +9496,17 @@ Error counterpart of warning if <code>--werror</code> given
<h2 id="examples">EXAMPLES</h2>
<p>Create “out.png” (or “out.gif” if zint built without PNG support) in
the current directory, as a Code 128 symbol.</p>
<div class="sourceCode" id="cb135"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb135-1"><a href="#cb135-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-d</span> <span class="st">&#39;This Text&#39;</span></span></code></pre></div>
<p>Create “qr.svg” in the current directory, as a QR Code symbol.</p>
<div class="sourceCode" id="cb136"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb136-1"><a href="#cb136-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> QRCode <span class="at">-d</span> <span class="st">&#39;This Text&#39;</span> <span class="at">-o</span> <span class="st">&#39;qr.svg&#39;</span></span></code></pre></div>
class="sourceCode bash"><code class="sourceCode bash"><span id="cb136-1"><a href="#cb136-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-d</span> <span class="st">&#39;This Text&#39;</span></span></code></pre></div>
<p>Create “qr.svg” in the current directory, as a QR Code symbol.</p>
<div class="sourceCode" id="cb137"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb137-1"><a href="#cb137-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> QRCode <span class="at">-d</span> <span class="st">&#39;This Text&#39;</span> <span class="at">-o</span> <span class="st">&#39;qr.svg&#39;</span></span></code></pre></div>
<p>Use batch mode to read from an input file “ean13nos.txt” containing a
list of 13-digit GTINs, each on a separate line, to create a series of
EAN-13 barcodes, formatting the output filenames to “ean001.gif”,
“ean002.gif” etc. using the special character “~”.</p>
<div class="sourceCode" id="cb137"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb137-1"><a href="#cb137-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> EANX <span class="at">--batch</span> <span class="at">-i</span> <span class="st">&#39;ean13nos.txt&#39;</span> <span class="at">-o</span> <span class="st">&#39;ean~~~.gif&#39;</span></span></code></pre></div>
<div class="sourceCode" id="cb138"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb138-1"><a href="#cb138-1" aria-hidden="true" tabindex="-1"></a><span class="ex">zint</span> <span class="at">-b</span> EANX <span class="at">--batch</span> <span class="at">-i</span> <span class="st">&#39;ean13nos.txt&#39;</span> <span class="at">-o</span> <span class="st">&#39;ean~~~.gif&#39;</span></span></code></pre></div>
<h2 id="bugs">BUGS</h2>
<p>Please send bug reports to
https://sourceforge.net/p/zint/tickets/.</p>
@ -9590,13 +9615,17 @@ class="footnote-back" role="doc-backlink">↩︎</a></p></li>
<li id="fn17"><p><code>ZINT_CAP_EANUPC</code> was previously named
<code>ZINT_CAP_EXTENDABLE</code>, which is still recognised.<a
href="#fnref17" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
<li id="fn18"><p><code>BARCODE_CODE128AB</code> previously used the name
<code>BARCODE_CODE128B</code>, which is still recognised.<a
<li id="fn18"><p>The library <code>libzueci</code>, which can convert
both to and from UTF-8 and ECI, is available at <a
href="https://sourceforge.net/projects/libzueci/">https://sourceforge.net/projects/libzueci/</a>.<a
href="#fnref18" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
<li id="fn19"><p>The DX number may be looked up in The (Modified) Big
<li id="fn19"><p><code>BARCODE_CODE128AB</code> previously used the name
<code>BARCODE_CODE128B</code>, which is still recognised.<a
href="#fnref19" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
<li id="fn20"><p>The DX number may be looked up in The (Modified) Big
Film Database at <a
href="https://thebigfilmdatabase.merinorus.com">https://thebigfilmdatabase.merinorus.com</a>.<a
href="#fnref19" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
href="#fnref20" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
</ol>
</section>
</body>

43
docs/manual.pmd
View File

@ -2482,8 +2482,8 @@ being the number of elements it contains. The zint_seg structure is of the form:
```c
struct zint_seg {
unsigned char *source; /* Data to encode */
int length; /* Length of `source`. If 0, `source` must be
NUL-terminated */
int length; /* Length of `source`. If 0 or negative, `source`
must be NUL-terminated */
int eci; /* Extended Channel Interpretation */
};
```
@ -2669,7 +2669,34 @@ if (cap & ZINT_CAP_ECI) {
}
```
## 5.16 Zint Version
## 5.16 UTF-8 to ECI convenience functions
As a convenience the conversion done by Zint from UTF-8 to ECIs is exposed in
two helper functions (compatible with the `libzueci`[^18] functions
`zueci_utf8_to_eci()` and `zueci_dest_len_eci()`):
```c
int ZBarcode_UTF8_To_ECI(int eci, const unsigned char *source, int length,
unsigned char dest[], int *p_dest_length);
int ZBarcode_Dest_Len_ECI(int eci, const unsigned char *source, int length,
int *p_dest_length);
```
Call `ZBarcode_Dest_Len_ECI()` to get the size of buffer sufficient to
accommodate the conversion, then call `ZBarcode_UTF8_To_ECI()` with an
appropriately sized buffer to do the conversion. The final destination length,
returned in `p_dest_length`, may be smaller than the estimate given by
`ZBarcode_Dest_Len_ECI()`. If `length` is zero or less, `source` must be
NUL-terminated. The destination buffer is not NUL-terminated. The obsolete ECIs
0, 1 and 2 are supported.
[^18]: The library `libzueci`, which can convert both to and from UTF-8 and ECI,
is available at [https://sourceforge.net/projects/libzueci/](
https://sourceforge.net/projects/libzueci/).
## 5.17 Zint Version
Whether the Zint library linked to was built with PNG support may be determined
with:
@ -3192,13 +3219,13 @@ alphanumerics) are not recommended.
![`zint -b CODE128AB -d "130170X178"`](images/code128ab.svg){.lin}
It is sometimes advantageous to stop Code 128 from using Code Set C which
compresses numerical data. The `BARCODE_CODE128AB`[^18] variant (symbology 60)
compresses numerical data. The `BARCODE_CODE128AB`[^19] variant (symbology 60)
suppresses Code Set C in favour of Code Sets A and B.
Note that the special extra escapes mentioned above are not available for this
variant (nor for any other).
[^18]: `BARCODE_CODE128AB` previously used the name `BARCODE_CODE128B`, which is
[^19]: `BARCODE_CODE128AB` previously used the name `BARCODE_CODE128B`, which is
still recognised.
#### 6.1.10.3 GS1-128
@ -3790,7 +3817,7 @@ first and last digit are ignored, leaving a 4-digit DX Extract number in any
case, which must be in the range 16 to 2047. The second format `"NNN-NN"`
represents the DX Extract as two numbers separated by a dash (`-`), the first
number being 1 to 3 digits (range 1 to 127) and the second 1 to 2 digits (range
0 to 15).[^19]
0 to 15).[^20]
The optional frame number is a number in the range 0 to 63, and may have a half
frame indicator `"A"` appended. Special character sequences (with or without a
@ -3800,7 +3827,7 @@ number 62, `"K"` or `"00"` means frame number 63, and `"F"` means frame number
A parity bit is automatically added by Zint.
[^19]: The DX number may be looked up in The (Modified) Big Film Database at
[^20]: The DX number may be looked up in The (Modified) Big Film Database at
[https://thebigfilmdatabase.merinorus.com](
https://thebigfilmdatabase.merinorus.com).
@ -4796,7 +4823,7 @@ maximum of 128 digits and does not include a check digit.
## 7.1 License
Zint, libzint and Zint Barcode Studio are Copyright © 2025 Robin Stuart. All
Zint, `libzint` and Zint Barcode Studio are Copyright © 2025 Robin Stuart. All
historical versions are distributed under the GNU General Public License version
3 or later. Versions 2.5 and later are released under a dual license: the
encoding library is released under the BSD (3 clause) license whereas the GUI,

40
docs/manual.txt
View File

@ -72,7 +72,8 @@ February 2025
- 5.13 Scaling Helpers
- 5.14 Verifying Symbology Availability
- 5.15 Checking Symbology Capabilities
- 5.16 Zint Version
- 5.16 UTF-8 to ECI convenience functions
- 5.17 Zint Version
- 6. Types of Symbology
- 6.1 One-Dimensional Symbols
- 6.1.1 Code 11
@ -2434,8 +2435,8 @@ number of elements it contains. The zint_seg structure is of the form:
struct zint_seg {
unsigned char *source; /* Data to encode */
int length; /* Length of `source`. If 0, `source` must be
NUL-terminated */
int length; /* Length of `source`. If 0 or negative, `source`
must be NUL-terminated */
int eci; /* Extended Channel Interpretation */
};
@ -2599,7 +2600,27 @@ For example:
printf("PDF417 does not support ECI\n");
}
5.16 Zint Version
5.16 UTF-8 to ECI convenience functions
As a convenience the conversion done by Zint from UTF-8 to ECIs is exposed in
two helper functions (compatible with the libzueci[18] functions
zueci_utf8_to_eci() and zueci_dest_len_eci()):
int ZBarcode_UTF8_To_ECI(int eci, const unsigned char *source, int length,
unsigned char dest[], int *p_dest_length);
int ZBarcode_Dest_Len_ECI(int eci, const unsigned char *source, int length,
int *p_dest_length);
Call ZBarcode_Dest_Len_ECI() to get the size of buffer sufficient to accommodate
the conversion, then call ZBarcode_UTF8_To_ECI() with an appropriately sized
buffer to do the conversion. The final destination length, returned in
p_dest_length, may be smaller than the estimate given by
ZBarcode_Dest_Len_ECI(). If length is zero or less, source must be
NUL-terminated. The destination buffer is not NUL-terminated. The obsolete ECIs
0, 1 and 2 are supported.
5.17 Zint Version
Whether the Zint library linked to was built with PNG support may be determined
with:
@ -3069,7 +3090,7 @@ alphanumerics) are not recommended.
[zint -b CODE128AB -d "130170X178"]
It is sometimes advantageous to stop Code 128 from using Code Set C which
compresses numerical data. The BARCODE_CODE128AB[18] variant (symbology 60)
compresses numerical data. The BARCODE_CODE128AB[19] variant (symbology 60)
suppresses Code Set C in favour of Code Sets A and B.
Note that the special extra escapes mentioned above are not available for this
@ -3621,7 +3642,7 @@ first and last digit are ignored, leaving a 4-digit DX Extract number in any
case, which must be in the range 16 to 2047. The second format "NNN-NN"
represents the DX Extract as two numbers separated by a dash (-), the first
number being 1 to 3 digits (range 1 to 127) and the second 1 to 2 digits (range
0 to 15).[19]
0 to 15).[20]
The optional frame number is a number in the range 0 to 63, and may have a half
frame indicator "A" appended. Special character sequences (with or without a
@ -5656,8 +5677,11 @@ representable in HRT.
[17] ZINT_CAP_EANUPC was previously named ZINT_CAP_EXTENDABLE, which is still
recognised.
[18] BARCODE_CODE128AB previously used the name BARCODE_CODE128B, which is still
[18] The library libzueci, which can convert both to and from UTF-8 and ECI, is
available at https://sourceforge.net/projects/libzueci/.
[19] BARCODE_CODE128AB previously used the name BARCODE_CODE128B, which is still
recognised.
[19] The DX number may be looked up in The (Modified) Big Film Database at
[20] The DX number may be looked up in The (Modified) Big Film Database at
https://thebigfilmdatabase.merinorus.com.