System.AnsiStrings.Format

Aus RAD Studio API Documentation
Wechseln zu: Navigation, Suche

Delphi

function Format(const Format: AnsiString; const Args: array of const): AnsiString;
function Format(const Format: AnsiString; const Args: array of const; const AFormatSettings: TFormatSettings): AnsiString;

C++

extern DELPHI_PACKAGE System::AnsiString __fastcall Format(const System::AnsiString Format, const System::TVarRec *Args, const int Args_High)/* overload */;

Eigenschaften

Typ Sichtbarkeit Quelle Unit Übergeordnet
function public
System.AnsiStrings.pas
System.AnsiStrings.hpp
System.AnsiStrings System.AnsiStrings

Beschreibung

Die Routine Format formatiert die im Parameter Args angegebene Argumentliste anhand des im Parameter Format übergebenen Format-Strings.

Format-Strings enthalten zwei Typen von Objekten: reine Zeichen und Formatbezeichner. Reine Zeichen werden wörtlich in den resultierenden String kopiert. Formatbezeichner rufen Argumente aus der Argumentliste ab und weisen ihnen ein Format zu.

Formatbezeichner werden in der folgenden Form angegeben:

% ["Index" :] [-] ["Breite"] [. "Genauigkeit"] "Typ"

Jeder Formatbezeichner beginnt mit dem Zeichen %. Auf das Prozentzeichen folgt eine der nachstehenden Angaben (in der aufgeführten Reihenfolge):

  1. Ein optionaler Argumentindex-Bezeichner: ["Index" :]
  2. Eine optionale Angabe für die linksbündige Ausrichtung: [-]
  3. Eine optionale Breitenangabe: ["Breite"]
  4. Eine optionale Genauigkeitsangabe: [. "Genauigkeit"]
  5. Das erforderliche Zeichen für den Umwandlungstyp: "Typ"


Konvertierungszeichen

Folgende Konvertierungszeichen werden unterstützt:

Wert Bedeutung

d

Dezimal. Das Argument muss ein Integerwert sein. Der Wert wird in einen String umgewandelt, der aus Dezimalzahlen besteht. Wenn es sich um eine negative Zahl handelt, beginnt der String mit einem Minuszeichen. Wenn der Format-String einen Bezeichner für die Genauigkeit enthält, muss der resultierende String mindestens die angegebene Anzahl von Stellen aufweisen. Enthält er weniger Stellen, wird der String auf der linken Seite mit Nullen aufgefüllt.

u

Vorzeichenlose Dezimalzahl. Entspricht dem Format d, allerdings enthält der resultierende String kein Vorzeichen.

e

Wissenschaftliche Notation. Das Argument muss ein Gleitkommawert sein. Der Wert wird in einen String mit der folgenden Form umgewandelt: "-d.ddd...E+ddd". Der resultierende String beginnt mit einem Minuszeichen, wenn es sich um eine negative Zahl handelt. Vor dem Dezimaltrennzeichen steht immer eine Ziffer. Die Gesamtzahl der Stellen im Ergebnis-String (einschließlich der Ziffer vor dem Dezimalkomma) wird durch den Genauigkeitsbezeichner im Format-String festgelegt. Ist dieser nicht vorhanden, wird eine vorgegebene Genauigkeit von 15 Stellen angenommen. Auf den Exponenten "E" im String folgen immer ein Plus- oder Minuszeichen und mindestens drei Stellen.

f

Fest. Das Argument muss ein Gleitkommawert sein. Der Wert wird in einen String der folgenden Form umgewandelt: "-ddd.ddd...". Wenn es sich um eine negative Zahl handelt, beginnt der String mit einem Minuszeichen. Die Anzahl der Stellen nach dem Dezimalkomma wird durch den Genauigkeitsbezeichner im Format-String festgelegt. Ist dieser nicht vorhanden, wird eine vorgegebene Genauigkeit von zwei Dezimalstellen verwendet.

g

Allgemein. Das Argument muss ein Gleitkommawert sein. Der Wert wird unter Verwendung des Formats Fest oder Wissenschaftliche Notation in den kürzest möglichen Dezimal-String umgewandelt. Die Anzahl der signifikanten Stellen im resultierenden String wird durch den Genauigkeitsbezeichner im Format-String festgelegt. Ist dieser nicht vorhanden, wird eine vorgegebene Genauigkeit von 15 Stellen angenommen. Nachfolgende Nullen werden aus dem resultierenden String entfernt. Ein Dezimaltrennzeichen wird nur bei Bedarf angezeigt. Für den resultierenden String wird das Festkommaformat verwendet, wenn die Anzahl der Stellen vor dem Dezimaltrennzeichen kleiner oder gleich der festgelegten Genauigkeit und der Wert größer oder gleich 0,00001 ist. In allen anderen Fällen wird die wissenschaftliche Notation benutzt.

n

