std::scanf, std::fscanf, std::sscanf

Défini dans l'en-tête `<cstdio>`
int scanf( const char* format, ... );	(1)
int fscanf( std::FILE* stream, const char* format, ... );	(2)
int sscanf( const char* buffer, const char* format, ... );	(3)

Lit des données à partir de diverses sources, les interprète selon format et stocke les résultats dans des emplacements donnés.

1) Lit les données depuis stdin.

2) Lit les données depuis le flux de fichier stream.

3) Lit les données depuis la chaîne de caractères terminée par un caractère nul buffer.

Paramètres

stream	-	flux de fichier d'entrée depuis lequel lire
buffer	-	pointeur vers une chaîne de caractères terminée par un caractère nul depuis laquelle lire
format	-	pointeur vers une chaîne de caractères terminée par un caractère nul spécifiant comment lire l'entrée
...	-	arguments de réception

La chaîne de caractères format se compose de

caractères multi-octets non blancs sauf % : chaque tel caractère dans la chaîne de format consomme exactement un caractère identique du flux d'entrée, ou provoque l'échec de la fonction si le caractère suivant sur le flux n'est pas égal.
caractères blancs : tout caractère blanc unique dans la chaîne de format consomme tous les caractères blancs consécutifs disponibles de l'entrée (déterminé comme si par appel à std::isspace dans une boucle). Notez qu'il n'y a pas de différence entre "\n", " ", "\t\t" ou d'autres caractères blancs dans la chaîne de format.
spécifications de conversion. Chaque spécification de conversion a le format suivant :

caractère d'introduction %.

(optionnel) caractère de suppression d'affectation *. Si cette option est présente, la fonction n'affecte pas le résultat de la conversion à un argument de réception.

(optionnel) nombre entier (supérieur à zéro) qui spécifie la largeur de champ maximale, c'est-à-dire le nombre maximal de caractères que la fonction est autorisée à consommer lors de la conversion spécifiée par la spécification de conversion courante. Notez que %s et %[ peuvent entraîner un débordement de tampon si la largeur n'est pas fournie.

(optionnel) modificateur de longueur qui spécifie la taille de l'argument de réception, c'est-à-dire le type de destination réel. Cela affecte la précision de la conversion et les règles de débordement. Le type de destination par défaut est différent pour chaque type de conversion (voir tableau ci-dessous).

spécificateur de format de conversion.

Les spécificateurs de format suivants sont disponibles :

