DELPHI, la fonction Format()

Mises à jours du :
09/10/09

Corrections :
15/01/06, 30/11/05

Première version :
29/11/05

par Dr.who (Deefaze)

pour www.developpez.com

Licence : Pas d'Utilisation Commerciale, Partage des Conditions Initiales à l'Identique, v2.0 France

Tiré en grande partie de l'aide de Borland Delphi 7 © Borland 2002

 Sommaire

A) Quand utiliser Format ?

B) Performances

C) Déclaration de format dans Delphi

D) Qu'est-ce qu'une chaine de formatage ?

E) Qu'est-ce qu'un spécificateur de format ?

F) Tableau des types de spécificateurs de format

G) Format flottant et séparateur décimal

H) Écriture des spécificateurs d'indice, taille et précision

I) Conclusion
A) Quand utiliser Format ?

Utilisez format dés que vous désirez convertir une valeur en une chaine de caractères. En effet,
Format vas vous faciliter grandement la vie dans ce domaine, en remplaçant toutes les autres
fonctions comme FloatToStr ou IntToStr...

Exemple (afficher les coordonnées de la souris sur le titre de la fiche):

procedure TForm1.FormMouseMove(Sender: TObject; Shift: TShiftState; X,Y: Integer);

begin
caption := 'x: '+IntToStr(X)+' | y: '+IntToStr(Y);
end;

Seras facilement remplaçable par :

procedure TForm1.FormMouseMove(Sender: TObject; Shift: TShiftState; X,Y: Integer);
begin
caption := format('x: %.4d | y: %.4d',[X, Y]);
end;

Comme vous l'avez compris, Format est LA fonction spécialisée dans le formatage de chaines, rendant
ainsi l'écriture et la lecture du code plus simple.

A.Bis) Recommandations.

- Les chaines de formatage ne sont pas compilées dans Delphi, contrairement en C et C++. Vérifiez
donc bien le type des spécificateurs de format que vous utiliserez pour éviter les erreurs d'exécution.

- Pour les concaténations de chaines courtes (string et char), il est préférable de ne pas utiliser format,
mais plutôt la bonne vieille méthode qui est la plus rapide, par exemple :

SC := protocol+'://'+domainename+'/';
{ au lieu de : SC := format('%s://%s/',[protocol,domainename]); }

B) Performances

Je vous le donne en mille, Format est plus rapide que la plupart des méthodes de base que tout le
monde utilise! (note de l'auteur : parfois oui, parfois non! Mesurez!)

Parlons chiffres et millisecondes, avec un bench (test de performances) tout simple :

- 1er test :

for X := 1 to 1000000 do s := 'X = ' + IntToStr(X);

Résultat :
Moyenne de 945 ms (sur Athlon XP 1800+) presque 1 seconde.

- 2eme test :

for X := 1 to 1000000 do s := format('X = %d',[X]);

Résultat :
Moyenne de 532 ms (sur Athlon XP 1800+) presque 1/2 seconde.

Format affiche de meilleures performance et vous permettras d'optimiser correctement vos

programmes, surtout sur les méthodes de conversions valeurs vers texte.
C) Déclaration de format dans Delphi

Format est déclarée dans l'unité SysUtils de Delphi.

Elle se présente de cette manière :

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

begin
FmtStr(Result, Format, Args);
end;

function Format(const Format: string; const Args: array of const;

const FormatSettings: TFormatSettings): string;
begin
FmtStr(Result, Format, Args, FormatSettings);
end;

const Format correspond à la chaine de format, elle contient le texte et les spécificateurs de format de
cette dernière.

const Args correspond au tableau d'arguments à appliquer aux spécificateurs de format contenus dans
la chaine de formatage.

const FormatSettings (facultatif) permet de définir des variables de format temporaire qui n'affectent
pas les variables globales du programme (decimalSeparator par exemple) .

Format fait appel à FmtStr(); incluse elle aussi dans l'unité SysUtils.

D) Qu'est-ce qu'une chaine de formatage ?

Une chaine de formatage est tout simplement une chaine qui contient d'une part du texte et d'autre part
des spécificateurs de format.

E) Qu'est-ce qu'un spécificateur de format ?

Un spécificateur de format est un "marqueur" qui permet d'identifier le type et les paramètres de
traitement d'un argument à formater dans une chaine de format.

Dans Delphi comme dans C++, un spécificateur de format commence toujours par le symbole "%".
Il est donc logique que le caractères % (pour afficher un pourcentage par exemple) s'obtienne donc en
le doublant comme ceci "%%" à l'instar d'un double ' ' dans une chaine string, exemple :

format('le rapport est de : %.2f %%',[rapport]);

