(PHP 4, PHP 5, PHP 7)
sprintf — Retourne une chaîne formatée
Retourne une chaîne formatée, avec le format
format, en utilisant les arguments
args.
formatLa chaîne de format est composé de zéro ou plusieurs directives : des caractères ordinaires (à l’exception de %) qui sont copiés directement dans le résultat et des spécifications de conversion, chacun ayant pour résultat de récupérer ses propres paramètre.
Une spécification de conversion qui suit ce prototype : %[flags][width][.precision]specifier.
| Drapeau | Description |
|---|---|
| - | Justifie le texte à gauche donnée la largeur du champ ; Justification à droite est le comportement par défaut. |
| + | Préfixe les nombres positives avec un signe plus + ; Par défaut seul les nombres négatifs sont préfixés avec un signe négatif. |
| (espace) | Complète le résultat avec des espaces. Ceci est par défaut. |
| 0 | Complète uniquement les nombres à gauches avec des zéros. Avec le spécificateur s ceci peut aussi compléter à droite avec des zéros. |
| '(char) | Complète le résultat avec le caractère (char). |
Un entier indiquant combien de caractères (au minimum) cette conversion doit avoir pour résultat.
Un point . suivie d'un entier dont sa signification dépend du spécificateur :
Note: Si le point est spécifié sans une valeur explicite pour la précision, 0 est assumé.
Note: Tenter d'utiliser une position supérieure à
PHP_INT_MAXgénèrera une alerte.
| Spécificateur | Description |
|---|---|
| % | Un caractère de pourcentage littéral. Aucun argument n'est nécessaire. |
| b | L'argument est traité comme un entier et présenté comme un nombre binaire. |
| c | L'argument est traité comme un entier et présenté comme le caractère de code ASCII correspondant. |
| d | L'argument est traité comme un entier et présenté comme un nombre entier décimal (signé). |
| e | L'argument est traité comme une notation scientifique (e.g. 1.2e+2). Le spécificateur de précision représente le nombre de chiffres après la virgule depuis PHP 5.2.1. Dans les versions antérieures, il a été pris comme nombre des chiffres significatifs (moins un). |
| E | Comme le spécificateur e mais utilise une lettre majuscule (par exemple 1.2E+2). |
| f | L'argument est traité comme un nombre à virgule flottante (type float) et présenté comme un nombre à virgule flottante (tenant compte de la locale utilisée). |
| F | L'argument est traité comme un nombre à virgule flottante (type float) et présenté comme un nombre à virgule flottante (ne tenant pas compte de la locale utilisée). Disponible à partir de PHP 5.0.3. |
| g |
Format général. Soit P égal à la précision si différent de 0, 6 si la précision est omit ou 1 si la précision est zéro. Alors, si la conversion avec le style E aurait comme exposant X : Si P > X ≥ −4, la conversion est avec style f et précision P − (X + 1). Sinon, la conversion est avec le style e et précision P - 1. |
| G | Comme le spécificateur g mais utilise E et F. |
| o | L'argument est traité comme un entier et présenté comme un nombre octal. |
| s | L'argument est traité et présenté comme une chaîne de caractères. |
| u | L'argument est traité comme un entier et présenté comme un nombre décimal non signé. |
| x | L'argument est traité comme un entier et présenté comme un nombre hexadécimal (les lettres en minuscules). |
| X | L'argument est traité comme un entier et présenté comme un nombre hexadécimal (les lettres en majuscules). |
Le spécificateur de type c ignore l'alignement et la taille.
Le fait de tenter d'utiliser une combinaison d'une chaîne et de spécificateurs avec des jeux de caractères qui nécessitent plus d'un octet par caractères donnera un résultat inattendu.
Les variables seront contraints à un type approprié pour le spécificateur :
| Type | Spécificateurs |
|---|---|
| string | s |
| integer | d, u, c, o, x, X, b |
| double | g, G, e, E, f, F |
...
Retourne une chaîne de caractères créée suivant le format
format, ou FALSE si une erreur survient.
Exemple #1 Échange d'arguments
La chaîne de format supporte le numérotage et l'échange d'arguments.
<?php
$num = 5;
$location = 'bananier';
$format = 'Il y a %d singes dans le %s';
echo sprintf($format, $num, $location);
?>
L'exemple ci-dessus va afficher :
Il y a 5 singes dans le bananier
Mais imaginez que la chaîne de format soit créée dans un script séparé, comme une bibliothèque : cela arrive lorsqu'il faut internationaliser une application. Suivant la langue, il faudra peut-être écrire :
<?php
$format = 'Le %s a %d singes';
echo sprintf($format, $num, $location);
?>
Nous avons désormais un problème. L'ordre des arguments a été changé, et ne correspond plus à l'ordre des arguments dans le script PHP. Nous souhaitons laisser le code PHP intact, mais simplement indiquer dans la chaîne de formatage l'ordre dans lequel les arguments doivent être utilisés. La chaîne de format peut être réécrite ainsi :
<?php
$format = 'Le %2$s a %1$d singes';
echo sprintf($format, $num, $location);
?>
Un des avantages est que les paramètres fictifs peuvent être répétés sans ajouter plus d'arguments dans le code.
<?php
$format = 'Le %2$s a %1$d singes.
C\'est un beau %2$s avec %1$d singes.';
echo sprintf($format, $num, $location);
?>
Lors de l'utilisation du mécanisme de l'échange d'arguments, le spécificateur de position n$ doit survenir immédiatement après le signe de pourcentage(%), avant tout autre spécificateur, tel que dans l'exemple suivant.
Exemple #2 Spécification du caractère de remplissage
<?php
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);
?>
L'exemple ci-dessus va afficher :
......123 000000123
Exemple #3 Spécificateur de position avec d'autres spécificateurs
<?php
$format = 'The %2$s contains %1$04d monkeys';
echo sprintf($format, $num, $location);
?>
L'exemple ci-dessus va afficher :
The tree contains 0005 monkeys
Exemple #4 sprintf() : entier sans espace
<?php
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
?>
Exemple #5 sprintf() : formatage de devises
<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
echo $money;
echo "\n";
$formatted = sprintf("%01.2f", $money);
echo $formatted;
?>
L'exemple ci-dessus va afficher :
123.1 123.10
Exemple #6 sprintf() : notation scientifique
<?php
$number = 362525200;
echo sprintf("%.3e", $number);
?>
L'exemple ci-dessus va afficher :
3.625e+8