System.AnsiStrings.Format

Aller au parent : System.AnsiStrings

Delphi

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

C++

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

Sommaire

1 Propriétés
2 Description

Propriétés

Type	Visibilité	Source	Unité	Parent
function	public	System.AnsiStrings.pas System.AnsiStrings.hpp	System.AnsiStrings	System.AnsiStrings

Description

Formate la liste d'arguments spécifiée par le paramètre Args en utilisant la chaîne de format spécifiée par le paramètre Format.

Les chaînes de format contiennent deux types d'objets : les caractères bruts et les spécificateurs de format. Les caractères bruts sont copiés tels quels dans la chaîne résultante. Les spécificateurs de format récupèrent les arguments dans la liste des arguments en y appliquant un format.

Les spécificateurs de format ont la forme suivante :

% ["index" :] [-] ["width"] [. "prec"] "type"

Un spécificateur de format commence par un caractère %. Ce qui suit % est, dans l'ordre :

un spécificateur facultatif d'index d'argument, ["index" :]
un indicateur facultatif d'alignement à gauche, [-]
un spécificateur facultatif de largeur, ["width"]
un spécificateur facultatif de précision, [. "prec"]
le caractère de type de conversion requis, "type"

Caractères de conversion

Les caractères de conversion suivants sont supportés :

Valeur	Signification
d	Décimal. L'argument doit être une valeur entière. La valeur est convertie en une chaîne de chiffres décimaux. La chaîne résultante débute par un signe moins si le nombre est négatif. Si la chaîne de format contient un spécificateur de précision, la chaîne résultante doit contenir au moins le nombre indiqué de chiffres ; si cela n'est pas le cas, des caractères zéro de remplissage sont rajoutés dans la partie gauche de la chaîne.
u	Décimal sans signe. Comme d mais sans signe en sortie.
e	Scientifique. L'argument doit être une valeur flottante. La valeur est convertie en une chaîne de la forme `"-d.ddd...E+ddd"`. La chaîne résultante commence par un signe moins si le nombre est négatif, et la virgule décimale est toujours précédée d'un chiffre. Le nombre total de chiffres dans la chaîne résultante (y compris celui qui précède la virgule) est donné par le spécificateur de précision dans la chaîne de format. Si celui-ci est omis, une précision de 15 est prise en compte par défaut. Le caractère exposant `"E"` dans la chaîne résultante est toujours suivi d'un signe plus ou moins, puis de trois chiffres au moins.
f	Fixe. L'argument doit être une valeur flottante. La valeur est convertie en une chaîne de la forme `"-ddd.ddd..."`. La chaîne résultante débute par un signe moins si le nombre est négatif. Le nombre de chiffres après la virgule est fourni par le spécificateur de précision de la chaîne de format ; 2 décimales sont prises en compte par défaut si le spécificateur de précision est omis.
g	Général. L'argument doit être une valeur flottante. La valeur est convertie en une chaîne décimale la plus courte possible en utilisant le format fixe ou scientifique. Le nombre de chiffres significatifs dans la chaîne résultante est fourni par le spécificateur de précision dans la chaîne de format ; une précision par défaut de 15 est prise en compte si le spécificateur de précision est omis. Les caractères zéro sont supprimés de la fin de la chaîne résultante et la virgule décimale n'apparaît que si elle est nécessaire. La chaîne résultante utilise le format fixe si le nombre de chiffres à gauche de la virgule est inférieur ou égal à la précision indiquée et si la valeur est supérieure ou égale à 0,00001. Sinon, la chaîne résultante fait appel au format scientifique.
n	Numérique L'argument doit être une valeur flottante. La valeur est convertie en une chaîne de la forme `"-d,ddd,ddd.ddd..."`. Le format n correspond au format f, sauf que la chaîne résultante contient le séparateur des milliers.
m	Monétaire. L'argument doit être une valeur flottante. La valeur est convertie en une chaîne représentant un montant monétaire. La conversion est contrôlée par les variables globales CurrencyString, CurrencyFormat, NegCurrFormat, ThousandSeparator, DecimalSeparator et CurrencyDecimals; toutes sont initialisées à partir des paramètres régionaux fournis par le système d'exploitation. Par exemple, les préférences de format monétaire peuvent être définies dans la section International du panneau de configuration Windows. Si la chaîne de format contient un spécificateur de précision, il remplace la valeur donnée par la variable globale CurrencyDecimals.
p	Pointeur. L'argument doit être une valeur de type pointeur. La valeur est convertie en une chaîne de la forme `"XXXX:YYYY"` où `XXXX` et `YYYY` sont les parties segment et offset du pointeur exprimées sous la forme de quatre chiffres hexadécimaux.
s	Chaîne. L'argument doit être un caractère, une chaîne ou une valeur PChar. La chaîne ou le caractère est inséré à la place du spécificateur de format. Le spécificateur de précision, s'il est défini dans la chaîne de format, indique la taille maximale de la chaîne résultante. Si l'argument est une chaîne de taille supérieure, celle-ci est tronquée.
x	Hexadécimal. L'argument doit être une valeur entière. La valeur est convertie en une chaîne de chiffres hexadécimaux. Si la chaîne de format contient un spécificateur de précision, ce dernier spécifie que la chaîne résultante doit contenir au moins le nombre indiqué de chiffres. Si la valeur a moins de chiffres, des caractères zéro de remplissage sont rajoutés dans la partie gauche de la chaîne résultante.

