wcsxfrm - Langzeichenkette transformieren

Definition	#include <wchar.h> size_t wcsxfrm(wchar_t *ws1, const wchar_t *ws2, size_t n);
Beschreibung	wcsxfrm() transformiert die Langzeichenkette, auf die ws2 zeigt, und schreibt das Ergebnis der Transformation in das Feld, auf das ws1 zeigt. Die Transformation wird so durchgeführt, dass die Funktion wcscmp() für zwei transformierte Langzeichenketten denselben Returnwert (größer, gleich oder kleiner null) liefert, wie die Funktion wcscoll() für die beiden ursprünglichen, nicht transformierten Langzeichenketten. Es werden maximal n Langzeichen-Codes in das Feld geschrieben (inklusive des abschließenden Null-Zeichens). Wenn n den Wert 0 hat, darf wc1 ein Nullzeiger sein. Falls zwischen sich überlappenden Objekten kopiert wird, ist das Ergebnis undefiniert.
Returnwert	Ganzzahliger Wert < n
		der die Anzahl der in das Feld geschriebenen Langzeichen-Codes angibt (ohne abschließende Null).
	Ganzzahliger Wert >= n
		In diesem Falle ist der Inhalt des Feldes ws1 unbestimmt.
	(size_t)-1	bei Fehler. errno wird gesetzt, um den Fehler anzuzeigen.
Fehler	wcsxfrm() schlägt fehl, wenn gilt:
	EINVAL	Die Langzeichenkette, auf die ws2 zeigt, enthält Langzeichen-Codes, die außerhalb des Wertebereichs der gewählten Sortierfolge liegen.
	ENOMEM	Es steht nicht genügend Speicherplatz für die internen Verwaltungsdaten zur Verfügung.
Hinweise	Es wird so transformiert, dass zwei transformierte Langzeichenketten von wcscmp() gemäß der in LC_COLLATE festgelegten Sortierfolge geordnet werden. Die Tatsache, dass ws1 ein Nullzeiger sein darf, wenn n den Wert 0 hat, ist nützlich, wenn die Größe des Feldes vor der Transformation bestimmt werden soll. Da es im Standard keinen festlegten Wert für den Fehlerfall gibt, wird empfohlen, errno auf den Wert 0 zu setzen, dann wcsxfrm() aufzurufen und nach dem Aufruf errno zu überprüfen. Falls errno ungleich 0 ist, kann angenommen werden, dass ein Fehler aufgetreten ist. Einschränkung In dieser Version des C-Laufzeitsystems werden nur 1-Byte-Zeichen als Langzeichen unterstützt. Sie sind vom Typ wchar_t (siehe stddef.h). (Ende)
Siehe auch	wcscmp(), wcscoll(), wchar.h.