11.49 sprintf()

Mit dieser Funktion kann ein String gemäß den Vorgaben in einem Formatstring formatiert werden. Sie ist ähnlich zu der in der C-Bibliothek verfügbaren Funktion.

Definition

string sprintf
(
      string   Format     input,
      anyvalue Argument1  input
  { , anyvalue Argument2  input }
      ...
  { , anyvalue Argument15 input }
)

Parameter

string Format input

Format beschreibt die Formatierung des Ausgabestrings. Die einzelnen Formate lehnen sich sehr stark an die Notation in ANSI-C an. Gewisse Einschränkungen sind jedoch nötig. Der IDM kann nicht überprüfen, ob der übergebene Formatstring stimmt. Falsche Angaben in den Argumenten der Funktion führen zu Fehlern.

Die Datentypen des Dialog Managers werden sämtlich über %s (plus eventuelle Formatierungen) ausgegeben; Ausnahmen bilden die Datentypen integer und pointer, diese werden über numerische Formatierungstypen ausgegeben. Die möglichen Werte für den Dialog Manager werden im Kapitel „Syntax des Formatstrings“ erklärt.

anyvalue Argument1 input
anyvalue Argument2 input
…
anyvalue Argument15 input

Diese (optionalen) Parameter müssen entsprechend dem Formatstring angegeben werden.

Sie werden für das korrespondierende Formatzeichen in den Ausgabestring eingesetzt.

Rückgabewert

Der Rückgabewert ist ein String entsprechend dem Eingabeformat Format, bei Fehlern wird ein Leerstring zurückgegeben.

Syntax des Formatstrings

Ein Format wird mit einem % (Prozentzeichen) eingeleitet. Der folgende Ausdruck beschreibt die Syntax eines Formates des IDM sprintf():

%[argument$] [flags] [width] [.precision] type
%[argument$] [flags] [width] [.precision] ([singular],[plural])

Die einzelnen Elemente der Ausdrücke werden wie folgt definiert:

argument

Dieser Parameter dient der Steuerung der Reihenfolge der angegebenen Parameter. Im Normalfall werden die angegebenen Argumente der Reihe nach genommen. Mit Hilfe dieser Option kann statt dem nächsten Argument ein beliebiges Argument, das über seine Position (Nummer) angesprochen wird, genommen werden. Hierbei ist die Mehrfachverwendung von Parametern möglich.

Beispiel 

text DateFormat "Date"
{
  0: "%02d.%02d.%04d";        // German
  1: "%2$02d/%1$02d/%3$04d";  // British
}
...
sprintf(DateFormat,7,9,1965);
// variant 0:"07.09.1965"
// variant 1:"09/07/1965"

flags

Der IDM unterstützt folgende Flags: +, -, 0, #

Über die Flags + und - kann definiert werden, ob der String links- (-) oder rechtsbündig (+) formatiert werden soll, d.h. ob Leerzeichen, die auf Grund der Breite notwendig sind, am Anfang oder Ende des Strings eingefügt werden sollen.

Zusätzlich kann für die Ausgabe von Zahlen hier eine 0 angegeben werden, dass die Strings mit Nullen aufgefüllt werden. Wird hier ein # angegeben, ergibt dies beim hexadezimalen Zahlenformat 0x bzw. 0X.

width

Mit Hilfe dieses Parameters wird gesteuert, wie viele Zeichen minimal ausgegeben werden sollen. Wenn dabei weniger Zeichen als hier angegeben ausgegeben werden, so werden am Anfang oder Ende des Strings, gesteuert über den flag-Parameter, Leerzeichen eingefügt. Ist der String länger als die hier angegebene Feldlänge, werden alle Zeichen ausgegeben.

Zusätzlich kann dieser Parameter auch aus einem Stern (*) bestehen. Dies bedeutet, dass das folgende Argument aus der Argumentliste benutzt wird, um die Ausgabegröße zu definieren.

Beispiele

sprintf("%0*x",4,255) wird interpretiert als sprintf("%04x",255)

sprintf("%s %*s","Hallo",40,"Welt") wird interpretiert als sprintf("%s %40s","Hallo","Welt")

.precision

Über diesen Parameter kann gesteuert werden, in welcher Länge ein String ausgegeben werden soll. Diese Angabe wird immer mit einem Punkt . eingeleitet und führt anders als beim Parameter width zu einem Abschneiden des Strings.

Beispiele 

sprintf("%.5s", "123456789")  // Ergebnis "12345"
sprintf("%.*s", 2, "1234")    // Ergebnis "12"

type

Über den Typ wird definiert, wie das entsprechende Argument betrachtet werden soll. Dabei gibt es im IDM folgende Möglichkeiten

Typ

Ausgabeformat

d

Zahl mit Vorzeichen.

u

Zahl ohne Vorzeichen

b

Zahl im Binärformat

o

Zahl im Oktalformat

x

Zahl im Hexadezimalformat, wobei abcdef benutzt wird.

X

