Namensräume
Varianten
Aktionen

strtok, strtok_s

Von cppreference.com
< c‎ | string‎ | byte
 
C
 
Bibliothek für Zeichenketten
 
Null-terminierte Byte-Strings
Funktionen
Zeichenmanipulation
Konvertierungen zu und von numerischen Formaten
Stringmanipulation
Stringuntersuchung
strtokstrtok_s
(C11)

Speichermanipulation
Sonstiges
(C11)(C11)
 
Definiert in Header <string.h>
(1)
char* strtok( char* str, const char* delim );
 (bis C99)
char* strtok( char* restrict str, const char* restrict delim );
 (seit C99)
char* strtok_s( char* restrict str, rsize_t* restrict strmax,
                const char* restrict delim, char** restrict ptr );
 (2) (seit C11)

Tokenisiert eine nullterminierte Byte-Zeichenkette.

1) Eine Folge von Aufrufen von strtok zerlegt die von str gezeigte Zeichenkette in eine Folge von Tokens, die jeweils durch ein Zeichen aus der von delim gezeigten Zeichenkette begrenzt sind. Jeder Aufruf in der Sequenz hat ein Suchziel 
  • Wenn str nicht null ist, ist der Aufruf der erste Aufruf in der Sequenz. Das Suchziel ist die nullterminierte Byte-Zeichenkette, auf die str zeigt.
  • Wenn str null ist, ist der Aufruf einer der nachfolgenden Aufrufe in der Sequenz. Das Suchziel wird durch den vorherigen Aufruf in der Sequenz bestimmt.
Jeder Aufruf in der Sequenz durchsucht das Suchziel nach dem ersten Zeichen, das **nicht** in der Trennzeichenkette enthalten ist, auf die delim zeigt; die Trennzeichenkette kann sich von Aufruf zu Aufruf unterscheiden.
  • Wenn ein solches Zeichen nicht gefunden wird, gibt es keine Tokens im Suchziel. Das Suchziel für den nächsten Aufruf in der Sequenz bleibt unverändert.[1]
  • Wenn ein solches Zeichen gefunden wird, ist es der Anfang des aktuellen Tokens. strtok sucht dann von dort nach dem ersten Zeichen, das in der Trennzeichenkette enthalten ist.
    • Wenn ein solches Zeichen nicht gefunden wird, erstreckt sich das aktuelle Token bis zum Ende des Suchziels. Das Suchziel für den nächsten Aufruf in der Sequenz ist eine leere Zeichenkette.[2]
    • Wenn ein solches Zeichen gefunden wird, wird es durch ein Nullzeichen überschrieben, das das aktuelle Token beendet. Das Suchziel für den nächsten Aufruf in der Sequenz beginnt beim folgenden Zeichen.
Wenn str oder delim kein Zeiger auf eine nullterminierte Byte-Zeichenkette ist, ist das Verhalten undefiniert.
2) Gleich wie (1), außer mit folgenden Unterschieden
  • Bei jedem Aufruf wird die Anzahl der noch zu sehenden Zeichen in str in *strmax geschrieben und der interne Zustand des Tokenizers in *ptr geschrieben.
  • Nachfolgende Aufrufe in der Sequenz müssen strmax und ptr mit den Werten übergeben, die vom vorherigen Aufruf gespeichert wurden.
  • Die folgenden Fehler werden 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.
    • *ptr ist ein Nullzeiger für einen nachfolgenden Aufruf in der Sequenz.
    • *strmax ist größer als RSIZE_MAX.
    • Das Ende des gefundenen Tokens tritt nicht innerhalb der ersten *s1max Zeichen des Suchziels auf.
Wenn sowohl str auf ein Zeichenarray verweist, dem das Nullzeichen fehlt, als auch strmax auf einen Wert verweist, der größer als die Größe dieses Zeichenarrays ist, ist das Verhalten undefiniert.
Wie bei allen grenzgeprüften Funktionen ist strtok_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 <string.h> auf die Ganzzahlkonstante 1 setzt.
  1. ↑ Ein Token kann in einem nachfolgenden Aufruf mit einer anderen Trennzeichenkette gebildet werden.
  2. ↑ Es können keine weiteren Tokens in nachfolgenden Aufrufen gebildet werden.

Inhalt

[bearbeiten] Parameter

