puntero a una cadena de caracteres terminada en nulo desde la que leer
format
-
puntero a una cadena de caracteres terminada en nulo que especifica cómo leer la entrada
...
-
argumentos receptores
La cadena format consta de
caracteres multibyte que no son espacios en blanco excepto %: cada uno de estos caracteres en la cadena de formato consume exactamente un carácter idéntico del flujo de entrada, o hace que la función falle si el siguiente carácter en el flujo no es igual.
caracteres de espacio en blanco: cualquier carácter de espacio en blanco individual en la cadena de formato consume todos los caracteres de espacio en blanco consecutivos disponibles de la entrada (determinado como si se llamara a std::isspace en un bucle). Nótese que no hay diferencia entre "\n", " ", "\t\t" u otros espacios en blanco en la cadena de formato.
especificaciones de conversión. Cada especificación de conversión tiene el siguiente formato:
carácter introductorio %.
(opcional) carácter de supresión de asignación *. Si esta opción está presente, la función no asigna el resultado de la conversión a ningún argumento receptor.
(opcional) número entero (mayor que cero) que especifica el ancho máximo de campo, es decir, el número máximo de caracteres que la función puede consumir al realizar la conversión especificada por la especificación de conversión actual. Nótese que %s y %[ pueden provocar desbordamiento de búfer si no se proporciona el ancho.
(opcional)modificador de longitud que especifica el tamaño del argumento receptor, es decir, el tipo de destino real. Esto afecta la precisión de la conversión y las reglas de desbordamiento. El tipo de destino predeterminado es diferente para cada tipo de conversión (ver la tabla a continuación).
especificador de formato de conversión.
Los siguientes especificadores de formato están disponibles:
Conversión especificador
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í
%
Coincide literalmente con %.
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
c
Coincide con un carácter o una secuencia de caracteres.
Si se utiliza un especificador de ancho, coincide exactamente con ancho caracteres (el argumento debe ser un puntero a un array con suficiente espacio).
A diferencia de %s y %[, no añade el carácter nulo al array.
N/A
N/A
char*
wchar_t*
N/A
N/A
N/A
N/A
N/A
s
Coincide con una secuencia de caracteres que no son espacios en blanco (una cadena).
Si se usa un especificador de ancho, coincide hasta ancho o hasta el primer carácter de espacio en blanco, lo que ocurra primero.
Siempre almacena un carácter nulo además de los caracteres coincidentes (por lo que el array de argumentos debe tener espacio para al menos ancho+1 caracteres).
[conjunto ]
Coincide con una secuencia no vacía de caracteres del conjunto de caracteres.
Si el primer carácter del conjunto es ^, entonces se emparejan todos los caracteres que no están en el conjunto.
Si el conjunto comienza con ] o ^] entonces el carácter ] también se incluye en el conjunto.
Está definido por la implementación si el carácter - en una posición no inicial en el conjunto de exploración puede indicar un rango, como en [0-9].
Si se usa el especificador de ancho, solo coincide hasta ancho.
Siempre almacena un carácter nulo además de los caracteres coincidentes (por lo que el array de argumentos debe tener espacio para al menos ancho+1 caracteres).
d
Coincide con un entero decimal.
El formato del número es el mismo que espera std::strtol con el valor 10 para el argumento base.
signedchar* o unsignedchar*
signedshort* o unsignedshort*
signedint* o unsignedint*
signedlong* o unsignedlong*
signedlonglong* o unsignedlonglong*
std::intmax_t* o std::uintmax_t*
std::size_t*
std::ptrdiff_t*
N/A
b(C++26)
Coincide con un entero binario sin signo.
El formato del número es el mismo que espera std::strtoul con el valor 2 para el argumento base.
i
Coincide con un entero.
El formato del número es el mismo que espera std::strtol con el valor 0 para el argumento base (la base se determina por los primeros caracteres analizados).
u
Coincide con un entero decimal sin signo.
El formato del número es el mismo que espera std::strtoul con el valor 10 para el argumento base.
o
Coincide con un entero octal sin signo.
El formato del número es el mismo que espera std::strtoul con el valor 8 para el argumento base.
x X
Coincide con un entero hexadecimal sin signo.
El formato del número es el mismo que espera std::strtoul con el valor 16 para el argumento base.
n
Devuelve el número de caracteres leídos hasta ahora.
No se consume ninguna entrada. No incrementa el contador de asignaciones.
Si el especificador tiene un operador de supresión de asignación definido, el comportamiento es indefinido.
a(C++11) A(C++11) e E f F(C++11) g G
Coincide con un número de punto flotante.
El formato del número es el mismo que espera std::strtof.
N/A
N/A
float*
double*
N/A
N/A
N/A
N/A
longdouble*
p
Coincide con una secuencia de caracteres definida por la implementación que define un puntero.
printfLas funciones de la familia %p deberían producir la misma secuencia usando el especificador de formato
.
N/A
void**
N/A
N/A
N/A
N/A
N/A
N/A
Notas
Para cada especificador de conversión que no sea n, la secuencia más larga de caracteres de entrada que no exceda ningún ancho de campo especificado y que sea exactamente lo que el especificador de conversión espera o un prefijo de una secuencia que esperaría, es lo que se consume del flujo. El primer carácter, si lo hay, después de esta secuencia consumida permanece sin leer. Si la secuencia consumida tiene longitud cero o si no se puede convertir como se especificó anteriormente, se produce un error de coincidencia a menos que el fin de archivo, un error de codificación o un error de lectura impidan la entrada del flujo, en cuyo caso es un error de entrada.
Excepto para el especificador %, el elemento de entrada (o, para %n, el recuento de caracteres de entrada) primero se convierte a un tipo apropiado para el especificador de conversión. A menos que la asignación se haya suprimido con *, el resultado de la conversión se escribe en el objeto apuntado por el siguiente argumento que aún no se ha escrito. Si este objeto no tiene un tipo apropiado, o si el resultado de la conversión no se puede representar en el objeto, el comportamiento es indefinido.
Todos los especificadores de conversión que no sean [, c y n consumen y descartan todos los caracteres de espacio en blanco iniciales (determinado como si se llamara a std::isspace) antes de intentar analizar la entrada. Estos caracteres consumidos no cuentan para el ancho máximo de campo especificado.
Los especificadores de conversión lc, ls y l[ realizan la conversión de caracteres multibyte a caracteres anchos como si se llamara a std::mbrtowc con un objeto std::mbstate_t inicializado a cero antes de que se convierta el primer carácter.
Los especificadores de conversión s y [ siempre almacenan el terminador nulo además de los caracteres coincidentes. El tamaño del array de destino debe ser al menos uno mayor que el ancho de campo especificado. El uso de %s o %[, sin especificar el tamaño del array de destino, es tan inseguro como std::gets.
Hay un punto de secuencia después de la acción de cada especificador de conversión; esto permite almacenar varios campos en la misma variable "receptora".
Al analizar un valor de punto flotante incompleto que termina en el exponente sin dígitos, como al analizar "100er" con el especificador de conversión %f, la secuencia "100e" (el prefijo más largo de un número de punto flotante posiblemente válido) se consume, lo que resulta en un error de coincidencia (la secuencia consumida no se puede convertir a un número de punto flotante), quedando "r" restante. Algunas implementaciones existentes no siguen esta regla y retroceden para consumir solo "100", dejando "er", por ejemplo, glibc bug 1765.
Si una especificación de conversión no es válida, el comportamiento es indefinido.
Valor de retorno
Número de argumentos receptores asignados exitosamente (que puede ser cero en caso de que ocurra un error de coincidencia antes de que se asignara el primer argumento receptor), o
EOF
si ocurre un fallo de entrada antes de que se asignara el primer argumento receptor.
Complejidad
No está garantizado. Notablemente, algunas implementaciones de
std::sscanf
son
O(N)
, donde
N
=
std::
strlen
(
buffer
)
[1]
. Para análisis de cadenas de alto rendimiento, consulte
std::from_chars
.
Notas
Debido a que la mayoría de especificadores de conversión primero consumen todos los espacios en blanco consecutivos, código como
std::scanf("%d", &a);
std::scanf("%d", &b);
leerá dos enteros que se ingresen en líneas diferentes (el segundo
%
d
consumirá el salto de línea restante del primero) o en la misma línea, separados por espacios o tabulaciones (el segundo
%
d
consumirá los espacios o tabulaciones).
The conversion specifiers that do not consume leading whitespace, such as
%
c
, can be made to do so by using a whitespace character in the format string:
std::scanf("%d", &a);
std::scanf(" %c", &c);// ignorar el salto de línea después de %d, luego leer un carácter
Tenga en cuenta que algunas implementaciones de
std::sscanf
implican una llamada a
std::strlen
, lo que hace que su tiempo de ejecución sea lineal respecto a la longitud de toda la cadena. Esto significa que si
std::sscanf
se llama en un bucle para analizar repetidamente valores desde el inicio de una cadena, su código podría ejecutarse en tiempo cuadrático (
ejemplo
).
Ejemplo
Ejecutar este código
#include <clocale>#include <cstdio>#include <iostream>int main(){int i, j;float x, y;char str1[10], str2[4];wchar_t warr[2];std::setlocale(LC_ALL, "en_US.utf8");char input[]="25 54.32E-1 Thompson 56789 0123 56ß水";// se analiza de la siguiente manera:// %d: un entero// %f: un valor de punto flotante// %9s: una cadena de máximo 9 caracteres que no sean espacios// %2d: un entero de dos dígitos (dígitos 5 y 6)// %f: un valor de punto flotante (dígitos 7, 8, 9)// %*d: un entero que no se almacena en ningún lugar// ' ': todos los espacios consecutivos// %3[0-9]: una cadena de máximo 3 dígitos (dígitos 5 y 6)// %2lc: dos caracteres anchos, usando conversión de multibyte a anchoconstint ret = std::sscanf(input, "%d%f%9s%2d%f%*d %3[0-9]%2lc",
&i, &x, str1, &j, &y, str2, warr);std::cout<<"Converted "<< ret <<" fields:\n""i = "<< i <<"\n""x = "<< x <<"\n""str1 = "<< str1 <<"\n""j = "<< j <<"\n""y = "<< y <<"\n""str2 = "<< str2 <<std::hex<<"\n""warr[0] = U+"<<(int)warr[0]<<"\n""warr[1] = U+"<<(int)warr[1]<<'\n';}
Salida:
Converted 7 fields:
i = 25
x = 5.432
str1 = Thompson
j = 56
y = 789
str2 = 56
warr[0] = U+df
warr[1] = U+6c34