atoi, _atoi_l, _wtoi, _wtoi_l

Article
06/09/2015

Convertit une chaîne en entier.

int atoi(
   const char *str 
);
int _wtoi(
   const wchar_t *str 
);
int _atoi_l(
   const char *str,
   _locale_t locale
);
int _wtoi_l(
   const wchar_t *str,
   _locale_t locale
);

Paramètres

str
Chaîne à convertir.
locale
Paramètres régionaux à utiliser.

Valeur de retour

Chaque fonction retourne la valeur int qui est produite lors de l'interprétation des caractères d'entrée comme des nombres. La valeur de retour est 0 pour atoi et _wtoi, si l'entrée ne peut pas être convertie en une valeur de ce type.

Dans le cas d'un dépassement de capacité avec de grandes valeurs intégrales négatives, LONG_MIN est retourné. atoi et _wtoi retournent INT_MAX et INT_MIN dans ces conditions. Dans tous les cas hors limites, errno a la valeur ERANGE. Si le paramètre qui est passé est NULL, le gestionnaire de paramètres non valides est appelé, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, ces fonctions définissent errno avec la valeur EINVAL et retournent 0.

Notes

Ces fonctions convertissent une chaîne de caractères en une valeur entière (atoi et _wtoi). La chaîne d'entrée est une séquence de caractères qui peuvent être interprétés comme une valeur numérique du type spécifié. La fonction cesse de lire la chaîne au premier caractère qu'elle ne peut pas reconnaître comme faisant partie d'un nombre. Ce caractère peut être le caractère null ('\0' ou L'\0') qui termine la chaîne.

L'argument str de atoi et _wtoi a la forme suivante:

[whitespace] [sign] [digits]]

Un whitespace se compose d'espaces ou de caractères de tabulation, qui sont ignorés ; un sign est soit plus (+) soit moins (–) ; et les digits se composent d'un ou de plusieurs chiffres.

Les versions de ces fonctions avec le suffixe _l sont identiques, sauf qu'elles utilisent les paramètres régionaux passés au lieu des paramètres régionaux actuels. Pour plus d'informations, consultez Paramètres régionaux.

Mappages de routines de texte générique

Routine TCHAR.H	_UNICODE & _MBCS non définis	_MBCS défini	_UNICODE défini
_tstoi	atoi	atoi	_wtoi
_ttoi	atoi	atoi	_wtoi

Configuration requise

Routines	En-tête requis
atoi	<stdlib.h>
_atoi_l, _wtoi, _wtoi_l	<stdlib.h> ou <wchar.h>

Exemple

Ce programme montre comment les nombres stockés sous la forme de chaines peuvent etre convertis en des valeurs numériques en utilisant les fonctions atoi.

// crt_atoi.c
// This program shows how numbers 
// stored as strings can be converted to
// numeric values using the atoi functions.

#include <stdlib.h>
#include <stdio.h>
#include <errno.h>

int main( void )
{
    char    *str = NULL;
    int     value = 0;

    // An example of the atoi function.
    str = "  -2309 ";
    value = atoi( str );
    printf( "Function: atoi( \"%s\" ) = %d\n", str, value );

    // Another example of the atoi function.
    str = "31412764";
    value = atoi( str );
    printf( "Function: atoi( \"%s\" ) = %d\n", str, value );

    // Another example of the atoi function 
    // with an overflow condition occuring.
    str = "3336402735171707160320";
    value = atoi( str );
    printf( "Function: atoi( \"%s\" ) = %d\n", str, value );
    if (errno == ERANGE)
    {
       printf("Overflow condition occurred.\n");
    }
}