Retourne une chaîne formatée

# sprintf

(PHP 4, PHP 5, PHP 7)

sprintf — Retourne une chaîne formatée

### Description

sprintf ( string `$format` [, mixed `$...` ] ) : string

Retourne une chaîne formatée, avec le format `format`, en utilisant les arguments `args`.

### Liste de paramètres

`format`

  La chaîne de format est composée de zéro, une ou plusieurs directives : les caractères ordinaires (à l'exception de %) qui sont copiés directement dans le résultat et des spécifications de conversion, qui exploitent chacune un des arguments passés après la chaîne de format. Ces formats s'appliquent à sprintf() et printf().

  Chaque spécification de conversion est constituée d'un signe de pourcentage (%), suivi d'un ou plusieurs des éléments suivants, dans cet ordre :

  1. Le signe optionnel ne force pas le nombre à être positif/négatif mais force à utiliser le signe - ou + sur un nombre. Par défaut, seul le signe - est utilisé sur un nombre s'il est négatif. Ce spécificateur force également les nombres positifs à avoir un signe + d'attaché.
  2. Un remplisseur optionnel qui indique quel caractère sera utilisé pour compléter le résultat jusqu'à la longueur requise. Ce peut être le caractère d'espace, ou le caractère 0. Par défaut, le remplissage se fait avec des espaces. Un autre caractère de remplissage peut être spécifié en le préfixant avec un guillemet simple (') : voir les exemples ci-dessous.
  3. Un spécificateur d'alignement qui indique si le résultat doit être aligné à gauche ou à droite. Par défaut, le résultat est aligné à droite. Le caractère - fera que le résultat sera justifié à gauche.
  4. Un nombre optionnel, spécificateur de taille indique le nombre minimum de caractères que cette conversion doit fournir en résultat.
  5. Un spécificateur de précision de la forme d'un point ("."), suivi par un nombre de décimales qui doivent être affichées pour les nombres décimaux. Lorsque vous utilisez ce spécificateur dans une chaîne, il agit comme un point de coupure, définissant une limite maximale de caractères de la chaîne. Additionnellement, le caractère utilisé pour remplir un nombre peut optionnellement être spécifié entre le point et le chiffre.

  6. Un spécificateur de type qui indique le type avec lequel l'argument sera traité. Plusieurs types possibles :

     - % : 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 (en base 10) 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 (au moins un).
     - E : comme %e mais utilise des lettres en majuscule (i.e. 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 depuis PHP 5.0.3.
     - g : le plus court entre %e et %f.
     - G : le plus court entre %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 entier (en base 10) 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).

  Les variables seront contraints à un type approprié pour le spécificateur :

  Gestion des types
  Type | Spécificateurs
  --- | ---
  string | s
  integer | d, u, c, o, x, X, b
  double | g, G, e, E, f, F

  Avertissement

  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.

  La chaîne de format supporte le numérotage et l'échange d'arguments. Par exemple :

  Exemple #1 Échange d'arguments

  `<?php
  $num = 5;
  $location = 'bananier';
  $format = 'Il y a %d singes dans le %s';
  echo sprintf($format, $num, $location);
  ?>`
  Ainsi, cet exemple affichera : "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 :

  Exemple #2 Échange d'arguments (2)

  `<?php
  $format = 'Le %s a %d singes';
  echo sprintf($format, $num, $location);
  ?>`
  Ici, nous voyons bien le 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 :

  Exemple #3 Échange d'arguments (3)

  `<?php
  $format = 'Le %2$s a %1$d singes';
  echo sprintf($format, $num, $location);
  ?>`
  Un des avantages est que vous pouvez désormais exploiter plusieurs fois les arguments sans les répéter. Ainsi :

  Exemple #4 Échange d'arguments (4)

  `<?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 #5 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 #6 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

  > Note:

  > Tenter d'utiliser une position supérieure à `PHP_INT_MAX` fera que la fonction sprintf() génèrera une alerte.

  Avertissement

  Le spécificateur c ignore l'alignement et la taille.

`...`

### Valeurs de retour

Retourne une chaîne de caractères créée suivant le format `format`, ou `FALSE` si une erreur survient.

### Exemples

Exemple #7 printf() : divers exemples

`<?php
$n = 43951789;
$u = -43951789;
$c = 65; // ASCII 65 is 'A'
// notez le double %%, cela affiche un caractère '%' littéral
printf("%%b = '%b'\n", $n); // représentation binaire
printf("%%c = '%c'\n", $c); // affiche le caractère ascii, comme la fonction chr()
printf("%%d = '%d'\n", $n); // représentation standard d'un entier
printf("%%e = '%e'\n", $n); // notation scientifique
printf("%%u = '%u'\n", $n); // représentation entière non signée d'un entier positif
printf("%%u = '%u'\n", $u); // représentation entière non signée d'un entier négatif
printf("%%f = '%f'\n", $n); // représentation en virgule flottante
printf("%%o = '%o'\n", $n); // représentation octale
printf("%%s = '%s'\n", $n); // représentation chaîne de caractères
printf("%%x = '%x'\n", $n); // représentation hexadécimal (minuscule)
printf("%%X = '%X'\n", $n); // représentation hexadécimal (majuscule)
printf("%%+d = '%+d'\n", $n); // indication du signe pour un entier positif
printf("%%+d = '%+d'\n", $u); // indication du signe pour un entier négatif
?>`

L'exemple ci-dessus va afficher :

    %b = '10100111101010011010101101'
    %c = 'A'
    %d = '43951789'
    %e = '4.39518e+7'
    %u = '43951789'
    %u = '4251015507'
    %f = '43951789.000000'
    %o = '247523255'
    %s = '43951789'
    %x = '29ea6ad'
    %X = '29EA6AD'
    %+d = '+43951789'
    %+d = '-43951789'

Exemple #8 printf() : spécificateurs chaînes de caractères

`<?php
$s = 'monkey';
$t = 'many monkeys';
printf("[%s]\n", $s); // affichage d'une chaîne standard
printf("[%10s]\n", $s); // justification à droite avec des espaces
printf("[%-10s]\n", $s); // justification à gauche avec des espaces
printf("[%010s]\n", $s); // l'espacement nul fonctionne aussi sur les chaînes
printf("[%'#10s]\n", $s); // utilisation du caractère personnalisé de séparation '#'
printf("[%10.10s]\n", $t); // justification à gauche mais avec une coupure à 10 caractères
?>`

L'exemple ci-dessus va afficher :

    [monkey]
    [    monkey]
    [monkey    ]
    [0000monkey]
    [####monkey]
    [many monke]

Exemple #9 sprintf() : entier sans espace

`<?php
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
?>`

Exemple #10 sprintf() : formatage de devises

`<?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"
?>`

Exemple #11 sprintf(): notation scientifique

`<?php
$number = 362525200;
echo sprintf("%.3e", $number); // affiche 3.625e+8
?>`

### Voir aussi

- printf() - Affiche une chaîne de caractères formatée
- sscanf() - Analyse une chaîne à l'aide d'un format
- fscanf() - Analyse un fichier en fonction d'un format
- vsprintf() - Retourne une chaîne formatée
- number_format() - Formate un nombre pour l'affichage
- date() - Formate une date/heure locale