Data Structures | Defines | Functions

# Standard library functions
[C library]

This part of the library has been extended with functions that are not part of the standard but that I believe are useful in a resource constrained system, especially if you want to avoid the use of a `printf()` and `scanf()` type function. More...

## Data Structures
struct | div_t
| Structure holding the result for div(). More...
struct | udiv_t
| Structure holding the result for udiv(). More...
struct | lldiv_t
| Structure holding the result for lldiv(). More...
struct | ulldiv_t
| Structure holding the result for ulldiv(). More...
## Defines
#define | RAND_MAX 0x7fffffff
| The largest random number returned by random_r().
## Functions
div_t | div (int numerator, int denominator)
| Compute quotient and remainder of a signed integer (32-bit) division.
udiv_t | udiv (unsigned numerator, unsigned denominator)
| Compute quotient and remainder of an unsigned integer (32-bit) division.
lldiv_t | lldiv (long long numerator, long long denominator)
| Compute quotient and remainder of a signed long long (64-bit) division.
ulldiv_t | ulldiv (unsigned long long numerator, unsigned long long denominator)
| Compute quotient and remainder of an unsigned long long (64-bit) division.
void * | bsearch (const void *key, const void *base, size_t nmemb, size_t size, int(*comp)(const void *, const void *))
| Binary search in an ordered array.
void | hsort (int numb, void *parm, int(*comp)(int, int, void *), void(*copy)(int, int, void *))
| Sort an array.
void | qsort (void *base, size_t nmemb, size_t size, int(*comp)(const void *, const void *))
| Sort an array.
int * | srandom_r (int seed, int *state, size_t size)
| Initialises the random number generator.
int | random_r (int *state)
| Random number generator.
double | strtod (const char *nptr, char **eptr)
| Convert a string to a double.
double | strtode (const char *nptr, char **eptr, void(*optr)(void))
| Convert a string to double precision float number.
long | strtol (const char *nptr, char **eptr, int base)
| Convert a string to a signed long number.
long | strtole (const char *nptr, char **eptr, int base, void(*optr)(void))
| Convert a string to a signed long number.
long long | strtoll (const char *nptr, char **eptr, int base)
| Convert a string to a signed long long number.
long long | strtolle (const char *nptr, char **eptr, int base, void(*optr)(void))
| Convert a string to a signed long long number.
unsigned long | strtoul (const char *nptr, char **eptr, int base)
| Convert a string to an unsigned long number.
unsigned long | strtoule (const char *nptr, char **eptr, int base, void(*optr)(void))
| Convert a string to an unsigned long number.
unsigned long long | strtoull (const char *nptr, char **eptr, int base)
| Convert a string to an unsigned long long number.
unsigned long long | strtoulle (const char *nptr, char **eptr, int base, void(*optr)(void))
| Convert a string to an unsigned long long number.
int | ulltostr (char *buff, unsigned long long numb, int base, int uppc)
| Converts a 64-bit unsigned integer to ASCII with an arbitrary radix.
int | ulltostr10 (char *buff, unsigned long long numb)
| Convert an unsigned long long to a string in radix 10.
int | ulltostr2n (char *buff, unsigned long long numb, int base, int uppc)
| Converts a 32-bit unsigned integer to ASCII in radix 2^N.
int | ultostr (char *buff, unsigned long numb, int base, int uppc)
| Converts a 32-bit unsigned integer to ASCII with an arbitrary radix.
int | ultostr10 (char *buff, unsigned long numb)
| Converts a 32-bit unsigned integer to ASCII in radix 10.
int | ultostr2n (char *buff, unsigned long numb, int base, int uppc)
| Converts a 32-bit unsigned integer to ASCII in radix 2^N.

## Detailed Description

This part of the library has been extended with functions that are not part of the standard but that I believe are useful in a resource constrained system, especially if you want to avoid the use of a `printf()` and `scanf()` type function.

To use these functions you have to include `stdlib.h`.

## String to number conversions