Zahl im Hexadezimalformat, wobei ABCDEF benutzt wird.

c

Ausgabe eines Zeichens

s

Ausgabe eines Strings

Für den Einsatz im IDM wurden die Formate für Strings (%s) und Zahlen (%d, %u, %x, %o) erweitert. Dieses Verhalten wird in der nachfolgenden Tabelle dargestellt. Dabei wird [numerisch] als Ersatz für d, x, X, b oder u verwendet.

Datentyp

Steuerung über %

Ergebnis

void

%s

%[numerisch]

Leerstring

ERROR

string

%s

sonst

Eingabestring

ERROR

text

%s

%[numerisch

zugehöriger String

Textid im Zahlenformat

object

%s

%[numerisch

Name des Objekts

DM_ID im Zahlenformat

pointer

%s

%[numerisch

ERROR

Adresse des Pointers im Zahlenformat

event

%s

%[numerisch

Name des Ereignisses

Nummer des Ereignisses im Zahlenformat

enum

%s

%[numerisch

Name der Enumeration

Nummer der Enumeration im Zahlenformat

attribute

%s

%[numerisch

%Name des Attributes

Nummer des Attributes im Zahlenformat

method

%s

%[numerisch

Name der Methode

Nummer der Methode im Zahlenformat

integer

%s

%[numerisch

ERROR

Zahl im Zahlenformat

index

%s

%[numerisch

Beide Werte des Index

ERROR

boolean

%s

%[numerisch

Ausgabe von true oder false als String

Ausgabe von 0 (false) oder 1 im Zahlenformat

class

%s

%[numerisch

Name der Klasse

Interne Nummer der Klasse im Zahlenformat

datatype

%s

%[numerisch

Datentyp als String

Datentyp im Zahlenformat

Pluralism

Über diesen Parameter kann eine von dem Wert eines Arguments abhängige gesteuerte Ausgabe erfolgen. Dabei kann zwischen dem angegebenen Singular- oder Pluralwert ausgewählt werden. Diese Werte müssen dabei immer in eckigen Klammern angegeben und durch ein | getrennt werden. Welcher Wert angezeigt wird, entscheidet der angegebene Wert, der für diesen Teil des Strings im Parameterbereich angegeben wird.

Dabei bewirkt die Angabe von

1
Singularwert
<> 1
Pluralwert

Beispiel 

sprintf("%d %[Haus|Häuser]", 1);  // "1 Haus"
sprintf("%d %[Haus|Häuser]", 2);  // "2 Häuser"
sprintf("%d %[Haus|Häuser]", 0);  // "0 Häuser"

Zusammenfassende Beispiele

!! Ausgabe einer hexadezimalen Zahl in einen statischen Text.

dialog HexOut

window W
{
  child statictext HexOutput { }
}

on dialog start
{
  variable integer Answer := 42;
  variable string S;
  S := sprintf("Dies ist eine Hexzahl: %X", Answer);
  W.HexOutput.text := S;
}
!! Ausgabe eines Datums in einen statischen Text.
!! Dabei werden Varianten verwendet, um Länderspezifika zu unterstuetzen
!! (Reihenfolge von Tag, Monat und Jahr).
dialog VariantDate
text DateFormat "DateFormat"
{
  0: "%02d.%02d.%04d";
  1: "%2$02d/%1$02d/3$04d";
}

window W
{
  child statictext Date{ }
}

on dialog start
{
  variable integer Day := 7;
  variable integer Month := 9;
  variable integer Year := 1965;
  variable string S;
  S := sprintf(DateFormat,Day,Month,Year);
  !! language variant 0: S = "07.09.1965"
  !! language variant 1: S = "09/07/1965"
  W.Date.text := S;
}
!! Beispiel für das Ausnutzen von Singular und Pluralwerten.
dialog SingularPlural

on dialog start
{
  sprintf("%d %[Haus|Häuser]", 1);  // "1 Haus"
  sprintf("%d %[Haus|Häuser]", 2);  // "2 Häuser"
  sprintf("%d %[Haus|Häuser]", 0);  // "0 Häuser"

  print sprintf("%3d Datei%[|en] kopiert", 1);
  // Ergebnis:  1 Datei kopiert
  print sprintf("%3d Datei%[|en] kopiert", 34);
  // Ergebnis: 34 Dateien kopiert
  print sprintf("%3d Datei%[|en] kopiert", 0);
  // Ergebnis:  0 Dateien kopiert
}
!! Dieser Dialog zeigt Spezifika von sprintf() im IDM.
dialog DMInterna

window W1 { }

on dialog start
{
  print sprintf("Attribut %s hat Nummer %1$d", W1.visible);
  // Ergebnis: Attribut .visible hat Nummer 1
 
  print sprintf("Fenster %s hat DM_ID %d", W1, W1);
  // Ergebnis: Fenster W1 hat DM_ID 5
 
  print sprintf("Index %s", [1,2]);
  // Ergebnis: Index [1,2]
}