wstring(3C) wstring(3C)
NAME
wstring: wcscat, wcsncat, wcschr, wcsrchr, wcscmp, wcsncmp, wcscpy,
wcsncpy, wcsspn, wcscspn, wcslen, wcspbrk, wcstok, wcswcs, wcsstr -
Operationen für Zeichenketten aus Wide-Character-Werten
SYNTAX
#include <wchar.h>
wchart *wcscat(wchart *ws1, const wchart *ws2);
wchart *wcsncat(wchart *ws1, const wchart *ws2, sizet n);
wchart *wcschr(const wchart *ws1, wint wc);
wchart *wcsrchr(const wchart *ws, wintt wc);
int wcscmp(const wchart *ws1, const wchart *ws2);
int wcsncmp(const wchart *ws1, const wchart *ws2, sizet n);
wchart *wcscpy(wchart *ws1, const wchart *ws2);
wchart *wcsncpy(wchart *ws1, const wchart *ws2, sizet n);
sizet wcsspn(const wchart *ws1, const wchart *ws2);
sizet wcscspn(const wchart *ws1, const wchart *ws2);
sizet wcslen(const wchart *ws);
wchart wcspbrk(const wchart *ws1, const wchart *ws2);
wchart *wcstok(wchart *ws1, const wchart *ws2, wchart **ptr);
wchart *wcswcs(const wchart *ws1, const wchart *ws2);
wchart *wcsstr(const wchart *ws1, const wchart *ws2);
BESCHREIBUNG
Die Funktion wcscat() verkettet zwei Zeichenketten aus Wide-Charac-
ter-Werten. Dabei hängt sie eine Kopie der Zeichenkette aus Wide-
Character-Werten, auf die ws2 zeigt, (einschließlich abschließendem
Nullbyte) an das Ende der Zeichenkette aus Wide-Character-Werten an,
auf die ws1 zeigt. Der erste Wide-Character-Wert von ws2 überschreibt
das Nullbyte am Ende von ws1. Wenn sich überlappende Objekte ineinan-
der kopiert werden, ist das Verhalten nicht definiert.
Die Funktion wcsncat() hängt maximal an Wide-Character-Werte aus dem
Feld, auf das ws2 zeigt, an das Ende der Zeichenkette aus Wide-Charac-
ter-Werten, auf die ws1 zeigt, an (ein Nullbyte und Wide-Character-
Werte im Anschluß an das Nullbyte werden nicht angehängt). Der erste
Wide-Character-Wert von ws2 überschreibt das Nullbyte am Ende von ws1.
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
wstring(3C) wstring(3C)
An das Ergebnis wird immer ein abschließendes Nullbyte angehängt. Wenn
sich überlappende Objekte ineinander kopiert werden, ist das Verhalten
nicht definiert.
Die Funktion wcschr() liest Zeichenketten aus Wide-Character-Werten.
Sie stellt das erste Vorkommen von wc in der Zeichenkette aus Wide-
Character-Werten fest, auf die ws1 zeigt. Der Wert von wc muß ein Zei-
chen sein, das als Typ wchart darstellbar ist. Es muß außerdem ein
Wide-Character-Wert sein, der in der aktuellen Locale einem gültigen
Zeichen entspricht. Das abschließende Nullbyte wird als Teil der Zei-
chenkette aus Wide-Character-Werten betrachtet.
Die Funktion wcsrchr() stellt das letzte Vorkommen von wc in der Zei-
chenkette aus Wide-Character-Werten fest, auf die ws zeigt. Der Wert
von wc muß ein Zeichen sein, das als Typ wchart darstellbar ist. Es
muß außerdem ein Wide-Character-Wert sein, der in der aktuellen inter-
nationlen Umgebung einem gültigen Zeichen entspricht. Das abschlie-
ßende Nullbyte wird als Teil der Zeichenkette aus Wide-Character-
Werten betrachtet.
Die Funktion wcscmp() vergleicht die Zeichenkette aus Wide-Character-
Werten, auf die ws1 zeigt, mit der Zeichenkette aus Wide-Character-
Werten, auf die ws2 zeigt. Das Vorzeichen eines Rückgabewerts, der
nicht Null ist, wird durch das Vorzeichen der Differenz zwischen den
Werten des ersten Wide-Character-Wertepaares bestimmt, bei dem sich
für die verglichenen Objekte ein Unterschied ergibt.
Die Funktion wcsncmp() vergleicht maximal n Wide-Character-Werte im
Feld, auf das ws1 zeigt, mit dem Feld, auf das ws2 zeigt (Wide-Charac-
ter-Werte, die auf ein Nullbyte folgen, werden nicht verglichen). Das
Vorzeichen eines Rückgabewerts, der nicht Null ist, wird durch das
Vorzeichen der Differenz zwischen den Werten des ersten Wide-Charac-
ter-Wertepaares bestimmt, bei dem sich für die verglichenen Objekte
ein Unterschied ergibt.
Die Funktion wcscpy() kopiert die Zeichenkette aus Wide-Character-
Werten, auf die ws2 zeigt, (einschließlich abschließendem Nullbyte),
in das Feld, auf das ws1 zeigt. Wenn sich überlappende Objekte inein-
ander kopiert werden, ist das Verhalten nicht definiert.
Die Funktion wcsncpy() kopiert maximal n Wide-Character-Werte aus dem
Feld, auf das ws2 zeigt, in das Feld, auf das ws1 zeigt (Wide-Charac-
ter-Werte, die auf ein Nullbyte folgen, werden nicht kopiert). Wenn
sich überlappende Objekte ineinander kopiert werden, ist das Verhalten
nicht definiert. Wenn es unter den ersten n Wide-Character-Werten im
Feld, auf das ws2 zeigt, kein Nullbyte gibt, ist das Ergebnis nicht
mit einem Nullbyte abgeschlossen. Wenn das Feld, auf das ws2 zeigt,
eine Zeichenkette aus Wide-Character-Werten mit weniger als n Wide-
Character-Werten ist, werden so lange Nullbytes an die Kopie im Feld,
auf das ws1 zeigt, angehängt, bis insgesamt n Wide-Character-Werte
geschrieben wurden.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
wstring(3C) wstring(3C)
Die Funktion wcsspn() fragt die Länge einer Teil-Zeichenkette aus
Wide-Character-Werten ab. Sie berechnet die Länge des maximalen
Anfangssegments der durch ws1 angegebenen Zeichenkette aus Wide-Char-
acter-Werten, die ganz aus Wide-Character-Werten aus der durch ws2
angegebenen Zeichenkette besteht.
Die Funktion wcscspn() fragt die Länge einer komplementären Teil-Zei-
chenkette aus Wide-Character-Werten ab. Sie berechnet die Länge des
maximalen Anfangssegments der durch ws1 angegebenen Zeichenkette aus
Wide-Character-Werten, die ganz aus Wide-Character-Werten besteht, die
nicht in der durch ws2 angegebenen Zeichenkette enthalten sind.
Die Funktion wcslen() berechnet die Anzahl der Wide-Character-Werte in
der Zeichenkette aus Wide-Character-Werten, auf die ws zeigt. Dabei
wird das abschließende Nullbyte nicht berücksichtigt.
Die Funktion wcspbrk() durchsucht Zeichenketten aus Wide-Character-
Werten nach Wide-Character-Werten. Sie stellt das erste Vorkommen von
Wide-Character-Werten aus der durch ws2 angegebenen Zeichenkette in
der Zeichenkette aus Wide-Character-Werten fest, auf die ws1 zeigt.
Eine Folge von Aufrufen der Funktion wcstok() zerlegt die Zeichenkette
aus Wide-Character-Werten, auf die ws1 zeigt, in eine Folge von
Tokens. Jedes Token wird durch einen Wide-Character-Wert aus der durch
ws2 angegebenen Zeichenkette aus Wide-Character-Werten begrenzt. Das
dritte Argument zeigt auf einen vom Aufrufer gelieferten Zeiger vom
Typ wchart, in dem die Funktion wcstok() Informationen speichert, die
notwendig sind, um das Lesen der selben Zeichenkette aus Wide-Charac-
ter-Werten fortzuführen.
Der erste Aufruf der Folge hat ws1 als erstes Argument. Dann folgen
Aufrufe, die einen Nullzeiger als erstes Argument haben. Die Trennzei-
chenkette, auf die ws2 zeigt, kann von Aufruf zu Aufruf anders sein.
Der erste Aufruf der Folge durchsucht die Zeichenkette aus Wide-Char-
acter-Werten, auf die ws1 zeigt, nach dem ersten Wide-Character-Wert,
der nicht in der aktuellen Trennzeichenkette enthalten ist, auf die
ws2 zeigt. Wird ein solcher Wide-Character-Wert nicht gefunden, so
sind keine Tokens in der Zeichenkette aus Wide-Character-Werten, auf
die ws1 zeigt. Die Funktion wcstok() gibt dann einen Nullzeiger
zurück. Wenn ein entsprechender Wide-Character-Wert gefunden wird, so
ist dieser der Anfang des ersten Tokens.
Die Funktion wcstok() sucht ab dieser Stelle einen Wide-Character-
Wert, der in der aktuellen Trennzeichenkette enthalten ist. Wird ein
solcher Wide-Character-Wert nicht gefunden, erstreckt sich das aktu-
elle Token bis zum Ende der Zeichenkette aus Wide-Character-Werten,
auf die ws1 zeigt. Darauf folgende Suchläufe nach einem Token geben
einen Nullzeiger zurück. Wird ein entsprechender Wide-Character-Wert
gefunden, so wird er von einem Wide-Character-Nullbyte überschrieben,
das das aktuelle Token beendet. Die Funktion wcstok() speichert einen
Zeiger auf den folgenden Wide-Character-Wert, ab dem die nächste Suche
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
wstring(3C) wstring(3C)
nach einem Token beginnt.
Jeder weitere Aufruf mit einem Nullzeiger als Wert für das erste Argu-
ment beginnt mit der Suche ab dem gespeicherten Zeiger. Das Verhalten
ist wie oben beschrieben.
Die Implementierung verhält sich, als ob keine Funktion die Funktion
wcstok() aufruft.
Die Funktion wcswcs() stellt das erste Vorkommen der Folge von Wide-
Character-Werten (ohne abschließendem Nullbyte) aus der durch ws2
angegebenen Zeichenkette aus Wide-Character-Werten in der Zeichenkette
aus Wide-Character-Werten fest, auf die ws1 zeigt.
Die Funktion wcsstr() stellt das erste Vorkommen der Folge von Wide-
Character-Werten (ohne abschließendem Nullbyte) aus der durch ws2
angegebenen Zeichenkette aus Wide-Character-Werten in der Zeichenkette
aus Wide-Character-Werten fest, auf die ws1 zeigt.
RÜCKGABEWERT
Die Funktion wcscat() liefert s1 zurück. Zur Anzeige eines Fehlers ist
kein Rückgabewert reserviert.
Die Funktion wcsncat() liefert ws1 zurück. Zur Anzeige eines Fehlers
ist kein Rückgabewert reserviert.
Nach der Ausführung liefert wcschr() einen Zeiger auf den Wide-Charac-
ter-Code beziehungsweise einen Nullzeiger zurück, wenn der Wide-Char-
acter-Code nicht gefunden wurde.
Nach erfolgreicher Ausführung liefert wcsrchr() einen Zeiger auf den
Wide-Character-Code beziehungsweise einen Nullzeiger zurück, wenn wc
in der Wide-Character-Zeichenkette nicht vorkommt.
Nach der Ausführung liefert wcscmp() eine Ganzzahl größer, gleich oder
kleiner als 0 zurück, wenn die Wide-Character-Zeichenkette, auf die
ws1 zeigt, größer, gleich oder kleiner als die Wide-Character-Zeichen-
kette ist, auf die ws2 zeigt.
Nach erfolgreicher Ausführung liefert die Funktion wcsncmp() eine
Ganzzahl größer, gleich oder kleiner als 0 zurück, wenn das möglicher-
weise nullterminierte Array, auf das ws1 zeigt, größer, gleich oder
kleiner als das möglicherweise nullterminierte Array ist, auf das ws2
zeigt.
Die Funktion wcscpy() liefert ws1 zurück. Zur Anzeige eines Fehlers
ist kein Rückgabewert reserviert.
Die Funktion wcsncpy() liefert ws1 zurück. Zur Anzeige eines Fehlers
ist kein Rückgabewert reserviert.
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
wstring(3C) wstring(3C)
Die Funktion wcsspn() liefert die Länge von ws1 zurück. Zur Anzeige
eines Fehlers ist kein Rückgabewert reserviert.
Die Funktion wcscspn() liefert die Länge von ws1 zurück. Zur Anzeige
eines Fehlers ist kein Rückgabewert reserviert.
Die Funktion wcslen() liefert ws zurück. Zur Anzeige eines Fehlers ist
kein Rückgabewert reserviert.
Nach erfolgreicher Ausführung liefert wcspbrk() einen Zeiger auf den
Wide-Character-Code beziehungsweise einen Nullzeiger zurück, wenn kein
Wide-Character-Code aus ws2 in ws1 vorkommt.
Nach erfolgreicher Ausführung liefert die Funktion wcstok() einen Zei-
ger auf den ersten Wide-Character-Code eines Token zurück. Wenn kein
Token vorhanden ist, gibt die Funktion einen Nullzeiger zurück.
Nach erfolgreicher Ausführung liefert die Funktion wcswcs() einen
Nullzeiger auf die gefundene Wide-Character-Zeichenkette beziehungs-
weise einen Nullzeiger zurück, wenn die Wide-Character-Zeichenkette
nicht gefunden wurde. Wenn ws2 auf eine Wide-Character-Zeichenkette
mit Nullänge zeigt, gibt die Funktion ws1 zurück.
Nach erfolgreicher Ausführung liefert die Funktion wcsstr() einen
Nullzeiger auf die gefundene Wide-Character-Zeichenkette beziehungs-
weise einen Nullzeiger zurück, wenn die Wide-Character-Zeichenkette
nicht gefunden wurde. Wenn ws2 auf eine Wide-Character-Zeichenkette
mit Nullänge zeigt, gibt die Funktion ws1 zurück.
SIEHE AUCH
wchar(5).
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98