vsprintf

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

vsprintfDevuelve una string formateada

Descripción

vsprintf(string $format, array $values): string

vsprintf() funciona como sprintf(), pero acepta un array como argumento, en lugar de una lista de argumentos.

Parámetros

format

La cadena de formato está compuesta por cero o más directivas: caracteres ordinarios (excepto %) que se copian directamente al resultado y especificaciones de conversión, cada una con su propio parámetro.

Una especificación de conversión que sigue este prototipo: %[argnum$][flags][width][.precision]specifier.

Argnum

Un entero seguido de un signo dólar $, para especificar qué número de argumento tratar en la conversión.

Banderas

Bandera Descripción
- Justifica el texto a la izquierda dado el ancho del campo; la justificación a la derecha es el comportamiento por omisión.
+ Prefija los números positivos con un signo más +; por omisión solo los números negativos son prefijados con un signo negativo.
(espacio) Rellena el resultado con espacios. Esto es por omisión.
0 Rellena solo los números a la izquierda con ceros. Con el especificador s esto también puede rellenar a la derecha con ceros.
'(char) Rellena el resultado con el carácter (char).

Ancho

Sea un entero indicando el número de caracteres (mínimo) que esta conversión debe producir, o *. Si * es utilizado, entonces el ancho es proporcionado como un valor entero adicional precediendo al que se formatea por el especificador.

Precisión

Un punto . seguido opcionalmente sea de un entero, o de *, cuya significación depende del especificador:

  • Para los especificadores e, E, f y F: esto es el número de dígitos a mostrar después de la coma (por omisión, esto es 6).
  • Para los especificadores g, G, h y H: esto es el número máximo de dígitos significativos a mostrar.
  • Para el especificador s: actúa como un punto de corte, definiendo un límite máximo de caracteres de la cadena.

Nota: Si el punto es especificado sin un valor explícito para la precisión, 0 es asumido. Si * es utilizado, la precisión es proporcionada como un valor entero adicional precediendo al que se formatea por el especificador.

Especificadores
Especificador Descripción
% Un carácter de porcentaje literal. No se necesita ningún argumento.
b El argumento es tratado como un entero y presentado como un número binario.
c El argumento es tratado como un entero y presentado como el carácter de código ASCII correspondiente.
d El argumento es tratado como un entero y presentado como un número entero decimal (firmado).
e El argumento es tratado como una notación científica (ej. 1.2e+2).
E Como el especificador e pero utiliza una letra mayúscula (por ejemplo 1.2E+2).
f El argumento es tratado como un número de coma flotante (tipo número decimal) y presentado como un número de coma flotante (teniendo en cuenta la configuración local).
F El argumento es tratado como un número de coma flotante (tipo número decimal) y presentado como un número de coma flotante (sin tener en cuenta la configuración local).
g

Formato general.

Sea P igual a la precisión si diferente de 0, 6 si la precisión es omitida o 1 si la precisión es cero. Entonces, si la conversión con el estilo E tuviera como exponente X:

Si P > X ≥ −4, la conversión es con estilo f y precisión P − (X + 1). De lo contrario, la conversión es con el estilo e y precisión P - 1.

G Como el especificador g pero utiliza E y f.
h Como el especificador g pero utiliza F. Disponible a partir de PHP 8.0.0.
H Como el especificador g pero utiliza E y F. Disponible a partir de PHP 8.0.0.
o El argumento es tratado como un entero y presentado como un número octal.
s El argumento es tratado y presentado como una cadena de caracteres.
u El argumento es tratado como un entero y presentado como un número decimal no firmado.
x El argumento es tratado como un entero y presentado como un número hexadecimal (las letras en minúsculas).
X El argumento es tratado como un entero y presentado como un número hexadecimal (las letras en mayúsculas).

Advertencia

El especificador de tipo c ignora el alineamiento y el tamaño.

Advertencia

Intentar utilizar una combinación de una cadena y especificadores con juegos de caracteres que necesitan más de un octeto por carácter dará un resultado inesperado.

Las variables serán forzadas a un tipo apropiado para el especificador:

Manejo de tipos
Tipo Especificadores
string s
int d, u, c, o, x, X, b
float e, E, f, F, g, G, h, H

values

Valores devueltos

Devuelve una string formateada a partir del array de valores values, y utilizando el formato format.

Errores/Excepciones

As of PHP 8.0.0, a ValueError is thrown if the number of arguments is zero. Prior to PHP 8.0.0, a E_WARNING was emitted instead.

As of PHP 8.0.0, a ValueError is thrown if [width] is less than zero or bigger than PHP_INT_MAX. Prior to PHP 8.0.0, a E_WARNING was emitted instead.

As of PHP 8.0.0, a ValueError is thrown if [precision] is less than zero or bigger than PHP_INT_MAX. Prior to PHP 8.0.0, a E_WARNING was emitted instead.

As of PHP 8.0.0, a ValueError is thrown when less arguments are given than required. Prior to PHP 8.0.0, false was returned and a E_WARNING emitted instead.

Historial de cambios

Versión Descripción
8.0.0 Esta función ya no devuelve false en caso de fallo.
8.0.0 Lanza una ValueError si el número de argumentos es cero; anteriormente, esta función emitía un E_WARNING.
8.0.0 Lanza una ValueError si [width] es inferior a cero o superior a PHP_INT_MAX; anteriormente, esta función emitía un E_WARNING.
8.0.0 Lanza una ValueError si [precision] es inferior a cero o superior a PHP_INT_MAX; anteriormente, esta función emitía un E_WARNING.
8.0.0 Lanza una ArgumentCountError cuando se proporcionan menos argumentos de los requeridos; anteriormente, esta función emitía un E_WARNING.

Ejemplos

Ejemplo #1 Ejemplo con vsprintf(): enteros con ceros iniciales

<?php
print vsprintf("%04d-%02d-%02d", explode('-', '1988-8-1'));
?>

El ejemplo anterior mostrará :

1988-08-01

Ver también

  • printf() - Muestra una string formateada
  • sprintf() - Devuelve una string formateada
  • fprintf() - Escribe una cadena formateada en un flujo
  • vprintf() - Muestra una string formateada
  • vfprintf() - Escribe una cadena formateada en un flujo
  • sscanf() - Analiza una cadena utilizando un formato
  • fscanf() - Analiza un archivo según un formato
  • number_format() - Formatea un número para su visualización
  • date() - Da formato a una marca de tiempo de Unix (Unix timestamp)