Main class for processing GS1 barcode data, including validation, format conversion, and generation of outputs such as GS1 Digital Link URIs and Human-Readable Interpretation text. More...

#include <gs1encoders.hpp>

Public Member Functions
	GS1Encoder ()
	Initialises a new instance of the GS1Encoder class.

	GS1Encoder (const InitOpts &opts)
	Initialises a new instance of the GS1Encoder class with the given options.

	~GS1Encoder ()
	Destructor. Releases the native context.

	GS1Encoder (const GS1Encoder &)=delete
	Copy construction is deleted: the underlying native context cannot be duplicated.

GS1Encoder &	operator= (const GS1Encoder &)=delete
	Copy assignment is deleted: the underlying native context cannot be duplicated.

	GS1Encoder (GS1Encoder &&other) noexcept
	Move-construct from another encoder.

GS1Encoder &	operator= (GS1Encoder &&other) noexcept
	Move-assign from another encoder.

std::optional< std::string >	init_fallback_warning () const
	The warning message produced when initialisation fell back to the embedded AI table because the supplied Syntax Dictionary could not be loaded.

std::string	version () const
	Get the version string of the library.

int	max_data_str_length () const
	Get the maximum size of the input data buffer for barcode message content.

Symbology	sym () const
	Get the current symbology type.

void	set_sym (Symbology s)
	Set the current symbology type.

bool	add_check_digit () const
	Get the current "add check digit" mode.

void	set_add_check_digit (bool v)
	Enable or disable "add check digit" mode for EAN/UPC and GS1 DataBar symbols.

bool	permit_unknown_ais () const
	Get the current "permit unknown AIs" mode.

void	set_permit_unknown_ais (bool v)
	Enable or disable acceptance of unknown AIs in parsed input.

bool	permit_zero_suppressed_gtin_in_dl_uris () const
	Get the current "permit zero-suppressed GTIN in GS1 DL URIs" mode.

void	set_permit_zero_suppressed_gtin_in_dl_uris (bool v)
	Enable or disable acceptance of zero-suppressed GTINs in GS1 Digital Link URIs.

bool	include_data_titles_in_hri () const
	Get the current "include data titles in HRI" mode.

void	set_include_data_titles_in_hri (bool v)
	Enable or disable inclusion of AI Data Titles in HRI output.

bool	validation_enabled (Validation v) const
	Get the current enabled status of an AI validation procedure.

void	set_validation_enabled (Validation v, bool enabled)
	Enable or disable an AI validation procedure.

std::string	data_str () const
	Get the raw data that would be directly encoded within a GS1 barcode message.

void	set_data_str (const std::string &v)
	Set the raw barcode message data.

std::string	ai_data_str () const
	Get the barcode data input rendered as a bracketed AI element string.

void	set_ai_data_str (const std::string &v)
	Set the barcode data input from a bracketed GS1 AI element string.

std::string	get_dl_uri (const std::string &stem) const
	Render the current AI-based input data as a GS1 Digital Link URI.

std::string	scan_data () const
	Get the scan data string a reader would return for the current data and symbology.

void	set_scan_data (const std::string &v)
	Process normalised scan data received from a barcode reader.

std::vector< std::string >	hri () const
	Get the Human-Readable Interpretation ("HRI") text for the current input data.

std::vector< std::string >	dl_ignored_query_params () const
	Get the non-numeric (ignored) query parameters from a GS1 Digital Link URI.

std::string	err_markup () const
	Get the marked-up offending AI from the most recent linting failure.

Detailed Description

Main class for processing GS1 barcode data, including validation, format conversion, and generation of outputs such as GS1 Digital Link URIs and Human-Readable Interpretation text.

Move-only: the underlying native context cannot be duplicated, but ownership can be transferred. The destructor releases the native resources, so the object can be used at any scope without manual cleanup.

Constructor & Destructor Documentation

◆ GS1Encoder() [1/3]

gs1encoders::GS1Encoder::GS1Encoder ( )

inline

Initialises a new instance of the GS1Encoder class.

Uses default options: the embedded AI table is loaded and no Syntax Dictionary file is read.

Exceptions

GS1EncoderGeneralException if the library fails to initialise.

See also: GS1Encoder(const InitOpts &)

◆ GS1Encoder() [2/3]

gs1encoders::GS1Encoder::GS1Encoder ( const InitOpts & opts )

inlineexplicit

Initialises a new instance of the GS1Encoder class with the given options.

If construction succeeds but the embedded AI table was loaded as a fallback (because the supplied gs1encoders::InitOpts::syntax_dictionary() failed to load and gs1encoders::InitOpts::fallback_on_syndict_error() was set), the underlying load error is exposed via init_fallback_warning().