Les caractères de conversion peuvent être indiqués indifféremment en majuscules ou en minuscules : le résultat obtenu est le même.

Quel que soit le format flottant, les deux caractères utilisés comme séparateur décimal et séparateur des milliers sont respectivement définis par les variables globales DecimalSeparator et ThousandSeparator.

Les spécificateurs d'indice, de taille et de précision peuvent être directement spécifiés en utilisant des chaînes contenant des chiffres décimaux (par exemple "%10d") ou indirectement, en utilisant le caractère astérisque (par exemple "%*.*f"). Lorsque vous utilisez l'astérisque, l'argument suivant dans la liste (qui doit être obligatoirement une valeur entière) devient la valeur effectivement utilisée. Par exemple,

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

Format('%8.2f', [123.456])

sont équivalents.

Un spécificateur de taille définit la taille minimale du champ lors de la conversion. Si la chaîne résultante est de taille inférieure à la taille minimale définie, la chaîne est comblée par des espaces afin d'accroître la taille du champ. Par défaut, le résultat est aligné à droite en ajoutant en faisant précéder la valeur d'espaces, mais si le spécificateur de format contient un indicateur d'alignement à gauche (un caractère "-" précédant le spécificateur de taille), le résultat est aligné à gauche par l'ajout d'espaces après la valeur.

Un spécificateur d'indice définit la valeur courante de l'indice de la liste. L'indice du premier argument dans la liste est 0. A l'aide du spécificateur d'indice, vous pouvez formater un même argument plusieurs fois de suite. Par exemple,

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

produit la chaîne :

'10 20 10 20'

La fonction Format peut être combinée à d'autres fonctions de formatage. Par exemple :

S := Format('Votre total était de %s sur %s', [FormatFloat('$#,##0.00;;zero', Total),FormatDateTime('mm/dd/yy', Date)]);

Ce code utilise les fonctions FormatFloat et FormatDateTime pour personnaliser le format au-delà de ce qui est possible avec la fonction Format.

Chacune des routines de formatage de chaînes qui utilise les variables globales pour le formatage (séparateurs, décimaux, formats date/heure, etc.) a un équivalent surchargé nécessitant un paramètre de type TFormatSettings. Ce paramètre supplémentaire fournit les informations de formatage plutôt que les variables globales. Pour de plus amples informations, voir la documentation de TFormatSettings.