[[libnew:stdlib]]

This shows you the differences between two versions of the page.

libnew:stdlib [2015/08/27 17:29] aralbrec completed |
libnew:stdlib [2016/05/21 03:04] (current) aralbrec |
||
---|---|---|---|

Line 4: | Line 4: | ||

^ Header | [[http://z88dk.cvs.sourceforge.net/viewvc/z88dk/z88dk/include/_DEVELOPMENT/sccz80/stdlib.h?content-type=text%2Fplain|{z88dk}/include/_DEVELOPMENT/sccz80/stdlib.h]] | | ^ Header | [[http://z88dk.cvs.sourceforge.net/viewvc/z88dk/z88dk/include/_DEVELOPMENT/sccz80/stdlib.h?content-type=text%2Fplain|{z88dk}/include/_DEVELOPMENT/sccz80/stdlib.h]] | | ||

^ | [[http://z88dk.cvs.sourceforge.net/viewvc/z88dk/z88dk/include/_DEVELOPMENT/sdcc/stdlib.h?content-type=text%2Fplain|{z88dk}/include/_DEVELOPMENT/sdcc/stdlib.h]] | | ^ | [[http://z88dk.cvs.sourceforge.net/viewvc/z88dk/z88dk/include/_DEVELOPMENT/sdcc/stdlib.h?content-type=text%2Fplain|{z88dk}/include/_DEVELOPMENT/sdcc/stdlib.h]] | | ||

- | ^ Source | [[http://z88dk.cvs.sourceforge.net/viewvc/z88dk/z88dk/libsrc/_DEVELOPMENT/stdlib/z80/|{z88dk}/libsrc/_DEVELOPMENT/stdlib]] | | ||

Other References: | Other References: | ||

Line 28: | Line 27: | ||

===== TYPES ===== | ===== TYPES ===== | ||

- | ^ size_t | unsigned int | | + | ^ size_t | unsigned int | |

- | ^ wchar_t | unsigned char<sup>**1**</sup> | | + | ^ wchar_t | unsigned char<sup>**1**</sup> | |

- | | | | | + | | | | |

- | ^ float_t | float type suppresses compiler warnings<sup>**2**</sup> | | + | ^ float_t | float type suppresses compiler warnings<sup>**2**</sup> | |

- | ^ double_t | double type suppresses compiler warnings<sup>**2**</sup> | | + | ^ double_t | double type suppresses compiler warnings<sup>**2**</sup> | |

- | | | | | + | | | | |

- | ^ div_t | struct { int rem; int quot; }; | | + | ^ div_t | struct { int rem; int quot; }; | |

- | ^ divu_t | struct { unsigned int rem; unsigned int quot; }; | | + | ^ divu_t | struct { unsigned int rem; unsigned int quot; }; | |

- | ^ ldiv_t | struct { long quot; long rem; }; | | + | ^ ldiv_t | struct { long quot; long rem; }; | |

- | ^ ldivu_t | struct { unsigned long quot; unsigned long rem; }; | | + | ^ ldivu_t | struct { unsigned long quot; unsigned long rem; }; | |

+ | ^ lldiv_t<sup>**3**</sup> | struct { long long rem; long long quot; }; | | ||

+ | ^ lldivu_t<sup>**3**</sup> | struct { unsigned long long rem; unsigned long long quot; }; | | ||

<sup>**1**</sup> Wide characters are not supported by the library and are aliased to chars. | <sup>**1**</sup> Wide characters are not supported by the library and are aliased to chars. | ||

<sup>**2**</sup> The compilers only support one floating point type so float and double are aliased. | <sup>**2**</sup> The compilers only support one floating point type so float and double are aliased. | ||

+ | <sup>**3**</sup> Nightly build, sdcc only. | ||

====== NUMERIC CONVERSIONS ====== | ====== NUMERIC CONVERSIONS ====== | ||

Line 53: | Line 55: | ||

==== char *itoa(int num, char *buf, int radix) ==== | ==== char *itoa(int num, char *buf, int radix) ==== | ||

- | Writes the integer //num// as a nul-terminated string into the buffer pointed at by //buf// using the indicated //radix//. If //radix// is ten, indicating a decimal number, //num// is treated as signed so that a negative number will have a preceding minus sign written to the buffer. Any other radix treats //num// as an unsigned number. | + | Writes the integer //num// as a nul-terminated string into the buffer pointed at by //buf// using the indicated //radix//. Returns a pointer in //buf// to the terminating NUL char. If //radix// is ten, indicating a decimal number, //num// is treated as signed so that a negative number will have a preceding minus sign written to the buffer. Any other radix treats //num// as an unsigned number. |

The buffer pointed to by //buf// must be large enough to hold the result to avoid buffer overrun (minimum 17 bytes for base 2). If //buf// is 0 the function immediately returns with 0 result and carry flag set. | The buffer pointed to by //buf// must be large enough to hold the result to avoid buffer overrun (minimum 17 bytes for base 2). If //buf// is 0 the function immediately returns with 0 result and carry flag set. | ||

Line 81: | Line 83: | ||

==== char *ltoa(long num, char *buf, int radix) ==== | ==== char *ltoa(long num, char *buf, int radix) ==== | ||

- | Writes the long //num// as a nul-terminated string into the buffer pointed at by //buf// using the indicated //radix//. If //radix// is ten, indicating a decimal number, //num// is treated as signed so that a negative number will have a preceding minus sign written to the buffer. Any other radix treats //num// as an unsigned number. | + | Writes the long //num// as a nul-terminated string into the buffer pointed at by //buf// using the indicated //radix//. Returns a pointer in //buf// to the terminating NUL char. If //radix// is ten, indicating a decimal number, //num// is treated as signed so that a negative number will have a preceding minus sign written to the buffer. Any other radix treats //num// as an unsigned number. |

The buffer pointed to by //buf// must be large enough to hold the result to avoid buffer overrun (minimum 33 bytes for base 2). If //buf// is 0 the function immediately returns with 0 result and carry flag set. | The buffer pointed to by //buf// must be large enough to hold the result to avoid buffer overrun (minimum 33 bytes for base 2). If //buf// is 0 the function immediately returns with 0 result and carry flag set. | ||

Line 110: | Line 112: | ||

As strtol() but out of range numbers saturate at +2<sup>32</sup>-1. Negative numbers receive two's complement. | As strtol() but out of range numbers saturate at +2<sup>32</sup>-1. Negative numbers receive two's complement. | ||

+ | |||

+ | ===== LONG LONG ===== | ||

+ | |||

+ | ==== long long atoll(char *buf) ==== | ||

+ | |||

+ | (nightly build, sdcc)\\ | ||

+ | |||

+ | An alias for strtoll(buf, 0, 10) | ||

+ | |||

+ | ==== char *lltoa(long long num, char *buf, int radix) ==== | ||

+ | |||

+ | (nightly build, sdcc)\\ | ||

+ | |||

+ | Writes the long long //num// as a nul-terminated string into the buffer pointed at by //buf// using the indicated //radix//. Returns a pointer in //buf// to the terminating NUL char. If //radix// is ten, indicating a decimal number, //num// is treated as signed so that a negative number will have a preceding minus sign written to the buffer. Any other radix treats //num// as an unsigned number. | ||

+ | |||

+ | The buffer pointed to by //buf// must be large enough to hold the result to avoid buffer overrun (minimum 65 bytes for base 2). If //buf// is 0 the function immediately returns with 0 result and carry flag set. | ||

+ | |||

+ | If an error occurs, the carry flag is set, 0 is returned and errno will be set to: | ||

+ | |||

+ | * [EINVAL] //radix// is not in the range [2,36] | ||

+ | |||

+ | ==== char *ulltoa(unsigned long long num, char *buf, int radix) ==== | ||

+ | |||

+ | (nightly build, sdcc)\\ | ||

+ | |||

+ | As lltoa() but //num// is treated as unsigned. This only differs from lltoa() for base 10 conversion. | ||

+ | |||

+ | ==== long long strtoll(const char *nptr, char **endptr, int base) ==== | ||

+ | |||

+ | (nightly build, sdcc)\\ | ||

+ | |||

+ | Parses the C-string //nptr//, interpreting its content as a signed integral number of radix //base// and returns this number as a long long. If //endptr// is not 0, the function also sets //endptr// to point to the first character after the number. | ||

+ | |||

+ | The function first discards any leading whitespace and then accepts the longest string of characters that can compose a number of radix //base//. This number is converted to a long long and returned as a result. If an overflow occurs, the result saturates at +2<sup>63</sup>-1 or -2<sup>63</sup>. If there are no valid digits, 0 is returned. If //base// is not in [0,2-36], 0 is returned. | ||

+ | |||

+ | If //base// is 0, the radix used is determined from the string. A leading '0x' or '0X' indicates the number is base 16, a leading '0' indicates the number is base 8, otherwise the number is base 10. | ||

+ | |||

+ | If an error occurs, the return value is as described above, carry flag will be set and errno will be set to: | ||

+ | |||

+ | * [EINVAL] no valid digits in the radix indicated | ||

+ | * [EINVAL] radix is not in the range [0,2-36] | ||

+ | * [ERANGE] an overflow occurred during conversion | ||

+ | |||

+ | ==== unsigned long long strtoull(const char *nptr, char **endptr, int base) ==== | ||

+ | |||

+ | (nightly build, sdcc)\\ | ||

+ | |||

+ | As strtoll() but out of range numbers saturate at +2<sup>64</sup>-1. Negative numbers receive two's complement. | ||

===== FLOATING POINT ===== | ===== FLOATING POINT ===== | ||

Line 125: | Line 175: | ||

The function first discards any leading whitespace and then accepts the longest string of characters that can compose a double. This string is converted to a double and returned as the result. | The function first discards any leading whitespace and then accepts the longest string of characters that can compose a double. This string is converted to a double and returned as the result. | ||

- | An acceptable input string encodes a double in either decimal form or hexadecimal form or contains the strings "inf", "infinity", "nan" or "nan(*)" in either lower case or upper case. Decimal form looks like "+-ddd.ddde+-ddd" where the signs, decimal point and exponential indicator are optional. Hexadecimal form looks like "+-0xhhh.hhhp+-ddd" where the signs, decimal point and exponential indicator are optional and the "h" indicate hexadecimal digits. Hexadecimal form represents the exact bit pattern stored in the internal double representation. | + | An acceptable input string encodes a double in either decimal form or hexadecimal form or contains the strings "inf", "infinity", "nan" or "nan(*)" in either lower case or upper case. Decimal form looks like "+-ddd.ddde+-ddd" where the signs, decimal point and exponential indicator are optional. Hexadecimal form looks like "+-0xhhh.hhhp+-ddd" where the signs, decimal point and exponential indicator are optional and the "h" indicate hexadecimal digits. Hexadecimal form represents the exact bit pattern stored in the internal double representation. **Note that library configuration may disable parsing of hex strings and/or the special strings "inf", etc**. |

If an error occurs, the return value is as indicated below, the carry flag is set and errno is set to: | If an error occurs, the return value is as indicated below, the carry flag is set and errno is set to: | ||

Line 195: | Line 245: | ||

====== MEMORY MANAGEMENT ====== | ====== MEMORY MANAGEMENT ====== | ||

- | See [[libnew:alloc_malloc|malloc.h]]. | + | See [[libnew:alloc_malloc#memory_management_functions|malloc.h]]. |

==== void *aligned_alloc(size_t alignment, size_t size) ==== | ==== void *aligned_alloc(size_t alignment, size_t size) ==== | ||

Line 292: | Line 342: | ||

==== long labs(long j) ==== | ==== long labs(long j) ==== | ||

+ | |||

+ | Return the absolute value of //j//. | ||

+ | |||

+ | ==== long long llabs(long long j) ==== | ||

+ | |||

+ | (nightly build, sdcc)\\ | ||

Return the absolute value of //j//. | Return the absolute value of //j//. | ||

Line 324: | Line 380: | ||

On division by zero, the quotient is +ULONG_MAX, the remainder is //numer//, carry flag is set and errno is set to: | On division by zero, the quotient is +ULONG_MAX, the remainder is //numer//, carry flag is set and errno is set to: | ||

+ | |||

+ | * [EDOM] division by zero | ||

+ | |||

+ | ==== void _lldiv_(lldiv_t *d, long long numer, long long denom) ==== | ||

+ | |||

+ | (nightly build, sdcc)\\ | ||

+ | |||

+ | Use a single signed long long division //(numer / denom)// to compute quotient and remainder and store that in the struct pointed at by //d//. | ||

+ | |||

+ | On division by zero, the quotient is +LLONG_MAX or -LLONG_MIN, the remainder is //numer//, carry flag is set and errno is set to: | ||

+ | |||

+ | * [EDOM] division by zero | ||

+ | |||

+ | ==== void _lldivu_(lldivu_t *d, unsigned long long numer, unsigned long long denom) ==== | ||

+ | |||

+ | (nightly build, sdcc)\\ | ||

+ | |||

+ | Use a single unsigned long long division //(numer / denom)// to compute quotient and remainder and store that in the struct pointed at by //d//. | ||

+ | |||

+ | On division by zero, the quotient is +ULLONG_MAX, the remainder is //numer//, carry flag is set and errno is set to: | ||

* [EDOM] division by zero | * [EDOM] division by zero | ||