Parameters

opts	initialisation options.

Exceptions

GS1EncoderGeneralException if the library fails to initialise.

See also: GS1Encoder(); InitOpts; init_fallback_warning()

◆ ~GS1Encoder()

gs1encoders::GS1Encoder::~GS1Encoder ( )

inline

Destructor. Releases the native context.

Safe to invoke on a moved-from object (which holds no context).

◆ GS1Encoder() [3/3]

gs1encoders::GS1Encoder::GS1Encoder ( GS1Encoder && other )

inlinenoexcept

Move-construct from another encoder.

Transfers ownership of the native context (and any init_fallback_warning() value) from other. After the move, other holds no context and must not be used for any operation other than destruction or move-assignment.

Member Function Documentation

◆ add_check_digit()

bool gs1encoders::GS1Encoder::add_check_digit ( ) const

inline

Get the current "add check digit" mode.

Returns: true if check digits will be generated automatically; false if the data must include a valid check digit.

See also: set_add_check_digit()

◆ ai_data_str()

std::string gs1encoders::GS1Encoder::ai_data_str ( ) const

inline

Get the barcode data input rendered as a bracketed AI element string.

Returns the data as a human-friendly bracketed AI element string, for example "(01)12312312312333(10)ABC123(99)TEST". Returns an empty string when the input data does not contain AI data.

Returns: the bracketed AI element string, or an empty string when no AI data is set.

See also: set_ai_data_str(); data_str()

◆ data_str()

std::string gs1encoders::GS1Encoder::data_str ( ) const

inline

Get the raw data that would be directly encoded within a GS1 barcode message.

Returns the contents of the library's barcode message buffer. Equivalent to the value last passed to set_data_str(), or the encoding produced from set_ai_data_str() or set_scan_data().

Returns: the raw barcode data input buffer.

See also: set_data_str(); ai_data_str(); set_ai_data_str(); set_scan_data()

◆ dl_ignored_query_params()

std::vector< std::string > gs1encoders::GS1Encoder::dl_ignored_query_params ( ) const

inline

Get the non-numeric (ignored) query parameters from a GS1 Digital Link URI.

When set_data_str() parses a GS1 Digital Link URI, query parameters that are not numeric AI keys are ignored for the purposes of AI extraction. This method returns those ignored parameters so the application can present which sections of the URI were not interpreted as AI data.

For example, given the input data https://a/01/12312312312333/22/ABC?name=Donald%2dDuck&99=ABC&testing&type=cartoon, this method returns:

name=Donald%2dDuck
testing
type=cartoon

The returned strings are not URI-decoded.

Returns: one std::string per ignored query parameter; empty vector when no DL URI has been parsed or none were ignored.

See also: set_data_str()

◆ err_markup()

std::string gs1encoders::GS1Encoder::err_markup ( ) const

inline

Get the marked-up offending AI from the most recent linting failure.

When a setter throws gs1encoders::GS1EncoderParameterException because of a linting failure on AI-based data, this method returns a marked-up rendering of the offending AI. Where it is meaningful to identify the offending characters within the AI value, those characters are surrounded by "|" characters; otherwise the entire AI value is surrounded by "|" characters.

Returns an empty string when no linting failure has been recorded.

Returns: the marked-up offending AI, or an empty string.

See also: set_data_str(); set_ai_data_str()

◆ get_dl_uri()

std::string gs1encoders::GS1Encoder::get_dl_uri ( const std::string & stem ) const

inline

Render the current AI-based input data as a GS1 Digital Link URI.

Converts the current AI data into GS1 Digital Link URI form. For example, the AI data (01)12345678901231(10)ABC123(11)210630 with stem https://id.example.com/stem might produce https://id.example.com/stem/01/12345678901231?10=ABC123&11=210630.

Parameters

stem	URI stem used as a prefix; pass an empty string to use the GS1 canonical stem (`https://id.gs1.org/`).

Returns: the GS1 Digital Link URI for the current data.

Exceptions

GS1EncoderDigitalLinkException if the current data cannot be expressed as a GS1 Digital Link URI (for example because no AI data is set).

See also: set_ai_data_str(); set_data_str()

◆ hri()

std::vector< std::string > gs1encoders::GS1Encoder::hri ( ) const

inline

Get the Human-Readable Interpretation ("HRI") text for the current input data.

Returns one HRI line per AI in the order they appear in the data. For composite symbols a separator line "--" is inserted to distinguish the linear and 2D components, for example for input ^011231231231233310ABC123|^99XYZ(TM) CORP the HRI is:

(01) 12312312312333
(10) ABC123
--
(99) XYZ(TM) CORP

AI Data Titles from the GS1 General Specifications are included when include_data_titles_in_hri() is enabled.

Returns: one std::string per HRI line; empty vector when no AI data is set.

See also: set_include_data_titles_in_hri(); set_ai_data_str()

◆ include_data_titles_in_hri()

bool gs1encoders::GS1Encoder::include_data_titles_in_hri ( ) const

inline

Get the current "include data titles in HRI" mode.

Returns: true if HRI output includes AI Data Titles from the GS1 General Specifications; false otherwise.

See also: set_include_data_titles_in_hri(); hri()

◆ init_fallback_warning()

std::optional< std::string > gs1encoders::GS1Encoder::init_fallback_warning ( ) const

inline

The warning message produced when initialisation fell back to the embedded AI table because the supplied Syntax Dictionary could not be loaded.

Set only when both gs1encoders::InitOpts::syntax_dictionary() and gs1encoders::InitOpts::fallback_on_syndict_error() were used, the dictionary file failed to open or parse, and the embedded AI table was loaded as a fallback. In that case the returned optional contains the load error reported by the underlying library (e.g. "Cannot read file …"); on plain successful initialisation, the returned optional is std::nullopt.

The value is fixed at construction; subsequent operations on the encoder do not modify it.

Returns: underlying load error message, or std::nullopt on plain success.

See also: GS1Encoder(const InitOpts &); InitOpts::fallback_on_syndict_error()

◆ max_data_str_length()

int gs1encoders::GS1Encoder::max_data_str_length ( ) const

inline

Get the maximum size of the input data buffer for barcode message content.

This is an implementation limit; on memory-constrained systems it may be lowered by rebuilding the library. In practice each symbology has its own data capacity that may be somewhat less than this maximum.

Returns: the maximum number of bytes that may be supplied for encoding.

See also: set_data_str(); set_ai_data_str()

◆ operator=()

GS1Encoder & gs1encoders::GS1Encoder::operator= ( GS1Encoder && other )

inlinenoexcept

Move-assign from another encoder.

Frees this object's existing native context (if any) and then transfers ownership of the native context (and any init_fallback_warning() value) from other. After the move, other holds no context and must not be used for any operation other than destruction or move-assignment. Self-assignment is a no-op.

◆ permit_unknown_ais()

bool gs1encoders::GS1Encoder::permit_unknown_ais ( ) const

inline

Get the current "permit unknown AIs" mode.

Returns: true if unknown AIs are accepted in parsed input; false if all AIs in the input data must be known.

See also: set_permit_unknown_ais()

◆ permit_zero_suppressed_gtin_in_dl_uris()

bool gs1encoders::GS1Encoder::permit_zero_suppressed_gtin_in_dl_uris ( ) const

inline

Get the current "permit zero-suppressed GTIN in GS1 DL URIs" mode.

Returns: true if zero-suppressed GTINs are permitted in GS1 Digital Link URIs; false otherwise.

See also: set_permit_zero_suppressed_gtin_in_dl_uris()

◆ scan_data()

std::string gs1encoders::GS1Encoder::scan_data ( ) const

inline

Get the scan data string a reader would return for the current data and symbology.

Returns the string that a scanner would produce when reading a symbol of the currently selected symbology containing the current input data. The output is prefixed with the appropriate AIM Symbology Identifier (e.g. ]Q3... for GS1 QR Code, ]C1... for GS1-128 with composite). Returns an empty string when no symbology is selected.

Returns: the scan data string, or an empty string when no symbology is selected.

See also: set_scan_data(); sym()

◆ set_add_check_digit()

void gs1encoders::GS1Encoder::set_add_check_digit ( bool v )

inline

Enable or disable "add check digit" mode for EAN/UPC and GS1 DataBar symbols.

When false (the default), the input data must contain a valid check digit. When true, the input data must not contain a check digit; one is computed automatically.

This option is only meaningful for symbologies that accept fixed-length data — specifically EAN/UPC and GS1 DataBar except Expanded (Stacked).

Parameters

v	`true` to enable automatic check-digit generation; `false` to require it in the input.

Exceptions

GS1EncoderParameterException if the value is rejected.

See also: add_check_digit()

◆ set_ai_data_str()

void gs1encoders::GS1Encoder::set_ai_data_str ( const std::string & v )

inline

Set the barcode data input from a bracketed GS1 AI element string.

The input is provided in human-friendly format without FNC1 characters (which are inserted automatically), for example:

(01)12345678901231(10)ABC123(11)210630

This syntax harmonises the input format across all symbologies — for example (01)00031234000054 is acceptable for EAN-13, UPC-A, UPC-E, any variant of the GS1 DataBar family, GS1 QR Code and GS1 Data Matrix.

The input is validated against the AI data syntax rules at the point of being set; on failure this setter throws gs1encoders::GS1EncoderParameterException, and when the failure is due to invalid AI content err_markup() returns a marked-up rendering of the offending AI.

Any literal "(" characters in AI element values must be escaped as "\‍(" to avoid being conflated with the start of the next AI.

For symbologies that support a composite component (all except Data Matrix, QR Code and DotCode) the linear and 2D components can be separated with a "|" character, e.g. (01)12345678901231|(10)ABC123(11)210630.

Parameters

v	the bracketed AI element string to be parsed.

Exceptions

GS1EncoderParameterException if the data is invalid; err_markup() identifies the offending AI on a linting failure.

See also: ai_data_str(); set_data_str(); err_markup()

◆ set_data_str()

void gs1encoders::GS1Encoder::set_data_str ( const std::string & v )

inline

Set the raw barcode message data.

A leading "^" indicates the data is in GS1 Application Identifier syntax; subsequent "^" characters represent the FNC1 non-data separator that delimits variable-length fields.

Inputs beginning with "^" are validated against the AI data syntax rules; on failure this setter throws gs1encoders::GS1EncoderParameterException, and when the failure is due to invalid AI content err_markup() returns a marked-up rendering of the offending AI.

Inputs beginning with "http://" or "https://" are parsed as GS1 Digital Link URIs; the corresponding AI element string is extracted and validated.

EAN/UPC, GS1 DataBar and GS1-128 support a Composite Component. The Composite Component must be specified in AI syntax. It is separated from the primary linear component with a "|" character and begins with FNC1 in first position, e.g. "^0112345678901231|^10ABC123^11210630" (linear component (01)12345678901231, composite component (10)ABC123(11)210630).

Note: For GS1 data it is simpler and less error-prone to specify the input in human-friendly bracketed AI syntax via set_ai_data_str(), which inserts FNC1 characters automatically.

Parameters

v	the raw barcode data to be set.

Exceptions

GS1EncoderParameterException if the data is invalid; err_markup() identifies the offending AI on a linting failure.

See also: data_str(); set_ai_data_str(); err_markup()

◆ set_include_data_titles_in_hri()

void gs1encoders::GS1Encoder::set_include_data_titles_in_hri ( bool v )

inline

Enable or disable inclusion of AI Data Titles in HRI output.

When true, AI data titles defined in the GS1 General Specifications are included in the HRI text returned by hri() to give "mixed HRI / non-HRI text" formatting. When false (the default), HRI is produced without data titles.

Parameters

v	`true` to include data titles; `false` to omit them.

Exceptions

GS1EncoderParameterException if the value is rejected.

See also: include_data_titles_in_hri(); hri()

◆ set_permit_unknown_ais()

void gs1encoders::GS1Encoder::set_permit_unknown_ais ( bool v )

inline

Enable or disable acceptance of unknown AIs in parsed input.

When false (the default), all AIs represented by the input data must be known to the library's AI table. When true, unknown AIs (those not in the AI table) are accepted.

Note: The option only applies to parsed input, specifically bracketed AI data supplied via set_ai_data_str() and GS1 Digital Link URIs supplied via set_data_str(). Unbracketed AI element strings containing unknown AIs cannot be parsed because it is not possible to differentiate the AI from its data value when the length of the AI is uncertain.

Parameters

v	`true` to permit unknown AIs; `false` to reject them.

Exceptions

GS1EncoderParameterException if the value is rejected.

See also: permit_unknown_ais(); set_ai_data_str(); set_data_str()

◆ set_permit_zero_suppressed_gtin_in_dl_uris()

void gs1encoders::GS1Encoder::set_permit_zero_suppressed_gtin_in_dl_uris ( bool v )

inline

Enable or disable acceptance of zero-suppressed GTINs in GS1 Digital Link URIs.

When false (the default), the value of a path component for AI (01) must be a full GTIN-14. When true, the value may be a GTIN-14 with leading zeros suppressed (a GTIN-13, GTIN-12 or GTIN-8).

This option only applies to parsed input data, specifically GS1 Digital Link URIs. Since zero-suppressed GTINs are deprecated by the GS1 Digital Link standard, this option should only be enabled when it is necessary to accept legacy GS1 Digital Link URIs that carry zero-suppressed GTIN-14.

