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)
Definiert in Header <wchar.h>
(1)
int wscanf ( const wchar_t * format, ... ) ;
(seit C95)
(bis C99)
int wscanf ( const wchar_t * restrict format, ... ) ;
(seit C99)
(2)
int fwscanf ( FILE * stream, const wchar_t * format, ... ) ;
(seit C95)
(bis C99)
int fwscanf ( FILE * restrict stream,
const wchar_t * restrict format, ... ) ;
(seit C99)
(3)
int swscanf ( const wchar_t * buffer, const wchar_t * format, ... ) ;
(seit C95)
(bis C99)
int swscanf ( const wchar_t * restrict buffer,
const wchar_t * restrict format, ... ) ;
(seit C99)
int wscanf_s ( const wchar_t * restrict format, ... ) ;
(4) (seit C11)
int fwscanf_s ( FILE * restrict stream,
const wchar_t * restrict format, ... ) ;
(5) (seit C11)
int swscanf_s ( const wchar_t * restrict s,
const wchar_t * restrict format, ... ) ;
(6) (seit C11)

Liest Daten aus verschiedenen Quellen, interpretiert sie gemäß format und speichert die Ergebnisse an den angegebenen Speicherorten.

1) Liest die Daten von stdin .
2) Liest die Daten aus dem Dateistrom stream .
3) Liest die Daten aus der nullterminierten Breitzeichenkette buffer . Das Erreichen des Endes der Zeichenkette entspricht dem Erreichen der Dateiende-Bedingung für fwscanf
4-6) Gleich wie (1-3) , außer dass % c , % s und % [ Konvertierungsspezifizierer jeweils zwei Argumente erwarten (den üblichen Zeiger und einen Wert vom Typ rsize_t , der die Größe des Empfangsarrays angibt, die 1 sein kann, wenn mit % lc in ein einzelnes Breitzeichen gelesen wird) und außer dass die folgenden Fehler zur Laufzeit erkannt werden und die aktuell installierte Constraint-Handler-Funktion aufrufen:
  • eines der Argumente vom Zeigertyp ist ein Nullzeiger
  • format , stream oder buffer ist ein Nullzeiger
  • die Anzahl der Zeichen, die durch % c , % s oder % [ geschrieben würden, plus das abschließende Nullzeichen, das zweite ( rsize_t ) Argument überschreiten würden, das für jeden dieser Konvertierungsspezifizierer bereitgestellt wurde
  • optional jeder andere erkennbare Fehler, wie unbekannter Konvertierungsspezifizierer
Wie alle bounds-checked-Funktionen sind wscanf_s , fwscanf_s und swscanf_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ durch die Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ als den Integer-Konstanten 1 definiert, bevor <wchar.h> eingebunden wird.

Inhaltsverzeichnis

Parameter

stream - Eingabedateistream, von dem gelesen wird
buffer - Zeiger auf einen nullterminierten Breitzeichen-String, von dem gelesen wird
format - Zeiger auf einen nullterminierten Breitzeichen-String, der angibt, wie die Eingabe gelesen wird
... - Empfangende Argumente.


Die Format -Zeichenkette besteht aus

  • Nicht-Leerzeichen-Breitzeichen außer % : Jedes solche Zeichen im Formatstring konsumiert genau ein identisches Zeichen aus dem Eingabestrom oder führt zum Fehlschlagen der Funktion, falls das nächste Zeichen im Strom nicht gleich ist.
  • Leerzeichenzeichen: Jedes einzelne Leerzeichenzeichen im Formatstring konsumiert alle verfügbaren aufeinanderfolgenden Leerzeichenzeichen aus der Eingabe (bestimmt wie durch wiederholten Aufruf von iswspace ). Beachten Sie, dass es keinen Unterschied zwischen " \n " , " " , " \t \t " oder anderen Leerzeichen im Formatstring gibt.
  • Konvertierungsspezifikationen. Jede Konvertierungsspezifikation hat folgendes Format:
  • Einleitendes % Zeichen.
  • (optional) unterdrückendes Zuweisungszeichen * . Wenn diese Option vorhanden ist, weist die Funktion das Ergebnis der Konvertierung keinem empfangenden Argument zu.
  • (optional) Ganzzahl (größer als Null), die die maximale Feldbreite angibt, also die maximale Anzahl von Zeichen, die die Funktion bei der Durchführung der durch die aktuelle Konvertierungsspezifikation angegebenen Konvertierung verarbeiten darf. Beachten Sie, dass % s und % [ zu einem Pufferüberlauf führen können, wenn die Breite nicht angegeben wird.
  • (optional) Längenmodifikator der die Größe des empfangenden Arguments angibt, also den eigentlichen Zieltyp. Dies beeinflusst die Konvertierungsgenauigkeit und Überlaufregeln. Der Standardzieltyp ist für jeden Konvertierungstyp unterschiedlich (siehe Tabelle unten).
  • Konvertierungsformat-Spezifizierer.

Die folgenden Formatbezeichner sind verfügbar:

Konvertierungsspezifizierer
Erklärung Erwarteter
Argumenttyp
Längenmodifikator→ hh h keine l ll j z t L
Nur verfügbar seit C99→ Ja Ja Ja Ja Ja
%
Entspricht dem Literal % .
N/A N/A N/A N/A N/A N/A N/A N/A N/A
c

Erfasst ein Zeichen oder eine Sequenz von Zeichen .

  • Bei Verwendung eines Breiten-Spezifizierers werden genau Breite Breitzeichen erfasst (das Argument muss ein Zeiger auf ein Array mit ausreichend Platz sein).
  • Im Gegensatz zu %s und %[ wird dem Array kein Nullzeichen angehängt.
N/A N/A
char *
wchar_t *
N/A N/A N/A N/A N/A
s

Entspricht einer Folge von Nicht-Leerzeichen (einer Zeichenkette ).

  • Wenn ein Breitenbezeichner verwendet wird, entspricht es bis zu Breite oder bis zum ersten Leerzeichen, je nachdem, was zuerst auftritt.
  • Speichert immer ein Nullzeichen zusätzlich zu den übereinstimmenden Zeichen (daher muss das Argument-Array Platz für mindestens Breite+1 Zeichen haben).
[ set  ]

Stimmt mit einer nicht-leeren Zeichenfolge aus dem set von Zeichen überein.

  • Wenn das erste Zeichen des Sets ^ ist, werden alle Zeichen außerhalb des Sets gematcht.
  • Wenn das Set mit ] oder ^] beginnt, wird das ] -Zeichen ebenfalls in das Set aufgenommen.
  • Es ist implementierungsdefiniert, ob das Zeichen - an einer nicht-initialen Position im Scanset einen Bereich angeben kann, wie in [0-9] .
  • Wenn eine Breitenangabe verwendet wird, werden nur bis zu width Zeichen gematcht.
  • Speichert immer ein Nullzeichen zusätzlich zu den gematchten Zeichen (daher muss das Argument-Array Platz für mindestens width+1 Zeichen haben).
d

Erkennt eine dezimale Ganzzahl .

  • Das Zahlenformat entspricht dem von wcstol mit dem Wert 10 für das base Argument.
signed char * oder unsigned char *
signed short * oder unsigned short *
signed int * oder unsigned int *
signed long * oder unsigned long *
signed long long * oder unsigned long long *
N/A
i

Erkennt eine Ganzzahl .

  • Das Zahlenformat entspricht dem von wcstol mit dem Wert ​ 0 ​ für das base Argument erwarteten Format (die Basis wird durch die ersten eingelesenen Zeichen bestimmt).
u

Entspricht einem vorzeichenlosen Dezimalzahl .

  • Das Zahlenformat ist identisch mit dem von wcstoul erwarteten Format mit dem Wert 10 für das base Argument.
o

Entspricht einer vorzeichenlosen Oktalzahl .

  • Das Zahlenformat ist identisch mit dem von wcstoul erwarteten Format mit dem Wert 8 für das base Argument.
x
X

Erkennt eine vorzeichenlose hexadezimale Ganzzahl .

  • Das Zahlenformat entspricht dem von wcstoul mit dem Wert 16 für das base Argument erwarteten Format.
n

Gibt die Anzahl der bisher gelesenen Zeichen zurück.

  • Es wird keine Eingabe konsumiert. Erhöht nicht die Zuweisungsanzahl.
  • Wenn der Format-Spezifizierer den Zuweisungsunterdrückungsoperator definiert hat, ist das Verhalten undefiniert.
a (C99)
A (C99)
e
E
f
F (C99)
g
G

Erkennt eine Gleitkommazahl .

  • Das Zahlenformat entspricht dem von wcstof erwarteten Format.
N/A N/A
float *
double *
N/A N/A N/A N/A
long double *
p

Entspricht einer implementierungsdefinierten Zeichensequenz, die einen Zeiger definiert.

  • printf -Funktionen sollten dieselbe Sequenz mit dem %p -Formatbezeichner erzeugen.
N/A N/A
void **
N/A N/A N/A N/A N/A N/A
Hinweise

Für jeden Konvertierungsspezifizierer außer n wird die längste Folge von Eingabezeichen, die keine spezifizierte Feldbreite überschreitet und entweder genau dem entspricht, was der Konvertierungsspezifizierer erwartet, oder ein Präfix einer solchen Sequenz ist, aus dem Stream gelesen. Das erste Zeichen nach dieser gelesenen Sequenz bleibt ungelesen. Wenn die gelesene Sequenz die Länge null hat oder nicht wie oben spezifiziert konvertiert werden kann, tritt ein Übereinstimmungsfehler auf, es sei denn, Dateiende, ein Kodierungsfehler oder ein Lesefehler verhinderten die Eingabe aus dem Stream, in welchem Fall es sich um einen Eingabefehler handelt.

Alle Konvertierungsspezifizierer außer [ , c und n konsumieren und verwerfen alle führenden Leerzeichen (bestimmt wie durch Aufruf von iswspace ), bevor versucht wird, die Eingabe zu parsen. Diese konsumierten Zeichen zählen nicht zur spezifizierten maximalen Feldbreite.

Wenn der Längenspezifizierer l nicht verwendet wird, führen die Konvertierungsspezifizierer c , s und [ eine Breit-zu-Multibyte-Zeichenkonvertierung durch, als ob wcrtomb mit einem mbstate_t -Objekt aufgerufen würde, das vor der Konvertierung des ersten Zeichens auf null initialisiert wurde.

Die Konvertierungsspezifizierer s und [ speichern immer den Null-Terminator zusätzlich zu den übereinstimmenden Zeichen. Die Größe des Zielarrays muss mindestens um eins größer sein als die spezifizierte Feldbreite. Die Verwendung von % s oder % [ ohne Angabe der Zielarraygröße ist genauso unsicher wie gets .

Die korrekten Konvertierungsspezifikationen für die Festbreiten-Ganzzahltypen ( int8_t usw.) sind im Header <inttypes.h> definiert (obwohl SCNdMAX , SCNuMAX usw. synonym mit % jd , % ju usw. ist).

Es gibt einen Sequenzpunkt nach der Aktion jedes Konvertierungsspezifizierers; dies erlaubt das Speichern mehrerer Felder in derselben "Senken"-Variable.

Beim Parsen eines unvollständigen Gleitkommawerts, der im Exponenten ohne Ziffern endet, wie z.B. das Parsen von "100er" mit dem Konvertierungsspezifizierer % f , wird die Sequenz "100e" (das längste Präfix einer möglicherweise gültigen Gleitkommazahl) konsumiert, was zu einem Übereinstimmungsfehler führt (die konsumierte Sequenz kann nicht in eine Gleitkommazahl konvertiert werden), wobei "r" übrig bleibt. Einige bestehende Implementierungen folgen dieser Regel nicht und rollen zurück, um nur "100" zu konsumieren, und lassen "er" übrig, z.B. glibc bug 1765 .

Wenn eine Konvertierungsspezifikation ungültig ist, ist das Verhalten undefiniert.

Rückgabewert

1-3) Anzahl der erfolgreich zugewiesenen empfangenen Argumente, oder EOF wenn ein Lesefehler auftritt, bevor das erste empfangene Argument zugewiesen wurde.
4-6) Gleich wie (1-3) , außer dass EOF auch zurückgegeben wird, wenn eine Runtime Constraint-Verletzung vorliegt.

Beispiel

Diesen Code ausführen 
#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"Enter state, age, and pi value: ");
    if (wscanf(L"%ls%d%f", state, &age, &pi) != NUM_VARS) {
        fprintf(stderr, "Error reading input.\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, "Error reading input.\n");
        return ERR_READ;
    }
#endif
    wprintf(L"State: %ls\nAge  : %d years\nPi   : %.5f\n\n", state, age, pi);
    FILE* fp = tmpfile();
    if (fp) {
        // write some data to temp file
        if (!fwprintf(fp, L"Mississippi Jackson 420000 807")) {
            fprintf(stderr, "Error writing to file.\n");
            fclose(fp);
            return ERR_WRITE;
        }
        // rewind file pointer
        rewind(fp);
        // read data into variables
        fwscanf(fp, L"%ls%ls%u%d", state, capital, &population, &elevation);
        wprintf(L"State  : %ls\nCapital: %ls\nJackson population (in 2020): %u\n"
                L"Highest elevation: %dft\n",
                state, capital, population, elevation);
        fclose(fp);
    }
}

Mögliche Ausgabe: 

State: California
Age  : 170 years
Pi   : 3.14159
State  : Mississippi
Capital: Jackson
Jackson population (in 2020): 420000
Highest elevation: 807ft

Referenzen

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

Siehe auch

(C99) (C99) (C99) (C11) (C11) (C11)
Liest formatierte Breitzeichen-Eingabe von stdin , einem Dateistrom
oder einem Puffer unter Verwendung einer variablen Argumentenliste
(Funktion)
C++-Dokumentation für wscanf , fwscanf , swscanf