Namespaces
Variants

wscanf, fwscanf, swscanf, wscanf_s, fwscanf_s, swscanf_s

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Functions
File access
Unformatted input/output
Formatted input
(C11) (C11) (C11)
wscanf fwscanf swscanf wscanf_s fwscanf_s swscanf_s
(C95) (C95) (C95) (C11) (C11) (C11)
Défini dans l'en-tête <wchar.h>
(1)
int wscanf ( const wchar_t * format, ... ) ;
(depuis C95)
(jusqu'à C99)
int wscanf ( const wchar_t * restrict format, ... ) ;
(depuis C99)
(2)
int fwscanf ( FILE * stream, const wchar_t * format, ... ) ;
(depuis C95)
(jusqu'à C99)
int fwscanf ( FILE * restrict stream,
const wchar_t * restrict format, ... ) ;
(depuis C99)
(3)
int swscanf ( const wchar_t * buffer, const wchar_t * format, ... ) ;
(depuis C95)
(jusqu'à C99)
int swscanf ( const wchar_t * restrict buffer,
const wchar_t * restrict format, ... ) ;
(depuis C99)
int wscanf_s ( const wchar_t * restrict format, ... ) ;
(4) (depuis C11)
int fwscanf_s ( FILE * restrict stream,
const wchar_t * restrict format, ... ) ;
(5) (depuis C11)
int swscanf_s ( const wchar_t * restrict s,
const wchar_t * restrict format, ... ) ;
(6) (depuis C11)

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

1) Lit les données depuis stdin .
2) Lit les données du flux de fichier stream .
3) Lit les données de la chaîne large terminée par un caractère nul buffer . Atteindre la fin de la chaîne équivaut à atteindre la condition de fin de fichier pour fwscanf
4-6) Identique à (1-3) , sauf que % c , % s , et % [ attendent chacun deux arguments (le pointeur habituel et une valeur de type rsize_t indiquant la taille du tableau de réception, qui peut être 1 lors de la lecture avec % lc dans un seul caractère large) et sauf que les erreurs suivantes sont détectées à l'exécution et appellent la fonction gestionnaire de contraintes actuellement installée :
  • l'un des arguments de type pointeur est un pointeur nul
  • format , stream , ou buffer est un pointeur nul
  • le nombre de caractères qui seraient écrits par % c , % s , ou % [ , plus le caractère nul de fin, dépasserait le deuxième argument ( rsize_t ) fourni pour chacun de ces spécificateurs de conversion
  • optionnellement, toute autre erreur détectable, telle qu'un spécificateur de conversion inconnu
Comme toutes les fonctions à vérification des limites, wscanf_s , fwscanf_s , et swscanf_s ne sont garanties d'être disponibles que si __STDC_LIB_EXT1__ est défini par l'implémentation et si l'utilisateur définit __STDC_WANT_LIB_EXT1__ à la constante entière 1 avant d'inclure <wchar.h> .

Table des matières

Paramètres

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


La chaîne de format se compose de

  • caractères larges non-blancs sauf % : chaque caractère de ce type 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 dans le flux n'est pas égal.
  • caractères d'espacement : tout caractère d'espacement unique dans la chaîne de format consomme tous les caractères d'espacement consécutifs disponibles en entrée (déterminés comme en appelant iswspace dans une boucle). Notez qu'il n'y a aucune différence entre " \n " , " " , " \t \t " , ou tout autre espacement 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'assignation * . Si cette option est présente, la fonction n'assigne pas le résultat de la conversion à aucun argument récepteur.
  • (optionnel) nombre entier (supérieur à zéro) qui spécifie la largeur maximale du champ , c'est-à-dire le nombre maximum de caractères que la fonction est autorisée à consommer lors de la conversion spécifiée par la spécification de conversion actuelle. Notez que % s et % [ peuvent entraîner un dépassement de tampon si la largeur n'est pas fournie.
  • (optionnel) modificateur de longueur qui spécifie la taille de l'argument récepteur, c'est-à-dire le type de destination réel. Cela affecte la précision de conversion et les règles de dépassement de capacité. Le type de destination par défaut est différent pour chaque type de conversion (voir le 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
Uniquement disponible depuis C99→ Oui Oui Oui Oui Oui
%
Correspond au caractère 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 à width caractères larges (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 le spécificateur de largeur est utilisé, correspond jusqu'à width ou jusqu'au premier caractère blanc, selon ce qui apparaît en premier.
  • Stocke toujours un caractère nul en plus des caractères correspondants (donc le tableau d'arguments doit avoir de la place pour au moins width+1 caractères).
[ set  ]

Correspond à une séquence non vide de caractères de l'ensemble set de caractères.

  • Si le premier caractère de l'ensemble est ^ , alors tous les caractères non inclus dans l'ensemble sont correspondants.
  • 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 - en position non initiale dans le scanset peut indiquer un intervalle, comme dans [0-9] .
  • Si le spécificateur de largeur est utilisé, correspond uniquement jusqu'à width .
  • 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 width+1 caractères).
d

Correspond à un entier décimal .

  • Le format du nombre est le même que celui attendu par wcstol 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 *
N/A
i

Correspond à un entier .

  • Le format du nombre est le même que celui attendu par wcstol 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 wcstoul 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 wcstoul 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 wcstoul 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'assignations.
  • Si le spécificateur a un opérateur de suppression d'assignation défini, le comportement est indéfini.
a (C99)
A (C99)
e
E
f
F (C99)
g
G

Correspond à un nombre à virgule flottante .

  • Le format du nombre est le même que celui attendu par wcstof .
N/A N/A
float *
double *
N/A N/A N/A N/A
long double *
p

Correspond à la séquence de caractères définie par l'implémentation représentant un pointeur .

  • printf et les fonctions apparentées doivent produire la même séquence en utilisant le %p spécificateur de format.
N/A N/A
void **
N/A N/A N/A N/A N/A N/A
Notes

Pour tout spécificateur de conversion autre que n , la séquence la plus longue de caractères d'entrée qui ne dépasse pas la largeur de champ spécifiée et qui correspond exactement à ce que le spécificateur de conversion attend ou est un préfixe d'une séquence qu'il attendrait, est ce qui est consommé depuis le flux. Le premier caractère, s'il existe, après cette séquence consommée reste non lu. Si la séquence consommée a une longueur nulle ou si la séquence consommée ne peut pas être convertie comme spécifié ci-dessus, un échec de correspondance se produit, sauf si la fin de fichier, une erreur d'encodage ou une erreur de lecture a empêché la lecture depuis le flux, auquel cas c'est un échec d'entrée.

Tous les spécificateurs de conversion autres que [ , c , et n consomment et ignorent tous les caractères d'espacement initiaux (déterminés comme en appelant iswspace ) 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.

Si le spécificateur de longueur l n'est pas utilisé, les spécificateurs de conversion c , s , et [ effectuent une conversion de caractères larges en multioctets comme en appelant wcrtomb avec un objet mbstate_t initialisé à zéro avant la conversion du premier caractère.

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 gets .

Les spécifications de conversion correctes pour les types entiers de largeur fixe ( int8_t , etc.) sont définies dans l'en-tête <inttypes.h> (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 "réceptacle".

Lors de l'analyse d'une valeur flottante incomplète se terminant 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 flottant potentiellement valide) est consommée, résultant en une erreur de correspondance (la séquence consommée ne peut pas être convertie en nombre flottant), 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

1-3) Nombre d'arguments de réception correctement assignés, ou EOF si une erreur de lecture survient avant que le premier argument de réception ne soit assigné.
4-6) Identique à (1-3) , sauf que EOF est également retourné en cas de violation de contrainte d'exécution.

Exemple

Exécuter ce code 
#include <stdio.h>
#include <wchar.h>
#include <string.h>
#define NUM_VARS   3
#define ERR_READ   2
#define ERR_WRITE  3
int main(void) {
    wchar_t state[64];
    wchar_t capital[64];
    unsigned int population = 0;
    int elevation = 0;
    int age = 0;
    float pi = 0;
#if INTERACTIVE_MODE
    wprintf(L"Saisir l'état, l'âge et la valeur de pi : ");
    if (wscanf(L"%ls%d%f", state, &age, &pi) != NUM_VARS) {
        fprintf(stderr, "Erreur de lecture de l'entrée.\n");
        return ERR_READ;
    }
#else
    wchar_t* input = L"California 170 3.141592";
    if (swscanf(input, L"%ls%d%f", state, &age, &pi) != NUM_VARS) {
        fprintf(stderr, "Erreur de lecture de l'entrée.\n");
        return ERR_READ;
    }
#endif
    wprintf(L"État : %ls\nÂge  : %d ans\nPi   : %.5f\n\n", state, age, pi);
    FILE* fp = tmpfile();
    if (fp) {
        // écrire des données dans le fichier temporaire
        if (!fwprintf(fp, L"Mississippi Jackson 420000 807")) {
            fprintf(stderr, "Erreur d'écriture dans le fichier.\n");
            fclose(fp);
            return ERR_WRITE;
        }
        // rembobiner le pointeur de fichier
        rewind(fp);
        // lire les données dans les variables
        fwscanf(fp, L"%ls%ls%u%d", state, capital, &population, &elevation);
        wprintf(L"État  : %ls\nCapitale : %ls\nPopulation de Jackson (en 2020) : %u\n"
                L"Altitude maximale : %dpieds\n",
                state, capital, population, elevation);
        fclose(fp);
    }
}

Sortie possible : 

État : California
Âge  : 170 ans
Pi   : 3.14159
État  : Mississippi
Capitale : Jackson
Population de Jackson (en 2020) : 420000
Altitude maximale : 807pieds

Références

  • Norme C11 (ISO/CEI 9899:2011) :
  • 7.29.2.2 La fonction fwscanf (p: 410-416)
  • 7.29.2.4 La fonction swscanf (p: 417)
  • 7.29.2.12 La fonction wscanf (p: 421)
  • K.3.9.1.2 La fonction fwscanf_s (p: 628-629)
  • K.3.9.1.5 La fonction swscanf_s (p: 631)
  • K.3.9.1.14 La fonction wscanf_s (p: 638)
  • Norme C99 (ISO/CEI 9899:1999) :
  • 7.24.2.2 La fonction fwscanf (p: 356-362)
  • 7.24.2.4 La fonction swscanf (p: 362)
  • 7.24.2.12 La fonction wscanf (p: 366-367)

Voir aussi

(C99) (C99) (C99) (C11) (C11) (C11)
lit une entrée de caractères larges formatée depuis stdin , un flux de fichier
ou un tampon en utilisant une liste d'arguments variables
(fonction)
Documentation C++ pour wscanf , fwscanf , swscanf