Expressions
functions, formats, cultures.

01Where expressions are used

Every element of the label model has the property Expression (JSON "expression"): text elements, barcodes (Code) and RFID elements (Data). When an expression is set it wins over Text/Code and over DataField. The result is converted to text with the engine culture and then printed; {t:key} placeholders in the result are translated like in fixed texts.

{ "type": "text", "x": 4, "y": 4, "expression": "Upper([name]) + \", \" + [customer.city]" }
{ "type": "barcode", "x": 4, "y": 20, "symbology": "Gs1_128", "expression": "GS1(\"01\", [gtin], \"10\", [lot])" }

The engine is ZplCore.Labels.ExpressionEngine; every Label has one (label.Expressions) for custom functions, variables and the culture. Expressions are evaluated per record when the label is bound (label.For<T>(), JSON records, DataRow …) and once for label.ToZpl() without data.

{
  "price": 1234.5,
  "oldPrice": 1499,
  "culture": "de-DE",
  "name": "Müller",
  "first": "Anna",
  "last": "Schmidt",
  "sku": "ab-123",
  "qty": 3,
  "weight": 0.4567,
  "date": "2026-10-22",
  "deDate": "22.10.2026",
  "gtin": "09521234543213",
  "lot": "LOT42",
  "serial": "42",
  "textPrice": "19.99",
  "textOld": "9.99",
  "empty": "",
  "nothing": null,
  "inStock": true,
  "Preis [EUR]": 4.5,
  "Preis.netto": 3.1,
  "customer": { "name": "ACME GmbH", "city": "Graz", "zip": "8010" },
  "items": [ { "name": "Bolt" }, { "name": "Nut" } ]
}

02Quick start: a price tag in several cultures

Two text elements: the old price, struck out, only when it is higher than the current price, and the current price as currency. The culture comes from the record ([culture]), so one label prints German, US or Japanese prices:

{ "type": "text", "expression": "If([oldPrice] > [price], \"instead of \" + Format([oldPrice], \"C\", [culture]), \"\")", "strikeout": true },
{ "type": "text", "expression": "Format([price], \"C\", [culture])", "fontSize": 22, "bold": true }

• The culture argument is a culture name such as "de-DE", written as a literal or read from a field. Missing or empty → the engine culture (default: invariant, currency sign ¤). See Cultures.
• The comparison [oldPrice] > [price] is numeric – also when prices arrive as text (CSV, JSON strings): two texts that are numbers are compared as numbers. See Types.
• An empty result prints nothing; the struck-out element then simply stays empty.

03Syntax

04Operators & precedence

From lowest to highest precedence; operators of the same level are evaluated left to right.

05Types & conversion