Spécificateur de conversion	Explication	Type d'argument attendu
Modificateur de longueur →		`hh`	`h`	aucun	`l`	`ll`	`j`	`z`	`t`	`L`
Disponible seulement depuis C++11 →		Oui				Oui	Oui	Oui	Oui
`%`	Correspond au littéral `%`.	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A
`c`	Correspond à un caractère ou à une séquence de caractères. Si un spécificateur de largeur est utilisé, correspond exactement à largeur caractères (l'argument doit être un pointeur vers un tableau avec suffisamment d'espace). Contrairement à %s et %[, n'ajoute pas le caractère nul au tableau.	N/A	N/A	`char*`	`wchar_t*`	N/A	N/A	N/A	N/A	N/A
`s`	Correspond à une séquence de caractères non blancs (une chaîne). Si un spécificateur de largeur est utilisé, correspond jusqu'à largeur ou jusqu'au premier caractère blanc, selon la première occurrence. Stocke toujours un caractère nul en plus des caractères correspondants (donc le tableau d'argument doit avoir de la place pour au moins largeur+1 caractères).
`[`ensemble `]`	Correspond à une séquence non vide de caractères de l'ensemble de caractères. Si le premier caractère de l'ensemble est `^`, alors tous les caractères ne faisant pas partie de l'ensemble sont mis en correspondance. Si l'ensemble commence par `]` ou `^]` alors le caractère `]` est également inclus dans l'ensemble. Il est défini par l'implémentation si le caractère `-` dans une position non initiale dans l'ensemble de balayage peut indiquer une plage, comme dans `[0-9]`. Si un spécificateur de largeur est utilisé, correspond seulement jusqu'à largeur. Stocke toujours un caractère nul en plus des caractères correspondants (donc le tableau d'argument doit avoir de la place pour au moins largeur+1 caractères).
`d`	Correspond à un entier décimal. Le format du nombre est le même que celui attendu par std::strtol avec la valeur `10` pour l'argument `base`.	`signed char` ou `unsigned char`	`signed short` ou `unsigned short`	`signed int` ou `unsigned int`	`signed long` ou `unsigned long`	`signed long long` ou `unsigned long long`	`std::intmax_t` ou `std::uintmax_t`	`std::size_t*`	`std::ptrdiff_t*`	N/A
`b` (C++26)	Correspond à un entier binaire non signé. Le format du nombre est le même que celui attendu par std::strtoul avec la valeur `2` pour l'argument `base`.
`i`	Correspond à un entier. Le format du nombre est le même que celui attendu par std::strtol avec la valeur `0` pour l'argument `base` (la base est déterminée par les premiers caractères analysés).
`u`	Correspond à un entier décimal non signé. Le format du nombre est le même que celui attendu par std::strtoul avec la valeur `10` pour l'argument `base`.
`o`	Correspond à un entier octal non signé. Le format du nombre est le même que celui attendu par std::strtoul avec la valeur `8` pour l'argument `base`.
`x` `X`	Correspond à un entier hexadécimal non signé. Le format du nombre est le même que celui attendu par std::strtoul avec la valeur `16` pour l'argument `base`.
`n`	Retourne le nombre de caractères lus jusqu'à présent. Aucune entrée n'est consommée. N'incrémente pas le compteur d'affectations. Si le spécificateur a un opérateur de suppression d'affectation défini, le comportement est indéfini.
`a` (C++11) `A` (C++11) `e` `E` `f` `F` (C++11) `g` `G`	Correspond à un nombre à virgule flottante. Le format du nombre est le même que celui attendu par std::strtof.	N/A	N/A	`float*`	`double*`	N/A	N/A	N/A	N/A	`long double*`
`p`	Correspond à une séquence de caractères définie par l'implémentation définissant un pointeur. `printf` Les fonctions de la famille doivent produire la même séquence en utilisant le spécificateur de format `%p`.	N/A	N/A	`void**`	N/A	N/A	N/A	N/A	N/A	N/A
Notes
Pour chaque spécificateur de conversion autre que `n`, la plus longue séquence de caractères d'entrée qui ne dépasse aucune largeur de champ spécifiée et qui est soit exactement ce que le spécificateur de conversion attend, soit un préfixe d'une séquence qu'il attendrait, est ce qui est consommé du flux. Le premier caractère, s'il y en a, après cette séquence consommée reste non lu. Si la séquence consommée a une longueur nulle ou si elle ne peut pas être convertie comme spécifié ci-dessus, l'échec de correspondance se produit sauf si la fin de fichier, une erreur d'encodage ou une erreur de lecture empêche l'entrée depuis le flux, auquel cas c'est un échec d'entrée. Sauf pour le spécificateur `%`, l'élément d'entrée (ou, pour `%n`, le nombre de caractères d'entrée) est d'abord converti en un type approprié au spécificateur de conversion. Sauf si l'affectation a été supprimée avec `*`, le résultat de la conversion est écrit dans l'objet pointé par l'argument suivant qui n'a pas encore été écrit. Si cet objet n'est pas d'un type approprié, ou si le résultat de la conversion ne peut pas être représenté dans l'objet, le comportement est indéfini. Tous les spécificateurs de conversion autres que `[`, `c` et `n` consomment et ignorent tous les caractères blancs de tête (déterminés comme si par appel à std::isspace) avant de tenter d'analyser l'entrée. Ces caractères consommés ne comptent pas dans la largeur de champ maximale spécifiée. Les spécificateurs de conversion `lc`, `ls` et `l[` effectuent une conversion multi-octets en caractère large comme si par appel à std::mbrtowc avec un objet std::mbstate_t initialisé à zéro avant que le premier caractère ne soit converti. Les spécificateurs de conversion `s` et `[` stockent toujours le terminateur nul en plus des caractères correspondants. La taille du tableau de destination doit être au moins supérieure d'un à la largeur de champ spécifiée. L'utilisation de `%s` ou `%[`, sans spécifier la taille du tableau de destination, est aussi dangereuse que std::gets. Les spécifications de conversion correctes pour les types d'entiers de largeur fixe (std::int8_t, etc.) sont définies dans l'en-tête `<cinttypes>` (bien que `SCNdMAX`, `SCNuMAX`, etc. soient synonymes de `%jd`, `%ju`, etc.). Il y a un point de séquence après l'action de chaque spécificateur de conversion ; cela permet de stocker plusieurs champs dans la même variable « puits ». Lors de l'analyse d'une valeur à virgule flottante incomplète qui se termine par l'exposant sans chiffres, comme l'analyse de `"100er"` avec le spécificateur de conversion `%f`, la séquence `"100e"` (le plus long préfixe d'un nombre à virgule flottante potentiellement valide) est consommée, entraînant une erreur de correspondance (la séquence consommée ne peut pas être convertie en nombre à virgule flottante), avec `"r"` restant. Certaines implémentations existantes ne suivent pas cette règle et reviennent en arrière pour ne consommer que `"100"`, laissant `"er"`, par exemple bogue glibc 1765. Si une spécification de conversion est invalide, le comportement est indéfini.

Valeur de retour

Nombre d'arguments de réception affectés avec succès (qui peut être nul en cas d'échec de correspondance avant l'affectation du premier argument de réception), ou EOF si un échec d'entrée se produit avant l'affectation du premier argument de réception.

Complexité

Non garantie. Notamment, certaines implémentations de std::sscanf sont $O(N)$ , où N = std::strlen(buffer) [1]. Pour une analyse performante de chaînes, voir std::from_chars.

Notes

Étant donné que la plupart des spécificateurs de conversion consomment d'abord tous les caractères blancs consécutifs, un code tel que

std::scanf("%d", &a);
std::scanf("%d", &b);

lira deux entiers qui sont saisis sur des lignes différentes (le deuxième %d consommera le saut de ligne laissé par le premier) ou sur la même ligne, séparés par des espaces ou des tabulations (le deuxième %d consommera les espaces ou les tabulations).

Les spécificateurs de conversion qui ne consomment pas les caractères blancs de tête, tels que %c, peuvent être amenés à le faire en utilisant un caractère blanc dans la chaîne de format :

std::scanf("%d", &a);
std::scanf(" %c", &c); // ignore the endline after %d, then read a char

Notez que certaines implémentations de std::sscanf impliquent un appel à std::strlen, ce qui rend leur temps d'exécution linéaire en fonction de la longueur de la chaîne entière. Cela signifie que si std::sscanf est appelé dans une boucle pour analyser de manière répétée des valeurs depuis le début d'une chaîne, votre code pourrait s'exécuter en temps quadratique (exemple).

Exemple

Exécuter ce code

#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ß水";
    // parse as follows:
    // %d: an integer 
    // %f: a floating-point value
    // %9s: a string of at most 9 non-whitespace characters
    // %2d: two-digit integer (digits 5 and 6)
    // %f: a floating-point value (digits 7, 8, 9)
    // %*d an integer which isn't stored anywhere
    // ' ': all consecutive whitespace
    // %3[0-9]: a string of at most 3 digits (digits 5 and 6)
    // %2lc: two wide characters, using multibyte to wide conversion
    const int 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';
}

