strtol, strtoll

long      strtol( const char*          str, char**          str_end, int base );

long      strtol( const char* restrict str, char** restrict str_end, int base );

long long strtoll( const char* restrict str, char** restrict str_end, int base );

Interpretiert einen ganzzahligen Wert in einer Byte-Zeichenkette, auf die str zeigt.

Verwirft alle Leerzeichen (wie durch Aufruf von isspace ermittelt), bis das erste Nicht-Leerzeichen gefunden wird, nimmt dann so viele Zeichen wie möglich, um eine gültige Basis-n (wobei n=base) Ganzzahldarstellung zu bilden und konvertiert diese in einen ganzzahligen Wert. Die gültige Ganzzahl besteht aus den folgenden Teilen:

• (optional) Plus- oder Minuszeichen
• (optional) Präfix (0) zur Angabe der oktalen Basis (gilt nur, wenn die Basis 8 oder 0)
• (optional) Präfix (0x oder 0X) zur Angabe der hexadezimalen Basis (gilt nur, wenn die Basis 16 oder 0)
• eine Folge von Ziffern

Der gültige Wertebereich für die Basis ist {0, 2, 3, ..., 36}. Die gültigen Ziffern für Ganzzahlen mit Basis-2 sind {0, 1}, für Ganzzahlen mit Basis-3 sind {0, 1, 2} und so weiter. Für Basen größer als 10 umfassen gültige Ziffern alphabetische Zeichen, beginnend mit Aa für Ganzzahlen mit Basis-11 bis zu Zz für Ganzzahlen mit Basis-36. Die Groß-/Kleinschreibung der Zeichen wird ignoriert.

Zusätzliche numerische Formate können von der derzeit installierten C-Lokalisierung akzeptiert werden.

Wenn der Wert von base 0 ist, wird die numerische Basis automatisch erkannt: Wenn das Präfix 0 ist, ist die Basis oktal, wenn das Präfix 0x oder 0X ist, ist die Basis hexadezimal, andernfalls ist die Basis dezimal.

Wenn das Minuszeichen Teil der Eingabesequenz war, wird der aus der Ziffernfolge berechnete numerische Wert wie durch unäre Minus im Ergebnistyp negiert.

Die Funktionen setzen den Zeiger, auf den str_end zeigt, so, dass er auf das Zeichen nach dem letzten interpretierten numerischen Zeichen zeigt. Wenn str_end ein Nullzeiger ist, wird er ignoriert.

Wenn die str leer ist oder nicht die erwartete Form hat, wird keine Konvertierung durchgeführt, und (wenn str_end kein Nullzeiger ist) wird der Wert von str im Objekt gespeichert, auf das str_end zeigt.

Parameter

Rückgabewert

• Bei Erfolg wird ein ganzzahliger Wert entsprechend dem Inhalt von str zurückgegeben.
• Wenn der konvertierte Wert außerhalb des Bereichs des entsprechenden Rückgabetyps liegt, tritt ein Bereichsfehler auf (setzt errno auf ERANGE) und LONG_MAX, LONG_MIN, LLONG_MAX oder LLONG_MIN wird zurückgegeben (entsprechend dem Vorzeichen des Werts und dem Rückgabetyp).
• Wenn keine Konvertierung durchgeführt werden kann, wird 0 zurückgegeben.

Beispiel

#include <errno.h>
#include <limits.h>
#include <stdbool.h>
#include <stdio.h>
#include <stdlib.h>
 
int main(void)
{
    // parsing with error handling
    const char* p = "10 200000000000000000000000000000 30 -40 junk";
    printf("Parsing '%s':\n", p);

    for (;;)
    {
        // errno can be set to any non-zero value by a library function call
        // regardless of whether there was an error, so it needs to be cleared
        // in order to check the error set by strtol
        errno = 0;
        char* end;
        const long i = strtol(p, &end, 10);
        if (p == end)
            break;
 
        const bool range_error = errno == ERANGE;
        printf("Extracted '%.*s', strtol returned %ld.", (int)(end-p), p, i);
        p = end;
 
        if (range_error)
            printf("\n --> Range error occurred.");
 
        putchar('\n');
    }
    
    printf("Unextracted leftover: '%s'\n\n", p);
 
    // parsing without error handling
    printf("\"1010\" in binary  --> %ld\n", strtol("1010", NULL, 2));
    printf("\"12\"   in octal   --> %ld\n", strtol("12",   NULL, 8));
    printf("\"A\"    in hex     --> %ld\n", strtol("A",    NULL, 16));
    printf("\"junk\" in base-36 --> %ld\n", strtol("junk", NULL, 36));
    printf("\"012\"  in auto-detected base --> %ld\n", strtol("012",  NULL, 0));
    printf("\"0xA\"  in auto-detected base --> %ld\n", strtol("0xA",  NULL, 0));
    printf("\"junk\" in auto-detected base --> %ld\n", strtol("junk", NULL, 0));
}

Parsing '10 200000000000000000000000000000 30 -40 junk':
Extracted '10', strtol returned 10.
Extracted ' 200000000000000000000000000000', strtol returned 9223372036854775807.
 --> Range error occurred.
Extracted ' 30', strtol returned 30.
Extracted ' -40', strtol returned -40.
Unextracted leftover: ' junk'

"1010" in binary  --> 10
"12"   in octal   --> 10
"A"    in hex     --> 10
"junk" in base-36 --> 926192
"012"  in auto-detected base --> 10
"0xA"  in auto-detected base --> 10
"junk" in auto-detected base --> 0

Referenzen

Siehe auch