GS1Encoder

public class GS1Encoder

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.

  • Recognised GS1 barcode formats (“symbologies”) for processing scan data.

    This enum defines all supported GS1 barcode symbology types that can be used with the encoder. Each symbology has specific characteristics and use cases.

    See more

    Declaration

    Swift

    public enum Symbology : Int32

  • Optional AI validation procedures that may be applied to detect invalid inputs.

    These validation procedures are applied when AI data is provided using setAIdataStr(_:), setDataStr(_:) or setScanData(_:).

    Note

    Some validation procedures are “locked” (always enabled and cannot be modified). All validation procedures are listed to maintain correct enum value alignment with the native library.
    See more

    Declaration

    Swift

    public enum Validation : UInt32

  • Initialises a new instance of the GS1Encoder class.

    Throws

    GS1EncoderError.generalError if the library fails to initialise

    Declaration

    Swift

    public init() throws

  • Release library resources.

    This method will release the resources allocated by the native library. After calling this method, the GS1Encoder instance should not be used.

    Declaration

    Swift

    public func free()

  • Get the version string of the library.

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

    Declaration

    Swift

    public func getVersion() -> String

    Return Value

    The version of the library

  • Get the current symbology type.

    This might be set manually via setSym(_:) or automatically when processing scan data with setScanData(_:).

    See also

    setSym(_:)

    See also

    Symbology

    See also

    setScanData(_:)

    Declaration

    Swift

    public func getSym() -> Symbology

    Return Value

    The current symbology type

  • Set the symbology type.

    This allows the symbology to be specified as any one of the Symbology types.

    Throws

    GS1EncoderError.parameterError if an invalid symbology type is provided

    See also

    getSym()

    See also

    Symbology

    Declaration

    Swift

    public func setSym(_ value: Symbology) throws

    Parameters

    value

    The symbology type to set

  • Get the current status of the “add check digit” mode for EAN/UPC and GS1 DataBar symbols.

    See also

    setAddCheckDigit(_:)

    Declaration

    Swift

    public func getAddCheckDigit() -> Bool

    Return Value

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

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

    If false (default), then the data string must contain a valid check digit. If true, then the data string must not contain a check digit as one will be generated automatically.

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

    Throws

    GS1EncoderError.parameterError if the value is invalid

    See also

    getAddCheckDigit()

    Declaration

    Swift

    public func setAddCheckDigit(_ value: Bool) throws

    Parameters

    value

    true to enable automatic check digit generation; false to require check digit in data

  • Get the status of the “include data titles in HRI” flag.

    Returns true if data titles should be included in HRI; otherwise false.

    Declaration

    Swift

    public func getIncludeDataTitlesInHRI() -> Bool

    Return Value

    The status of the “include data titles in HRI” flag

  • Set the “include data titles in HRI” flag.

    When set to true, data titles from the GS1 General Specification will be included in the HRI text.

    Default: false

    Throws

    GS1EncoderError.parameterError if an error occurs

    Declaration

    Swift

    public func setIncludeDataTitlesInHRI(_ value: Bool) throws

    Parameters

    value

    true to include data titles in HRI; false otherwise

  • Get the status of the “permit unknown AIs” mode.

    Returns true if unknown AIs are permitted; otherwise false.

    Declaration

    Swift

    public func getPermitUnknownAIs() -> Bool

    Return Value

    The status of the “permit unknown AIs” mode

  • Set the “permit unknown AIs” mode.

    When set to true, AIs that are not recognised by the library will not be rejected. This can be useful when processing AIs that are not yet supported by the library.

    Default: false

    Throws

    GS1EncoderError.parameterError if an error occurs

    Declaration

    Swift

    public func setPermitUnknownAIs(_ value: Bool) throws

    Parameters

    value

    true to permit unknown AIs; false to reject them

  • Get the status of the “permit zero-suppressed GTIN in GS1 DL URIs” mode.

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

    Declaration

    Swift

    public func getPermitZeroSuppressedGTINinDLuris() -> Bool

    Return Value

    The status of the “permit zero-suppressed GTIN in GS1 DL URIs” mode

  • Set the status of the “permit zero-suppressed GTIN in GS1 DL URIs” mode.

    When set to true, zero-suppressed GTINs (such as GTIN-8, GTIN-12, GTIN-13) will be permitted in Digital Link URIs. When false, GTINs must be expressed in their canonical GTIN-14 form.

    Default: false

    Throws

    GS1EncoderError.parameterError if an error occurs

    Declaration

    Swift

    public func setPermitZeroSuppressedGTINinDLuris(_ value: Bool) throws

    Parameters

    value

    true to permit zero-suppressed GTINs; false to require canonical form

  • Get whether a specific validation procedure is enabled.

    See also

    setValidationEnabled(validation:enabled:)

    See also

    Validation

    Declaration

    Swift

    public func getValidationEnabled(_ validation: Validation) -> Bool

    Parameters

    validation

    The validation procedure to query

    Return Value

    true if the validation is enabled; false otherwise

  • Enable or disable a specific validation procedure.

    Validation procedures can be selectively enabled or disabled to control which checks are applied to AI data.

    Throws

    GS1EncoderError.parameterError if the validation cannot be changed (e.g., it is locked)

    See also

    getValidationEnabled(_:)

    See also

    Validation

    Declaration

    Swift

    public func setValidationEnabled(validation: Validation, enabled: Bool) throws

    Parameters

    validation

    The validation procedure to configure
    enabled

    true to enable the validation; false to disable it

  • Get the “validate AI associations” flag.

    Returns true if mandatory associations between AIs are being validated; otherwise false.

    Declaration

    Swift

    @available(*, deprecated, message: "Use getValidationEnabled(_:﹚ with Validation.RequisiteAIs instead")
