System.SysUtils.Format

De RAD Studio API Documentation
Aller à : navigation, rechercher

Delphi

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

C++

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

Propriétés

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


Description

Renvoie une chaîne formatée assemblée à partir d'une chaîne de format et d'un tableau d'arguments.

La fonction Format formate la série d'arguments d'un tableau (sans type) ouvert.

Format est la chaîne de format. Pour de plus amples informations sur les chaînes de format, voir Chaînes de format', décrites dans cette rubrique.

Args est un tableau d'arguments à appliquer aux spécificateurs de Format. Pour C++, Args_High spécifie l'index du dernier élément de Args (nombre d'éléments moins un).

Format renvoie les résultats de l'application des arguments de Args à la chaîne de format Format.

Deux syntaxes sont données pour Format. La première forme de Format n'est pas thread-safe car elle utilise les informations de localisation contenues dans les variables globales. La seconde forme de Format, qui est thread-safe, fait référence aux informations de localisation contenues dans le paramètre AFormatSettings. Avant d'appeler la forme thread-safe de Format, vous devez placer les informations de localisation dans AFormatSettings. Pour placer un ensemble de valeurs locales par défaut dans AFormatSettings, appelez TFormatSettings.Create.

Chaînes de format

Les chaînes de format spécifient les formats requis par les routines de formatage à usage général. Les chaînes de format passées aux routines de formatage de chaînes contiennent deux types d'objets : les caractères littéraux et les spécificateurs de format. Les caractères littéraux sont copiés mot pour mot dans la chaîne résultante. Les spécificateurs de format récupèrent les arguments de la liste d'arguments et leur applique le formatage.

Les spécificateurs de format ont la forme suivante :

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

Un spécificateur de format commence par un caractère %. Après le signe pourcent, vous trouvez les éléments suivants dans cet ordre :

  1. Un spécificateur facultatif d'index à base 0 (le premier élément a l'index 0) de l'argument, [index ":"].
  2. Un indicateur facultatif de justification à gauche, ["-"].
  3. Un spécificateur facultatif de largeur, [width].
  4. Un spécificateur facultatif de précision, ["." prec].
  5. Le caractère de type de conversion, type.


Le tableau suivant résume les valeurs possibles de type :

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. 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. Similaire à d, mais sans signe en sortie.

e

Scientifique. L'argument doit être une valeur à virgule flottante. La valeur est convertie en une chaîne de la forme "-d.ddd...E+ddd". La chaîne résultante débute par un signe moins si le nombre est négatif. Un chiffre précède toujours le séparateur décimal. Le nombre total de chiffres dans la chaîne résultante (y compris celui qui précède le séparateur décimal) 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 d'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 à virgule 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 le séparateur décimal 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 à virgule 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 de queue sont retirés de la chaîne résultante et un séparateur décimal n'apparaît que s'il est nécessaire. La chaîne résultante utilise le format virgule fixe si le nombre de chiffres à gauche du séparateur décimal est inférieur ou égal à la précision spécifiée et si la valeur est supérieure ou égale à 0,00001. Sinon, la chaîne résultante utilise le format scientifique.

n

Nombre. L'argument doit être une valeur à virgule 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 à virgule flottante. La valeur est convertie en une chaîne représentant une valeur monétaire. La conversion est contrôlée par les variables globales CurrencyString, CurrencyFormat, NegCurrFormat, ThousandSeparator, DecimalSeparator, et CurrencyDecimals ou leur équivalent dans une structure de données TFormatSettings. Si la chaîne de format contient un spécificateur de précision, il redéfinit la valeur donnée par la variable globale CurrencyDecimals ou son équivalent TFormatSettings.

p

Pointeur. L'argument doit être une valeur de type pointeur. La valeur est convertie en une chaîne de 8 caractères qui représente la valeur du pointeur en hexadécimal.

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 présent dans la chaîne de format, spécifie la longueur 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, il indique que la chaîne résultante doit contenir au moins le nombre spécifié de chiffres ; si ce n'est pas le cas, des zéros de remplissage sont rajoutés dans la partie gauche de la chaîne.


Pour afficher le caractère % (c'est-à-dire pour afficher un littéral  %, pas pour commencer un spécificateur de format), utilisez la séquence %%. Exemple :

Writeln(Format('%d%%', [100])); // displays '100%'

Pour tous les formats à virgule flottante, les caractères réels utilisés comme séparateur décimal et séparateur des milliers sont obtenus depuis les variables globales DecimalSeparator et ThousandSeparator, ou leur équivalent TFormatSettings.

Les spécificateurs d'index, de largeur et de précision peuvent être directement spécifiés, en utilisant une chaîne contenant des chiffres décimaux (par exemple "%10d") ou indirectement, en utilisant un caractère astérisque (par exemple "%*.*f").Lorsque vous utilisez un astérisque, l'argument suivant dans la liste d'arguments devient la valeur effectivement utilisée. Sachez que la largeur est une valeur integer, tandis que la précision est une valeur unsigned integer. Par exemple,

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

st équivalent à :

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

De même, dans C++ :

TVarRec args[3] = {8,2,123.456};
Format ("%*.*f", args, 2);

st équivalent à :

TVarRec args[1] = {123.456};
Format ("%8.2f", args, 0);

Un spécificateur de largeur définit la largeur de champ minimale pour une conversion. Si la chaîne résultante est plus courte que la largeur de champ minimale, elle est comblée par des espaces afin d'accroître la largeur de champ. Par défaut, le résultat est justifié à droite en faisant précéder la valeur d'espaces, mais si le spécificateur de format contient un indicateur de justification à gauche (un caractère tiret "-" précédant le spécificateur de largeur), le résultat est justifié à gauche par l'ajout d'espaces après la valeur.

Un spécificateur d'index définit l'index en cours de la liste d'arguments sur la valeur spécifiée. L'index du premier argument de la liste d'arguments est 0. A l'aide des spécificateurs d'index, il est possible de formater le même argument plusieurs fois. Par exemple, "Format('%d %d %0:d %1:d', [10, 20])" produit la chaîne '10 20 10 20'.

Remarque :  La définition du spécificateur d'index affecte tous les formatages ultérieurs. Ainsi, Format('%d %d %d %0:d %d', [1, 2, 3, 4]) renvoie '1 2 3 1 2', et pas '1 2 3 1 4'. Pour obtenir le second résultat, vous devez utiliser Format('%d %d %d %0:d %3:d', [1, 2, 3, 4]).

Voir aussi

Exemples de code