pd.if.org Git - pdclib/blob - includes/stdlib.h

   1 /* 7.20 General utilities <stdlib.h>
   2
   3    This file is part of the Public Domain C Library (PDCLib).
   4    Permission is granted to use, modify, and / or redistribute at will.
   5 */
   6
   7 #ifndef _PDCLIB_STDLIB_H
   8 #define _PDCLIB_STDLIB_H _PDCLIB_STDLIB_H
   9 #include <_PDCLIB_int.h>
  10 _PDCLIB_BEGIN_EXTERN_C
  11
  12 #ifndef _PDCLIB_SIZE_T_DEFINED
  13 #define _PDCLIB_SIZE_T_DEFINED _PDCLIB_SIZE_T_DEFINED
  14 typedef _PDCLIB_size_t size_t;
  15 #endif
  16
  17 #ifndef _PDCLIB_NULL_DEFINED
  18 #define _PDCLIB_NULL_DEFINED _PDCLIB_NULL_DEFINED
  19 #define NULL _PDCLIB_NULL
  20 #endif
  21
  22 #ifndef _PDCLIB_MB_CUR_MAX_DEFINED
  23 #define _PDCLIB_MB_CUR_MAX_DEFINED
  24 #define MB_CUR_MAX (_PDCLIB_mb_cur_max())
  25 #endif
  26
  27 /* Numeric conversion functions */
  28
  29 /* TODO: atof(), strtof(), strtod(), strtold() */
  30
  31 double atof( const char * nptr ) _PDCLIB_nothrow;
  32 double strtod( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr ) _PDCLIB_nothrow;
  33 float strtof( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr ) _PDCLIB_nothrow;
  34 long double strtold( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr ) _PDCLIB_nothrow;
  35
  36 /* Seperate the character array nptr into three parts: A (possibly empty)
  37    sequence of whitespace characters, a character representation of an integer
  38    to the given base, and trailing invalid characters (including the terminating
  39    null character). If base is 0, assume it to be 10, unless the integer
  40    representation starts with 0x / 0X (setting base to 16) or 0 (setting base to
  41    8). If given, base can be anything from 0 to 36, using the 26 letters of the
  42    base alphabet (both lowercase and uppercase) as digits 10 through 35.
  43    The integer representation is then converted into the return type of the
  44    function. It can start with a '+' or '-' sign. If the sign is '-', the result
  45    of the conversion is negated.
  46    If the conversion is successful, the converted value is returned. If endptr
  47    is not a NULL pointer, a pointer to the first trailing invalid character is
  48    returned in *endptr.
  49    If no conversion could be performed, zero is returned (and nptr in *endptr,
  50    if endptr is not a NULL pointer). If the converted value does not fit into
  51    the return type, the functions return LONG_MIN, LONG_MAX, ULONG_MAX,
  52    LLONG_MIN, LLONG_MAX, or ULLONG_MAX respectively, depending on the sign of
  53    the integer representation and the return type, and errno is set to ERANGE.
  54 */
  55 /* There is strtoimax() and strtoumax() in <inttypes.h> operating on intmax_t /
  56    uintmax_t, if the long long versions do not suit your needs.
  57 */
  58 long int strtol( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
  59 long long int strtoll( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
  60 unsigned long int strtoul( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
  61 unsigned long long int strtoull( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
  62
  63 /* These functions are the equivalent of (int)strtol( nptr, NULL, 10 ),
  64    strtol( nptr, NULL, 10 ) and strtoll(nptr, NULL, 10 ) respectively, with the
  65    exception that they do not have to handle overflow situations in any defined
  66    way.
  67    (PDCLib does not simply forward these to their strtox() equivalents, but
  68    provides a simpler atox() function that saves a couple of tests and simply
  69    continues with the conversion in case of overflow.)
  70 */
  71 int atoi( const char * nptr ) _PDCLIB_nothrow;
  72 long int atol( const char * nptr ) _PDCLIB_nothrow;
  73 long long int atoll( const char * nptr ) _PDCLIB_nothrow;
  74
  75 /* Pseudo-random sequence generation functions */
  76
  77 extern unsigned long int _PDCLIB_seed;
  78
  79 #define RAND_MAX 32767
  80
  81 /* Returns the next number in a pseudo-random sequence, which is between 0 and
  82    RAND_MAX.
  83    (PDCLib uses the implementation suggested by the standard document, which is
  84    next = next * 1103515245 + 12345; return (unsigned int)(next/65536) % 32768;)
  85 */
  86 int rand( void ) _PDCLIB_nothrow;
  87
  88 /* Initialize a new pseudo-random sequence with the starting seed. Same seeds
  89    result in the same pseudo-random sequence. The default seed is 1.
  90 */
  91 void srand( unsigned int seed ) _PDCLIB_nothrow;
  92
  93 /* Memory management functions */
  94
  95 /* Allocate a chunk of heap memory of given size. If request could not be
  96    satisfied, return NULL. Otherwise, return a pointer to the allocated
  97    memory. Memory contents are undefined.
  98 */
  99 void * malloc( size_t size ) _PDCLIB_nothrow;
 100
 101 /* Allocate a chunk of heap memory that is large enough to hold nmemb elements
 102    of the given size, and zero-initialize that memory. If request could not be
 103    satisfied, return NULL. Otherwise, return a pointer to the allocated
 104    memory.
 105 */
 106 void * calloc( size_t nmemb, size_t size ) _PDCLIB_nothrow;
 107
 108 /* De-allocate a chunk of heap memory previously allocated using malloc(),
 109    calloc(), or realloc(), and pointed to by ptr. If ptr does not match a
 110    pointer previously returned by the mentioned allocation functions, or
 111    free() has already been called for this ptr, behaviour is undefined.
 112 */
 113 void free( void * ptr ) _PDCLIB_nothrow;
 114
 115 /* Resize a chunk of memory previously allocated with malloc() and pointed to
 116    by ptr to the given size (which might be larger or smaller than the original
 117    size). Returns a pointer to the reallocated memory, or NULL if the request
 118    could not be satisfied. Note that the resizing might include a memcpy()
 119    from the original location to a different one, so the return value might or
 120    might not equal ptr. If size is larger than the original size, the value of
 121    memory beyond the original size is undefined. If ptr is NULL, realloc()
 122    behaves like malloc().
 123 */
 124 void * realloc( void * ptr, size_t size ) _PDCLIB_nothrow;
 125
 126 /* Communication with the environment */
 127
 128 /* These two can be passed to exit() or _Exit() as status values, to signal
 129    successful and unsuccessful program termination, respectively. EXIT_SUCCESS
 130    can be replaced by 0. How successful or unsuccessful program termination are
 131    signaled to the environment, and what happens if exit() or _Exit() are being
 132    called with a value that is neither of the three, is defined by the hosting
 133    OS and its glue function.
 134 */
 135 #define EXIT_SUCCESS _PDCLIB_SUCCESS
 136 #define EXIT_FAILURE _PDCLIB_FAILURE
 137
 138 /* Initiate abnormal process termination, unless programm catches SIGABRT and
 139    does not return from the signal handler.
 140    This implementantion flushes all streams, closes all files, and removes any
 141    temporary files before exiting with EXIT_FAILURE.
 142    abort() does not return.
 143 */
 144 _PDCLIB_noreturn void abort( void ) _PDCLIB_nothrow;
 145
 146 /* Register a function that will be called on exit(), or when main() returns.
 147    At least 32 functions can be registered this way, and will be called in
 148    reverse order of registration (last-in, first-out).
 149    Returns zero if registration is successfull, nonzero if it failed.
 150 */
 151 int atexit( void (*func)( void ) ) _PDCLIB_nothrow;
 152
 153 /* Normal process termination. Functions registered by atexit() (see above) are
 154    called, streams flushed, files closed and temporary files removed before the
 155    program is terminated with the given status. (See comment for EXIT_SUCCESS
 156    and EXIT_FAILURE above.)
 157    exit() does not return.
 158 */
 159 _PDCLIB_noreturn void exit( int status ) _PDCLIB_nothrow;
 160
 161 /* Normal process termination. Functions registered by atexit() (see above) are
 162    NOT CALLED. This implementation DOES flush streams, close files and removes
 163    temporary files before the program is teminated with the given status. (See
 164    comment for EXIT_SUCCESS and EXIT_FAILURE above.)
 165    _Exit() does not return.
 166 */
 167 _PDCLIB_noreturn void _Exit( int status ) _PDCLIB_nothrow;
 168
 169 /* Search an environment-provided key-value map for the given key name, and
 170    return a pointer to the associated value string (or NULL if key name cannot
 171    be found). The value string pointed to might be overwritten by a subsequent
 172    call to getenv(). The library never calls getenv() itself.
 173    Details on the provided keys and how to set / change them are determined by
 174    the hosting OS and its glue function.
 175 */
 176 char * getenv( const char * name ) _PDCLIB_nothrow;
 177
 178 /* If string is a NULL pointer, system() returns nonzero if a command processor
 179    is available, and zero otherwise. If string is not a NULL pointer, it is
 180    passed to the command processor. If system() returns, it does so with a
 181    value that is determined by the hosting OS and its glue function.
 182 */
 183 int system( const char * string ) _PDCLIB_nothrow;
 184
 185 /* Searching and sorting */
 186
 187 /* Do a binary search for a given key in the array with a given base pointer,
 188    which consists of nmemb elements that are of the given size each. To compare
 189    the given key with an element from the array, the given function compar is
 190    called (with key as first parameter and a pointer to the array member as
 191    second parameter); the function should return a value less than, equal to,
 192    or greater than 0 if the key is considered to be less than, equal to, or
 193    greater than the array element, respectively.
 194    The function returns a pointer to the first matching element found, or NULL
 195    if no match is found.
 196
 197    ** May throw **
 198 */
 199 void * bsearch( const void * key, const void * base, size_t nmemb, size_t size, int (*compar)( const void *, const void * ) );
 200
 201 /* Do a quicksort on an array with a given base pointer, which consists of
 202    nmemb elements that are of the given size each. To compare two elements from
 203    the array, the given function compar is called, which should return a value
 204    less than, equal to, or greater than 0 if the first argument is considered
 205    to be less than, equal to, or greater than the second argument, respectively.
 206    If two elements are compared equal, their order in the sorted array is not
 207    specified.
 208
 209    ** May throw **
 210 */
 211 void qsort( void * base, size_t nmemb, size_t size, int (*compar)( const void *, const void * ) );
 212
 213 /* Integer arithmetic functions */
 214
 215 /* Return the absolute value of the argument. Note that on machines using two-
 216    complement's notation (most modern CPUs), the largest negative value cannot
 217    be represented as positive value. In this case, behaviour is unspecified.
 218 */
 219 int abs( int j ) _PDCLIB_nothrow;
 220 long int labs( long int j ) _PDCLIB_nothrow;
 221 long long int llabs( long long int j ) _PDCLIB_nothrow;
 222
 223 /* These structures each have a member quot and a member rem, of type int (for
 224    div_t), long int (for ldiv_t) and long long it (for lldiv_t) respectively.
 225    The order of the members is platform-defined to allow the div() functions
 226    below to be implemented efficiently.
 227 */
 228 typedef struct _PDCLIB_div_t     div_t;
 229 typedef struct _PDCLIB_ldiv_t   ldiv_t;
 230 typedef struct _PDCLIB_lldiv_t lldiv_t;
 231
 232 /* Return quotient (quot) and remainder (rem) of an integer division in one of
 233    the structs above.
 234 */
 235 div_t div( int numer, int denom ) _PDCLIB_nothrow;
 236 ldiv_t ldiv( long int numer, long int denom ) _PDCLIB_nothrow;
 237 lldiv_t lldiv( long long int numer, long long int denom ) _PDCLIB_nothrow;
 238
 239 /* TODO: Multibyte / wide character conversion functions */
 240
 241 /* TODO: Macro MB_CUR_MAX */
 242
 243 /*
 244 int mblen( const char * s, size_t n );
 245 int mbtowc( wchar_t * _PDCLIB_restrict pwc, const char * _PDCLIB_restrict s, size_t n );
 246 int wctomb( char * s, wchar_t wc );
 247 size_t mbstowcs( wchar_t * _PDCLIB_restrict pwcs, const char * _PDCLIB_restrict s, size_t n );
 248 size_t wcstombs( char * _PDCLIB_restrict s, const wchar_t * _PDCLIB_restrict pwcs, size_t n );
 249 */
 250
 251 _PDCLIB_END_EXTERN_C
 252 #endif