Zahl. Das Argument muss ein Gleitkommawert sein. Der Wert wird in einen String der folgenden Form umgewandelt: "-d,ddd,ddd.ddd...". Das Format n entspricht dem Format f, allerdings enthält der resultierende String Tausendertrennzeichen.

m

Währung. Das Argument muss ein Gleitkommawert sein. Der Wert wird in einen String umgewandelt, der einen Währungsbetrag darstellt. Die Konvertierung wird über die globalen Variablen CurrencyString, CurrencyFormat, NegCurrFormat, ThousandSeparator, DecimalSeparator und CurrencyDecimals gesteuert. Diese Variablen werden mit den Gebietseinstellungen der Windows-Systemsteuerung initialisiert. Beispielsweise wird das Währungsformat im Bereich Regions- und Ländereinstellungen in der Windows-Systemsteuerung festgelegt. Enthält der Format-String einen Genauigkeitsbezeichner, setzt dieser den Wert in der globalen Variablen CurrencyDecimals außer Kraft.

p

Zeiger. Das Argument muss ein Zeigerwert sein. Der Wert wird in einen String der folgenden Form umgewandelt: "XXXX:YYYY", wobei XXXX und YYYY die Segment- und Offset-Teile des Zeigers sind, die in vier hexadezimalen Ziffern ausgedrückt werden.

s

String. Das Argument muss ein Zeichen, ein String oder ein PChar-Wert sein. Der String bzw. das Zeichen wird anstelle des Formatbezeichners eingefügt. Wenn im Format-String ein Genauigkeitsbezeichner angegeben ist, bestimmt er die maximale Länge des resultierenden Strings. Ist das Argument ein String, der diese Maximallänge überschreitet, wird der String abgeschnitten.

x

Hexadezimal. Das Argument muss ein Integerwert sein. Der Wert wird in einen String umgewandelt, der aus hexadezimalen Stellen besteht. Wenn der Format-String einen Bezeichner für die Genauigkeit enthält, muss der resultierende String mindestens die angegebene Anzahl von Stellen aufweisen. Enthält er weniger Stellen, wird der String auf der linken Seite mit Nullen aufgefüllt.

Konvertierungszeichen können beliebig in Klein- oder Großschreibung angegeben werden.

Bei allen Gleitkommaformaten wird das Zeichen für das Dezimal- bzw. das Tausendertrennzeichen aus den globalen Variablen DecimalSeparator und ThousandSeparator ermittelt.

Die Bezeichner für Index, Breite und Genauigkeit können direkt durch Angabe eines Strings mit dezimalen Ziffern (z.B. "%10d") oder indirekt mit Hilfe von Sternchen (z.B. "%*.*f") angegeben werden. Im letzteren Fall wird das Argument, das in der Argumentliste auf das Sternchen folgt (es muss sich dabei um einen Integerwert handeln), als tatsächlicher Wert verwendet. Zum Beispiel sind die zwei Beispiele identisch:

Format('%*.*f', [8, 2, 123.456])
Format('%8.2f', [123.456])

Der Breitenbezeichner legt die minimale Länge des Feldes für die Konvertierung fest. Ist der resultierende String kürzer als die minimale Feldlänge, wird er mit Leerzeichen aufgefüllt. Per Vorgabe werden die Leerzeichen vor dem Wert eingefügt, um eine rechtsbündige Ausrichtung zu erreichen. Enthält der Formatbezeichner jedoch einen Indikator für linksbündige Ausrichtung (vor dem Breitenbezeichner steht in diesem Fall ein Minuszeichen "-"), werden die Leerzeichen nach dem Wert eingefügt und dieser linksbündig ausgerichtet.

Ein Indexbezeichner setzt den aktuellen Index der Argumentliste auf den angegebenen Wert. Der Index des ersten Arguments in der Liste hat den Wert 0. Durch die Verwendung von Indexbezeichnern kann dasselbe Argument mehrfach formatiert werden. Beispielsweise erzeugt

Format('%d %d %0:d %d', [10, 20])

den String

'10 20 10 20'

Die Funktion Format kann mit anderen Formatfunktionen kombiniert werden. Zum Beispiel:

S := Format('Your total was %s on %s', [FormatFloat('$#,##0.00;;zero', Total), FormatDateTime('mm/dd/yy', Date)]);

Dieser Code verwendet die Funktionen FormatFloat und FormatDateTime zum Anpassen des Formats über das hinaus, was mit der Funktion Format möglich ist.

Alle Routinen zur String-Formatierung, die globale Variablen für die Formatierung (Formate für Trennzeichen, Dezimalzeichen, Datums- und Zeitangaben usw.) verwenden, haben ein überladenes Äquivalent, für das ein Parameter des Typs TFormatSettings erforderlich ist. Dieser zusätzliche Parameter stellt die Formatinformationen anstelle der globalen Variablen bereit. Weitere Informationen hierzu finden Sie in der Dokumentation zu TFormatSettings.

Siehe auch

Codebeispiele