Values are numbers (double), text, booleans, dates (DateTime) or empty (null). Integer and decimal values from records (C# int, long, decimal, JSON numbers) become numbers; everything else keeps its type. Conversions happen where an operator or function needs another type:

+ adds only when both sides are numbers. A number from a text field is text: [textPrice] + 1 joins. Comparisons are numeric when one side is a number or both sides are texts that are numbers (read with the engine culture, then invariant); other text is compared as text. Convert with Num() (or ToNumber(text, culture)) for arithmetic:

With the engine culture de-DE (C#: label.Expressions.Culture) the same conversions use German conventions:

06Empty & missing values

A field that is missing, JSON null or a C# null is empty. Without data (label.ToZpl()) every field is empty. Empty values never throw: they print as "", count as 0 and as false.

07Fields & binding

[name] reads a value of the current record. Records can be C# objects (properties and fields), dictionaries, ExpandoObject, JsonElement/JsonNode, DataRow or LiteDB documents; LabelBinding.Map("name", r => …) adds computed fields. The lookup:

1. A name with . or [n] is a path: [customer.city], [items[0].name]. A column whose name is exactly that text wins over the path (imported tables often have columns like Preis.netto).
2. Exact name first, then ignoring case.
3. Names of other elements: [Items.Total] or [Items.Total.Text] is the printed text of the element named Total – also when it comes later on the label (circular references give ""). A bare [Total] finds an element only after it has been printed and only when no record field has that name.

var label = new Label(LabelUnit.Mm, 100, 50)
    .Add(new TextItem { Name = "Net", Y = 4, Expression = "Format([price] / 1.2, \"0.00\")" })
    .Add(new TextItem { Y = 12, Expression = "\"net \" + [Items.Net] + \" / gross \" + Format([price], \"0.00\")" });
// with { price = 12 }: "net 10.00 / gross 12.00"

08Job variables

Variables are written without brackets (with brackets only the binding variables marked ✓ work).

The names are not reserved: a record field called PAGE_NUMBER (or one of the other binding variables) wins over the variable. LABEL_INDEX, LABEL_NUMBER and REPEAT_INDEX win over fields of the same name when written without brackets. Without a binding (label.ToZpl()) the binding variables are empty.

09Cultures

A culture decides decimal and thousands separators, currency, percent sign, date order, month and day names – and for some cultures even the calendar. zplCore uses .NET cultures (ICU data of the operating system). Two places set it:

• The default is invariant so labels never change with the server's regional settings: 1234.5, 10/22/2026, currency sign ¤.
• Label JSON has no engine culture (Label.Expressions is not serialized). In JSON templates pass the culture as argument – literal "de-DE" or from the record [culture]. Label.Culture is something else: it selects the language of {t:key} translations.
• The argument is a culture name: "de-DE", "en-US", "fr-CH", a neutral language such as "de", or "". A value that is not text (number, empty field) or empty text means the engine culture.
• Unknown names throw FormatException: Unknown culture '…': only cultures that .NET knows (predefined in the ICU data) are accepted – "!!", "xx-YY" or "foo" fail.
• Data-bound elements without expression use DataFieldFormat and TextItem.CultureName instead (no culture: invariant with a format); expressions do not read CultureName. The standard calendar and the plain spaces described below apply to them as well.

The engine culture changes the conversions without arguments (here tr-TR, where the upper case of i is İ):

var label = Label.FromJson(json);                         // JSON: no engine culture
label.Expressions.Culture = CultureInfo.GetCultureInfo("de-DE");   // C#: for the whole label
// Format([price], "C") → "1.234,50 €", [price] + " EUR" → "1234,5 EUR"
// Format([price], "C", "en-US") → "$1,234.50" (the argument wins)

Results per culture

The same values in common cultures. The engine prints them the same on Windows, Linux and macOS: special spaces become plain spaces – the no-break and narrow no-break spaces of fr-FR, pl-PL or sv-SE thousands and of times such as 2:30 PM (U+00A0, U+202F, U+2000–U+200A, U+205F), which ICU versions set differently and printer fonts often cannot print – and dates use the culture's standard calendar (below). Other characters still come from the ICU data of the operating system, e.g. the apostrophe of de-CH (’ or ') and the direction marks of Arabic texts; the tests compare those normalized.

10Number formats

The 2nd argument of Format(value, format, culture?) is a .NET format string. For numbers:

Rounding: standard formats with fewer decimals than the value (N0, F0, C0, P0 …) round an exact half to the even digit – 1234.5 → 1234, 2.5 → 2, 3.5 → 4. Custom formats ("0", "#,##0") and Round() round half away from zero (12.5 → 13). For prices round first: Format(Round([price]), "C0", …).

Separators in a custom format are placeholders: . prints the decimal separator of the culture, , its thousands separator. Put unit texts in single quotes ("0.00 'kg'"): letters such as E would otherwise be read as format characters. Double quotes inside the expression's text would end it.

Numbers as text ("19.99" from CSV or a JSON string) are formatted like numbers when a format is given: the text is read with the engine culture; text that is not a number prints unchanged.

11Date formats

Format formats dates – values from Now(), Today(), AddDays…, ToDate(…) or DateTime fields of C# records. Dates in JSON or CSV are text: convert them with ToDate first, otherwise Format prints the text unchanged.

There is no week number in .NET date formats. / and : in a pattern print the culture's date and time separators.

12Function reference

All 47 built-in functions. Names ignore case. Missing arguments are empty (null); extra arguments are ignored unless noted. Arguments are converted as described in Types: “text” arguments go through text conversion, “number” arguments through number conversion (non-numbers → 0), counts are truncated to whole numbers.

Text

Upper(text) · Lower(text)

Upper / lower case with the engine culture. Returns text.

Len(text)

Number of UTF-16 characters. Returns a number (empty → 0).

Left(text, n) · Right(text, n)

The first / last n characters; n is clamped to 0…length (never an error).

Mid(text, start, n?)

1-based start (1 = first character, values below 1 count as 1), n characters or the rest.

Substring(text, start, n?)

0-based start (clamped), n characters or the rest.

Trim(text, chars?) · TrimStart(text) · TrimEnd(text)

Removes white space at both ends / the start / the end. Trim with a 2nd argument removes those characters instead (each character of the text is one to remove).

Replace(text, find, with)

Replaces every occurrence (case-sensitive). An empty find returns the text unchanged.

PadLeft(text, width, char?) · PadRight(text, width, char?)

Fills up to width characters with the first character of char (default space). Longer text stays unchanged.

Contains(text, part) · StartsWith(text, part) · EndsWith(text, part)

True/false, ignoring case.

IndexOf(text, part)

0-based position of part ignoring case, −1 when missing.

Concat(value, …)

Joins any number of values as text (empty values add nothing).

Repeat(text, n)

The text n times; n is clamped to 0…10,000.

Conditions

If(condition, then, else?)

Returns then when the condition is true (see boolean conversion), else else (missing → empty). Both branches are evaluated before the choice, so a branch must not throw (e.g. GS1 with an empty value) – choose the arguments instead.

IsEmpty(value)

True for empty values and ""; " " and 0 are not empty.

Coalesce(value, …)

The first value that is neither empty nor ""; empty when there is none.

Math

Round(number, decimals?)

Rounds half away from zero (2.5 → 3, −2.5 → −3) to 0…15 decimals (default 0; values outside are clamped, so negative decimals round to whole numbers). Binary floating point applies: Round(1.005, 2) is 1.

Floor(number) · Ceiling(number) · Abs(number)

Round down / up, absolute value.

Min(number, …) · Max(number, …)

Smallest / largest of the arguments as numbers; without arguments 0.

Date

Now() · Today()

Current date and time / today at 00:00 from Expressions.Clock (default: the local clock). Set the clock for tests or reprints with the original date.

AddDays(date, days) · AddMonths(date, months) · AddYears(date, years)

Adds (or subtracts, negative) days – fractions allowed – or whole months / years. A text date is converted like ToDate(text). The end of the month is kept valid (31 Jan + 1 month = 28/29 Feb).

ToDate(text, format?, culture?)

Reads a date. With format the text must match exactly (DateTime.TryParseExact, names in culture); otherwise – or when it does not match – the text is read with the engine culture, then invariant. Text that is no date gives 0001-01-01 (no error): check with Format(…, "yyyy") = "0001" if needed.

Conversion & formatting

Format(value, format?, culture?) · ToString(value, format?, culture?)

ToString is the same function under another name. Numbers, dates and other formattable values: value.ToString(format, culture) (see number and date formats). Text with a format is read as a number with the engine culture and formatted; other text, booleans and empty values are converted to text unchanged. Without format: the value as text in culture. Errors: unknown culture name, a format the value rejects (D, X on a number with decimals).

Str(value)

Value as text with the engine culture.

Num(value)

Value as number with the engine culture (then invariant); not a number → 0.

ToNumber(text, culture?)

Like Num, the text read in culture first. Accepts sign, one decimal separator and exponent; with a culture argument also that culture's thousands separators in their places ("1.234,5" in de-DE → 1234.5, but "12,5" in en-US is no number). Without culture no thousands separators. Not a number → 0.

IsNumeric(value, culture?)

True for numbers and for text that reads as a number in culture (with a culture argument like ToNumber, thousands separators included; default: engine culture); false for booleans, empty values and other text.

Check digits

Gs1CheckDigit(digits)

Returns the digits with the GS1 mod-10 check digit appended (GTIN, SSCC, GLN …). The input is not validated – pass digits only.

Mod10(digits) · Luhn(digits) · Mod11(digits) · Mod43(text)

Return only the check character: GS1/UPC weighting 3-1, Luhn (cards), mod 11 weights 2…7 (X for 10), Code 39 mod 43. Errors: invalid characters for the method.

VoicePickCode(gtin, lot, date?)

The 4-digit PTI voice pick code (CRC-16 of GTIN + lot [+ date as YYMMDD]); a date value is written as yyMMdd.

GS1

GS1(ai1, value1, ai2, value2, …)

Builds the GS1 element string in bracketed form (01)…(10)… from pairs. AIs are written as text ("01", 2–4 digits; brackets are removed). Every pair is checked against the GS1 table – known AI, length, character set, check digit, date, mandatory and exclusive combinations – and an error throws FormatException naming the AI, so a wrong code is never printed. Use it as Expression of a GS1-128 barcode (Symbology.Gs1_128): the FNC1 separators after variable-length values are added when the barcode is written. Values must not contain brackets.

label.Add(new BarcodeItem
{
    X = 5, Y = 20, Symbology = Symbology.Gs1_128,
    Expression = "GS1(\"01\", [gtin], \"17\", Format(ToDate([expiry]), \"yyMMdd\"), \"10\", [lot])",
});

More on GS1 barcodes: GS1 in the documentation.

13C# API

ExpressionEngine can be used on its own or through label.Expressions:

using System.Globalization;
using ZplCore.Labels;

var engine = new ExpressionEngine
{
    Culture = CultureInfo.GetCultureInfo("de-DE"),          // default: InvariantCulture
    Clock = () => new DateTime(2026, 10, 22, 14, 30, 5),     // Now()/Today()
};
engine.Variables["VAT"] = 0.19;                                // own variables
engine.SetCustomFunction("Euro", a => ExpressionEngine.Num(a[0]).ToString("0.00", CultureInfo.InvariantCulture) + " EUR");

var record = new Dictionary<string, object?> { ["price"] = 12.5m };
object? value = engine.Evaluate("[price] * (1 + VAT)", f => record.GetValueOrDefault(f));   // 14.875 (double)
string text = engine.EvaluateToString("Euro([price])", f => record.GetValueOrDefault(f));   // "12.50 EUR"
string date = engine.EvaluateToString("Format(Today(), \"D\")");                             // "Donnerstag, 22. Oktober 2026"

Thread safety: once configured, Evaluate may run on many threads (label jobs do this). Configuring (variables, functions, type references) is not thread-safe. Custom functions, type references and a custom clock make jobs run sequentially by default, see parallel generation.

14Errors

An invalid expression throws FormatException when the element is generated (ToZpl, Render, binding jobs) – the label is not printed with a wrong text. Messages are English:

Math.Max(…) without AddTypeReference(typeof(Math)) reads Math as a (missing) field – hence “Member Max on null”.

Wrong data does not throw (except in GS1 and invalid culture names): unknown fields are empty, text that is no number counts as 0, text that is no date is 0001-01-01. Check labels before printing with Label.Validate(record) and the label tests.

15Recipes

16Pitfalls

• Text that is no number is compared as text. "a10" < "a9" is true; two number texts ("9.99", "19.99") are compared as numbers.
• + with an empty field joins. [missing] + 1 + 1 is "11"; write Num([missing]) + 1 + 1.
• Dates from JSON/CSV are text. Format([date], "dd.MM.yyyy") prints the text unchanged; use Format(ToDate([date]), …), with a pattern for non-ISO texts: ToDate([deDate], "dd.MM.yyyy").
• No culture → invariant. Format([price], "C") prints ¤1,234.50; pass a culture or set label.Expressions.Culture in C#.
• ar-SA and th-TH use other calendars for dates.
• D/X formats need whole numbers: Format(2.5, "D3") throws; round first or use "000".
• Thousands separators are read only by ToNumber/IsNumeric with a culture argument; Num and conversions without culture need plain numbers.
• Text that is no date or number does not throw: it becomes 0001-01-01 or 0.
• not binds tighter than =: write not ([a] = 1).
• Both branches of If are evaluated. A GS1() call with an empty value throws even in the branch that is not chosen.
• Unit texts in formats: quote them ("0.0 'kg'").
• Quotes in label JSON: "expression": "Format([price], \"C\", \"de-DE\")" – the JSON escapes are not part of the expression.
• Engine limits: at most 256 levels of nested parentheses, arguments and unary operators (ExpressionEngine.MaxNesting); deeper expressions throw FormatException instead of exhausting the stack. The online builder limits length and nesting further.