wcstok, wcstok_s

Definiert in Header `<wchar.h>`
	(1)
wchar_t* wcstok( wchar_t* str, const wchar_t* delim, wchar_t** ptr );			(seit C95) (bis C99)
wchar_t* wcstok( wchar_t* restrict str, const wchar_t* restrict delim, wchar_t** restrict ptr );			(seit C99)
wchar_t* wcstok_s( wchar_t* restrict str, rsize_t* restrict strmax, const wchar_t* restrict delim, wchar_t** restrict ptr);		(2)	(seit C11)

1) Findet das nächste Token in einem Null-terminierten Wide-String, auf den von str gezeigt wird. Die Trennzeichen werden durch den Null-terminierten Wide-String identifiziert, auf den von delim gezeigt wird.

Diese Funktion ist dazu gedacht, mehrmals aufgerufen zu werden, um aufeinanderfolgende Tokens aus demselben String zu erhalten.

Wenn str != NULL, wird der Aufruf als erster Aufruf von wcstok für diesen speziellen Wide-String behandelt. Die Funktion sucht nach dem ersten Wide-Zeichen, das *nicht* in delim enthalten ist.

Wenn kein solches Wide-Zeichen gefunden wird, gibt es überhaupt keine Tokens in str, und die Funktion gibt einen Nullzeiger zurück.
Wenn ein solches Wide-Zeichen gefunden wird, ist es der *Anfang des Tokens*. Die Funktion sucht dann von diesem Punkt aus nach dem ersten Wide-Zeichen, das *in* delim enthalten ist.

Wenn kein solches Wide-Zeichen gefunden wird, hat str nur ein Token, und zukünftige Aufrufe von wcstok geben einen Nullzeiger zurück.
Wenn ein solches Wide-Zeichen gefunden wird, wird es *durch das Null-Wide-Zeichen* L'\0' *ersetzt*, und der Parser-Status (typischerweise ein Zeiger auf das nachfolgende Wide-Zeichen) wird an der vom Benutzer bereitgestellten Stelle *ptr gespeichert.

Die Funktion gibt dann den Zeiger auf den Anfang des Tokens zurück.

Wenn str == NULL, wird der Aufruf als nachfolgender Aufruf von wcstok behandelt: Die Funktion fährt dort fort, wo sie im vorherigen Aufruf mit demselben *ptr aufgehört hat. Das Verhalten ist dasselbe, als ob der Zeiger auf das Wide-Zeichen, das auf das zuletzt erkannte Token folgt, als str übergeben wird.

2) Wie bei (1), außer dass bei jedem Schritt die Anzahl der noch zu prüfenden Zeichen in str in *strmax geschrieben wird. Wiederholte Aufrufe (mit Null str) müssen sowohl strmax als auch ptr mit den vom vorherigen Aufruf gespeicherten Werten übergeben. Außerdem werden die folgenden Fehler zur Laufzeit erkannt und rufen die aktuell installierte Constraint-Handler-Funktion auf, ohne etwas in das von ptr gezeigte Objekt zu schreiben.

strmax, delim oder ptr ist ein Nullzeiger.
bei einem nicht-initialen Aufruf (mit Null str) ist *ptr ein Nullzeiger.
beim ersten Aufruf ist *strmax Null oder größer als RSIZE_MAX / sizeof(wchar_t).
Die Suche nach dem Ende eines Tokens erreicht das Ende des Quellstrings (gemessen am Anfangswert von *strmax), ohne den Null-Terminator zu finden.

Wie alle grenzgeprüften Funktionen ist wcstok_s nur dann garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert wird und wenn der Benutzer __STDC_WANT_LIB_EXT1__ vor dem Einbinden von <wchar.h> auf die ganzzahlige Konstante 1 setzt.

[bearbeiten] Parameter

str	-	Zeiger auf den Null-terminierten Wide-String, der tokenisiert werden soll.
delim	-	Zeiger auf den Null-terminierten Wide-String, der die Trennzeichen identifiziert.
ptr	-	Zeiger auf ein Objekt vom Typ wchar_t*, das sowohl von `wcstok` als auch von `wcstok_s` verwendet wird, um den internen Zustand des Parsers zu speichern.
strmax	-	Zeiger auf ein Objekt, das anfangs die Größe von str enthält: wcstok_s speichert die Anzahl der noch zu prüfenden Zeichen.

[bearbeiten] Rückgabewert

Gibt den Zeiger auf den Anfang des nächsten Tokens oder einen Nullzeiger zurück, wenn keine weiteren Tokens vorhanden sind.

[bearbeiten] Hinweis

Diese Funktion ist destruktiv: Sie schreibt die L'\0'-Zeichen in die Elemente des Strings str. Insbesondere kann ein Wide-String-Literal nicht als erstes Argument von wcstok verwendet werden.

Im Gegensatz zu strtok aktualisiert wcstok keinen statischen Speicher: Es speichert den Parser-Status an der vom Benutzer bereitgestellten Stelle.

Im Gegensatz zu den meisten anderen Tokenizern können die Trennzeichen bei wcstok für jedes nachfolgende Token unterschiedlich sein und sogar vom Inhalt der vorherigen Tokens abhängen.

Die Implementierung von wcstok_s in der Windows CRT ist inkompatibel mit dem C-Standard, sie ist lediglich ein Alias für wcstok.

[bearbeiten] Beispiel

Führen Sie diesen Code aus

#include <stdio.h>
#include <wchar.h>
 
int main(void)
{
    wchar_t input[] = L"A bird came down the walk";
    printf("Parsing the input string '%ls'\n", input);
    wchar_t* buffer;
    wchar_t* token = wcstok(input, L" ", &buffer);
    while (token)
    {
        printf("%ls\n", token);
        token = wcstok(NULL, L" ", &buffer);
    }
 
    printf("Contents of the input string now: '");
    for (size_t n = 0; n < sizeof input / sizeof *input; ++n)
        input[n] ? printf("%lc", input[n]) : printf("\\0");
    puts("'");
}

Ausgabe

Parsing the input string 'A bird came down the walk'
A
bird
came
down
the
walk
Contents of the input string now: 'A\0bird\0came\0down\0the\0walk\0'

[bearbeiten] Referenzen

C11-Standard (ISO/IEC 9899:2011)

7.29.4.5.7 Die Funktion wcstok (S. 437-438)

K.3.9.2.3.1 Die Funktion wcstok_s (S. 645-646)

C99-Standard (ISO/IEC 9899:1999)

7.24.4.5.7 Die Funktion wcstok (S. 383-384)

[bearbeiten] Siehe auch

strtokstrtok_s (C11)	findet das nächste Token in einem Byte-String (Funktion) [bearbeiten]
C++ Dokumentation für wcstok

Compiler-Unterstützung
Sprache
Header
Typunterstützung
Programm-Dienstprogramme
Unterstützung für variable Funktionsargumente
Fehlerbehandlung
Dynamische Speicherverwaltung
Bibliothek für Zeichenketten
Algorithmen
Numerik
Datums- und Zeitdienstprogramme
Ein-/Ausgabeunterstützung
Lokalisierungsunterstützung
Unterstützung für Nebenläufigkeit (C11)
Technische Spezifikationen
Symbolindex

cppreference.com

Namensräume

Varianten

Ansichten

Aktionen