Les spécificateurs de format ont la forme suivante : (tiré de l'aide Delphi)

"%"[index ":"]["-"][largeur]["."précision]type
 Comme dit précédemment, Le spécificateur de format commence toujours par le symbole %, il sera
suivis ensuite de divers paramètres (dans l'ordre) :

[index ":"] correspond à l'index de l'argument dans le tableau d'arguments (facultatif)

["-"] correspond à l'alignement par défaut à gauche (facultatif)
[largeur] correspond à la taille (facultatif)
["." prec] correspond à la précision (facultatif) très utile pour les valeurs de type flottant
type correspond au type de l'argument à convertir
(Provoquera une erreur de conversion si l'argument n'est pas de ce type)

Index, Largeur et Précision doivent être de type entier.

F) Tableau des types de spécificateurs de format

TYPE DEFINITION

%d Entiers

Types admits :
integer, smallint, shortint, longint, int64, byte, word, uint64, cardinal, longword...

Si le spécificateur de précision est défini, la chaine en sortie sera remplie de zéro (leadZero) si la
taille de l'entier est inférieure à celle de la précision.

exemple :

format('mon chiffre est : %.4d', [12]);

renvois "mon chiffre est : 0012"

%u Entiers non-signés, valeur absolue

Types admits :
integer, smallint, shortint, longint, int64, byte, word, uint64, cardinal, longword...

identique à %d mais sans retour de signe. Permet une petite optimisation.

%u serai équivalent à :

format('%d', [abs(var)]);

%e Réels écriture scientifique

Types admits :
single, real, real48, double, comp, extended, currency.

La valeur est convertie en une chaîne de la forme "-d.ddd...E+ddd". 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 "E" dans la chaîne résultante est toujours suivi d'un signe "+" ou "-", puis de trois
chiffres au moins.
%f Réels

Types admits :
single, real, real48, double, comp, extended, currency.

Définissez un spécificateur de précision pour définir le nombre de chiffres après la virgule.

exemple :

format('Pi = %.4f', [pi]);

renvois "Pi = 3,1415"

format('Pi = %.0f', [pi]);

renvois "Pi = 3"

%g Réels, au plus court

Types admits :
single, real, real48, double, comp, extended, currency.

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, Réels avec séparateurs de milliers

et entiers. (voir note)

Types admits :
single, real, real48, double, comp, extended, currency.

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
des séparateurs des milliers.

exemple :

format('%n', [1024584248.125]);
renvois "1 024 584 248,125"
 NOTE : (%n suite)

Types :
integer, smallint, shortint, longint, byte, word, int64, cardinal.

Pour ces types vous devrez écrire format de cette façon :

format('%.0n', [VarInt + 0.0]);

Sinon format renvois une erreur de conversion.

exemple :

format('Taille : %.0n octets', [24533126 + 0.0]);

renvois "Taille : 24 533 126 octets"

%m Réels représentation monétaire

Types admits :
single, real, real48, double, comp, extended, currency.

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 remplace la valeur envoyée par la

variable globale CurrencyDecimals ou son équivalent TFormatSettings.

exemple :

CurrencyString := '€';
format('15 Francs en Euros = %.5m', [15 * 0,152449]);
renvois "15 Francs en Euros = 2,286735 €"
CurrencyString := 'Fr';
format('15 Euros en Francs = %.2m', [15 * 6.55957]);
renvois "15 Euros en Francs = 98,39355 Fr"

%p Adresses de pointeur

Types supportés :
(^Type), pAnsiString, pString, pByteArray, pCurrency, pDouble, pExtended, pSingle,
pInteger, pOleVariant, pShortString, pTextBuf, pVarRec, pVariant, pWideString,
pWordArray, pointer(...)...

La valeur est convertie en une chaîne de 8 caractères (32bits) hexadécimaux, chaine qui
représente l'adresse du pointeur.

exemple :

format('%p', [PInteger(1024)]);
renvois "00000400"

%p renvois l'adresse du pointeur et non la valeur pointée par ce dernier.

 %s Chaîne de caractères

Types admits :
String, Char, PChar, AnsiString, WideString, ShortString, AnsiChar, WideChar...

La chaîne ou le caractère est inséré à la place du spécificateur de format. Définissez le

spécificateur de précision pour indiquer la taille maximale de la chaine, qui sera alors tronquée
automatiquement si elle est plus grande (très pratique).

exemple :

format('nom : %s, prénom : %s', [edit1.text, edit2.text]);

renvois "nom : Borland, prénom : Delphi"

Voir les recommandations dans le A.Bis

%x Hexadécimal

Types admits :
ordinaux, scalaires, entiers, integer, smallint, shortint, longint, byte, word, int64, cardinal,
longword, uint64...

La valeur est convertie en sa représentation hexadécimale. Si la chaîne de format contient un

spécificateur de précision, ce dernier spécifie que la chaîne doit contenir au moins le nombre
indiqué de chiffres; si cela n'est pas le cas, des caractères zéro de remplissage sont ajoutés
dans la partie gauche de la chaîne (LeadZero).

exemple :

format('Char : #%0:.3d | Hexa : %0:.2x', [ord(' ')]);

renvois "Char : #032 | Hexa : 20"

G) Format flottant et séparateur décimal

