Retourne une chaîne formatée

# sprintf

(PHP 4, PHP 5, PHP 7, PHP 8)

sprintf — Retourne une chaîne formatée

### Description

function sprintf(string `$format`, mixed `...$values`): string

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

### Liste de paramètres

`format`
  La 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 : `%[argnum$][flags][width][.precision]specifier`.

  ##### Argnum

  Un entier suivit d'un signe dollar `$`, pour spécifier quel numéro d'argument à traiter dans la conversion.

  ##### Drapeaux

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

  ##### Largeur

  Soit un entier indiquant le nombre de caractères (minimum) que cette conversion doit produire, soit `*`. Si `*` est utilisé, alors la largeur est fournie en tant que valeur entière supplémentaire précédant celle formatée par le spécificateur.

  ##### Precision

  Un point `.` suivi optionnellement soit d'un entier, soit de `*`, dont la signification dépend du spécificateur :

  - Pour les spécificateurs `e`, `E`, `f` et `F` : ceci est le nombre de chiffres à afficher après la virgule (par défaut, ceci est 6).
  - Pour les spécificateurs `g`, `G`, `h` et `H` : ceci est le nombre maximal de chiffres significatifs à afficher. digits to be printed.
  - Pour le spécificateur `s` : il agit comme un point de coupure, définissant une limite maximale de caractères de la chaîne.

  > Note: Si le point est spécifié sans une valeur explicite pour la précision, 0 est assumé. Si `*` est utilisé, la précision est fournie en tant que valeur entière supplémentaire précédant celle formatée par le spécificateur.

  Spécificateurs
  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`).
  `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 nombre décimal) 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 nombre décimal) et présenté comme un nombre à virgule flottante (ne tenant pas compte de la locale utilisée).
  `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`.
  `h` | Comme le spécificateur `g` mais utilise `F`. Disponible à partir de PHP 8.0.0.
  `H` | Comme le spécificateur `g` mais utilise `E` et `F`. Disponible à partir de PHP 8.0.0.
  `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).

  Avertissement

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

  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.

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

  Gestion des types
  Type | Spécificateurs
  --- | ---
  string | `s`
  int | `d`, `u`, `c`, `o`, `x`, `X`, `b`
  float | `e`, `E`, `f`, `F`, `g`, `G`, `h`, `H`

`values`

### Valeurs de retour

Retourne une chaîne de caractères créée suivant le format `format`.

### Erreurs / Exceptions

À partir de PHP 8.0.0, une ValueError est lancée si le nombre d'arguments est nul. Antérieur à PHP 8.0.0, un `E_WARNING` était émis à la place.

À partir de PHP 8.0.0, une ValueError est lancée si `[width]` est inférieur à zéro ou supérieur à `PHP_INT_MAX`. Antérieur à PHP 8.0.0, un `E_WARNING` était émis à la place.

À partir de PHP 8.0.0, une ValueError est lancée si `[precision]` est inférieur à zéro ou supérieur à `PHP_INT_MAX`. Antérieur à PHP 8.0.0, un `E_WARNING` était émis à la place.

À partir de PHP 8.0.0, une ArgumentCountError est lancée lorsque moins d'arguments sont donnés que requis. Antérieur à PHP 8.0.0, `false` était retourné et un `E_WARNING` était émis à la place.

### Historique

Version | Description
--- | ---
8.0.0 | Cette fonction ne renvoie plus `false` en cas d'échec.
8.0.0 | Lance une ValueError si le nombre d'arguments est zéro ; auparavant, cette fonction émettait un `E_WARNING`.
8.0.0 | Lance une ValueError si `[width]` est inférieur à zéro ou supérieur à `PHP_INT_MAX` ; auparavant, cette fonction émettait un `E_WARNING`.
8.0.0 | Lance une ValueError si `[precision]` est inférieur à zéro ou supérieur à `PHP_INT_MAX` ; auparavant, cette fonction émettait un `E_WARNING`.
8.0.0 | Lance une ArgumentCountError lorsque moins d'arguments sont donnés que requis ; auparavant, cette fonction émettait un `E_WARNING`.

### Exemples

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 :

Exemple #2 Mauvais ordre des arguments

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

    <?php
    $num = 5;
    $location = 'tree';
    $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 :

Exemple #3 Utilisation de l'espace réservé d'ordre

    <?php
    $num = 5;
    $location = 'tree';

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

Exemple #4 Répétition de l'espace réservé

    <?php
    $num = 5;
    $location = 'tree';

    $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
    $num = 5;
    $location = 'tree';

    $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 #7 sprintf() : entier sans espace

    <?php
    $year = 2005;
    $month = 5;
    $day = 6;

    $isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
    echo $isodate, PHP_EOL;
    ?>

Exemple #8 sprintf() : formatage de devises

    <?php
    $money1 = 68.75;
    $money2 = 54.35;
    $money = $money1 + $money2;
    echo $money, PHP_EOL;

    $formatted = sprintf("%01.2f", $money);
    echo $formatted, PHP_EOL;
    ?>

L'exemple ci-dessus va afficher :

    123.1
    123.10

Exemple #9 sprintf() : notation scientifique

    <?php
    $number = 362525200;

    echo sprintf("%.3e", $number), PHP_EOL;
    ?>

L'exemple ci-dessus va afficher :

    3.625e+8

### Voir aussi

- printf() - Affiche une chaîne de caractères formatée
- fprintf() - Écrit une chaîne formatée dans un flux
- vprintf() - Affiche une chaîne formatée
- vsprintf() - Retourne une chaîne formatée
- vfprintf() - Écrit une chaîne formatée dans un flux
- sscanf() - Analyse une chaîne à l'aide d'un format
- fscanf() - Analyse un fichier en fonction d'un format
- number_format() - Formate un nombre pour l'affichage
- date() - Formate un horodatage Unix

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open