sprintf

(PHP 4, PHP 5, PHP 7)

sprintf — Devuelve un string formateado

Descripción

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

Devuelve un string producido según el string de formateo dado por format.

Parámetros

format

El string de formateo está compuesto de cero o más directivas: caracteres ordinarios (excluyendo %) que son copiados directamente al resultado, y especificaciones de conversión, donde cada una de las cuales da lugar a extraer su propio parámetro. Esto se aplica tanto para sprintf() como para printf().

Cada especificación de conversión consiste en un signo de porcentaje (%), seguido por uno o más de estos elementos, en orden:

  1. Un especificador de signo opcional que fuerza a usar un signo (- o +) en un número. Por defecto, sólo el signo - se utiliza en un número si es negativo. Esta especificación fuerza números positivos para que también tengan adjunto el signo + (agregado en PHP 4.3.0).
  2. Un especificador de relleno opcional que indica qué carácter se utiliza para rellenar el resultado hasta el tamaño justo del string. Este puede ser un carácter de espacio o un 0 (el carácter cero). El valor por defecto es rellenar con espacios. Un carácter de relleno alternativo se puede especificar prefijándolo con una comilla simple ('). Ver los ejemplos más adelante.
  3. Un especificador de alineación opcional que indica si el resultado debe ser alineado a la izquierda o a la derecha. El valor por defecto es justificado a la derecha, un carácter - lo justificará a la izquierda.
  4. Un número opcional, un especificador de ancho que indica de cuántos caracteres (mínimo) resultará esta conversión.
  5. Un especificador de precisión opcional en la forma de un punto (.) seguido de un string opcional de dígitos decimales que indica cuántos dígitos decimales deben mostrarse para los números de punto flotante. Cuando se utiliza este especificador con un string, actúa como un punto de corte, estableciendo un límite máximo de caracteres al string. Además, el carácter para empleado cuando se rellena un número podría especificarse opcionalmente entre el punto y el dígito.

  6. Un especificador de tipo que indica con qué tipo deben ser tratados los datos del argumento. Los tipos posibles son:

    • % - un carácter de porcentaje literal. No se requiere argumento.
    • b - el argumento es tratado como un valor de tipo integer y presentado como un número binario.
    • c - el argumento es tratado como un valor de tipo integer y presentado como el carácter con ese valor ASCII.
    • d - el argumento es tratado como un valor de tipo integer y presentado como un número decimal (con signo).
    • e - el argumento es tratado con notación científica (e.g. 1.2e+2). El especificador de precisión indica el número de dígitos después del punto decimal a partir de PHP 5.2.1. En versiones anteriores, se tomó como el número de dígitos significativos (menos uno).
    • E - como %e pero utiliza la letra mayúscula (e.g. 1.2E+2).
    • f - el argumento es tratado como un valor de tipo float y presentado como un número de punto flotante (considerando la configuración regional).
    • F - el argumento es tratado como un valor de tipo float y presentado como un número de punto flotante (no considerando la configuración regional). Disponible desde PHP 4.3.10 y PHP 5.0.3.
    • g - lo mismo que %e y %f.
    • G - lo mismo que %E y %f.
    • o - el argumento es tratado como un valor de tipo integer y presentado como un número octal.
    • s - el argumento es tratado y presentado como un string.
    • u - el argumento es tratado como un valor de tipo integer y presentado como un número decimal sin signo.
    • x - el argumento es tratado como un valor de tipo integer y presentado como un número hexadecimal (con las letras en minúsculas).
    • X - el argumento es tratado como un valor de tipo integer y presentado como un número hexadecimal (con las letras en mayúsculas).

Las variables serán forzadas por el especificador a un tipo adecuado:

Manejo de tipos
Tipo Especificador
string s
integer d, u, c, o, x, X, b
double g, G, e, E, f, F

Advertencia

Intentar usar una combinación de especificadores de string y ancho con conjuntos de caracteres que requieran más de un byte por carácter podría tener resultados inesperados.

El string de formato soporta la numeración/intercambio de argumentos. Aquí está un ejemplo:

Ejemplo #1 Intercambio de argumentos

<?php
$num = 5;
$ubicación = 'árbol';

$formato = 'Hay %d monos en el %s';
echo sprintf($formato, $num, $ubicación);
?>
Esto producirá " Hay 5 monos en el árbol". Pero imaginemos que estamos creando un string de formato en un fichero aparte, generalmente por que nos gustaría internacionalizarlo, reescribiéndolo así:

Ejemplo #2 Intercambio de argumentos

<?php
$formato = 'El %s contiene %d monos';
echo sprintf($formato, $num, $ubicación);
?>
Ahora tenemos un problema. El orden de los marcadores de posición en el string de formato no coincide con el orden de los argumentos en el código. Nos gustaría dejar el código tal cual y simplemente indicar en el string de formato a cuáles argumentos de los marcadores de posición se refieren. Tendríamos que escribir el string de formato de esta forma:

Ejemplo #3 Intercambio de argumentos

<?php
$formato = 'El %2$s contiene %1$d monos';
echo sprintf($formato, $num, $ubicación);
?>
Un beneficio adicional es que se pueden repetir los marcadores de posición sin agregar más argumentos en el código. Por ejemplo:

Ejemplo #4 Intercambio de argumentos

<?php
$formato = 'El %2$s contiene %1$d monos.
            Es un bonito %2$s con %1$d monos.';
echo sprintf($formato, $num, $ubicación);
?>
Cuando se utiliza el intercambio de argumentos, el especificador de posición n$ debe ir inmediatamente después del signo de porcentaje (%), antes de cualquier otro especificador, tal como se muestra en el ejemplo siguiente.

Ejemplo #5 Especificar un carácter de relleno

<?php
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);
?>