Parameters

v	`true` to accept zero-suppressed GTINs; `false` to require GTIN-14.

Exceptions

GS1EncoderParameterException if the value is rejected.

See also: permit_zero_suppressed_gtin_in_dl_uris()

◆ set_scan_data()

void gs1encoders::GS1Encoder::set_scan_data ( const std::string & v )

inline

Process normalised scan data received from a barcode reader.

Parses scan data (such as the output of a barcode reader) with AIM Symbology Identifiers enabled, populates the input data buffer with the message received, and selects a symbology that is able to carry the received data. Performs syntax checks for GS1 Digital Link and AI data input.

Example scan data input: ]C1011231231231233310ABC123{GS}99TESTING where {GS} represents ASCII character 29 (the FNC1 / GS separator).

A literal "|" character may be included in the scan data to indicate the separation between the first and second messages that would be transmitted by a reader configured to return the composite component when reading EAN/UPC symbols.

Note: In some instances the symbology determined by this library will not match that of the image actually scanned: the AIM Symbology Identifier prefix does not always uniquely identify the source symbology. For example GS1-128 Composite symbols share the same identifier as the GS1 DataBar family, and will therefore be detected as such.

Parameters

v	the normalised scan data string, including the AIM Symbology Identifier prefix.

Exceptions

GS1EncoderScanDataException if the scan data cannot be processed (for example because the AIM identifier is missing or the embedded data fails validation).

See also: scan_data(); sym()

◆ set_sym()

void gs1encoders::GS1Encoder::set_sym ( Symbology s )

inline

Set the current symbology type.

Parameters

s	the symbology type to set, from gs1encoders::Symbology.

Exceptions

GS1EncoderParameterException if an invalid symbology type is provided.

See also: sym(); Symbology

◆ set_validation_enabled()

void gs1encoders::GS1Encoder::set_validation_enabled	(	Validation	v,
		bool	enabled
	)

inline

Enable or disable an AI validation procedure.

Determines whether the given check is enforced when AI data is supplied via set_ai_data_str(), set_data_str() or set_scan_data(). When enabled is true the validation will be enforced; when false it will not.

Note: Some validation procedures are locked: always enabled and not modifiable. Attempting to change their status throws gs1encoders::GS1EncoderParameterException. The locked procedures are documented on each enumerator of gs1encoders::Validation.

Parameters

v	the validation procedure to set.
enabled	`true` to enable; `false` to disable.

Exceptions

GS1EncoderParameterException if the procedure is locked or the value is otherwise rejected.

See also: validation_enabled(); Validation

◆ sym()

Symbology gs1encoders::GS1Encoder::sym ( ) const

inline

Get the current symbology type.

May be set manually via set_sym() or automatically when processing scan data with set_scan_data().

Returns: the current symbology type.

See also: set_sym(); set_scan_data(); Symbology

◆ validation_enabled()

bool gs1encoders::GS1Encoder::validation_enabled ( Validation v ) const

inline

Get the current enabled status of an AI validation procedure.

Returns the status of one of the validation procedures defined in the gs1encoders::Validation enumeration. Some procedures are locked-on (always enabled and not modifiable); their getters always return true.

Parameters

v	the validation procedure to query.

Returns: true if the procedure is currently enabled.

See also: set_validation_enabled(); Validation

◆ version()

std::string gs1encoders::GS1Encoder::version ( ) const

inline

Get the version string of the library.

Returns a string containing the version of the library, typically the build date.

Returns: the version of the library.

The documentation for this class was generated from the following file:

gs1encoders.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ GS1Encoder() [1/3]

◆ GS1Encoder() [2/3]

◆ ~GS1Encoder()

◆ GS1Encoder() [3/3]

Member Function Documentation

◆ add_check_digit()

◆ ai_data_str()

◆ data_str()

◆ dl_ignored_query_params()

◆ err_markup()

◆ get_dl_uri()

◆ hri()

◆ include_data_titles_in_hri()

◆ init_fallback_warning()

◆ max_data_str_length()

◆ operator=()

◆ permit_unknown_ais()

◆ permit_zero_suppressed_gtin_in_dl_uris()

◆ scan_data()

◆ set_add_check_digit()

◆ set_ai_data_str()

◆ set_data_str()

◆ set_include_data_titles_in_hri()

◆ set_permit_unknown_ais()

◆ set_permit_zero_suppressed_gtin_in_dl_uris()

◆ set_scan_data()

◆ set_sym()

◆ set_validation_enabled()

◆ sym()

◆ validation_enabled()

◆ version()