13.17 <cstdlib>

The <cstdlib> header is the C++ version of the C standard <stdlib.h> header, which declares macros, types, and functions of general utility. Several functions in <cstdlib> convert character arrays to numbers. You can also use a string stream (see <sstream>) if you want more control over the conversion, or if you need to convert a number to a string.

The multibyte functions (mblen, etc.) have counterparts in <cwchar> that are reentrant, that is, the <cwchar> functions take an explicit mbstate_t* parameter to avoid using an internal, static shift state.

void abort(  )

The abort function raises the SIGABRT signal. Unless the program has registered a handler for SIGABRT, the default action is to terminate the program without destroying any automatic or static objects and without calling any atexit functions.

See Also

atexit function, exit function, raise in <csignal>, SIGABRT in <csignal>

int abs(int x)

long abs(long x)

The abs function returns the absolute value of x. The <cmath> header declares floating-point versions of the abs function.

See Also

labs function, abs function in <cmath>

extern "C"   int atexit(void (*func)(  ))

extern "C++" int atexit(void (*func)(  ))

The atexit function registers a parameterless function, func, which is called when the program exits normally.

Multiple functions can be registered, and registered functions are called in the opposite order of registration. A function can be registered more than once, in which case it will be called as many times as it was registered.

The atexit functions are not called if the program exits due to a signal, such as SIGABRT.

See Also

abort function, exit function

double atof(const char* str)

The atof function reads a floating-point number from the character array str and returns the value of the floating-point number. The conversion is similar to calling strtod(str, NULL).

See Also

atoi function, atol function, strtod function

int atoi(const char* str)

The atoi function reads an integer from the character array str and returns the value of the number. The atoi function is equivalent to calling static_cast<int>(strtol(str, NULL, 10)).

See Also

atof function, atol function, strtod function

long atol(const char* str)

The atol function reads an integer from the character array str, and returns the value of the number. The conversion is similar to calling strtol(str, NULL, 10).

See Also

atof function, atoi function, strtol function, strtoul func

extern "C"

  void* bsearch(const void* key, const void* base, size_t count, size_t size, int

               (*compare)(const void*, const void*))

extern "C++"

  void* bsearch(const void* key, const void* base, size_t count, size_t size, int

               (*compare)(const void*, const void*))

The bsearch function uses a binary search to search for key in the array base, in which each element takes up size bytes. There are count elements in the array.

The compare function is called with key as the first argument and a pointer into the array as the second. The function should return an integer less than zero if the key is less than the array element, greater than zero if the key is larger, or 0 if the key is the same as the array element.

The bsearch function returns a pointer to the array element that matches key or a null pointer if no element matches.

Two versions of bsearch are declared so the compare function can have "C" linkage or "C++" linkage.

See Also

qsort function, binary_search in <algorithm>

void* calloc(size_t count, size_t size)

The calloc function allocates count elements, each of size bytes, and initializes the allocated memory to all zeros. It returns a pointer to the start of the newly allocated memory or a null pointer if there is insufficient memory to fulfill the request. The pointer is suitably aligned for any type.

C++ programs should use the new operator instead of calling calloc. Call fill or memset to fill the allocated memory with zeros.

See Also

free function, malloc function, realloc function, new keyword, fill in <algorithm>, memset in <cstring>

div_t div(int numerator, int denominator)

ldiv_t div(long numerator, long denominator)

The div function divides numerator by denominator and returns the quotient and the remainder in a structure.

See Also

div_t type, ldiv function

struct div_t { int quot, rem; }

The div_t type is used only by the div function to return the quotient and remainder of an integer division. The order of the quot and rem members in the structure may vary between implementations.

See Also

div function, ldiv_t type

void exit(int code)

The exit function terminates the program normally. Automatic objects are not destroyed, but static objects are. Then, all functions registered with atexit are called in the opposite order of registration. The code is returned to the operating system. An exit code of 0 or EXIT_SUCCESS means successful completion. If code is EXIT_FAILURE, an indication of program failure is returned to the operating system. Other values of code are implementation-defined.

See Also

abort function, atexit function

int EXIT_FAILURE

Pass EXIT_FAILURE to exit to terminate the program normally and informs the operating system that the program was unsuccessful. Returning EXIT_FAILURE from main is the same as calling exit. The EXIT_FAILURE macro expands to an integer constant.

See Also

exit function

int EXIT_SUCCESS

Pass EXIT_SUCCESS to exit to terminate the program normally and inform the operating system that the program was successful. Returning EXIT_SUCCESS from main is the same as calling exit.

The value 0 also means success, but EXIT_SUCCESS is not necessarily equal to 0. The EXIT_SUCCESS macro expands to an integer constant.

See Also

exit function

void free(void* ptr)

The free function releases the memory that ptr points to. The pointer must have been returned by a call to malloc or calloc. After freeing the pointer, do not refer to the memory again.

See Also

