wcstol(3C) wcstol(3C)
NAME
wcstol, wcstoul - Wide-Character-Zeichenkette in long integer umwan-
deln
SYNTAX
#include <wchar.h>
long int wcstol(const wchart *nptr, wchart **endptr, int base);
unsigned long int wcstoul(const wchart *nptr, wchart **endptr,
int base);
BESCHREIBUNG
Die Funktion wcstol() wandelt den ersten Teil der Zeichenkette aus
Wide-Character-Werten, auf die nptr zeigt, in die Darstellung long int
um. Zuerst zerlegt sie die Eingabe-Zeichenkette aus Wide-Character-
Werten in drei Teile: eine, möglicherweise leere, Folge von Zwischen-
raumzeichen als Wide-Character-Werte (entsprechend der Angabe durch
die Funktion iswspace()) am Anfang, ein Folge, die als Integer-Wert
mit einer Dezimalzeichen-Darstellung interpretiert wird, die durch den
Wert von base bestimmt wird, und schließlich eine Zeichenkette aus
Wide-Character-Werten mit einem oder mehr nicht erkannten Wide-
Character-Werten, einschließlich abschließendem Nullbyte der Eingabe-
Zeichenkette aus Wide-Character-Werten. Dann wird versucht, die mitt-
lere Folge in einen Integer-Wert umzuwandeln. Anschließend wird das
Ergebnis zurückgegeben. Da Null, LONGMIN und LONGMAX sowohl bei
einem Fehler zurückgegeben werden als auch bei Erfolg gültige Rückga-
bewerte darstellen, muß eine Anwendung, die auf Fehler prüfen will,
die folgenden Aktionen ausführen: errno wird auf 0 gesetzt, wcstol()
aufgerufen und der Wert von errno überprüft. Falls dieser Wert
ungleich Null ist, wird angenommen, daß ein Fehler aufgetreten ist.
Die Funktion wcstoul() wandelt den ersten Teil der Zeichenkette aus
Wide-Character-Werten, auf die nptr zeigt, in die Darstellung unsigned
long int um. Zuerst zerlegt sie die Eingabe-Zeichenkette aus Wide-
Character-Werten in drei Teile: eine, möglicherweise leere, Folge von
Zwischenraumzeichen als Wide-Character-Werte (entsprechend der Angabe
durch die Funktion iswspace()) am Anfang, ein Folge, die als Integer-
Wert mit einer Dezimalzeichen-Darstellung interpretiert wird, die
durch den Wert von base bestimmt wird, und schließlich eine Zeichen-
kette aus Wide-Character-Werten mit einem oder mehr nicht erkannten
Wide-Character-Werten, einschließlich abschließendem Nullbyte der
Eingabe-Zeichenkette aus Wide-Character-Werten. Dann wird versucht,
die mittlere Folge in einen Integer-Wert umzuwandeln. Anschließend
wird das Ergebnis zurückgegeben. Da Null und LONGMAX sowohl bei einem
Fehler zurückgegeben werden, Null aber auch bei Erfolg einen gültigen
Rückgabewert darstellt, muß eine Anwendung, die auf Fehler prüfen
will, die folgenden Aktionen ausführen: errno wird auf 0 gesetzt,
wcstoul() aufgerufen und der Wert von errno überprüft. Falls dieser
Wert ungleich Null ist, wird angenommen, daß ein Fehler aufgetreten
ist. Anders als wcstod() und wcstol(), muß wcstoul() immer eine nicht
negative Zahl zurückgeben. Die Verwendung des Rückgabewerts von
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
wcstol(3C) wcstol(3C)
wcstoul() für Zahlen, die außerhalb des Bereichs liegen, für die Funk-
tion wcstoul() kann also zu schwerwiegenderen Problemen führen als zu
Genauigkeitsproblemen, wenn diese Zahlen negativ sein können.
Wenn der Wert von base gleich Null ist, so wird als Format der mittle-
ren Folge eine dezimale Konstante, oktale Konstante oder hexadezimale
Konstante erwartet. Dieser kann + bzw. - vorangestellt sein. Eine
dezimale Konstante beginnt mit einer Ziffer ungleich Null und besteht
aus einer Folge dezimaler Ziffern. Eine oktale Konstante besteht aus
dem Präfix 0 und optional einer Folge nur dezimaler Ziffern. Eine
hexadezimale Konstante besteht aus dem Präfix 0x bzw. 0X und einer
Folge dezimaler Ziffern und der Buchstaben a (bzw. A) bis f (bzw. F)
mit den Werten 10 bis 15.
Wenn der Wert von base zwischen 2 und 36 liegt, wird als Format der
Folge eine Folge von Buchstaben und Ziffern erwartet, die einen
Integer-Wert mit der Basis, die durch base bestimmt wird, darstellt
(allerdings keinen Integer-Wert mit Suffix). Optional kann das Vorzei-
chen + bzw. - vorangestellt sein. Den Buchstaben von a (bzw. A) bis
einschließlich z (bzw. Z) sind die Werte 10 bis 35 zugeordnet. Es sind
nur Buchstaben zulässig, deren Wert kleiner ist als der Wert von base.
Ist der Wert von base gleich 16, können die Darstellungen 0x bzw. 0X
für Wide-Character-Werte, gegebenenfalls mit Vorzeichen, der Zeichen-
und Buchstabenfolge voranstehen.
Diese mittlere Folge ist als die längste beginnende Teilfolge der
Eingabe-Zeichenkette aus Wide-Character-Werten definiert. Sie beginnt
mit dem ersten Wide-Character-Wert, der kein Zwischenraumzeichen ist
und das erwartete Format aufweist. Diese Folge enthält keine Wide-
Character-Werte, wenn die Eingabe-Zeichenkette aus Wide-Character-
Werten leer ist oder nur aus Wide-Character-Werten besteht, die Zwi-
schenraumzeichen sind, bzw. wenn der erste Wide-Character-Wert, der
kein Zwischenraumzeichen ist, etwas anderes als das Vorzeichen oder
ein zulässiger Buchstabe bzw. eine zulässige Ziffer ist.
Wenn diese mittlere Folge das erwartete Format aufweist und der Wert
von base gleich Null ist, wird die Folge der Wide-Character-Werte, die
mit der ersten Ziffer beginnt, als Integer-Konstante interpretiert.
Wenn diese mittlere Folge das erwartete Format aufweist und der Wert
von base zwischen 2 und 36 liegt, wird sie als Grundlage für die
Umwandlung verwendet. Jedem Buchstaben wird sein Wert (siehe oben)
zugeordnet. Wenn die Folge mit einem Minuszeichen beginnt, ist das
Ergebnis der Umwandlung negativ. Wenn endptr kein Nullzeiger ist, wird
ein Zeiger auf die abschließende Zeichenkette aus Wide-Character-
Werten in dem Objekt abgelegt, auf das endptr zeigt.
Wenn diese mittlere Folge leer ist oder nicht das erwartete Format
aufweist, wird keine Umwandlung durchgeführt. Der Wert von nptr wird
in dem Objekt abgelegt, auf das endptr zeigt, wenn endptr kein Null-
zeiger ist.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
wcstol(3C) wcstol(3C)
Die Funktionen wcstol() und wcstoul() schlagen fehl, wenn:
EINVAL Der Wert von base wird nicht unterstützt.
ERANGE Der Wert, der zurückgegeben werden soll, ist nicht darstell-
bar.
ERGEBNIS
Bei erfolgreicher Beendigung geben die Funktionen wcstol() und
wcstoul() gegebenenfalls den umgewandelten Wert zurück. Konnte keine
Umwandlung durchgeführt werden, so wird Null zurückgegeben, und errno
kann auf den Fehler gesetzt werden. Liegt der richtige Wert außerhalb
des Bereichs der darstellbaren Werte, so wird (je nach der verwendeten
Funktion und dem Vorzeichen des Wertes) LONGMAX, LONGMIN oder
ULONGMAX zurückgegeben und errno auf ERANGE gesetzt.
SIEHE AUCH
iswalpha(3C), wcstod(3C), scanf(3S), wchar(5).
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98