strtoul, _strtoul_l, wcstoul, _wcstoul_l

Artikel
06/09/2015

Konvertiert eine Zeichenfolge in einen langen ganzzahligen Wert ohne Vorzeichen.

unsigned long strtoul(
   const char *nptr,
   char **endptr,
   int base 
);
unsigned long _strtoul_l(
   const char *nptr,
   char **endptr,
   int base,
   _locale_t locale
);
unsigned long wcstoul(
   const wchar_t *nptr,
   wchar_t **endptr,
   int base 
);
unsigned long _wcstoul_l(
   const wchar_t *nptr,
   wchar_t **endptr,
   int base,
   _locale_t locale
);

Parameter

nptr
Zu konvertierende mit NULL endende Zeichenfolge.
endptr
Zeiger auf ein Zeichen, mit dem die Überprüfung beendet wird.
base
Zu verwendende Zahlenbasis.
locale
Zu verwendendes Gebietsschema.

Rückgabewert

strtoul gibt den konvertierten Wert zurück, sofern vorhanden, oder ULONG_MAX im Falle eines Überlaufs. strtoul gibt 0 zurück, wenn keine Konvertierung ausgeführt werden kann. wcstoul gibt Werte analog zu strtoul zurück. Für beide Funktionen wird errno auf ERANGE festgelegt, wenn ein Überlauf oder Unterlauf auftritt.

Weitere Informationen zu diesen und anderen Rückgabecodes finden Sie unter _doserrno, errno, _sys_errlist und _sys_nerr.

Hinweise

Jede dieser Funktionen konvertiert die Eingabezeichenfolge nptr in unsigned long.

strtoul stoppt das Lesen der nptr-Zeichenfolge beim ersten Zeichen, das nicht als Teil einer Zahl erkannt wird. Dies ist möglicherweise das abschließende Nullzeichen, kann aber auch das erste numerische Zeichen sein, dass größer oder gleich base ist. Die LC_NUMERIC-Kategorieeinstellung des Gebietsschemas bestimmt das Erkennen des Basiszeischen in nptr. Weitere Informationen finden Sie unter setlocale. strtoul und wcstoul verwenden das aktuelle Gebietsschema; _strtoul_l und _wcstoul_l sind identisch, verwenden allerdings das übergebene Gebietsschema. Weitere Informationen finden Sie unter Locale.

Wenn endptr nicht NULL ist, wird ein Zeiger auf das Zeichen, das die Überprüfung beendet hat, an dem Ort gespeichert, auf den durch endptr gezeigt wird. Wenn keine Konvertierung ausgeführt werden kann (keine gültigen Ziffern gefunden oder ungültige Basis angegeben), wird der Wert von nptr an dem Speicherort gespeichert, auf den durch endptr gezeigt wird.

wcstoul ist eine Breitzeichenversion von strtoul. Das dazugehörige nptr-Argument ist eine Breitzeichenfolge. Anderenfalls verhalten sich diese Funktionen identisch.

Zuordnung generischer Textroutinen

TCHAR.H-Routine	_UNICODE & _MBCS nicht definiert	_MBCS definiert	_UNICODE definiert
_tcstoul	strtoul	strtoul	wcstoul
_tcstoul_l	strtoul_l	_strtoul_l	_wcstoul_l

strtoul erwartet, dass nptr auf eine Zeichenfolge der folgenden Form zeigt:

[whitespace] [{+ | –}] [0 [{ x | X }]] [digits]

whitespace besteht möglicherweise aus Leerzeichen und Tabulatorzeichen, die ignoriert werden; digits sind eine oder mehrere Dezimalstellen. Das erste Zeichen, das dieser Form nicht entspricht, beendet die Überprüfung. Wenn base zwischen 2 und 36 liegt, wird dieser Wert als Basis der Zahl verwendet. Wenn base 0 ist, werden die ersten Zeichen der Zeichenfolge, auf die durch nptr gezeigt wird, zur Bestimmung der Basis verwendet. Wenn das erste Zeichen "0" und das zweite Zeichen nicht "x" oder "X" ist, wird die Zeichenfolge als ganze Oktalzahl interpretiert. Wenn das erste Zeichen "0" und das zweite Zeichen nicht "x" oder "X" ist, wird die Zeichenfolge als hexadezimale ganze Zahl interpretiert. Wenn das erste Zeichen "1" bis "9 " ist, wird die Zeichenfolge als ganze Dezimalzahl interpretiert. Die Buchstaben "a" bis "z" (bzw. "A" bis "Z") werden den Werten 10 bis 35 zugewiesen. Nur Buchstaben, deren zugewiesene Werte kleiner als base sind, sind zulässig. Das erste Zeichen außerhalb des Bereichs der Basis beendet die Überprüfung. Wenn beispielsweise base 0 und das erste überprüfte Zeichen "0" ist, wird eine ganze Oktalzahl angenommen und das Zeichen "8" oder "9" beendet die Überprüfung. strtoul lässt ein Pluszeichen (+) oder ein Minuszeichens (–) als Präfix zu. Ein führendes Minuszeichen gibt an, dass der Rückgabewert invertiert wird.