STRTOLL 3CW "03 January 2009" "mathcw-1.00"

Table of contents


NAME

STRTOLL - convert numeric string to long long int

SYNOPSIS

cc [ flags ] -I/usr/local/include file(s) -L/usr/local/lib -lmcw [ ... ]

#include <stdlib.h>

extern long long int strtoll (const char * str, char ** endptr, int base);

DESCRIPTION

strtoll converts a numeric string to a signed integer value of type long long int. The first argument should point to a numeric string, optionally beginning with whitespace, as identified by isspace(3), followed by an optional plus or minus sign, and then a digit string.

In the usual case, the third argument, base, is 0, meaning that the form of the numeric string selects the base automatically. Standard C requires recognition of decimal strings, octal strings beginning with a 0 digit, and hexadecimal strings beginning with the prefix 0x or 0X. Examples include 02724 and 0x5d4, which represent the decimal value 1492.

This implementation extends the Standard with support for binary strings beginning with 0b or 0B, octal strings beginning with 0o or 0O (zero-oh), and based-number strings of the form base@digits@, where base is in [2,36], and the digits are taken from the string 0123456789abcdefghijklmnopqrstuvwxyz, ignoring lettercase. The implementation also permits optional digit-separating underscores for enhanced readability. Examples of these extended formats are

0b1000_0000_0000_0000  (decimal 32_768),
0o377_777 (decimal 131_071),
36@abcXYZ@ (decimal 623_741_435).
If the third argument is nonzero, then it must be in the range [2,36], and the numeric string must be in that base. If the base is 16, a prefix 0x or 0X is optional.

The extensions of this implementation permit an optional binary prefix (0b or 0B) when the base is 2, and an optional octal prefix (0o or 0O) when the base is 8.

Based numbers are not recognized when the base argument is nonzero.

Integer type suffixes used in the C programming language family are not recognized by strtoll(3CW).


RETURN VALUES

If the first argument is NULL, or the third argument is not 0, or in the range [2,36], the return value is 0.

If no characters can be converted, the return value is 0.

If the numeric string represents a value larger than can be stored in a long long int, the overflow is detected, and the return value is the signed value of largest magnitude of that type, represented by the constants LLONG_MIN and LLONG_MAX in the standard header file <limits.h>. The overflow is recorded by setting the global value errno defined in <errno.h> to ERANGE.

Otherwise, the value returned is that of the longest numeric prefix of the first argument that encodes an integer value in the specified base.

If the second argument is non-NULL, it is set to point to the string that follows the last character successfully converted. The caller can then check that the initial character of that string is one that can legally follow a number in the application context of the user program, and, if desired, can continue parsing the remainder of the string.


SEE ALSO

isspace(3), strtol(3CW), strtoul(3CW), strtoull(3CW).