int
fprintf
(
std::
FILE
*
stream,
const
char
*
format, ...
)
;
(2)
int
sprintf
(
char
*
buffer,
const
char
*
format, ...
)
;
(3)
int
snprintf
(
char
*
buffer,
std::
size_t
buf_size,
const
char
*
format, ...
)
;
(4)
(desde C++11)
Carga los datos desde las ubicaciones dadas, los convierte a equivalentes de cadena de caracteres y escribe los resultados en una variedad de destinos.
2)
Escribe los resultados a un flujo de archivo
stream
.
3)
Escribe los resultados en una cadena de caracteres
buffer
.
4)
Escribe los resultados en una cadena de caracteres
buffer
. Como máximo se escriben
buf_size
-
1
caracteres. La cadena de caracteres resultante terminará con un carácter nulo, a menos que
buf_size
sea cero. Si
buf_size
es cero, no se escribe nada y
buffer
puede ser un puntero nulo, sin embargo el valor de retorno (número de bytes que se escribirían sin incluir el terminador nulo) aún se calcula y se devuelve.
Si una llamada a
sprintf
o
snprintf
provoca que se realice una copia entre objetos que se superponen, el comportamiento es indefinido (por ejemplo,
sprintf
(
buf,
"%s text"
, buf
)
;
).
puntero a una cadena de caracteres en la que escribir
buf_size
-
hasta
buf_size
-
1
caracteres pueden escribirse, más el terminador nulo
format
-
puntero a una cadena multibyte terminada en nulo que especifica cómo interpretar los datos
...
-
argumentos que especifican los datos a imprimir. Si cualquier argumento después de las
promociones de argumentos predeterminadas
no es del tipo esperado por la especificación de conversión correspondiente (el tipo esperado es el tipo promocionado o un tipo compatible del tipo promocionado), o si hay menos argumentos de los requeridos por
format
, el comportamiento es indefinido. Si hay más argumentos de los requeridos por
format
, los argumentos excedentes se evalúan y se ignoran
La cadena de
formato
consiste en caracteres de byte ordinarios (excepto
%
), que se copian sin cambios en el flujo de salida, y especificaciones de conversión. Cada especificación de conversión tiene el siguiente formato:
carácter introductorio
%
.
(opcional)
uno o más indicadores que modifican el comportamiento de la conversión:
-
: el resultado de la conversión se justifica a la izquierda dentro del campo (por defecto se justifica a la derecha).
+
: el signo de las conversiones con signo siempre se antepone al resultado de la conversión (por defecto el resultado va precedido por el signo menos solo cuando es negativo).
space
: si el resultado de una conversión con signo no comienza con un carácter de signo, o está vacío, se antepone un espacio al resultado. Se ignora si el indicador
+
está presente.
#
:
se realiza la
forma alternativa
de la conversión. Consulte la tabla siguiente para conocer los efectos exactos, de lo contrario el comportamiento es indefinido.
0
: para conversiones de números enteros y de punto flotante, se utilizan ceros iniciales para rellenar el campo en lugar de caracteres de
space
. Para números enteros se ignora si la precisión se especifica explícitamente. Para otras conversiones, el uso de este indicador da como resultado un comportamiento indefinido. Se ignora si el indicador
-
está presente.
(opcional)
valor entero o
*
que especifica el ancho mínimo del campo. El resultado se rellena con caracteres de
espacio
(por defecto), si es necesario, a la izquierda cuando está justificado a la derecha, o a la derecha si está justificado a la izquierda. En el caso cuando se utiliza
*
, el ancho se especifica mediante un argumento adicional de tipo
int
, que aparece antes del argumento a convertir y del argumento que proporciona la precisión si se suministra uno. Si el valor del argumento es negativo, resulta con el indicador
-
especificado y ancho de campo positivo (Nota: Este es el ancho mínimo: El valor nunca se trunca.).
(opcional)
.
seguido de un número entero o
*
, o ninguno que especifique la
precisión
de la conversión. En el caso cuando se utiliza
*
, la
precisión
se especifica mediante un argumento adicional de tipo
int
, que aparece antes del argumento a convertir, pero después del argumento que suministra el ancho mínimo del campo si se suministra uno. Si el valor de este argumento es negativo, se ignora. Si no se utiliza ni un número ni
*
, la precisión se toma como cero. Consulte la tabla siguiente para conocer los efectos exactos de la
precisión
.
(opcional)
modificador de longitud
que especifica el tamaño del argumento (en combinación con el especificador de formato de conversión, especifica el tipo del argumento correspondiente).
especificador de formato de conversión.
Los siguientes especificadores de formato están disponibles:
Especificador
de Conversión
Explicación
Tipo de
Argumento Esperado
Modificador de Longitud→
hh
h
ninguno
l
ll
j
z
t
L
Solo disponible desde C++11→
Sí
Sí
Sí
Sí
Sí
%
Escribe literalmente
%
. La especificación de conversión completa debe ser
%%
.
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
c
Escribe un
carácter único
.
El argumento se convierte primero a
unsigned
char
.
Si se utiliza el modificador
l
, el argumento se convierte primero a una cadena de caracteres como si fuera mediante
%ls
con un argumento
wchar_t
[
2
]
.
N/A
N/A
int
std::wint_t
N/A
N/A
N/A
N/A
N/A
s
Escribe una
cadena de caracteres
.
El argumento debe ser un puntero al elemento inicial de un arreglo de caracteres.
Precisión
especifica el número máximo de bytes a escribir. Si
Precisión
no se especifica, escribe cada byte hasta pero sin incluir el primer terminador nulo.
Si se utiliza el especificador
l
, el argumento debe ser un puntero al elemento inicial de un arreglo de
wchar_t
, que se convierte a arreglo de caracteres como si mediante una llamada a
std::wcrtomb
con estado de conversión inicializado a cero.
N/A
N/A
char
*
wchar_t
*
N/A
N/A
N/A
N/A
N/A
d
i
Convierte un
entero con signo
a representación decimal
[-]dddd
.
Precisión
especifica el número mínimo de dígitos a mostrar. La precisión por defecto es
1
.
Si tanto el valor convertido como la precisión son
0
la conversión no produce ningún carácter.
Para el modificador
z
, el tipo de argumento esperado es la versión con signo de
std::size_t
.
Convierte un
entero sin signo
a representación octal
oooo
.
Precisión
especifica el número mínimo de dígitos a mostrar. La precisión por defecto es
1
.
Si tanto el valor convertido como la precisión son
0
, la conversión no produce ningún carácter.
En la
implementación alternativa
la precisión se incrementa si es necesario para escribir un cero inicial. En ese caso, si tanto el valor convertido como la precisión son
0
, se escribe un único
0
.
Convierte un
entero sin signo
a representación hexadecimal
hhhh
.
Para la conversión
x
se utilizan las letras
abcdef
.
Para la conversión
X
se utilizan las letras
ABCDEF
.
Precisión
especifica el número mínimo de dígitos a mostrar. La precisión por defecto es
1
.
Si tanto el valor convertido como la precisión son
0
la conversión no produce ningún carácter.
En la
implementación alternativa
se antepone
0x
o
0X
a los resultados si el valor convertido es distinto de cero.
N/A
u
Convierte un
entero sin signo
a representación decimal
dddd
.
Precisión
especifica el número mínimo de dígitos a mostrar.
La precisión por defecto es
1
.
Si tanto el valor convertido como la precisión son
0
la conversión no produce ningún carácter.
N/A
f
F
(C++11)
Convierte
números de punto flotante
a la notación decimal en el estilo
[-]ddd.ddd
.
Precisión
especifica el número exacto de dígitos que aparecerán después del carácter de punto decimal.
La precisión por defecto es
6
.
En la
implementación alternativa
el carácter de punto decimal se escribe incluso si no le siguen dígitos.
Para el estilo de conversión de infinito y no-numérico consultar las
notas
.
N/A
N/A
double
double
(C++11)
N/A
N/A
N/A
N/A
long
double
e
E
Convierte
números de punto flotante
a notación exponencial decimal.
Para el estilo de conversión
e
se utiliza
[-]d.ddd
e
±dd
.
Para el estilo de conversión
E
se utiliza
[-]d.ddd
E
±dd
.
El exponente contiene al menos dos dígitos, se utilizan más dígitos solo si es necesario.
Si el valor es
0
, el exponente también es
0
.
Precisión
especifica el número exacto de dígitos que aparecen después del carácter de punto decimal.
La precisión predeterminada es
6
.
En la
implementación alternativa
el carácter de punto decimal se escribe incluso si no le siguen dígitos.
Para la conversión de infinito y no-número consultar las
notas
.
N/A
N/A
N/A
N/A
N/A
N/A
a
A
(C++11)
Convierte
números de punto flotante
a la notación exponencial hexadecimal.
Para el estilo de conversión
a
se utiliza
[-]
0x
h.hhh
p
±d
.
Para el estilo de conversión
A
se utiliza
[-]
0X
h.hhh
P
±d
.
El primer dígito hexadecimal no es
0
si el argumento es un valor de punto flotante normalizado.
Si el valor es
0
, el exponente también es
0
.
Precisión
especifica el número exacto de dígitos que aparecen después del carácter de punto hexadecimal.
La precisión predeterminada es suficiente para la representación exacta del valor.
En la
implementación alternativa
el carácter de punto decimal se escribe incluso si no le siguen dígitos.
Para la conversión de infinito y no-número consultar las
notas
.
N/A
N/A
N/A
N/A
N/A
N/A
g
G
Convierte un número de punto flotante a notación decimal o notación exponencial decimal dependiendo del valor y la precisión.
Para el estilo de conversión g se realizará la conversión con estilo e o f.
Para el estilo de conversión G se realizará la conversión con estilo E o
f
(until C++11)
F
(since C++11)
.
Sea P igual a la precisión si es distinta de cero,
6
si la precisión no está especificada, o
1
si la precisión es
0
.
Entonces, si una conversión con estilo E tendría un exponente X:
Si P > X ≥ −4, la conversión es con estilo f
o F
(since C++11)
y precisión P − 1 − X.
En caso contrario, la conversión es con estilo e o E y precisión P − 1.
A menos que se solicite representación alternativa, se eliminan los ceros finales y también se elimina el punto decimal si no queda parte fraccionaria.
Para la conversión de infinito y no-número, consulte las notas.
N/A
N/A
N/A
N/A
N/A
N/A
n
Devuelve el
número de caracteres escritos
hasta ahora por esta llamada a la función.
El resultado se
escribe
en el valor apuntado por el argumento.
La especificación no puede contener ningún
flag
,
field width
, o
precision
.
Para el modificador
z
, el tipo de argumento esperado es
S
*
, donde
S
es la versión con signo de
std::
size_t
.
Escribe una secuencia de caracteres definida por la implementación que define un
pointer
.
N/A
N/A
void
*
N/A
N/A
N/A
N/A
N/A
N/A
Notas
Las funciones de conversión de punto flotante convierten infinito a
inf
o
infinity
. Cuál se utiliza está definido por la implementación.
No-es-un-número se convierte a
nan
o
nan(
char_sequence
)
. Cuál se utiliza está definido por la implementación.
Las conversiones
F
,
E
,
G
,
A
generan
INF
,
INFINITY
,
NAN
en su lugar.
El especificador de conversión utilizado para imprimir
char
,
unsigned
char
,
signed
char
,
short
, y
unsigned
short
espera tipos promocionados de
promociones de argumentos por defecto
, pero antes de imprimir su valor será convertido a
char
,
unsigned
char
,
signed
char
,
short
, y
unsigned
short
. Es seguro pasar valores de estos tipos debido a la promoción que tiene lugar cuando se llama a una función variádica.
Las especificaciones de conversión correctas para los tipos de caracteres de ancho fijo (
std::int8_t
, etc) están definidas en el encabezado
<cinttypes>
(aunque
PRIdMAX
,
PRIuMAX
, etc son sinónimos de
%jd
,
%ju
, etc).
El especificador de conversión de escritura en memoria
%n
es un objetivo común de exploits de seguridad donde las cadenas de formato dependen de entrada del usuario.
Hay un
punto de secuencia
después de la acción de cada especificador de conversión; esto permite almacenar múltiples resultados
%n
en la misma variable o, como caso extremo, imprimir una cadena modificada por un
%n
anterior dentro de la misma llamada.
Si una especificación de conversión es inválida, el comportamiento es indefinido.
Valor de retorno
1,2)
Número de caracteres escritos si tiene éxito o un valor negativo si ocurrió un error.
3)
Número de caracteres escritos si es exitoso (sin incluir el carácter nulo terminador) o un valor negativo si ocurrió un error.
4)
Número de caracteres que habrían sido escritos para un búfer suficientemente grande si tuvo éxito (sin incluir el carácter nulo terminador), o un valor negativo si ocurrió un error. Por lo tanto, la salida (terminada en nulo) ha sido completamente escrita si y solo si el valor retornado es no negativo y menor que
buf_size
.
Notas
POSIX especifica que errno se establece en caso de error. También especifica especificaciones de conversión adicionales, especialmente el soporte para reordenamiento de argumentos (n$ inmediatamente después de % indica el argumento n-ésimo).
Llamar a std::snprintf con cero buf_size y puntero nulo para buffer es útil (cuando la sobrecarga de la doble llamada es aceptable) para determinar el tamaño de búfer necesario para contener la salida:
autofmt="sqrt(2) = %f";intsz=std::snprintf(nullptr,0,fmt,std::sqrt(2));std::vector<char>buf(sz+1);// note +1 for null terminatorstd::sprintf(buf.data(),fmt,std::sqrt(2));// certain to fit