strton(3ast)

NAME

strton, strtonll - convert string to integer with optional pseudo-float support

SYNOPSIS

long strton(const char* s, char** e, char *basep, int m)

intmax_t strtonll(const char* s, char** e, char *basep, int m)

DESCRIPTION

The strton and strtonll functions convert the zero-terminated string s to a long integer or an intmax_t integer, respectively. If e is not NULL, then *e is set to point to the first unrecognized character in s, or to its terminating zero byte if the conversion was fully successful. Leading isspace(3) characters in s are skipped over and ignored.

A number is composed of sign-base-number-suffix. All but number are optional. The sign may be + or -. The base may be 0x for hexadecimal, 0 for octal, or nn# for base 2 ≤ nn ≤ 64.

For bases greater than 10, the digits above 9 are represented by the lower case letters, the upper case letters, “@”, and “_”, respectively. For bases less than or equal to 36, upper and lower case letters can be used interchangeably.

If the string s has a base prefix. then the numeric value of the base detected is stored in *basep, which may affect subsequent calls. If, on entry, basep is not NULL and the numeric value of *basep is not zero, then the conversion is done from the base specified in basep, and the base prefix is not recognized.

A case-insensitive suffix may be specified in s if the base prefix is omitted. It multiplies the converted number and may be b for block (512), or one of the SI unit prefixes k for kilo (1000), M for mega (1000 × 1000), G for giga (1000 × 1000 × 1000), and so on for T (tera), P (peta), and E (exa), or one of the IEC power-of-two prefixes Ki for kibi (1024), Mi for mebi (1024 × 1024), Gi for gibi (1024 × 1024 × 1024), and so on for Ti (tebi), Pi (pebi), and Ei (exbi). The SI and IEC suffixes may optionally have a final B (i.e., bytes) added, which is accepted and ignored.

The m parameter may also be used to specify a multiplier. If neither a base prefix nor a multiplier suffix is supplied in s, and *basep is 0, and a value greater than 1 is specified in the m parameter, then the converted value will be multiplied by m.

Additionally, the m parameter may be used to support pseudo-floating point numbers. If m is greater than 1, and the suffix consists of the currently set locale's radix point (by default, “.”), followed by decimal digits, then s is treated as if it were a floating point number which is multiplied by m. For example, an s string value of "12.34" combined with an m value of 1000 yields an integer result of 12340.

A negative m disables the recognition of any suffix. Otherwise, if neither case above applies, m is ignored.

RETURN VALUES

The strton and strtonll functions return the value that represents the conversion of zero or more recognized characters in the string s up to the first unrecognized character or the terminating zero byte. The address of the first unrecognized character, or the terminating zero byte, is stored in *e if e is not NULL. Note that errno is not changed in this case.

If the specified base is less than 2 or greater than 64, then *e is set to s (if e is not NULL), the global variable errno is set to EINVAL, and 0 is returned.

If an overflow or underflow occurs, then errno is set to ERANGE and the return value is the function's integer type's maximum possible or minimum possible value, respectively.

SEE ALSO

atoi(3), scanf(3), setlocale(3), strtol(3), strtoul(3), strtod(3)