Manuel PHP
Précédent |  | Suivant

# sprintf

(PHP 3, PHP 4 )

sprintf -- Retourne une chaîne formatée.

## Description

string sprintf ( string format [, mixed args])

sprintf() retourne une chaîne, construite à partir des arguments `args`, et formatée avec `format`.

La chaîne de format est composée de 0 ou plus directives : généralement des caractères qui sont recopiés tels quels (hormis `%`), et des spécifications, chacune d'elle disposant de son propre paramètre. Cela s'applique à sprintf() et printf().

Chaque conversion consiste en un signe pourcentage (`%`), suivi d'un ou plusieurs éléments parmi ceux-ci :

1. Une option de remplissage, qui indique quel caractère sera utilisé pour le remplissage, et la taille finale de la chaîne. Le caractère de remplissage peut être un espace ou le caractère zéro (`0`).). La valeur par défaut est l'espace. Une autre valeur peut être spécifiée en la préfixant par un guillemet simple (`'`). Voir les exemples plus loin.

2. Un argument optionnel alignment spécifier qui indique que le résultat doit être justifié à droite ou à droite. Par défaut, il est justifié à gauche. Le caractère `-` signifie : justification à gauche.

3. Argument optionnel, width spécifier indique le nombre minimum de caractères que la conversion devrait retourner.

4. Argument optionnel, precision spécifier indique le nombre de chiffres utilisé pour afficher un nombre à virgule flottante. Cette option n'a d'effet que sur les nombres à virgule de type double (Une autre fonction pratique pour formater les nombres est : number_format()).

5. type specifier indique le type de données passées en argument. Les types possibles sont :

   `%` - un signe pourcentage : aucun argument nécessaire.
   `b` - l'argument est traité comme un entier, et représenté comme un nombre binaire.
   `c` - l'argument est traité comme un entier, et représenté comme un nombre ascii.
   `d` - l'argument est traité comme un entier, et représenté comme un nombre décimal.
   `u` - l'argument est traité comme un entier, et représenté comme un nombre décimal non signé.
   `f` - l'argument est traité comme un double, et représenté comme un nombre à virgule flottante.
   `o` - l'argument est traité comme un entier, et représenté comme un nombre octal.
   `s` - l'argument est traité tel quel, et représenté comme une chaîne.
   `x` - l'argument est traité comme un entier, et représenté comme un nombre hexadécimal (en minuscules).
   `X` - l'argument est traité comme un entier, et représenté comme un nombre hexadécimal (en majuscules).

A partir de PHP 4.0.6, le paramètre `format` supportera aussi la numérotation des arguments, et leur échange. Par exemple :

Exemple 1. Echange d'arguments : cas habituel
    <?php
      $format = "Il y a %d singes dans le %s";
      printf($format,$num,$location);
    ?>

Cela pourra afficher "Il y a 5 singes dans le baobab". Mais imaginons un instant que nous créons cette chaîne à partir d'un fichier séparé, car nous voulons internationaliser le message. On voudra notamment écrire librement :

Exemple 2. Echange d'arguments : cas problématique
    <?php
      $format = "Le %s contient %d singes";
      printf($format,$num,$location);
    ?>

Maintenant, on a un problème. L'ordre d'utilisation des variables dans la chaîne de formatage n'est pas celui d'appel de la fonction sprintf(). L'idéal serait de pouvoir garder l'ordre des arguments, quel que soit l'ordre des variables fournies. Il faudrait donc indiquer dans la chaîne de formatage dans quel ordre utiliser les valeurs. On pourrait écrire ceci à la place:

Exemple 3. Echange d'arguments : solution
    <?php
      $format = "Le %2&#92;$s contient %1&#92;$d singes";
      printf($format,$num,$location);
    ?>

Et vous pouvez désormais répéter les variables sans ajouter de nouvel argument. Par exemple :

Exemple 4. Echange d'arguments : répétition
    <?php
      $format = "Le %2&#92;$s contient %1&#92;$d singes.
         C&#39;est un beau %2&#92;$s, avec %1&#92;$d signes dessus.";
      printf($format,$num,$location);
    ?>

Exemple 5. Exemple avec sprintf() : complété avec des zéros
    <?php
      $isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
    ?>

Exemple 6. Exemple avec sprintf(): format monétaire
    <?php
      $money1 = 68.75;
      $money2 = 54.35;
      $money = $money1 + $money2;
    // echo $money affichera "123.1";
      $formatted = sprintf("%01.2f", $money);
    // echo $formatted affichera "123.10"
    ?>

Voir aussi printf(), sscanf(), fscanf() et number_format().

Précédent | Sommaire | Suivant
soundex | Niveau supérieur | sscanf