Funktionreferenz

StringFormat

Beschreibung anzeigen in

Gibt einen formatierten String zurück (ähnlich zu der C sprintf() Funktion).

StringFormat ( "format control" [, var1 [, ... var32]] )

Parameter

format control Das Format und die Flags, die benutzt werden (siehe Bemerkungen).
var1...var32 Bis zu 32 Variablen, die entsprechend dem "format control" ausgegeben werden.

Rückgabewert

Gibt den formatierten String zurück, entsprechend den "format control" Parametern.

Bemerkungen

Um einen zu großen Speicherverbrauch zu vermeiden, ist jede "Variable" auf 65535 Zeichen limitiert.
Steuerzeichenzeichen können in "format control" beinhaltet sein, wie \n (@LF), \r (@CR), \t (@TAB]. Also wenn man ein "\" haben will, muss man \\ anwenden; gleichfalls mit "%" %%.

"variable format" ist; %[flags] [width] [.precision] type

Bei ungültiger Format-Spezifikation ist das Verhalten undefiniert. In speziellen Fällen kann es durch ungültige Spezifikation zum Abbruch des Programms kommen.

    Spezifikation der Weite

Das zweite optionale Feld der Format-Spezifikation ist die Weitenspezifikation. Das Argument für die Weite ist eine nicht negative, dezimale Ganzzahl, die die minimale Zahl der zu druckenden Zeichen festlegt. Ist die Anzahl der Zeichen im Ausgabewert kleiner als die spezifizierte Weite, werden Leerzeichen rechts oder links zu den Werten addiert — abhängig davon ob der Flag für Links-Ausrichtung spezifiziert ist — bis die minimale Weite erreicht ist. Ist der Weite eine 0 vorangestellt werden Nullen addiert, bis das Minimum erreicht ist (nicht sinnvoll für links ausgerichtete Zahlen).

Die Weitenspezifikation verursacht niemals, dass ein Wert abgeschnitten wird. Ist die Anzahl der Zeichen im Ausgabewert größer als die spezifizierte Weite oder ist die Weite nicht angegeben, werden alle Zeichen gedruckt (entsprechend der Genauigkeit der Spezifizierung).

    Typ Spezifizierung

Typ Variablen Typ Ausgabeformat
d, i Ganzzahl Dezimale Ganzzahl mit Vorzeichen.
o Integer Oktale Ganzzahl ohne Vorzeichen.
u Integer Dezimale Ganzzahl ohne Vorzeichen.
x Integer Hexadezimal Ganzzahl (ohne VZ), Anwendung "abcdef".
X Integer Hexadezimal Ganzzahl (ohne VZ), Anwendung "ABCDEF".
e Float Wert mit Vorzeichen in der Form [ - ]d.dddd e [sign]ddd wobei d ein einzelnes dezimales Zeichen ist, dddd steht für ein oder mehrere dezimale Zeichen, ddd steht für genau drei dezimale Zeichen und sign (Vorzeichen) kann + oder - sein.
E Float Identisch zum e Format bis auf das E gegenüber e den Exponent einführt.
f Float Wert mit Vorzeichen in der Form [ - ]dddd.dddd, wobei dddd für ein oder mehrere dezimale Zeichen steht. Die Anzahl der Zeichen vor dem Dezimalpunkt ist abhängig von der Größenordnung der Zahl. Die Anzahl der Zeichen nach dem Dezimalpunkt ist abhängig von der verlangten Genauigkeit.
g Float Wert mit Vorzeichen ausgedruckt im f oder e Format, je nachdem welches Format für den gegebenen Wert und die erwartete Genauigkeit angemessener ist. Das e Format wird nur verwendet, wenn der Exponent des Werte weniger als -4 oder größer oder gleich dem Genauigkeitsargument ist. Nachfolgende Nullen werden abgeschnitten und der Dezimalpunkt erscheint nur, wenn ein oder mehrere Nachkommastellen folgen.
G Float Identisch zum g Format bis auf das E gegenüber e den Exponent einführt.
s String String.

    Flag Spezifizierung

