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 );

Interprète une valeur entière dans une chaîne d'octets pointée par str.

Ignore tous les caractères d'espacement (identifiés en appelant isspace) jusqu'à trouver le premier caractère non espace, puis prend autant de caractères que possible pour former une représentation de nombre entier valide en base n (où n=base) et les convertit en une valeur entière. La valeur entière valide se compose des parties suivantes :

• (optionnel) signe plus ou moins
• (optionnel) préfixe (0) indiquant la base octale (s'applique uniquement lorsque la base est 8 ou 0)
• (optionnel) préfixe (0x ou 0X) indiquant la base hexadécimale (s'applique uniquement lorsque la base est 16 ou 0)
• une séquence de chiffres

L'ensemble des valeurs valides pour la base est {0, 2, 3, ..., 36}. L'ensemble des chiffres valides pour les entiers en base 2 est {0, 1}, pour les entiers en base 3 est {0, 1, 2}, et ainsi de suite. Pour les bases supérieures à 10, les chiffres valides incluent les caractères alphabétiques, en commençant par Aa pour l'entier en base 11, jusqu'à Zz pour l'entier en base 36. La casse des caractères est ignorée.

Des formats numériques supplémentaires peuvent être acceptés par la locale C actuellement installée.

Si la valeur de base est 0, la base numérique est détectée automatiquement : si le préfixe est 0, la base est octale, si le préfixe est 0x ou 0X, la base est hexadécimale, sinon la base est décimale.

Si le signe moins faisait partie de la séquence d'entrée, la valeur numérique calculée à partir de la séquence de chiffres est annulée comme par moins unaire dans le type de résultat.

Les fonctions définissent le pointeur pointé par str_end pour pointer sur le caractère après le dernier caractère numérique interprété. Si str_end est un pointeur null, il est ignoré.

Si la str est vide ou n'a pas la forme attendue, aucune conversion n'est effectuée, et (si str_end n'est pas un pointeur null) la valeur de str est stockée dans l'objet pointé par str_end.

Paramètres

Valeur de retour

• En cas de succès, une valeur entière correspondant au contenu de str est renvoyée.
• Si la valeur convertie est en dehors de la plage du type de retour correspondant, une erreur de plage se produit (définissant errno à ERANGE) et LONG_MAX, LONG_MIN, LLONG_MAX ou LLONG_MIN est renvoyé (selon le signe de la valeur et le type de retour).
• Si aucune conversion ne peut être effectuée, 0 est renvoyé.

Exemple

#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

Références

Voir aussi