calloc function, malloc function, realloc function, delete keyword

char* getenv(const char* name)

The getenv function obtains the value of an environment variable. The environment is a system-defined list of name/value pairs. The getenv function searches the environment for name and returns the associated value. The getenv function returns a null pointer if the specified name is not found.

long labs(long x)

The labs function returns the absolute value of x.

See Also

abs function, abs function in <cmath>

ldiv_t ldiv(long numerator, long denominator)

The ldiv function divides numerator by denominator and returns the quotient and remainder in a structure.

See Also

div function, ldiv_t type

struct ldiv_t { long quot, rem; }

The ldiv_t type is used only as the return type for the ldiv function and the overloaded div function. It stores the quotient and remainder of a long integer division.

See Also

div_t type, ldiv function

void* malloc(size_t size)

The malloc function allocates size bytes of memory. It returns a pointer to the start of the newly allocated memory or a null pointer if there is insufficient memory to fulfill the request. The pointer is suitably aligned for any type.

C++ programs should use the new operator instead of calling malloc.

See Also

calloc function, free function, realloc function, new keyword

int MB_CUR_MAX

The MB_CUR_MAX macro is the maximum number of bytes required to represent a multibyte character in the extended character set, in any locale.

See Also

mblen function, mbtowc function, wctomb function, MB_LEN_MAX in <climits>, <clocale>

int mblen(const char* s, size_t n)

The mblen function returns the length of the multibyte character pointed to by s. The character array s can be null, it can point to an empty string, or it must have at least n bytes, which must form a valid multibyte character.

If s is null, the return value depends on whether multibyte characters have state-dependent encodings. (See Chapter 8 for a discussion of shift state.) The mblen function returns a nonzero value if encodings are state-dependent or 0 if encodings are not state-dependent.

If s points to an empty string, 0 is returned.

If s points to a valid multibyte character, the number of bytes that make up that character is returned. If s points to an invalid multibyte character, -1 is returned.

See Also

MB_CUR_MAX macro, mbtowc function, mbrlen in <cwchar>

size_t mbstowcs(whcar_t* dst, const char* src, size_t n)

The mbstowcs function converts a multibyte string to a wide character string. The src parameter points to the null-terminated multibyte string. Up to n wide characters are stored in dst. If fewer than n characters are stored, a null wide character is appended to the wide character array.

The return value is the number of wide characters stored in dst. If any multibyte character in src is not valid, the return value is static_cast<size_t>(-1).

See Also

mbtowc function, wcstombc function, mbcrtowcs in <cwchar>

int mbtowc(wchar_t* pwc, const char* src, size_t n)

The mbtowc function converts a multibyte character sequence to a single wide character. It starts by counting the number of bytes in src that make up the first multibyte character. It examines only the first n bytes.

If src is null, the return value depends on whether multibyte characters have state-dependent encodings. (See Chapter 8 for a discussion of shift state.) The mbtowc function returns a nonzero value if encodings are state-dependent or 0 if encodings are not state-dependent.

If src points to an empty string, 0 is returned.

If src points to a valid multibyte character, the number of bytes that make up that character is returned. If dst is not null, the multibyte character is converted to its equivalent wide character, and the wide character is stored in *dst.

If src points to an invalid multibyte character, -1 is returned.

See Also

mblen function, mbstowcs function, wctomb function, mbrtowc in <cwchar>

#define NULL  . . .

The NULL macro expands to a null pointer constant. See <cstddef> for more information.

See Also

NULL in <cstddef>

extern "C"

  void qsort(void* base, size_t count, size_t size, int 

            (*compare)(const void*, const void*))

extern "C++"

  void qsort(void* base, size_t count, size_t size, int 

            (*compare)(const void*, const void*))

The qsort function sorts in ascending order an array of count elements, each of size size bytes, in which base is the pointer to the first element. The array must have POD type. The sort is not stable, that is, the relative order of identical elements is not necessarily preserved.

The compare function takes two pointers into the array and compares the elements. It returns an integer: negative if the first element is less than the second, positive if the first is greater than the second, or 0 if the two elements are equal.

The name qsort derives from the original implementation, which used the Quick Sort algorithm. The current standard does not specify which sort algorithm is used, nor does it specify any performance characteristics of the sort algorithm.

Two versions of qsort are declared so the compare function can have "C" linkage or "C++" linkage.

See Also

bsearch function, sort in <algorithm>

int rand(  )

The rand function returns a pseudo-random integer in the range 0 to RAND_MAX, inclusive.

See Also

RAND_MAX macro, srand function

int RAND_MAX

RAND_MAX is the maximum value that rand can return. The RAND_MAX macro expands to an integer constant.

See Also

rand function

void* realloc(void* ptr, size_t size)

The realloc function changes the size of the allocated memory that ptr points to. The new size is size bytes. The return value is a pointer to the newly resized memory block, which might be at a different address than the original block. The pointer is suitably aligned for any type.