Flag Bedeutung Vorgabe
- Richtet das Ergebnis im gegebenen Feld links aus. Rechtsbündig.
+ Stellt dem Ausgabewert ein Vorzeichen (+ oder -) vor, falls der Ausgabewertes von diesem Typ ist. Vorzeichen erscheinen nur vor negativen Werten(-).
0 Wird width eine 0 vorangestellt werden Nullen addiert bis das Minimum der Weite erreicht ist. Kommen 0 und - vor, wird 0 ignoriert. Ist 0 spezifiziert mit einem Integer/Ganzzahl Format (i, u, x, X, o, d) wird 0 ignoriert. Kein auffüllen.
Blank Dem Ausgabewert wird ein Leerzeichen vorangestellt, wenn der Ausgabewert ein Vorzeichen enthält und positiv ist; Das Leerzeichen wird ignoriert, wenn das Leerzeichen und + flags erscheinen. Kein Leerzeichen.
# Benutzt mit dem o, x, oder X Format, der # Flag setzt jedem ungleich 0 Ausgabewert eine 0, 0x, oder 0X voran. Keine Leerzeichen.
# Benutzt mit dem e, E oder f Format, der # Flag zwingt den Ausgabewert in allen Fällen ein Dezimalpunkt zu enthalten. Der Dezimalpunkt wird nur bei nachfolgenden Zeichen angezeigt.
# Benutzt mit dem g oder G Format, der # Flag zwingt den Ausgabewert in allen Fällen einen Dezimalpunkt anzuzeigen und verhindert das Abschneiden von nachfolgenden Nullen. Wird ignoriert, wenn es mit d, i, u oder s benutzt wird. Der Dezimalpunkt wird nur bei noch nachfolgenden Zeichen angezeigt. Nachfolgende Nullen werden abgeschnitten.

    Spezifikation der Genauigkeit (precision)

Das dritte optionale Feld der Format Spezifikationen ist die Genauigkeitsangabe. Es handelt sich dabei um eine nicht negative dezimale Ganzzahl, der ein Punkt (.) vorangestellt wird. Diese Spezifikation legt fest: die Anzahl der Zeichen die gedruckt werden soll, die Anzahl der dezimalen Stellen oder die Anzahl signifikanter Zeichen (siehe Tabelle unten). Ungleich der Spezifikation der Weite, kann die Spezifikation der Genauigkeit das Abschneiden der Ausgabewerte bewirken oder das Runden von Fließkommazahlen. Ist die Genauigkeit mit 0 angegeben und ist der zu konvertierende Wert ebenfalls 0, enthält der Ausgabewert kein Zeichen (= no characters output), wie nachfolgend dargestellt:

StringFormat( "%.0d", 0 ); /* No characters return */

    Wie Genauigkeitsangaben den Typ beeinflussen

Typ Bedeutung Vorgabe
d, i, u, o, x, X Der Genauigkeitswert legt die minimale Anzahl der Zeichen, die gedruckt werden sollen, fest. Wenn die Anzahl der Zeichen im Argument kleiner ist als die Genauigkeit, wird der Ausgabewert links mit Nullen aufgefüllt. Der Wert wird nicht abgeschnitten, wenn die Anzahl der Zeichen die Genauigkeit überschreitet. Die Vorgabe für die Genauigkeit ist 1.
e, E Der Genauigkeitswert legt die Anzahl der zu druckenden Nachkommastellen fest. Die letzte Nachkommastelle wird gerundet. Der Vorgabewert ist 6. Ist die Genauigkeit 0 oder erscheint ein Punkt ohne Nachkommastellen, wird kein Dezimalpunkt gedruckt.
f Der Genauigkeitswert legt die Anzahl der Nachkommastellen fest. Wenn ein Dezimalpunkt erscheint, ist mindestens ein Zeichen davor. Der Wert wird auf die entsprechende Anzahl von Zeichen gerundet. Der Vorgabewert ist 6. Ist die Genauigkeit 0 oder erscheint ein Punkt ohne Nachkommastellen, wird kein Dezimalpunkt gedruckt.
g, G Der Genauigkeitswert legt die maximale Anzahl signifikanter Zeichen, die gedruckt werden sollen, fest. Sechs signifikante Zeichen werden gedruckt, wobei nachfolgende Nullen abgeschnitten werden.
s Der Genauigkeitswert legt die maximale Anzahl der zu druckenden Zeichen fest. Zeichen, die dieses Limit übersteigen, werden nicht gedruckt. Zeichen werden bis zum Auftreten eines Null-Zeichens gedruckt.

Beispiel

Example()