Sortie :

Converted 7 fields:
i = 25
x = 5.432
str1 = Thompson
j = 56
y = 789
str2 = 56
warr[0] = U+df
warr[1] = U+6c34

Voir aussi

vscanfvfscanfvsscanf (C++11)(C++11)(C++11)	lit l'entrée formatée depuis stdin, un flux de fichier ou un tampon en utilisant une liste d'arguments variables (fonction)
fgets	obtient une chaîne de caractères depuis un flux de fichier (fonction)
printffprintfsprintfsnprintf (C++11)	imprime une sortie formatée vers stdout, un flux de fichier ou un tampon (fonction)
from_chars (C++17)	convertit une séquence de caractères en une valeur entière ou à virgule flottante (fonction)
Documentation C pour scanf, fscanf, sscanf

Prise en charge du compilateur
Indépendant et hébergé
Langage
Bibliothèque standard
En-têtes de la bibliothèque standard
Exigences nommées
Macros de test de fonctionnalités (C++20)
Bibliothèque de support du langage
Bibliothèque de concepts (C++20)
Bibliothèque de diagnostics
Bibliothèque de gestion de la mémoire
Bibliothèque de métaprogrammation (C++11)
Bibliothèque d'utilitaires généraux
Bibliothèque de conteneurs
Bibliothèque d'itérateurs
Bibliothèque de plages (C++20)
Bibliothèque d'algorithmes
Bibliothèque de chaînes
Bibliothèque de traitement de texte
Bibliothèque numérique
Bibliothèque de date et heure
Bibliothèque d'entrée/sortie
Bibliothèque du système de fichiers (C++17)
Bibliothèque de support de la concurrence (C++11)
Bibliothèque de contrôle d'exécution (C++26)
Spécifications techniques
Index des symboles
Bibliothèques externes

Manipulateurs d'E/S
Fonctions d'impression (C++23)
E/S de style C
Tampons
basic_streambuf
basic_filebuf
basic_stringbuf
basic_spanbuf (C++23)
strstreambuf (C++98/26*)
basic_syncbuf (C++20)
Flux
Abstractions
ios_base
basic_ios
basic_istream
basic_ostream
basic_iostream
E/S de fichier
basic_ifstream
basic_ofstream
basic_fstream
E/S de chaîne
basic_istringstream
basic_ostringstream
basic_stringstream
E/S de tableau
basic_ispanstream (C++23)
basic_ospanstream (C++23)
basic_spanstream (C++23)
istrstream (C++98/26*)
ostrstream (C++98/26*)
strstream (C++98/26*)
Sortie synchronisée
basic_osyncstream (C++20)
Types
streamoff
streamsize
fpos
Interface de catégorie d'erreur
iostream_category (C++11)
io_errc (C++11)

fr.cppreference.net

Namespaces

Variants