"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 ou leur équivalent TFormatSettings."

Il faut comprendre par la, qu'en assignant une nouvelle valeur à ces variables globales, on peu modifier
l'aspect d'affichage mais également de réceptions des valeurs de type flottant.

Un exemple concret de cette méthode est par exemple la réception d'un chiffre à virgule dans une
boite d'édition (TEdit). L'utilisateur peut soit mettre un point « . » pour définir le séparateur décimal, soit
mettre une virgule « , » pour définir le séparateur des décimales.

Afin d'éviter le declenchement d'une exception de conversion, il nous faut écrire une méthode simple
pour savoir si nous sommes en présence d'un point ou d'une virgule comme séparateur de décimales.

Exemple :
 procededure TformX.EditXKeyPress(Sender: Tobject; var Key: char);
begin
if key in ['.',','] then
DecimalSeparator := Key;
end;

Cette méthode influera directement sur toutes les fonctions de conversion Flottant vers Chaine et
inversement, tel Format, FloatToStr, FloatToStrDef, StrToFloat etc....

Après traitement, nous pourrons réassigner à DecimalSeparator, une valeur par défaut (virgule par
exemple) et afficher les résultats en conséquence.

DecimalSeparator := ',';
Format('mon resultat est : %.2n',[resultat]);

Attention, la manipulation, modification des variables globales de formatage doit être faite avec
prudence et réflexion, sans abus aucuns.

H) Écriture des spécificateurs d'indice, taille et précision

"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".

Exemple :

format('%.*f',[precision, chiffre]);

Dans cet exemple, le caractère * sera remplacé par le variable "precision".

Retenez bien cette méthode car elle vous évitera de déclarer plusieurs constante de chaine de format
et donc permettras encore une fois d'alléger le code.

Voici un exemple de ce qu'il ne faut pas faire :

Function MaValeurToStr(const val: single; const Precision: byte=0): string;

const
Precision0 := '%.0f';
Precision2 := '%.2f';
Precision4 := '%.4f';
Begin
case Precision of
0 : CDF := Precision0;
1 : CDF := Precision2;
2 : CDF := Precision4;
end;
result := format(CDF,[val]);
end;

(PS : ne rigolez pas, j'ai déjà vus ce genre de code dans des programmes pourtant sérieux. Ce qui
démontre bien le manque de connaissance vis à vis de la fonction Format).

Voici maintenant la bonne version de la méthode :

 Function MaValeurToStr(const val: single; const Precision: byte=0): string;
Begin
result := format('%.*f',[Precision, val]);
end;

On peu bien sur, utiliser "*" pour l'indice ou pour la taille exemple (sur l'indice) :

Type
TColor3h = record
Red, Green, Blue : byte;
end;

TColorVl = (cvAll, cvRed, cvGreen, cvBlue);

Function RGBStrHex(const RGB: TColor3h; const color: TColorVl=cvAll): string;

Begin
// si on ne precise pas de couleur en particulier
if color <> cvAll then
// on renvois la couleur selon l'indice (ord) de color dans le type
// TColorvl format récupère ce chiffre comme indice dans le tableau
// d'arguments et nous renvois donc la couleur désirée
result := format('%*:.2x',[ord(color), RGB.Red, RGB.Green, RGB.Blue])
else
// sinon, on renvois tout, au format HTML.
result := format('#%.2x%.2x%.2x',[RGB.Red, RGB.Green, RGB.Blue])
end;

Dans cette fonction, grâce à "*" encore une fois, on raccourcit radicalement le code, ce qui évite de
faire des cascade de IF ... ELSE ou de CASE ... OF. La méthode devient alors simple et rapide, tout
cela grâce à Format.

I) Conclusion

Voila, ce tutoriel sur la fonction format est finit.

Vous pouvez en retenir que :

- Format est la solution la plus pratique pour convertir une valeur en une chaine de
caractères, même la plus courte qu'il soit.

- Format est souvent plus rapide que les méthodes :

Chaine = SousChaine + "type"ToStr(valeur).

- Format permet de réduire considérablement le code des diverses méthodes de conversion

en chaine de caractères et évite la multiplication des fonctions IntToStr, FloatToStr etc.

- Format peut fonctionner comme les fonctions très connues que sont LeadZero et LeadSpace!

- Passer à coté de Format ou l'ignorer, serait vraiment trop bête.

- La fonction Format rentre complètement dans le cadre "optimisation" des programmes.