Func Example()
    Local $iInt_Unsigned = 43951789
    Local $iInt_Negative = -43951789

    ConsoleWrite(@CRLF & "Numerische Formate" & @CRLF)

    PrintFormat($iInt_Unsigned, "%d", "Standard positiver Integer ohne Vorzeichen", 1) ; 43951789
    PrintFormat($iInt_Negative, "%d", "Standard negativer integer mit Vorzeichen", 1) ; -43951789
    PrintFormat($iInt_Unsigned, "%i", "Standard Integer", 1) ; 43951789
    PrintFormat($iInt_Unsigned, "%09i", "9 Ziffern mit führender Null", 1) ; 043951789
    PrintFormat($iInt_Unsigned, "%e", "wissenschaftliche Schreibweise") ; 4.395179e+007
    PrintFormat($iInt_Unsigned, "%u", "vorzeichenlose Integerschreibweise eines positiven Integerwerts", 1) ; 43951789
    PrintFormat($iInt_Negative, "%u", "vorzeichenlose Integerschreibweise eines negativen Integerwerts", 1) ; 4251015507
    PrintFormat($iInt_Unsigned, "%f", "standardmäßige Gleitpunktschreibweise") ; 43951789.000000
    PrintFormat($iInt_Unsigned, "%.2f", "Gleitpunktschreibweise mit 2 Stellen nach dem Dezimalpunkt", 1) ; 43951789.00
    PrintFormat($iInt_Unsigned, "%o", "Darstellung als Oktalzahl", 1) ; 247523255
    PrintFormat($iInt_Unsigned, "%s", "Darstellung als String", 1) ; 43951789
    PrintFormat($iInt_Unsigned, "%x", "Darstellung als Hexadezimalzahl mit Präfix in Kleinschreibung", 1) ; 29ea6ad
    PrintFormat($iInt_Unsigned, "%X", "Darstellung als Hexadezimalzahl ohne Präfix und in Großschreibung", 1) ; 29EA6AD
    PrintFormat($iInt_Unsigned, "%+d", "Darstellung eines positiven Integerwerts bei erzwungenem Vorzeichen", 1) ; +43951789
    PrintFormat($iInt_Negative, "%+d", "Darstellung eines negativen Integerwerts bei erzwungenem Vorzeichen", 1) ; -43951789

    Local $sString = "string"
    Local $sString_Long = "longstring"

    ConsoleWrite(@CRLF & "Stringformate - [ ] werden für den Beginn und das Ende des Strings verwendet" & @CRLF)

    PrintFormat($sString, "[%s]", "Standardstring", 1) ; [string]
    PrintFormat($sString, "[%10s]", "rechtsbündige Ausgabe von 10 Zeichen mit auffüllenden Leerzeichen") ; [    string]
    PrintFormat($sString, "[%-10s]", "linksbündige Ausgabe von 10 Zeichen mit auffüllenden Leerzeichen") ; [string    ]
    PrintFormat($sString_Long, "[%10.8s]", "rechtsbündige Ausrichtung von 10 Zeichen, aber nur 8 Zeichen der Variablen werden verwendet") ; [  longer s]
    PrintFormat($sString_Long, "[%-10.8s]", "linksbündige Ausrichtung von 10 Zeichen, aber nur 8 Zeichen der Variablen werden verwendet") ; [longer s  ]
    PrintFormat($sString, "[%010s]", "10 Zeichen mit führender Null") ; [0000string]

    ConsoleWrite(@CRLF & "Datenformat - jedes % verwendet einen neuen Parameter" & @CRLF)
    ConsoleWrite('"%02i\%02i\%04i" 0n (1, 9, 2013) => ' & StringFormat("%02i\%02i\%04i", 1, 9, 2013) & @CRLF)

    ConsoleWrite(@CRLF & "Nur ein zu formatierender String  ohne Variablen" & @CRLF)
    ConsoleWrite('"Etwas \tBeispieltext\n" => ' & StringFormat('Etwas \tBeispieltext\n'))
EndFunc   ;==>Example

Func PrintFormat($vVar, $sFormat, $sExplan, $iTab = 0)
    ConsoleWrite('"' & $sFormat & '" on ' & $vVar & @TAB & ' => ' & StringFormat($sFormat, $vVar))
    If $iTab Then ConsoleWrite(@TAB)
    ConsoleWrite(@TAB & " ; " & $sExplan & @CRLF)
EndFunc   ;==>PrintFormat