sprintf

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

sprintf — Restituisce una stringa formattata

Descrizione

sprintf(string $format, mixed $args = ?, mixed $... = ?): string

La funzione restituisce una stringa formattata in base al parametro format.

La stringa di formato è composta da 0 o più direttive: i caratteri ordinari (escluso il %) sono copiati direttamente nel risultato, mentre le specifiche di conversione, scaricano il proprio parametro. Queste note si applicano alle funzioni fprintf(), sprintf() e printf().

Ciascun parametro di conversione consiste nel segno percento (%), seguito da uno più dei seguenti elementi nell'ordine si ha:

Un parametro opzionale di specifica del segno che forza la presenza del segno (- oppure +) in caso di numero. Per default, si usa soltanto il segno - se il numero è negativo. Questo parametro forza i numeri positiva ad avere il segno +, ed è stato aggiunto in PHP 4.3.0.
Un parametro opzionale per la specifica del riempimento che indica quale carattere sarà utilizzato per completare la stringa risultante in modo da raggiungere la dimensione richiesta. Questo può essere uno spazio oppure uno 0 (il carattere zero). Per default si completa con spazi. Un carattere di riempimento alternativo può essere indicato anteponendo a questo l'apice singolo ('). Vedere gli esempi seguenti.
Un parametro opzionale per la specifica dell'allineamento che indica se la stringa risultante debba essere giustificata a destra o a sinistra. Per default le stringhe sono giustificate a destra; il carattere - forza la giustificazione a sinistra.
Un parametro numerico opzionale per la specifica della dimensione che indica di quanti caratteri (come minimo) debba essere lunga la stringa.
Un parametro opzionale per indicare la precisione per indicare quante cifre decimali debbano essere visualizzate per i numeri in virgola mobile. Quando si usa questo parametro in una stringa si impone come una sorta di punto di cutoff, esso imposta un limite alla lunghezza della stringa.
Una specifica di tipo che indica il tipo di dati dell'argomento. I possibili tipi sono:
- % - il carattere percento. Nessun argomento è richiesto.
- b - l'argomento è trattato come un intero e sarà presentato come numero binario.
- c - l'argomento è trattato come un intero e sarà presentato come carattere ASCII del valore corrispondente.
- d - l'argomento è trattato come un intero e sarà presentato come un numero decimale con segno.
- e - l'argomento è reso con notazione scientifica (ad esempio 1.2e+2).
- u - l'argomento è trattato come un intero e sarà presentato come un numero decimale senza segno.
- f - l'argomento è trattato come un float e sarà presentato come un numero in virgola mobile (influenzato dalle impostazioni locali).
- F - l'argomento è trattato come un numero float, e sarà presentato come un numero in virgola mobile (non influenzato dalle impostazioni locali). Disponibile da PHP 4.3.10 e PHP 5.0.3.
- o - l'argomento è trattato come un intero e sarà presentato come un numero ottale.
- s - l'argomento sarà trattato e presentato come una stringa.
- x - l'argomento sarà trattato come un intero e presentato in forma esadecimale (con le lettere in minuscolo).
- X - l'argomento è trattato come un intero e sarà presentato come un numero esadecimale (con le lettere maiuscole).

A partire dal PHP 4.0.6 la stringa di formato supporta lo scambio dei parametri. Eccone un esempio:

Example #1 Scambio dei parametri

<?php
$format = "There are %d monkeys in the %s";
printf($format, $num, $location);
?>

Questo esempio visualizza: "There are 5 monkeys in the tree". Ma supponiamo di volere creare una stringa di formato in file a parte, perché vogliamo rendere la procedura internazionale; e pertanto riscriviamo l'esempio come:

Example #2 Scambio dei parametri

<?php
$format = "The %s contains %d monkeys";
printf($format, $num, $location);
?>

Ora abbiamo un problema. L'ordine dei segnaposto nella stringa di formato non coincide con l'ordine dei parametri. Si vorrebbe potere lasciare inalterato il codice e potere indicare a quale parametro si riferisce il segnaposto. Ciò può essere fatto modificando la stringa di formato come:

Example #3 Scambio dei parametri

<?php
$format = "The %2\$s contains %1\$d monkeys";
printf($format, $num, $location);
?>

Un beneficio aggiuntivo è che si possono ripetere i segnaposto senza dovere ripetere i parametri. Ad esempio:

Example #4 Scambio di parametri

<?php
$format = "The %2\$s contains %1\$d monkeys.
           That's a nice %2\$s full of %1\$d monkeys.";
printf($format, $num, $location);
?>

Vedere anche printf(), sscanf(), fscanf(), vsprintf() e number_format().

Esempi

Example #5 Esempi di uso di printf()

<?php
$n =  43951789;
$u = -43951789;
$c = 65; // ASCII 65 is 'A'

// attenzione che i doppi %%, visualizzano il carattere '%' 
printf("%%b = '%b'\n", $n); // rappresentazione binaria
printf("%%c = '%c'\n", $c); // visualizza un carattere ASCII, coma la funzione chr()
printf("%%d = '%d'\n", $n); // rappresentazione di un intero standard
printf("%%e = '%e'\n", $n); // notazione scientifica
printf("%%u = '%u'\n", $n); // rappresentazione di un intero positivo privo di segno
printf("%%u = '%u'\n", $u); // rappresentazione di un intero negativo privo di segno
printf("%%f = '%f'\n", $n); // rappresentazine in virgola mobile
printf("%%o = '%o'\n", $n); // rappresentazione ottale
printf("%%s = '%s'\n", $n); // stringa
printf("%%x = '%x'\n", $n); // rappresentazione esadecimale (minuscolo)
printf("%%X = '%X'\n", $n); // rappresentazione esadecimale (maiuscolo)
printf("%%+d = '%+d'\n", $n); // indicazione del segno su un intero positivo
printf("%%+d = '%+d'\n", $u); // indicazione del segno su un intero negativo
?>

L'output di questo programma sarà:

%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'

Example #6 printf(): specifiche di stringa

<?php
$s = 'monkey';
$t = 'many monkeys';

printf("[%s]\n",      $s); // output standard di stringa
printf("[%10s]\n",    $s); // accostamento a destra con spazi
printf("[%-10s]\n",   $s); // accostamento a sinistra con spazi
printf("[%010s]\n",   $s); // completamento con zero funziona anche con le stringhe
printf("[%'#10s]\n",  $s); // utilizza il carattere di riempimento  '#'
printf("[%10.10s]\n", $t); // accostamento a sinistra con taglio a 10 caratteri
?>

L'output di questo programma sarà:

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

Example #7 sprintf(): interi completati con zeri

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

Example #8 sprintf(): formattazione della moneta

<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
// echo $money visualizzerà "123.1";
$formatted = sprintf("%01.2f", $money);
// echo $formatted visualizzerà "123.10"
?>

Example #9 sprintf(): notazione scientifica

<?php
$number = 362525200;

echo sprintf("%.3e", $number); // visualizza 3.63e+8
?>