str - Zeiger auf die nullterminierte Byte-Zeichenkette, die tokenisiert werden soll
delim - Zeiger auf die nullterminierte Byte-Zeichenkette, die Trennzeichen identifiziert
strmax - Zeiger auf ein Objekt, das anfänglich die Größe von str enthält: strtok_s speichert die Anzahl der zu prüfenden verbleibenden Zeichen
ptr - Zeiger auf ein Objekt vom Typ char*, das von strtok_s zur Speicherung seines internen Zustands verwendet wird

[bearbeiten] Rückgabewert

1) Gibt einen Zeiger auf das erste Zeichen des nächsten Tokens zurück oder einen Nullzeiger, wenn kein Token vorhanden ist.
2) Gibt einen Zeiger auf das erste Zeichen des nächsten Tokens zurück oder einen Nullzeiger, wenn kein Token vorhanden ist oder eine Laufzeit-Constraint-Verletzung vorliegt.

[bearbeiten] Hinweis

Diese Funktion ist destruktiv: sie schreibt die '\0' Zeichen in die Elemente der Zeichenkette str. Insbesondere kann eine Zeichenketten-Literal nicht als erstes Argument von strtok verwendet werden.

Jeder Aufruf von strtok modifiziert eine statische Variable: ist nicht threadsicher.

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

Die Funktion strtok_s unterscheidet sich von der POSIX-Funktion strtok_r, indem sie gegen das Schreiben außerhalb der zu tokenisierenden Zeichenkette schützt und Laufzeit-Constraints prüft. Die Signatur von Microsoft CRT strtok_s stimmt mit dieser POSIX-Definition von strtok_r überein, nicht mit der C11-Definition von strtok_s.

[bearbeiten] Beispiel

Führen Sie diesen Code aus
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <string.h>
 
int main(void)
{
    char input[] = "A bird came down the walk";
    printf("Parsing the input string '%s'\n", input);
    char* token = strtok(input, " ");
    while (token)
    {
        puts(token);
        token = strtok(NULL, " ");
    }
 
    printf("Contents of the input string now: '");
    for (size_t n = 0; n < sizeof input; ++n)
        input[n] ? putchar(input[n]) : fputs("\\0", stdout);
    puts("'");
 
#ifdef __STDC_LIB_EXT1__
    char str[] = "A bird came down the walk";
    rsize_t strmax = sizeof str;
    const char* delim = " ";
    char* next_token;
    printf("Parsing the input string '%s'\n", str);
    token = strtok_s(str, &strmax, delim, &next_token);
    while (token)
    {
        puts(token);
        token = strtok_s(NULL, &strmax, delim, &next_token);
    }
 
    printf("Contents of the input string now: '");
    for (size_t n = 0; n < sizeof str; ++n)
        str[n] ? putchar(str[n]) : fputs("\\0", stdout);
    puts("'");
#endif
}

Mögliche 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'
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

  • C23-Standard (ISO/IEC 9899:2024)
  • 7.24.5.8 Die Funktion strtok (S. TBD)
  • K.3.7.3.1 Die Funktion strtok_s (S. TBD)
  • C17-Standard (ISO/IEC 9899:2018)
  • 7.24.5.8 Die Funktion strtok (S. TBD)
  • K.3.7.3.1 Die Funktion strtok_s (S. TBD)
  • C11-Standard (ISO/IEC 9899:2011)
  • 7.24.5.8 Die Funktion strtok (S. 369-370)
  • K.3.7.3.1 Die Funktion strtok_s (S. 620-621)
  • C99-Standard (ISO/IEC 9899:1999)
  • 7.21.5.8 Die Funktion strtok (S. 332-333)
  • C89/C90-Standard (ISO/IEC 9899:1990)
  • 4.11.5.8 Die Funktion strtok

[bearbeiten] Siehe auch

 findet die erste Position eines beliebigen Zeichens aus einem String in einem anderen String
(Funktion) [bearbeiten]
 gibt die Länge des maximalen Anfangssegments zurück, das
nur aus den Zeichen besteht, die in einem anderen Byte-String nicht vorkommen
(Funktion) [bearbeiten]
 gibt die Länge des maximalen Anfangssegments zurück, das
nur aus den Zeichen besteht, die in einem anderen Byte-String vorkommen
(Funktion) [bearbeiten]
(C95)(C11)
 findet das nächste Token in einer breiten Zeichenkette
(Funktion) [bearbeiten]
C++ Dokumentation für strtok
Abgerufen von "https://cppreference.de/mwiki/index.php?title=c/string/byte/strtok&oldid=180884"