public func getValidateAIassociations() -> Bool

    Return Value

    The status of the “validate AI associations” flag

  • Set the “validate AI associations” flag.

    When set to true, the library will check for mandatory associations between AIs.

    Throws

    GS1EncoderError.parameterError if an error occurs

    Declaration

    Swift

    @available(*, deprecated, message: "Use setValidationEnabled(validation:enabled:﹚ with Validation.RequisiteAIs instead")
public func setValidateAIassociations(_ value: Bool) throws

    Parameters

    value

    true to enable validation of AI associations; false to disable

  • Get the raw barcode message data.

    The data string represents the raw message that would be encoded in a barcode symbol, using a harmonised format where FNC1 characters are represented by ^.

    See also

    setDataStr(_:)

    Declaration

    Swift

    public func getDataStr() -> String

    Return Value

    The barcode message data

  • Set the raw barcode message data.

    This accepts barcode message data in a harmonised format where:

    • A leading ^ indicates GS1 Application Identifier syntax data

    • A ^ at any other position represents an FNC1 separator character

    Throws

    GS1EncoderError.parameterError if the data is invalid

    See also

    getDataStr()

    Declaration

    Swift

    public func setDataStr(_ value: String) throws

    Parameters

    value

    The barcode message data to set

  • Get the AI data as a bracketed AI element string.

    Returns the AI data in human-friendly format using numerical AIs in brackets, e.g., (01)12345678901231(10)ABC123.

    See also

    setAIdataStr(_:)

    Declaration

    Swift

    public func getAIdataStr() -> String?

    Return Value

    The bracketed AI element string, or nil if no AI data is available

  • Set the AI data using a bracketed AI element string.

    This accepts AI data in human-friendly format using numerical AIs in brackets, e.g., (01)12345678901231(10)ABC123.

    Throws

    GS1EncoderError.parameterError if the data is invalid

    See also

    getAIdataStr()

    Declaration

    Swift

    public func setAIdataStr(_ value: String) throws

    Parameters

    value

    The bracketed AI element string

  • Get the scan data.

    Returns the scan data in the format that would be output by a barcode reader with AIM Symbology Identifiers enabled.

    See also

    setScanData(_:)

    Declaration

    Swift

    public func getScanData() -> String

    Return Value

    The scan data

  • Set the scan data.

    This accepts scan data in the format that would be output by a barcode reader with AIM Symbology Identifiers enabled. The symbology is extracted from the AIM Symbology Identifier and the AI data is extracted from the message.

    Throws

    GS1EncoderError.scanDataError if the scan data is invalid

    Note

    Requires that AIM Symbology Identifiers are enabled on the barcode reader, and that any embedded FNC1 separator characters are represented by GS characters (ASCII 29)

    See also

    getScanData()

    See also

    getSym()

    Declaration

    Swift

    public func setScanData(_ value: String) throws

    Parameters

    value

    The scan data to process

  • Get the error markup generated when parsing AI data fails due to a linting failure.

    When a setter function throws an error due to invalid AI-based data, a marked up instance of the AI that failed will be generated. Where it is meaningful to identify offending characters in the input data, these characters will be surrounded by | characters. Otherwise the entire AI value will be surrounded by | characters.

    Declaration

    Swift

    public func getErrMarkup() -> String

    Return Value

    The error markup showing the location of the error in the input data

  • Get a GS1 Digital Link URI that represents the AI-based input data.

    This generates a GS1 Digital Link URI from the current AI data. An optional stem can be provided to specify the domain and path prefix for the URI.

    Throws

    GS1EncoderError.digitalLinkError if the Digital Link URI cannot be generated

    Note

    AI data must be set using setAIdataStr(_:), setDataStr(_:) or setScanData(_:) before calling this method

    Declaration

    Swift

    public func getDLuri(_ stem: String? = nil) throws -> String

    Parameters

    stem

    Optional URI stem (e.g., https://example.com/). If not provided, a default stem is used

    Return Value

    The GS1 Digital Link URI

  • Get the Human-Readable Interpretation (HRI) text for the current AI data as an array of strings.

    The HRI provides a human-friendly representation of the AI data, with each array element representing a separate line of text. If data titles are enabled via setIncludeDataTitlesInHRI(_:), they will be included in the output.

    See also

    setIncludeDataTitlesInHRI(_:)

    Declaration

    Swift

    public func getHRI() -> Array<String>

    Return Value

    Array of strings representing the HRI text lines

  • Get the non-numeric (ignored) query parameters from a GS1 Digital Link URI as an array of strings.

    When a GS1 Digital Link URI is processed via setScanData(_:), any non-numeric query parameters (those not representing AI data) are extracted and made available through this method.

    See also

    setScanData(_:)

    Declaration

    Swift

    public func getDLignoredQueryParams() -> Array<String>

    Return Value

    Array of strings representing the ignored query parameters