The standard defines functions that convert a string to an integer and functions that convert a string to a float-point number. In case of an overflow, these functions are to set `errno` to the relevant error code. Since in your system there might not be an equivalent of errno or you have some custom implementation, the standard functions do not support error detection at all.
To make up for that deficiency, all string to number functions are also available in a form where they take an additional argument, a pointer to a function returning `void`, that is called if the conversion overflows. In that function you can implement your custom `errno` setting or equivalent error signalling functionality.

## Integer to string conversion

The standard does not define functions to convert integers to strings, probably because the functionality can be achieved by calling `sprintf()`. However, the formatted print core is huge compared to a simple conversion and if you need to convert integers to strings but otherwise do not need formatted print, then the code burden (and run-time overhead) of using sprintf() is excessive.
Therefore the library provides functions to convert 32 and 64 bit unsigned integers to strings. The generic function can convert numbers using any radix between 2 and 36 but specialised fast functions are also available for radix 10 and radices that are powers of 2.
None of the conversion functions use division and a conversion of a 32-bit number to a decimal string takes about as much time as a single 32-bit division on the ARM7TDMI core (it doesn't have a HW divider), conversion of a 64-bit number takes just a bit longer than twice as much.
It is possible that the decimal conversion is actually novel, at least I could not find any reference to the conversion method used by the library on the 'Net. If it is indeed novel and by any chance patentable (everything seems to be patentable these days), then it is hereby declared public knowledge and prior art to any future patent claim.

## Function Documentation

void* bsearch | ( | const void * | key,
|  | const void * | base,
|  | size_t | nmemb,
|  | size_t | size,
|  | int(*)(const void *, const void *) | comp |
| ) |  |  |

Binary search in an ordered array.

The routine searches for a key in an array of identical but otherwise arbitrary comparable objects that are sorted in ascending order. As the name implies, the routine uses binary search, therefore the maximum number of compares is ceil( log2( `nmemb` ) ).

Parameters:

  | key | Pointer to the key that should be found in the array.
  | base | Pointer to the array of objects to search. The array must be sorted in ascending order.
  | nmemb | The number of objects in the array.
  | size | The size of each member of the array, as returned by the `sizeof` operator.
  | comp | A pointer to a function that receives a pointer to the key as its first parameter and a pointer to an object as its second parameter. The function then returns less than 0, 0 or greater than 0 if the key is less than, equal to or greater than the object, respectively.

Returns:
  If the given key is found in the array, then the return value is a pointer to that object. If the key is not found, then NULL is returned. If the array contains multiple objects with the given search key, then which one is returned is undetermined.

div_t div | ( | int | numerator,
|  | int | denominator |
| ) |  |  |

Compute quotient and remainder of a signed integer (32-bit) division.

The function divides its `numerator` argument with its `denominator` argument and returns a structure containing the quotient and the remainder. The fields of the structure are called `quot` and `rem`, respectively. The quotient is rounded towards zero and the result is such that the following equation holds:

`numerator = quotient * denominator + remainder`

If the denominator is 0, then the behaviour is undefined.

Parameters:

  | numerator | The number to divide
  | denominator | The number to divide with

Returns:
  A structure containing both the quotient and the remainder.

Attention:
  To use this function you must link the library that contains the fast versions of the gcc support library functions (by default this library is called gccs) because that contains the actual division core.

void hsort | ( | int | numb,
|  | void * | parm,
|  | int(*)(int, int, void *) | comp,
|  | void(*)(int, int, void *) | copy |
| ) |  |  |

Sort an array.

The routine sorts an array of arbitrary comparable objects into ascending order. Unlike the qsort() function, this function does not assume that your array is a real array of identical objects in memory. Rather, the objects you want to sort are identified by an index, between 0 and N-1 where N is the number of objects you want to sort. The comparison function receives the indices, not pointers to objects. Since the hsort() function does not assume anything about your objects, it can not copy them. Therefore, you also have to supply a function that can copy an object to an other, receiving the index of both.
In addition, you have to facilitate the temporary storage of one object outside of your array. When you receive the index of -1, then that index refers to this extra storage facility. This is true for both the comparison and the copy function. This storage must be persistent during the execution of the hsort() function.
The function implements heapsort, thus the time needed to sort your array is O( N * log2( N ) ) operations, both compares and copies, regardless of the state of your array. In practice, hsort() will call the copy function somewhere between N*log2(N) and 2*N*log2(N) times and the compare function about 1.42 times more than the copy.
Note that since the function does not actually dereference any of your objects, the objects do not really have to be in an array, not even in memory and they do not need to be of the same size, or even the same object type. As long as you can compare and copy them by an index, that is, an integer identifying an object, you can sort them using this function.

Parameters:

  | numb | The number of objects to sort.
  | parm | A void pointer that will be passed as the third argument of the comparison and copy functions. The hsort() function only passes this argument to the two other functions, it does not use it itself.
  | comp | A pointer to a function that receives the index of two objects and returns less than 0, 0 or greater than 0 if the first object is, respectively, less than, equal to or greater than the second object. The index value of -1 refers to an extra storage facility, able to hold one object. A third parameter, a void pointer is also passed to the function, which is the second argument of the hsort() function.
  | copy | A pointer to a function that receives the index of two objects and copies the one selected by the second index to the object selected by the first. The index value of -1 refers to a temporary storage facility that can hold one object. A third parameter, a void pointer is also passed to the function, which is the second argument of the hsort() function.

lldiv_t lldiv | ( | long long | numerator,
|  | long long | denominator |
| ) |  |  |

Compute quotient and remainder of a signed long long (64-bit) division.

The function divides its `numerator` argument with its `denominator` argument and returns a structure containing the quotient and the remainder. The fields of the structure are called `quot` and `rem`, respectively. The quotient is rounded towards zero and the result is such that the following equation holds:

`numerator = quotient * denominator + remainder`

If the denominator is 0, then the behaviour is undefined.

Parameters:

  | numerator | The number to divide
  | denominator | The number to divide with

Returns:
  A structure containing both the quotient and the remainder.

Attention:
  To use this function you must link the library that contains the fast versions of the gcc support library functions (by default this library is called gccs) because that contains the actual division core.

void qsort | ( | void * | base,
|  | size_t | nmemb,
|  | size_t | size,
|  | int(*)(const void *, const void *) | comp |
| ) |  |  |

Sort an array.

The routine sorts an array of identical but otherwise arbitrary comparable objects into ascending order.

Parameters:

  | base | Pointer to the array of the objects to sort
  | nmemb | The number of objects in the array.
  | size | The size of each object in the array, as returned by the `sizeof` operator.
  | comp | A pointer to a function that receives pointers to two array members and returns less than 0, 0 or greater than 0 if the first argument is, respectively, less than, equal to or greater than the second argument.

Note:
  Despite being called `qsort()`, this function actually implements heapsort. Although quicksort is slightly faster, it has worse worst-case performance than heapsort and it also needs extra storage, that heapsort does not. In an embedded system worst-case behaviour is a rather important issue and usually you can't just allocate an unknown amount of temporary memory. Since the C99 standard does not specify that the qsort() function must actually implement quicksort, it seemed prudent to choose a sort algorithm that behaves well in those respects. Regardless of whether your array is random, sorted, or sorted in opposite direction you can expect around `nmemb` * log2(`nmemb`) swaps of array elements and up to twice as many comapares.

int random_r | ( | int * | state | ) |

Random number generator.

The function receives a state, which must have been prepared by the srandom_r() function, and returns a pseudorandom number and updates the state. The state must not be modified between calls and if it is shared between execution contexts, then mutual exclusivity must be ascertained.

If the size of the state is 2 words (see the srandom_r() function), then the classical rand() algorithm is used, which is a linear congruential generator. If the size is 8, 16, 32 or 64 words, then an additive lagged Fibonacci generator is used. The runtime of the latter generator is independent of the state size and it is very fast.

Note that although the generated numbers are high quality in terms of randomness (they have good statistical properties), they are not cryptographically safe. If you want to use this generator for cryptography, you should feed its output to a hash or cipher function and use the result of that as your random sequence. In addition, for cryptographic purposes you must assure that your seed is indeed random, preferably generated by some truly random process.

Parameters:

  | state | The state array which must have been initialised by the srandom_r() function.

Returns:
  A random number between 0 and RAND_MAX, which is actually defined as 231-1 (i.e. the largest 32-bit signed positive integer).

int* srandom_r | ( | int | seed,
|  | int * | state,
|  | size_t | size |
| ) |  |  |

Initialises the random number generator.

This function takes a 32-bit seed, and array of integers and the size of that array. It then initialises the array so that it can be used as the state for a pseudo-random generator.

The integer array should be 2, 8, 16, 32 or 64 ints long. Sizes other than the above will be rejected. The goodness and the period of the generator increases as you increase the size. Larger sizes mean longer execution time for this function, but the time consumption of the random_r() function remains the same.

Parameters:

  | seed | The seed of the generator. It should not be 0 and should not be negative, if it is, then it is taken as 1.
  | state | An array of 2, 8, 16, 32 or 64 integers, this will be the random number generator's state. This array must not be modified after the call except by the random_r() routine itself.
  | size | The size of the array, as returned by the `sizeof()` operator (i.e. size in bytes, not in words!)

Returns:
  The state pointer, if it succeeded or NULL, if the size argument wasn't one of the allowed values.

double strtod | ( | const char * | nptr,
|  | char ** | eptr |
| ) |  |  |

Convert a string to a double.

The function is identical in semantics to the strtode() function except that it does not provide a feedback on overlow conditions.

Parameters:

  | nptr | Pointer to the string to convert.
  | eptr | Pointer to a location to store the address of the first character that was not converted. NULL is allowed.

Returns:
  The numeric result of the conversion, if it was successful, the largest or smallest fload if there was an overflow and 0, if there was a conversion error.

double strtode | ( | const char * | nptr,
|  | char ** | eptr,
|  | void(*)(void) | optr |
| ) |  |  |

Convert a string to double precision float number.

The function processes the string pointed by the `nptr` parameter. Initial whitespace is skipped, then a possible '+' or '-' signum is processed. Following that, if the string starts with 0x or 0X followed by at least one hexadecimal digit, then a hexadecimal float conversion takes place. The format of the hexadecimal float number is a sequence if integer hexadecimal digits, an optional '.' followed by optional hexadecimal fractional digits, followed by an optional 'p' or 'P' exponent separator followed by an optional '+' or '-' exponent signum, followed by a sequence of decimal digits. The hexadecimal integer and fractinal digits are converted to a float point number in radix 16 and the exponent is interpreted as a power of 2. Note that the integer part of the mantissa can not be empty (it can be 0, but at least one hexadecimal digit must be present before the radix point or the exponent). If the number does not start with 0x, then a decimal conversion is attempted. If the signum is followed by a sequence of decimal digits, then it is the integer part of the mantissa. It can optionally followed by a '.' optionally followed by more decimal digits, that form the fractional part of the mantissa. The integer and fractional parts can't both be empty. If the number start with the decimal radix point, then the integer part of the mantissa is implicitely assumed to be 0. The mantissa is possibly followed by 'e' or 'E', followed by an optional '+' or '-', followed by a sequence of decimal digits. The 'E' and the characters following it are the decimal exponent. If the optional signum of the mantissa is followed by a case insensitive string of NAN, then the conversion result is a NaN (which is unsigned). If the string starts with INF, then the result will be a signed infinity. In that case, the input is further consumed up until the word INFINITY is found in full or the first character that doesn't match the word is found.

If the `eptr` argument is not NULL, then a pointer to the first character that was rejected will be stored at the location it points to. If there was no conversion, then the original pointer to the string will be stored.

If the conversion results in an overflow, then the returned value is the largest (absolute value) number representable in an IEEE-754 double is returned; in case of underflow the smallest such number is returned.

Parameters:

  | nptr | Pointer to the string to convert.
  | eptr | Pointer to a location to store the address of the first character that was not converted. NULL is allowed.
  | optr | Pointer to void (*)(void) function that will be called if there was an uder- or overflow. NULL is allowed. This facility can be used to implement errno in a system dependent manner.

Returns:
  The numeric result of the conversion, if it was successful, and 0, if there was a conversion error.

Note:
  This function is not a standard library function. Furthermore, the standard declares that in string representation either INF or INFINITY is to signal infinity. This implementation accepts any leading substring of INFINITY that is at least 3 characters long (i.e. INF or INFI or INFINIT are all accepted).

long strtol | ( | const char * | nptr,
|  | char ** | eptr,
|  | int | base |
| ) |  |  |

Convert a string to a signed long number.

The function is identical in semantics to the strtole() function except that it does not provide a feedback on overflow conditions.

Parameters:

  | nptr | Pointer to the string to convert.
  | eptr | Pointer to a location to store the address of the first character that was not converted. NULL is allowed.
  | base | The conversion base, must be 0 or between 2 and 36.

Returns:
  The numeric result of the conversion, if it was successful, the largest 32-bit unsigned integer if there was an overflow and undetermined, if there was a conversion error.

long strtole | ( | const char * | nptr,
|  | char ** | eptr,
|  | int | base,
|  | void(*)(void) | optr |
| ) |  |  |

Convert a string to a signed long number.

The function processes the string pointed by the `nptr` parameter. Initial whitespace is skipped, then a possible '+' or '-' signum is processed. Following that, characters that are valid digits in the radix specified by `base` will be processed. The conversion stops if a character that is not a valid digit in the givern radix is encountered. The returned value is the converted number, or 0 if there was an error.

If the `eptr` argument is not NULL, then a pointer to the character that was rejected will be stored at the location it points to. If there was no conversion, then the original pointer to the string will be stored.

If the conversion overflows, then the function returns the largest 32-bit positive or negative (if a '-' was present) signed integer. If the `optr` argument is not NULL, then a non-zero value will be stored at the pointed location if there was an overflow, and 0 if there was not.

The conversion radix must be between 2 and 36, inclusive. If the radix is out of range, then no conversion will take place. If the conversion radix is 16, then the sequence of digits can start with 0x or 0X, the x character is only processed if it is actually followed by at least one hexadecimal digit. A special case of the radix being 0 is also allowed. In that case if the digit sequence starts with 0x or 0X, then base-16 conversion takes place, otherwise if the sequence starts with 0, then octal conversion takes place, otherwise decimal conversion is attempted.

Parameters:

  | nptr | Pointer to the string to convert.
  | eptr | Pointer to a location to store the address of the first character that was not converted. NULL is allowed.
  | base | The conversion base, must be 0 or between 2 and 36.
  | optr | Pointer to void (*)(void) function that will be called if there was an overflow. NULL is allowed. This facility can be used to implement errno in a system dependent manner.

Returns:
  The numeric result of the conversion, if it was successful, the largest 32-bit signed integer with the relevant signum if there was an overflow and 0, if there was a conversion error.

Note:
  This function is not a standard library function.

long long strtoll | ( | const char * | nptr,
|  | char ** | eptr,
|  | int | base |
| ) |  |  |

Convert a string to a signed long long number.

The function is identical in semantics to the strtolle() function except that it does not provide a feedback on overlow conditions.

Parameters:

  | nptr | Pointer to the string to convert.
  | eptr | Pointer to a location to store the address of the first character that was not converted. NULL is allowed.
  | base | The conversion base, must be 0 or between 2 and 36.

Returns:
  The numeric result of the conversion, if it was successful, the largest 64-bit signed integer with the given signum if there was an overflow and 0, if there was a conversion error.

long long strtolle | ( | const char * | nptr,
|  | char ** | eptr,
|  | int | base,
|  | void(*)(void) | optr |
| ) |  |  |

Convert a string to a signed long long number.

The function processes the string pointed by the `nptr` parameter. Initial whitespace is skipped, then a possible '+' or '-' signum is processed. Following that, characters that are valid digits in the radix specified by `base` will be processed. The conversion stops if a character that is not a valid digit in the givern radix is encountered. The returned value is the converted number, or 0 if there was an error.

If the `eptr` argument is not NULL, then a pointer to the character that was rejected will be stored at the location it points to. If there was no conversion, then the original pointer to the string will be stored.

If the conversion overflows, then the function returns the largest 64-bit positive integer or the larges 64-bit negative integer, depending on whether a '-' signum was present. If the `optr` argument is not NULL, then a non-zero value will be stored at the pointed location if there was an overflow, and 0 if there was not.

The conversion radix must be between 2 and 36, inclusive. If the radix is out of range, then no conversion will take place. If the conversion radix is 16, then the sequence of digits can start with 0x or 0X, the x character is only processed if it is actually followed by at least one hexadecimal digit. A special case of the radix being 0 is also allowed. In that case if the digit sequence starts with 0x or 0X, then base-16 conversion takes place, otherwise if the sequence starts with 0, then octal conversion takes place, otherwise decimal conversion is attempted.

Parameters:

  | nptr | Pointer to the string to convert.
  | eptr | Pointer to a location to store the address of the first character that was not converted. NULL is allowed.
  | base | The conversion base, must be 0 or between 2 and 36.
  | optr | Pointer to void (*)(void) function that will be called if there was an overflow. NULL is allowed. This facility can be used to implement errno in a system dependent manner.

Returns:
  The numeric result of the conversion, if it was successful, the largest 64-bit signed integer with the given signum if there was an overflow and 0, if there was a conversion error.

Note:
  This function is not a standard library function.

unsigned long strtoul | ( | const char * | nptr,
|  | char ** | eptr,
|  | int | base |
| ) |  |  |

Convert a string to an unsigned long number.

The function is identical in semantics to the strtoulle() function except that it does not provide a feedback on overflow conditions.

Parameters:

  | nptr | Pointer to the string to convert.
  | eptr | Pointer to a location to store the address of the first character that was not converted. NULL is allowed.
  | base | The conversion base, must be 0 or between 2 and 36.

Returns:
  The numeric result of the conversion, if it was successful, the largest 64-bit unsigned integer if there was an overflow and undetermined, if there was a conversion error.

unsigned long strtoule | ( | const char * | nptr,
|  | char ** | eptr,
|  | int | base,
|  | void(*)(void) | optr |
| ) |  |  |

Convert a string to an unsigned long number.

The function processes the string pointed by the `nptr` parameter. Initial whitespace is skipped, then a possible '+' or '-' signum is processed. Following that, characters that are valid digits in the radix specified by `base` will be processed. The conversion stops if a character that is not a valid digit in the givern radix is encountered. The returned value is the converted number, or 0 if there was an error.

If the `eptr` argument is not NULL, then a pointer to the character that was rejected will be stored at the location it points to. If there was no conversion, then the original pointer to the string will be stored.

If the conversion overflows, then the function returns the largest 32-bit unsigned integer (all 1-s). If the `optr` argument is not NULL, then a non-zero value will be stored at the pointed location if there was an overflow, and 0 if there was not.

If a negative sign was encountered and otherwise the conversion was successful, then the 2's complement of the converted number will be returned.

The conversion radix must be between 2 and 36, inclusive. If the radix is out of range, then no conversion will take place. If the conversion radix is 16, then the sequence of digits can start with 0x or 0X, the x character is only processed if it is actually followed by at least one hexadecimal digit. A special case of the radix being 0 is also allowed. In that case if the digit sequence starts with 0x or 0X, then base-16 conversion takes place, otherwise if the sequence starts with 0, then octal conversion takes place, otherwise decimal conversion is attempted.

Parameters:

  | nptr | Pointer to the string to convert.
  | eptr | Pointer to a location to store the address of the first character that was not converted. NULL is allowed.
  | base | The conversion base, must be 0 or between 2 and 36.
  | optr | Pointer to void (*)(void) function that will be called if there was an overflow. NULL is allowed. This facility can be used to implement errno in a system dependent manner.

Returns:
  The numeric result of the conversion, if it was successful, the largest 32-bit unsigned integer if there was an overflow and 0, if there was a conversion error.

Note:
  This function is not a standard library function.

unsigned long long strtoull | ( | const char * | nptr,
|  | char ** | eptr,
|  | int | base |
| ) |  |  |

Convert a string to an unsigned long long number.

The function is identical in semantics to the strtoulle() function except that it does not provide a feedback on overlow conditions.

Parameters:

  | nptr | Pointer to the string to convert.
  | eptr | Pointer to a location to store the address of the first character that was not converted. NULL is allowed.
  | base | The conversion base, must be 0 or between 2 and 36.

Returns:
  The numeric result of the conversion, if it was successful, the largest 64-bit unsigned integer if there was an overflow and undetermined, if there was a conversion error.

unsigned long long strtoulle | ( | const char * | nptr,
|  | char ** | eptr,
|  | int | base,
|  | void(*)(void) | optr |
| ) |  |  |

Convert a string to an unsigned long long number.

The function processes the string pointed by the `nptr` parameter. Initial whitespace is skipped, then a possible '+' or '-' signum is processed. Following that, characters that are valid digits in the radix specified by `base` will be processed. The conversion stops if a character that is not a valid digit in the givern radix is encountered. The returned value is the converted number, or 0 if there was an error.

If the `eptr` argument is not NULL, then a pointer to the character that was rejected will be stored at the location it points to. If there was no conversion, then the original pointer to the string will be stored.

If the conversion overflows, then the function returns the largest 64-bit integer (all 1-s). If the `optr` argument is not NULL, then a non-zero value will be stored at the pointed location if there was an overflow, and 0 if there was not.

If a negative sign was encountered and otherwise the conversion was successful, then the 2's complement of the converted number will be returned.

The conversion radix must be between 2 and 36, inclusive. If the radix is out of range, then no conversion will take place. If the conversion radix is 16, then the sequence of digits can start with 0x or 0X, the x character is only processed if it is actually followed by at least one hexadecimal digit. A special case of the radix being 0 is also allowed. In that case if the digit sequence starts with 0x or 0X, then base-16 conversion takes place, otherwise if the sequence starts with 0, then octal conversion takes place, otherwise decimal conversion is attempted.

Parameters:

  | nptr | Pointer to the string to convert.
  | eptr | Pointer to a location to store the address of the first character that was not converted. NULL is allowed.
  | base | The conversion base, must be 0 or between 2 and 36.
  | optr | Pointer to void (*)(void) function that will be called if there was an overflow. NULL is allowed. This facility can be used to implement errno in a system dependent manner.

Returns:
  The numeric result of the conversion, if it was successful, the largest 64-bit unsigned integer if there was an overflow and 0, if there was a conversion error.

Note:
  This function is not a standard library function.

udiv_t udiv | ( | unsigned | numerator,
|  | unsigned | denominator |
| ) |  |  |

Compute quotient and remainder of an unsigned integer (32-bit) division.

The function divides its `numerator` argument with its `denominator` argument and returns a structure containing the quotient and the remainder. The fields of the structure are called `quot` and `rem`, respectively. The quotient is rounded towards zero and the result is such that the following equation holds:

`numerator = quotient * denominator + remainder`

If the denominator is 0, then the behaviour is undefined.

Parameters:

  | numerator | The number to divide
  | denominator | The number to divide with

Returns:
  A structure containing both the quotient and the remainder.

Attention:
  To use this function you must link the library that contains the fast versions of the gcc support library functions (by default this library is called gccs) because that contains the actual division core.

ulldiv_t ulldiv | ( | unsigned long long | numerator,
|  | unsigned long long | denominator |
| ) |  |  |

Compute quotient and remainder of an unsigned long long (64-bit) division.

The function divides its `numerator` argument with its `denominator` argument and returns a structure containing the quotient and the remainder. The fields of the structure are called `quot` and `rem`, respectively. The quotient is rounded towards zero and the result is such that the following equation holds:

`numerator = quotient * denominator + remainder`

If the denominator is 0, then the behaviour is undefined.

Parameters:

  | numerator | The number to divide
  | denominator | The number to divide with

Returns:
  A structure containing both the quotient and the remainder.

Attention:
  To use this function you must link the library that contains the fast versions of the gcc support library functions (by default this library is called gccs) because that contains the actual division core.

int ulltostr | ( | char * | buff,
|  | unsigned long long | numb,
|  | int | base,
|  | int | uppc |
| ) |  |  |

Converts a 64-bit unsigned integer to ASCII with an arbitrary radix.

The number will be converted without leading zeroes or spaces and the result is terminated by a 0 byte.

Parameters:

  | buff | Pointer to the buffer where the result is stored. At worst case the buffer needs to be 65 bytes long.
  | numb | The unsigned 64-bit integer to convert
  | base | The conversion base, [2..36]
  | uppc | A flag indicating that for digits above 9 uppercase letters should be used.

Returns:
  The length of the final string, not counting the terminating 0. If the base is not within the 2..36 range, no conversion takes place and 0 is returned.

Note:
  This function is not a standard C library function.

int ulltostr10 | ( | char * | buff,
|  | unsigned long long | numb |
| ) |  |  |

Convert an unsigned long long to a string in radix 10.

The function converts the unsigned long long to a string, using decimal conversion. The result is stored left-aligned, without leading zeroes and it is closed with a terminating NUL. The largest number results in a 20-digit decimal, therefore the buffer must be 21 bytes long.

Parameters:

  | buff | A character buffer that must be at least 21 bytes long
  | numb | The unsigned long long to convert

Returns:
  The length of the resulting string, not counting the terminating NUL.

Note:
  This function is not a standard C library function.

int ulltostr2n | ( | char * | buff,
|  | unsigned long long | numb,
|  | int | base,
|  | int | uppc |
| ) |  |  |

Converts a 32-bit unsigned integer to ASCII in radix 2^N.

The number will be converted without leading zeroes or spaces and the result is terminated by a 0 byte.

Parameters:

  | buff | Pointer to the buffer where the result is stored. At worst case the buffer needs to be 65 bytes long.
  | numb | The unsigned long long integer to convert
  | base | The conversion base, must be a power of 2 between 2 and 32.
  | uppc | For bases 16 or 32 if this flag is true, then digits over 9 will use uppercase letters. If the flag is false, then lowercase will be used.

Returns:
  The length of the final string, not counting the terminating 0. If the radix is not a power of 2 between 2 and 32 inclusive, then no conversion takes place and 0 is returned.

Note:
  This function is not a standard C library function.

int ultostr | ( | char * | buff,
|  | unsigned long | numb,
|  | int | base,
|  | int | uppc |
| ) |  |  |

Converts a 32-bit unsigned integer to ASCII with an arbitrary radix.

The number will be converted without leading zeroes or spaces and the result is terminated by a 0 byte. If the radix is larger than 10, then the case of letters used for digits over 9 is controlled by the `uppc` argument.

Parameters:

  | buff | Pointer to the buffer where the result is stored. At worst case the buffer needs to be 33 bytes long.
  | numb | The unsigned integer to convert
  | base | The conversion base, [2..36]
  | uppc | A flag indicating that for digits above 9 uppercase letters should be used.

Returns:
  The length of the final string, not counting the terminating 0. If the base is not within the 2..36 range, no conversion takes place and 0 is returned.

Note:
  This function is not a standard C library function.

int ultostr10 | ( | char * | buff,
|  | unsigned long | numb |
| ) |  |  |

Converts a 32-bit unsigned integer to ASCII in radix 10.

The number will be converted without leading zeroes or spaces and the result is terminated by a NUL byte.

Parameters:

  | numb | The unsigned integer to convert
  | buff | Pointer to the buffer where the result is stored. At worst case the buffer needs to be 11 bytes long.

Returns:
  The length of the final string, not counting the terminating NUL.

Note:
  This function is not a standard C library function.

int ultostr2n | ( | char * | buff,
|  | unsigned long | numb,
|  | int | base,
|  | int | uppc |
| ) |  |  |

Converts a 32-bit unsigned integer to ASCII in radix 2^N.

The number will be converted without leading zeroes or spaces and the result is terminated by a 0 byte.

Parameters:

  | buff | Pointer to the buffer where the result is stored. At worst case the buffer needs to be 33 bytes long.
  | numb | The unsigned integer to convert
  | base | Conversion base, one of 2, 4, 8, 16 or 32.
  | uppc | For bases 16 or 32 if this flag is true, then digits over 9 will use uppercase letters. If the flag is false, then lowercase will be used.

Returns:
  The length of the final string, not counting the terminating 0. If the radix is not a power of 2 between 2 and 32 inclusive, then no conversion takes place and 0 is returned.

Note:
  This function is not a standard C library function.