Ausdrücke
Funktionen, Formate, Kulturen.

01Wo Ausdrücke verwendet werden

Jedes Element des Label-Modells hat die Eigenschaft Expression (JSON "expression"): Textelemente, Barcodes (Code) und RFID-Elemente (Data). Ist ein Ausdruck gesetzt, hat er Vorrang vor Text/Code und vor DataField. Das Ergebnis wird mit der Engine-Kultur in Text umgewandelt und dann gedruckt; Platzhalter {t:key} im Ergebnis werden wie in festen Texten übersetzt.

{ "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])" }

Die Engine ist ZplCore.Labels.ExpressionEngine; jedes Label hat eine (label.Expressions) für eigene Funktionen, Variablen und die Kultur. Ausdrücke werden beim Binden des Etiketts je Datensatz ausgewertet (label.For<T>(), JSON-Datensätze, DataRow …) und bei label.ToZpl() ohne Daten einmal.

{
  "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" } ]
}

02Schnellstart: ein Preisschild in mehreren Kulturen

Zwei Textelemente: der alte Preis, durchgestrichen, nur wenn er höher ist als der aktuelle Preis, und der aktuelle Preis als Währung. Die Kultur kommt aus dem Datensatz ([culture]), sodass ein einziges Etikett deutsche, US- oder japanische Preise druckt:

{ "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 }

• Das Kultur-Argument ist ein Kulturname wie "de-DE", als Literal geschrieben oder aus einem Feld gelesen. Fehlt es oder ist es leer → die Engine-Kultur (Standard: invariant, Währungszeichen ¤). Siehe Kulturen.
• Der Vergleich [oldPrice] > [price] ist numerisch – auch wenn Preise als Text kommen (CSV, JSON-Strings): Zwei Texte, die Zahlen sind, werden als Zahlen verglichen. Siehe Typen.
• Ein leeres Ergebnis druckt nichts; das durchgestrichene Element bleibt dann einfach leer.

03Syntax

04Operatoren & Rangfolge

Von niedrigster zu höchster Rangfolge; Operatoren derselben Stufe werden von links nach rechts ausgewertet.

05Typen & Umwandlung

Werte sind Zahlen (double), Text, boolesche Werte, Datumswerte (DateTime) oder leer (null). Ganzzahl- und Dezimalwerte aus Datensätzen (C# int, long, decimal, JSON-Zahlen) werden zu Zahlen; alles andere behält seinen Typ. Umgewandelt wird dort, wo ein Operator oder eine Funktion einen anderen Typ braucht:

+ addiert nur, wenn beide Seiten Zahlen sind. Eine Zahl aus einem Textfeld ist Text: [textPrice] + 1 verbindet. Vergleiche sind numerisch, wenn eine Seite eine Zahl ist oder beide Seiten Texte sind, die Zahlen sind (gelesen mit der Engine-Kultur, dann invariant); anderer Text wird als Text verglichen. Zum Rechnen mit Num() (oder ToNumber(text, culture)) umwandeln:

Mit der Engine-Kultur de-DE (C#: label.Expressions.Culture) folgen dieselben Umwandlungen deutschen Konventionen:

06Leere & fehlende Werte

Ein Feld, das fehlt, JSON-null oder C#-null ist, ist leer. Ohne Daten (label.ToZpl()) ist jedes Feld leer. Leere Werte lösen nie einen Fehler aus: Sie drucken als "", zählen als 0 und als false.

07Felder & Bindung

[name] liest einen Wert des aktuellen Datensatzes. Datensätze können C#-Objekte (Properties und Felder), Dictionaries, ExpandoObject, JsonElement/JsonNode, DataRow oder LiteDB-Dokumente sein; LabelBinding.Map("name", r => …) fügt berechnete Felder hinzu. Die Suche:

1. Ein Name mit . oder [n] ist ein Pfad: [customer.city], [items[0].name]. Eine Spalte, deren Name genau dieser Text ist, hat Vorrang vor dem Pfad (importierte Tabellen haben oft Spalten wie Preis.netto).
2. Zuerst der exakte Name, dann ohne Beachtung der Groß-/Kleinschreibung.
3. Namen anderer Elemente: [Items.Total] oder [Items.Total.Text] ist der gedruckte Text des Elements namens Total – auch wenn es später auf dem Etikett kommt (Zirkelbezüge ergeben ""). Ein bloßes [Total] findet ein Element erst, nachdem es gedruckt wurde, und nur, wenn kein Feld des Datensatzes so heißt.

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\")" });
// mit { price = 12 }: "net 10.00 / gross 12.00"

08Auftragsvariablen

Variablen werden ohne Klammern geschrieben (mit Klammern funktionieren nur die mit ✓ markierten Bindungsvariablen).

Die Namen sind nicht reserviert: Ein Feld des Datensatzes namens PAGE_NUMBER (oder einer der anderen Bindungsvariablen) hat Vorrang vor der Variablen. LABEL_INDEX, LABEL_NUMBER und REPEAT_INDEX haben ohne Klammern geschrieben Vorrang vor gleichnamigen Feldern. Ohne Bindung (label.ToZpl()) sind die Bindungsvariablen leer.

09Kulturen

Eine Kultur bestimmt Dezimal- und Tausendertrennzeichen, Währung, Prozentzeichen, Datumsreihenfolge, Monats- und Tagesnamen – und bei manchen Kulturen sogar den Kalender. zplCore verwendet .NET-Kulturen (ICU-Daten des Betriebssystems). Sie wird an zwei Stellen festgelegt:

• Der Standard ist invariant, damit sich Etiketten nie mit den Regionaleinstellungen des Servers ändern: 1234.5, 10/22/2026, Währungszeichen ¤.
• Label-JSON hat keine Engine-Kultur (Label.Expressions wird nicht serialisiert). In JSON-Vorlagen die Kultur als Argument übergeben – als Literal "de-DE" oder aus dem Datensatz [culture]. Label.Culture ist etwas anderes: Es wählt die Sprache der Übersetzungen {t:key}.
• Das Argument ist ein Kulturname: "de-DE", "en-US", "fr-CH", eine neutrale Sprache wie "de" oder "". Ein Wert, der kein Text ist (Zahl, leeres Feld), oder leerer Text bedeutet die Engine-Kultur.
• Unbekannte Namen lösen FormatException: Unknown culture '…' aus: Angenommen werden nur Kulturen, die .NET kennt (in den ICU-Daten vordefiniert) – "!!", "xx-YY" oder "foo" schlagen fehl.
• Datengebundene Elemente ohne Ausdruck verwenden stattdessen DataFieldFormat und TextItem.CultureName (ohne Kultur: invariant mit einem Format); Ausdrücke lesen CultureName nicht. Der Standardkalender und die normalen Leerzeichen (unten) gelten auch dort.

Die Engine-Kultur ändert die Umwandlungen ohne Argumente (hier tr-TR, wo der Großbuchstabe von i İ ist):

var label = Label.FromJson(json);                         // JSON: keine Engine-Kultur
label.Expressions.Culture = CultureInfo.GetCultureInfo("de-DE");   // C#: für das ganze Etikett
// Format([price], "C") → "1.234,50 €", [price] + " EUR" → "1234,5 EUR"
// Format([price], "C", "en-US") → "$1,234.50" (das Argument hat Vorrang)

Ergebnisse je Kultur

Dieselben Werte in gängigen Kulturen. Der Engine druckt sie unter Windows, Linux und macOS gleich: Sonder-Leerzeichen werden zu normalen Leerzeichen – die geschützten und schmalen geschützten Leerzeichen der Tausendergruppen von fr-FR, pl-PL oder sv-SE und in Uhrzeiten wie 2:30 PM (U+00A0, U+202F, U+2000–U+200A, U+205F), die ICU-Versionen unterschiedlich setzen und Druckerschriften oft nicht drucken können – und Datumswerte verwenden den Standardkalender der Kultur (unten). Andere Zeichen stammen weiter aus den ICU-Daten des Betriebssystems, z. B. der Apostroph von de-CH (’ oder ') und die Richtungszeichen arabischer Texte; die Tests vergleichen diese normalisiert.

10Zahlenformate

Das 2. Argument von Format(value, format, culture?) ist ein .NET-Formatstring. Für Zahlen:

Rundung: Standardformate mit weniger Nachkommastellen als der Wert (N0, F0, C0, P0 …) runden eine exakte Hälfte zur geraden Ziffer – 1234.5 → 1234, 2.5 → 2, 3.5 → 4. Benutzerdefinierte Formate ("0", "#,##0") und Round() runden die Hälfte von null weg (12.5 → 13). Preise zuerst runden: Format(Round([price]), "C0", …).

Trennzeichen in einem benutzerdefinierten Format sind Platzhalter: . druckt das Dezimaltrennzeichen der Kultur, , ihr Tausendertrennzeichen. Einheitentexte in einfache Anführungszeichen setzen ("0.00 'kg'"): Buchstaben wie E würden sonst als Formatzeichen gelesen. Doppelte Anführungszeichen würden den Text des Ausdrucks beenden.

Zahlen als Text ("19.99" aus CSV oder einem JSON-String) werden wie Zahlen formatiert, wenn ein Format angegeben ist: Der Text wird mit der Engine-Kultur gelesen; Text, der keine Zahl ist, wird unverändert gedruckt.

11Datumsformate

Format formatiert Datumswerte – Werte aus Now(), Today(), AddDays…, ToDate(…) oder DateTime-Feldern von C#-Datensätzen. Datumswerte in JSON oder CSV sind Text: Sie zuerst mit ToDate umwandeln, sonst druckt Format den Text unverändert.

.NET-Datumsformate kennen keine Kalenderwoche. / und : in einem Muster drucken die Datums- und Zeittrennzeichen der Kultur.

12Funktionsreferenz

Alle 47 eingebauten Funktionen. Namen ignorieren Groß-/Kleinschreibung. Fehlende Argumente sind leer (null); zusätzliche Argumente werden ignoriert, sofern nicht anders angegeben. Argumente werden wie unter Typen beschrieben umgewandelt: „Text“-Argumente durchlaufen die Text-Umwandlung, „Zahl“-Argumente die Zahlen-Umwandlung (keine Zahl → 0), Anzahlen werden auf ganze Zahlen abgeschnitten.

Text

Upper(text) · Lower(text)

Groß- / Kleinschreibung mit der Engine-Kultur. Gibt Text zurück.

Len(text)

Anzahl der UTF-16-Zeichen. Gibt eine Zahl zurück (leer → 0).

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

Die ersten / letzten n Zeichen; n wird auf 0…Länge begrenzt (nie ein Fehler).

Mid(text, start, n?)

1-basierter Start (1 = erstes Zeichen, Werte unter 1 zählen als 1), n Zeichen oder der Rest.

Substring(text, start, n?)

0-basierter Start (begrenzt), n Zeichen oder der Rest.

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

Entfernt Leerraum an beiden Enden / am Anfang / am Ende. Trim mit einem 2. Argument entfernt stattdessen diese Zeichen (jedes Zeichen des Textes ist eines, das entfernt wird).

Replace(text, find, with)

Ersetzt jedes Vorkommen (Groß-/Kleinschreibung wird beachtet). Ein leeres find gibt den Text unverändert zurück.

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

Füllt auf width Zeichen mit dem ersten Zeichen von char auf (Standard: Leerzeichen). Längerer Text bleibt unverändert.

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

True/false, ohne Beachtung der Groß-/Kleinschreibung.

IndexOf(text, part)

0-basierte Position von part ohne Beachtung der Groß-/Kleinschreibung, −1, wenn nicht vorhanden.

Concat(value, …)

Verbindet beliebig viele Werte als Text (leere Werte fügen nichts hinzu).

Repeat(text, n)

Der Text n-mal; n wird auf 0…10.000 begrenzt.

Bedingungen

If(condition, then, else?)

Gibt then zurück, wenn die Bedingung wahr ist (siehe Umwandlung in boolesche Werte), sonst else (fehlt es → leer). Beide Zweige werden vor der Auswahl ausgewertet, ein Zweig darf also keinen Fehler auslösen (z. B. GS1 mit leerem Wert) – stattdessen die Argumente auswählen.

IsEmpty(value)

True für leere Werte und ""; " " und 0 sind nicht leer.

Coalesce(value, …)

Der erste Wert, der weder leer noch "" ist; leer, wenn es keinen gibt.

Mathematik

Round(number, decimals?)

Rundet die Hälfte von null weg (2,5 → 3, −2,5 → −3) auf 0…15 Nachkommastellen (Standard 0; Werte außerhalb werden begrenzt, negative Stellen runden also auf ganze Zahlen). Es gilt binäre Gleitkommaarithmetik: Round(1.005, 2) ergibt 1.

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

Abrunden / Aufrunden, Betrag.

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

Kleinstes / größtes der Argumente als Zahl; ohne Argumente 0.

Datum

Now() · Today()

Aktuelles Datum mit Uhrzeit / heute um 00:00 aus Expressions.Clock (Standard: die lokale Uhr). Die Uhr für Tests oder Nachdrucke mit dem ursprünglichen Datum setzen.

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

Addiert (oder subtrahiert, negativ) Tage – Bruchteile erlaubt – oder ganze Monate / Jahre. Ein Datum als Text wird wie bei ToDate(text) umgewandelt. Das Monatsende bleibt gültig (31. Jan. + 1 Monat = 28./29. Feb.).

ToDate(text, format?, culture?)

Liest ein Datum. Mit format muss der Text exakt passen (DateTime.TryParseExact, Namen in culture); andernfalls – oder wenn er nicht passt – wird der Text mit der Engine-Kultur gelesen, dann invariant. Text, der kein Datum ist, ergibt 0001-01-01 (kein Fehler): bei Bedarf mit Format(…, "yyyy") = "0001" prüfen.

Umwandlung & Formatierung

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

ToString ist dieselbe Funktion unter anderem Namen. Zahlen, Datumswerte und andere formatierbare Werte: value.ToString(format, culture) (siehe Zahlen- und Datumsformate). Text mit einem Format wird mit der Engine-Kultur als Zahl gelesen und formatiert; anderer Text, boolesche Werte und leere Werte werden unverändert in Text umgewandelt. Ohne Format: der Wert als Text in culture. Fehler: unbekannter Kulturname, ein Format, das der Wert ablehnt (D, X bei einer Zahl mit Nachkommastellen).

Str(value)

Wert als Text mit der Engine-Kultur.

Num(value)

Wert als Zahl mit der Engine-Kultur (dann invariant); keine Zahl → 0.

ToNumber(text, culture?)

Wie Num, der Text wird zuerst in culture gelesen. Akzeptiert Vorzeichen, ein Dezimaltrennzeichen und Exponent; mit Kultur-Argument auch die Tausendertrennzeichen dieser Kultur an ihren Stellen ("1.234,5" in de-DE → 1234.5, aber "12,5" in en-US ist keine Zahl). Ohne Kultur keine Tausendertrennzeichen. Keine Zahl → 0.

IsNumeric(value, culture?)

True für Zahlen und für Text, der sich in culture als Zahl lesen lässt (mit Kultur-Argument wie bei ToNumber samt Tausendertrennzeichen; Standard: Engine-Kultur); false für boolesche Werte, leere Werte und anderen Text.

Prüfziffern

Gs1CheckDigit(digits)

Gibt die Ziffern mit angehängter GS1-Mod-10-Prüfziffer zurück (GTIN, SSCC, GLN …). Die Eingabe wird nicht geprüft – nur Ziffern übergeben.

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

Geben nur das Prüfzeichen zurück: GS1/UPC-Gewichtung 3-1, Luhn (Karten), Mod 11 mit Gewichten 2…7 (X für 10), Code 39 Mod 43. Fehler: für das Verfahren ungültige Zeichen.

VoicePickCode(gtin, lot, date?)

Der 4-stellige PTI-Voice-Pick-Code (CRC-16 aus GTIN + Charge [+ Datum als YYMMDD]); ein Datumswert wird als yyMMdd geschrieben.

GS1

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

Baut aus Paaren den GS1-Element-String in Klammerschreibweise (01)…(10)…. AIs werden als Text geschrieben ("01", 2–4 Ziffern; Klammern werden entfernt). Jedes Paar wird gegen die GS1-Tabelle geprüft – bekannter AI, Länge, Zeichensatz, Prüfziffer, Datum, Pflicht- und Ausschlusskombinationen –, ein Fehler löst eine FormatException mit dem betroffenen AI aus, sodass nie ein falscher Code gedruckt wird. Als Expression eines GS1-128-Barcodes (Symbology.Gs1_128) verwenden: Die FNC1-Trenner nach Werten variabler Länge werden beim Schreiben des Barcodes eingefügt. Werte dürfen keine Klammern enthalten.

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

Mehr zu GS1-Barcodes: GS1 in der Dokumentation.

13C#-API

ExpressionEngine lässt sich eigenständig oder über label.Expressions verwenden:

using System.Globalization;
using ZplCore.Labels;

var engine = new ExpressionEngine
{
    Culture = CultureInfo.GetCultureInfo("de-DE"),          // Standard: InvariantCulture
    Clock = () => new DateTime(2026, 10, 22, 14, 30, 5),     // Now()/Today()
};
engine.Variables["VAT"] = 0.19;                                // eigene Variablen
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"

Threadsicherheit: Einmal konfiguriert, darf Evaluate auf vielen Threads laufen (Etikettenaufträge tun das). Das Konfigurieren (Variablen, Funktionen, Typreferenzen) ist nicht threadsicher. Eigene Funktionen, Typreferenzen und eine eigene Uhr lassen Aufträge standardmäßig sequenziell laufen, siehe parallele Erzeugung.

14Fehler

Ein ungültiger Ausdruck löst eine FormatException aus, wenn das Element erzeugt wird (ToZpl, Render, Bindungsaufträge) – das Etikett wird nicht mit falschem Text gedruckt. Die Meldungen sind englisch:

Math.Max(…) ohne AddTypeReference(typeof(Math)) liest Math als (fehlendes) Feld – daher „Member Max on null“.

Falsche Daten lösen keinen Fehler aus (außer in GS1 und bei ungültigen Kulturnamen): Unbekannte Felder sind leer, Text, der keine Zahl ist, zählt als 0, Text, der kein Datum ist, ergibt 0001-01-01. Etiketten vor dem Druck mit Label.Validate(record) und den Etikettentests prüfen.

15Rezepte

16Stolperfallen

• Text, der keine Zahl ist, wird als Text verglichen. "a10" < "a9" ist wahr; zwei Zahltexte ("9.99", "19.99") werden als Zahlen verglichen.
• + mit einem leeren Feld verbindet. [missing] + 1 + 1 ergibt "11"; Num([missing]) + 1 + 1 schreiben.
• Datumswerte aus JSON/CSV sind Text. Format([date], "dd.MM.yyyy") druckt den Text unverändert; Format(ToDate([date]), …) verwenden, bei Texten, die nicht ISO sind, mit Muster: ToDate([deDate], "dd.MM.yyyy").
• Keine Kultur → invariant. Format([price], "C") druckt ¤1,234.50; eine Kultur übergeben oder in C# label.Expressions.Culture setzen.
• ar-SA und th-TH verwenden andere Kalender für Datumswerte.
• Die Formate D/X brauchen ganze Zahlen: Format(2.5, "D3") löst einen Fehler aus; vorher runden oder "000" verwenden.
• Tausendertrennzeichen lesen nur ToNumber/IsNumeric mit Kultur-Argument; Num und Umwandlungen ohne Kultur brauchen Zahlen ohne Trennzeichen.
• Text, der kein Datum bzw. keine Zahl ist, löst keinen Fehler aus: Er wird zu 0001-01-01 bzw. 0.
• not bindet stärker als =: not ([a] = 1) schreiben.
• Beide Zweige von If werden ausgewertet. Ein GS1()-Aufruf mit leerem Wert löst auch in dem Zweig einen Fehler aus, der nicht gewählt wird.
• Einheitentexte in Formaten: in Anführungszeichen setzen ("0.0 'kg'").
• Anführungszeichen im Label-JSON: "expression": "Format([price], \"C\", \"de-DE\")" – die JSON-Escapes gehören nicht zum Ausdruck.
• Grenzen der Engine: höchstens 256 Ebenen verschachtelter Klammern, Argumente und unärer Operatoren (ExpressionEngine.MaxNesting); tiefere Ausdrücke lösen FormatException aus, statt den Stack zu erschöpfen. Der Online-Builder begrenzt Länge und Verschachtelung zusätzlich.