The contents of the original memory are preserved, up to the smaller of the new and old sizes. If the new size is larger than the old size, the extra memory above the old size is uninitialized.

The memory might be copied, so you can store only POD values in the memory that you reallocate with realloc.

If ptr is null, realloc behaves just like malloc(size). If size is 0, realloc is like free and frees ptr.

If there is insufficient memory to fulfill the request, the original memory is untouched, and a null pointer is returned.

See Also

calloc function, free function, malloc function, Chapter 6

typedef  . . .  size_t

The size_t type is the type of the result of the sizeof operator. It is an unsigned integral type. The exact type is implementation-defined.

See Also

size_t in <cstddef>

void srand(unsigned int seed)

The srand function saves seed as the seed for a new sequence of pseudo-random numbers to be returned by successive calls to rand. The default seed is 1.

See Also

rand function

double strtod(const char* str, char** end)

The strtod function converts a character array to a floating-point number. The string str is divided into three parts: optional whitespace, the text of the floating-point value, and a trailing part, which starts with the first character that cannot be part of a floating-point number. The first part is skipped, and the second part is converted to a floating-point value. If the second part is empty, 0 is returned. If end is not null, *end is assigned a pointer to the start of the third part of str. If the third part is empty, *end points to the terminating null character.

If the result would cause overflow, positive or negative HUGE_VAL is returned, and errno is set to ERANGE. If the result causes underflow, 0 is returned, and errno is set to ERANGE.

See Also

atoi function, strtol function, strtoul function, wcstod in <cwchar>

long int strtol(const char* str, char** end, int base)

The strtol function converts a character array to a long integer. The string str is divided into three parts: optional whitespace, the text of the integer value, and a trailing part, which starts with the first character that cannot be part of an integer. The first part is skipped, and the second part is converted to a long integer. If the second part is empty, 0 is returned. If end is not null, *end is assigned a pointer to the start of the third part of str. If the third part is empty, *end points to the terminating null character.

If base is 0, the base is determined from the prefix of the integer text: a leading 0x or 0X means hexadecimal, a leading 0 means octal, and anything else is decimal. Otherwise, base must be between 2 and 36, in which the letters a-z (of either case) represent digits with values of 10-35. Only letters that are appropriate for the base are permitted, that is, the corresponding digit value must be less than the base.

If the resulting value is too large or too small to fit in a long int, the value LONG_MAX or LONG_MIN is returned, and errno is set to ERANGE.

See Also

atol function, strtod function, strtoul function, wcstol in <cwchar>

unsigned long strtoul(const char* str, char** end, int base)

The strtoul function converts a character array to an unsigned long integer. The string str is divided into three parts: optional whitespace, the text of the integer value, and a trailing part, which starts with the first character that cannot be part of an integer. The first part is skipped, and the second part is converted to an unsigned long integer. If the second part is empty, 0 is returned. If end is not null, *end is assigned a pointer to the start of the third part of str. If the third part is empty, *end` points to the terminating null character.

If base is 0, the base is determined from the prefix of the integer text: a leading 0x or 0X means hexadecimal, a leading 0 means octal, and anything else is decimal. Otherwise, base must be between 2 and 36, in which the letters a-z (of either case) represent digits with values of 10-35. Only letters that are appropriate for the base are permitted, that is, the corresponding digit value must be less than the base.

If the resulting value is too large to fit in an unsigned long int, the value ULONG_MAX is returned, and errno is set to ERANGE.

See Also

atol function, strtod function, strtol function, wcstoul in <cwchar>

int system(const char* command)

The system function passes command to the host operating system to run as an external command. The use and interpretation of the command string is implementation-defined.

The return value is implementation-defined.

If command is null, the return value is true (nonzero) if a command processor is available; it is false (0) if no command processor is available.

int wctomb(char* s, wchar_t wc)

The wctomb function converts a wide character to a multibyte character. It first determines the number of bytes needed to represent wc as a multibyte character. If s is not null, the sequence of multibyte characters is stored there. At most, MB_CUR_MAX bytes are stored, and the return value is the actual number of bytes written to s. If wc does not have a valid multibyte encoding, -1 is returned.

If s is null, the return value is true (nonzero) if multibyte characters have state-dependent encodings, or false (0) if they do not.

See Also

mbtowc function, wcstombs function, wcrtomb in <cwchar>

size_t wcstombs(char* dst, const wchar_t* src, size_t n)

The wcstombs function converts a wide string src to a string dst of multibyte characters. At most, n bytes of dst are written to. If the conversion of src requires fewer than n bytes, a trailing null byte is appended to dst.

If any wide characters cannot be represented as a multibyte character, static_cast<size_t>(-1) is returned. Otherwise, the return value is the number of bytes written to dst (not counting a trailing null byte).

See Also

mbstowcs function, wctomb function, wcsrtombs in <cwchar>