El resultado del ejemplo sería:

......123
000000123

Ejemplo #6 Especificador de posición con otros especificadores

<?php
$formato = 'El %2$s contiene %1$04d monos';
echo sprintf($formato, $num, $ubicación);
?>

El resultado del ejemplo sería:

 El árbol contiene 0005 monos

Nota:

Tratar de utilizar marcadores de posición mayores que PHP_INT_MAX provocará que sprintf() genere mensajes de advertencia.

Advertencia

El especificador de tipo c ignora el relleno y el ancho

args

...

Valores devueltos

Devuelve un string producido de acuerdo con el string de formato format.

Ejemplos

Ejemplo #7 printf(): ejemplos varios

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

// observar el doble %%, esto muestra un carácter '%' literal
printf("%%b = '%b'\n", $n); // representación binaria
printf("%%c = '%c'\n", $c); // muestra el carácter ascii, igual que la función chr()
printf("%%d = '%d'\n", $n); // representación estándar de un entero
printf("%%e = '%e'\n", $n); // notación científica
printf("%%u = '%u'\n", $n); // representación sin signo de un entero positivo
printf("%%u = '%u'\n", $u); // representación sin signo de un entero negativo
printf("%%f = '%f'\n", $n); // representación de punto flotante
printf("%%o = '%o'\n", $n); // representación octal
printf("%%s = '%s'\n", $n); // representación en una cadena
printf("%%x = '%x'\n", $n); // representación hexadecimal (minúsculas)
printf("%%X = '%X'\n", $n); // representación hexadecimal (mayúsculas)

printf("%%+d = '%+d'\n", $n); // especificador de signo sobre un entero positivo
printf("%%+d = '%+d'\n", $u); // especificador de signo sobre un entero negativo
?>

El resultado del ejemplo sería:

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

Ejemplo #8 printf(): especificadores de string

<?php
$s = 'mono';
$t = 'muchos monos';

printf("[%s]\n",      $s); // salida estándar de string 
printf("[%10s]\n",    $s); // justificación a la derecha con espacios
printf("[%-10s]\n",   $s); // justificación a la izquierda con espacios
printf("[%010s]\n",   $s); // rellenado con ceros también funciona con strings
printf("[%'#10s]\n",  $s); // utiliza el carácter de relleno personalizado '#'
printf("[%10.10s]\n", $t); // justificación a la izquierda pero con un corte a los 10 caracteres
?>

El resultado del ejemplo sería:

[mono]
[      mono]
[mono      ]
[000000mono]
[######mono]
[muchos mon]

Ejemplo #9 sprintf(): valores de tipo integer rellenados con ceros

<?php
$fecha_iso = sprintf("%04d-%02d-%02d", $año, $mes, $día);
?>

Ejemplo #10 sprintf(): formato de moneda

<?php
$dinero1 = 68.75;
$dinero2 = 54.35;
$dinero = $dinero1 + $dinero2;
// echo $dinero producirá "123.1";
$formateado = sprintf("%01.2f", $dinero);
// echo $formateado producirá "123.10"
?>

Ejemplo #11 sprintf(): notación científica

<?php
$número = 362525200;

echo sprintf("%.3e", $número); // produce 3.625e+8
?>

Ver también

  • printf() - Imprimir una cadena con formato
  • sscanf() - Interpreta un string de entrada de acuerdo con un formato
  • fscanf() - Analiza la entrada desde un archivo de acuerdo a un formato
  • vsprintf() - Devuelve una cadena con formato
  • number_format() - Formatear un número con los millares agrupados
  • date() - Dar formato a la fecha/hora local