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

   1 /* 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
  11 #ifdef __cplusplus
  12 extern "C" {
  13 #endif
  14
  15 #ifndef _PDCLIB_SIZE_T_DEFINED
  16 #define _PDCLIB_SIZE_T_DEFINED _PDCLIB_SIZE_T_DEFINED
  17 typedef _PDCLIB_size_t size_t;
  18 #endif
  19
  20 #ifndef _PDCLIB_NULL_DEFINED
  21 #define _PDCLIB_NULL_DEFINED _PDCLIB_NULL_DEFINED
  22 #define NULL _PDCLIB_NULL
  23 #endif
  24
  25 #ifndef __cplusplus
  26
  27 #ifndef _PDCLIB_WCHAR_T_DEFINED
  28 #define _PDCLIB_WCHAR_T_DEFINED _PDCLIB_WCHAR_T_DEFINED
  29 typedef _PDCLIB_wchar_t wchar_t;
  30 #endif
  31
  32 #endif
  33
  34 #ifndef _PDCLIB_MB_CUR_MAX_DEFINED
  35 #define _PDCLIB_MB_CUR_MAX_DEFINED
  36 #define MB_CUR_MAX (_PDCLIB_mb_cur_max())
  37 #endif
  38
  39 /* Numeric conversion functions */
  40
  41 /* TODO: atof(), strtof(), strtod(), strtold() */
  42
  43 double atof( const char * nptr ) _PDCLIB_nothrow;
  44 double strtod( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr ) _PDCLIB_nothrow;
  45 float strtof( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr ) _PDCLIB_nothrow;
  46 long double strtold( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr ) _PDCLIB_nothrow;
  47
  48 /* Seperate the character array nptr into three parts: A (possibly empty)
  49    sequence of whitespace characters, a character representation of an integer
  50    to the given base, and trailing invalid characters (including the terminating
  51    null character). If base is 0, assume it to be 10, unless the integer
  52    representation starts with 0x / 0X (setting base to 16) or 0 (setting base to
  53    8). If given, base can be anything from 0 to 36, using the 26 letters of the
  54    base alphabet (both lowercase and uppercase) as digits 10 through 35.
  55    The integer representation is then converted into the return type of the
  56    function. It can start with a '+' or '-' sign. If the sign is '-', the result
  57    of the conversion is negated.
  58    If the conversion is successful, the converted value is returned. If endptr
  59    is not a NULL pointer, a pointer to the first trailing invalid character is
  60    returned in *endptr.
  61    If no conversion could be performed, zero is returned (and nptr in *endptr,
  62    if endptr is not a NULL pointer). If the converted value does not fit into
  63    the return type, the functions return LONG_MIN, LONG_MAX, ULONG_MAX,
  64    LLONG_MIN, LLONG_MAX, or ULLONG_MAX respectively, depending on the sign of
  65    the integer representation and the return type, and errno is set to ERANGE.
  66 */
  67 /* There is strtoimax() and strtoumax() in <inttypes.h> operating on intmax_t /
  68    uintmax_t, if the long long versions do not suit your needs.
  69 */
  70 long int strtol( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
  71 long long int strtoll( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
  72 unsigned long int strtoul( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
  73 unsigned long long int strtoull( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
  74
  75 /* These functions are the equivalent of (int)strtol( nptr, NULL, 10 ),
  76    strtol( nptr, NULL, 10 ) and strtoll(nptr, NULL, 10 ) respectively, with the
  77    exception that they do not have to handle overflow situations in any defined
  78    way.
  79    (PDCLib does not simply forward these to their strtox() equivalents, but
  80    provides a simpler atox() function that saves a couple of tests and simply
  81    continues with the conversion in case of overflow.)
  82 */
  83 int atoi( const char * nptr ) _PDCLIB_nothrow;
  84 long int atol( const char * nptr ) _PDCLIB_nothrow;
  85 long long int atoll( const char * nptr ) _PDCLIB_nothrow;
  86
  87 /* Pseudo-random sequence generation functions */
  88
  89 extern unsigned long int _PDCLIB_seed;
  90
  91 #define RAND_MAX 32767
  92
  93 /* Returns the next number in a pseudo-random sequence, which is between 0 and
  94    RAND_MAX.
  95    (PDCLib uses the implementation suggested by the standard document, which is
  96    next = next * 1103515245 + 12345; return (unsigned int)(next/65536) % 32768;)
  97 */
  98 int rand( void ) _PDCLIB_nothrow;
  99
 100 /* Initialize a new pseudo-random sequence with the starting seed. Same seeds
 101    result in the same pseudo-random sequence. The default seed is 1.
 102 */
 103 void srand( unsigned int seed ) _PDCLIB_nothrow;
 104
 105 /* Memory management functions */
 106
 107 /* Allocate a chunk of memory of given size. If request could not be
 108    satisfied, return NULL. Otherwise, return a pointer to the allocated
 109    memory. Memory contents are undefined.
 110 */
 111 void * malloc( size_t size ) _PDCLIB_nothrow;
 112
 113 /* Allocate a chunk of memory that is large enough to hold nmemb elements of
 114    the given size, and zero-initialize that memory. If request could not be
 115    satisfied, return NULL. Otherwise, return a pointer to the allocated
 116    memory.
 117 */
 118 void * calloc( size_t nmemb, size_t size ) _PDCLIB_nothrow;
 119
 120 /* Allocate a chunk of memory of given size, with specified alignment (which
 121    must be a power of two; if it is not, the next greater power of two is
 122    used). If request could not be satisfied, return NULL. Otherwise, return
 123    a pointer to the allocated memory.
 124 */
 125 void * aligned_alloc( size_t alignment, size_t size ) _PDCLIB_nothrow;
 126
 127 /* De-allocate a chunk of heap memory previously allocated using malloc(),
 128    calloc(), or realloc(), and pointed to by ptr. If ptr does not match a
 129    pointer previously returned by the mentioned allocation functions, or
 130    free() has already been called for this ptr, behaviour is undefined.
 131 */
 132 void free( void * ptr ) _PDCLIB_nothrow;
 133
 134 /* Resize a chunk of memory previously allocated with malloc() and pointed to
 135    by ptr to the given size (which might be larger or smaller than the original
 136    size). Returns a pointer to the reallocated memory, or NULL if the request
 137    could not be satisfied. Note that the resizing might include a memcpy()
 138    from the original location to a different one, so the return value might or
 139    might not equal ptr. If size is larger than the original size, the value of
 140    memory beyond the original size is undefined. If ptr is NULL, realloc()
 141    behaves like malloc().
 142 */
 143 void * realloc( void * ptr, size_t size ) _PDCLIB_nothrow;
 144
 145 /* Communication with the environment */
 146
 147 /* These two can be passed to exit() or _Exit() as status values, to signal
 148    successful and unsuccessful program termination, respectively. EXIT_SUCCESS
 149    can be replaced by 0. How successful or unsuccessful program termination are
 150    signaled to the environment, and what happens if exit() or _Exit() are being
 151    called with a value that is neither of the three, is defined by the hosting
 152    OS and its glue function.
 153 */
 154 #define EXIT_SUCCESS _PDCLIB_SUCCESS
 155 #define EXIT_FAILURE _PDCLIB_FAILURE
 156
 157 /* Initiate abnormal process termination, unless programm catches SIGABRT and
 158    does not return from the signal handler.
 159    This implementantion flushes all streams, closes all files, and removes any
 160    temporary files before exiting with EXIT_FAILURE.
 161    abort() does not return.
 162 */
 163 _PDCLIB_noreturn void abort( void ) _PDCLIB_nothrow;
 164
 165 /* Register a function that will be called on exit(), or when main() returns.
 166    At least 32 functions can be registered this way, and will be called in
 167    reverse order of registration (last-in, first-out).
 168    Returns zero if registration is successfull, nonzero if it failed.
 169 */
 170 int atexit( void (*func)( void ) ) _PDCLIB_nothrow;
 171
 172 /* Register a function that will be called on quick_exit(), or when main() returns.
 173    At least 32 functions can be registered this way, and will be called in
 174    reverse order of registration (last-in, first-out).
 175    Returns zero if registration is successfull, nonzero if it failed.
 176 */
 177 int at_quick_exit( void (*func)( void ) ) _PDCLIB_nothrow;
 178
 179 /* Normal process termination. Functions registered by atexit() (see above) are
 180    called, streams flushed, files closed and temporary files removed before the
 181    program is terminated with the given status. (See comment for EXIT_SUCCESS
 182    and EXIT_FAILURE above.)
 183    exit() does not return.
 184 */
 185 _PDCLIB_noreturn void exit( int status ) _PDCLIB_nothrow;
 186
 187 /* Normal process termination. Functions registered by atexit() (see above) are
 188    NOT CALLED. This implementation DOES flush streams, close files and removes
 189    temporary files before the program is teminated with the given status. (See
 190    comment for EXIT_SUCCESS and EXIT_FAILURE above.)
 191    _Exit() does not return.
 192 */
 193 _PDCLIB_noreturn void _Exit( int status ) _PDCLIB_nothrow;
 194
 195 /* Quick process termination. Functions registered by at_quick_exit() (see
 196    above) are called, and the process terminated. No functions registered
 197    with atexit() (see above) or signal handlers are called.
 198    quick_exit() does not return.
 199 */
 200 _PDCLIB_noreturn void quick_exit( int status );
 201
 202 /* Search an environment-provided key-value map for the given key name, and
 203    return a pointer to the associated value string (or NULL if key name cannot
 204    be found). The value string pointed to might be overwritten by a subsequent
 205    call to getenv(). The library never calls getenv() itself.
 206    Details on the provided keys and how to set / change them are determined by
 207    the hosting OS and its glue function.
 208 */
 209 char * getenv( const char * name ) _PDCLIB_nothrow;
 210
 211 /* If string is a NULL pointer, system() returns nonzero if a command processor
 212    is available, and zero otherwise. If string is not a NULL pointer, it is
 213    passed to the command processor. If system() returns, it does so with a
 214    value that is determined by the hosting OS and its glue function.
 215 */
 216 int system( const char * string ) _PDCLIB_nothrow;
 217
 218 /* Searching and sorting */
 219
 220 /* Do a binary search for a given key in the array with a given base pointer,
 221    which consists of nmemb elements that are of the given size each. To compare
 222    the given key with an element from the array, the given function compar is
 223    called (with key as first parameter and a pointer to the array member as
 224    second parameter); the function should return a value less than, equal to,
 225    or greater than 0 if the key is considered to be less than, equal to, or
 226    greater than the array element, respectively.
 227    The function returns a pointer to the first matching element found, or NULL
 228    if no match is found.
 229
 230    ** May throw **
 231 */
 232 void * bsearch( const void * key, const void * base, size_t nmemb, size_t size, int (*compar)( const void *, const void * ) );
 233
 234 /* Do a quicksort on an array with a given base pointer, which consists of
 235    nmemb elements that are of the given size each. To compare two elements from
 236    the array, the given function compar is called, which should return a value
 237    less than, equal to, or greater than 0 if the first argument is considered
 238    to be less than, equal to, or greater than the second argument, respectively.
 239    If two elements are compared equal, their order in the sorted array is not
 240    specified.
 241
 242    ** May throw **
 243 */
 244 void qsort( void * base, size_t nmemb, size_t size, int (*compar)( const void *, const void * ) );
 245
 246 /* Integer arithmetic functions */
 247
 248 /* Return the absolute value of the argument. Note that on machines using two-
 249    complement's notation (most modern CPUs), the largest negative value cannot
 250    be represented as positive value. In this case, behaviour is unspecified.
 251 */
 252 int abs( int j ) _PDCLIB_nothrow;
 253 long int labs( long int j ) _PDCLIB_nothrow;
 254 long long int llabs( long long int j ) _PDCLIB_nothrow;
 255
 256 /* These structures each have a member quot and a member rem, of type int (for
 257    div_t), long int (for ldiv_t) and long long it (for lldiv_t) respectively.
 258    The order of the members is platform-defined to allow the div() functions
 259    below to be implemented efficiently.
 260 */
 261 typedef struct _PDCLIB_div_t     div_t;
 262 typedef struct _PDCLIB_ldiv_t   ldiv_t;
 263 typedef struct _PDCLIB_lldiv_t lldiv_t;
 264
 265 /* Return quotient (quot) and remainder (rem) of an integer division in one of
 266    the structs above.
 267 */
 268 div_t div( int numer, int denom ) _PDCLIB_nothrow;
 269 ldiv_t ldiv( long int numer, long int denom ) _PDCLIB_nothrow;
 270 lldiv_t lldiv( long long int numer, long long int denom ) _PDCLIB_nothrow;
 271
 272 /* Multibyte / wide character conversion functions */
 273
 274 /* Affected by LC_CTYPE of the current locale. For state-dependent encoding,
 275    each function is placed into its initial conversion state at program
 276    startup, and can be returned to that state by a call with its character
 277    pointer argument s being a null pointer.
 278    Changing LC_CTYPE causes the conversion state to become indeterminate.
 279 */
 280
 281 /* If s is not a null pointer, returns the number of bytes contained in the
 282    multibyte character pointed to by s (if the next n or fewer bytes form a
 283    valid multibyte character); -1, if they don't; or 0, if s points to the
 284    null character.
 285    If s is a null pointer, returns nonzero if multibyte encodings in the
 286    current locale are stateful, and zero otherwise.
 287 */
 288 int mblen( const char * s, size_t n );
 289
 290 /* If s is not a null pointer, and the next n bytes (maximum) form a valid
 291    multibyte character sequence (possibly including shift sequences), the
 292    corresponding wide character is stored in pwc (unless that is a null
 293    pointer). If the wide character is the null character, the function is
 294    left in the initial conversion state.
 295    Returns the number of bytes in the consumed multibyte character sequence;
 296    or 0, if the resulting wide character is the null character. If the next
 297    n bytes do not form a valid sequence, returns -1.
 298    In no case will the returned value be greater than n or MB_CUR_MAX.
 299    If s is a null pointer, returns nonzero if multibyte encodings in the
 300    current locale are stateful, and zero otherwise.
 301 */
 302 int mbtowc( wchar_t * _PDCLIB_restrict pwc, const char * _PDCLIB_restrict s, size_t n );
 303
 304 /* Converts the wide character wc into the corresponding multibyte character
 305    sequence (including shift sequences). If s is not a null pointer, the
 306    multibyte sequence (at most MB_CUR_MAX characters) is stored at that
 307    location. If wc is a null character, a null byte is stored, preceded by
 308    any shift sequence needed to restore the initial shift state, and the
 309    function is left in the initial conversion state.
 310    Returns the number of bytes in the generated multibyte character sequence.
 311    If wc does not correspond to a valid multibyte character, returns -1.
 312    In no case will the returned value be greater than MB_CUR_MAX.
 313    If s is a null pointer, returns nonzero if multibyte encodings in the
 314    current locale are stateful, and zero otherwise.
 315 */
 316 int wctomb( char * s, wchar_t wc );
 317
 318 /* Convert a sequence of multibyte characters beginning in the initial shift
 319    state from the array pointed to by s into the corresponding wide character
 320    sequence, storing no more than n wide characters into pwcs. A null
 321    character is converted into a null wide character, and marks the end of
 322    the multibyte character sequence.
 323    If copying takes place between objects that overlap, behaviour is
 324    undefined.
 325    Returns (size_t)-1 if an invalid multibyte sequence is encountered.
 326    Otherwise, returns the number of array elements modified, not including
 327    a terminating null wide character, if any. (Target string will not be
 328    null terminated if the return value equals n.)
 329 */
 330 size_t mbstowcs( wchar_t * _PDCLIB_restrict pwcs, const char * _PDCLIB_restrict s, size_t n );
 331
 332 /* Convert a sequence of wide characters from the array pointed to by pwcs
 333    into a sequence of corresponding multibyte characters, beginning in the
 334    initial shift state, storing them in the array pointed to by s, stopping
 335    if the next multibyte character would exceed the limit of n total bytes
 336    or a null character is stored.
 337    If copying takes place between objects that overlap, behaviour is
 338    undefined.
 339    Returns (size_t)-1 if a wide character is encountered that does not
 340    correspond to a valid multibyte character. Otherwise, returns the number
 341    of array elements modified, not including a terminating null character,
 342    if any. (Target string will not be null terminated if the return value
 343    equals n.)
 344 */
 345 size_t wcstombs( char * _PDCLIB_restrict s, const wchar_t * _PDCLIB_restrict pwcs, size_t n );
 346
 347 #ifdef __cplusplus
 348 }
 349 #endif
 350
 351 #endif