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

   1 /* String handling <string.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_STRING_H
   8 #define _PDCLIB_STRING_H _PDCLIB_STRING_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 /* String function conventions */
  26
  27 /*
  28    In any of the following functions taking a size_t n to specify the length of
  29    an array or size of a memory region, n may be 0, but the pointer arguments to
  30    the call shall still be valid unless otherwise stated.
  31 */
  32
  33 /* Copying functions */
  34
  35 /* Copy a number of n characters from the memory area pointed to by s2 to the
  36    area pointed to by s1. If the two areas overlap, behaviour is undefined.
  37    Returns the value of s1.
  38 */
  39 void * memcpy( void * _PDCLIB_restrict s1, const void * _PDCLIB_restrict s2, size_t n ) _PDCLIB_nothrow;
  40
  41 /* Copy a number of n characters from the memory area pointed to by s2 to the
  42    area pointed to by s1. The two areas may overlap.
  43    Returns the value of s1.
  44 */
  45 void * memmove( void * s1, const void * , size_t n ) _PDCLIB_nothrow;
  46
  47 /* Copy the character array s2 (including terminating '\0' byte) into the
  48    character array s1.
  49    Returns the value of s1.
  50 */
  51 char * strcpy( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2 ) _PDCLIB_nothrow;
  52
  53 /* Copy a maximum of n characters from the character array s2 into the character
  54    array s1. If s2 is shorter than n characters, '\0' bytes will be appended to
  55    the copy in s1 until n characters have been written. If s2 is longer than n
  56    characters, NO terminating '\0' will be written to s1. If the arrays overlap,
  57    behaviour is undefined.
  58    Returns the value of s1.
  59 */
  60 char * strncpy( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2, size_t n ) _PDCLIB_nothrow;
  61
  62 /* Concatenation functions */
  63
  64 /* Append the contents of the character array s2 (including terminating '\0') to
  65    the character array s1 (first character of s2 overwriting the '\0' of s1). If
  66    the arrays overlap, behaviour is undefined.
  67    Returns the value of s1.
  68 */
  69 char * strcat( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2 ) _PDCLIB_nothrow;
  70
  71 /* Append a maximum of n characters from the character array s1 to the character
  72    array s1 (first character of s2 overwriting the '\0' of s1). A terminating
  73    '\0' is ALWAYS appended, even if the full n characters have already been
  74    written. If the arrays overlap, behaviour is undefined.
  75    Returns the value of s1.
  76 */
  77 char * strncat( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2, size_t n ) _PDCLIB_nothrow;
  78
  79 /* Comparison functions */
  80
  81 /* Compare the first n characters of the memory areas pointed to by s1 and s2.
  82    Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if
  83    s1 > s2.
  84 */
  85 int memcmp( const void * s1, const void * s2, size_t n ) _PDCLIB_nothrow;
  86
  87 /* Compare the character arrays s1 and s2.
  88    Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if
  89    s1 > s2.
  90 */
  91 int strcmp( const char * s1, const char * s2 ) _PDCLIB_nothrow;
  92
  93 /* Compare the character arrays s1 and s2, interpreted as specified by the
  94    LC_COLLATE category of the current locale.
  95    Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if
  96    s1 > s2.
  97    TODO: Currently a dummy wrapper for strcmp() as PDCLib does not yet support
  98    locales.
  99 */
 100 int strcoll( const char * s1, const char * s2 ) _PDCLIB_nothrow;
 101
 102 /* Compare no more than the first n characters of the character arrays s1 and
 103    s2.
 104    Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if
 105    s1 > s2.
 106 */
 107 int strncmp( const char * s1, const char * s2, size_t n ) _PDCLIB_nothrow;
 108
 109 /* Transform the character array s2 as appropriate for the LC_COLLATE setting of
 110    the current locale. If length of resulting string is less than n, store it in
 111    the character array pointed to by s1. Return the length of the resulting
 112    string.
 113 */
 114 size_t strxfrm( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2, size_t n ) _PDCLIB_nothrow;
 115
 116 /* Search functions */
 117
 118 /* Search the first n characters in the memory area pointed to by s for the
 119    character c (interpreted as unsigned char).
 120    Returns a pointer to the first instance found, or NULL.
 121 */
 122 void * memchr( const void * s, int c, size_t n ) _PDCLIB_nothrow;
 123
 124 /* Search the character array s (including terminating '\0') for the character c
 125    (interpreted as char).
 126    Returns a pointer to the first instance found, or NULL.
 127 */
 128 char * strchr( const char * s, int c ) _PDCLIB_nothrow;
 129
 130 /* Determine the length of the initial substring of character array s1 which
 131    consists only of characters not from the character array s2.
 132    Returns the length of that substring.
 133 */
 134 size_t strcspn( const char * s1, const char * s2 ) _PDCLIB_nothrow;
 135
 136 /* Search the character array s1 for any character from the character array s2.
 137    Returns a pointer to the first occurrence, or NULL.
 138 */
 139 char * strpbrk( const char * s1, const char * s2 ) _PDCLIB_nothrow;
 140
 141 /* Search the character array s (including terminating '\0') for the character c
 142    (interpreted as char).
 143    Returns a pointer to the last instance found, or NULL.
 144 */
 145 char * strrchr( const char * s, int c ) _PDCLIB_nothrow;
 146
 147 /* Determine the length of the initial substring of character array s1 which
 148    consists only of characters from the character array s2.
 149    Returns the length of that substring.
 150 */
 151 size_t strspn( const char * s1, const char * s2 ) _PDCLIB_nothrow;
 152
 153 /* Search the character array s1 for the substring in character array s2.
 154    Returns a pointer to that sbstring, or NULL. If s2 is of length zero,
 155    returns s1.
 156 */
 157 char * strstr( const char * s1, const char * s2 ) _PDCLIB_nothrow;
 158
 159 /* In a series of subsequent calls, parse a C string into tokens.
 160    On the first call to strtok(), the first argument is a pointer to the to-be-
 161    parsed C string. On subsequent calls, the first argument is NULL unless you
 162    want to start parsing a new string. s2 holds an array of seperator characters
 163    which can differ from call to call. Leading seperators are skipped, the first
 164    trailing seperator overwritten with '\0'.
 165    Returns a pointer to the next token.
 166    WARNING: This function uses static storage, and as such is not reentrant.
 167 */
 168 char * strtok( char * _PDCLIB_restrict s1, const char * _PDCLIB_restrict s2 ) _PDCLIB_nothrow;
 169
 170 /* Miscellaneous functions */
 171
 172 /* Write the character c (interpreted as unsigned char) to the first n
 173    characters of the memory area pointed to by s.
 174    Returns s.
 175 */
 176 void * memset( void * s, int c, size_t n ) _PDCLIB_nothrow;
 177
 178 /* Map an error number to a (locale-specific) error message string. Error
 179    numbers are typically errno values, but any number is mapped to a message.
 180    TODO: PDCLib does not yet support locales.
 181 */
 182 char * strerror( int errnum ) _PDCLIB_nothrow;
 183
 184 /* Returns the length of the string s (excluding terminating '\0').
 185 */
 186 size_t strlen( const char * s ) _PDCLIB_nothrow;
 187
 188 #if _PDCLIB_POSIX_MIN(2008098L)
 189 /* Returns the length of the string s (excluding terminating '\0') or maxlen if
 190  * no terminating '\0' is found in the first maxlen characters.
 191  */
 192 size_t strnlen( const char * s, size_t maxlen ) _PDCLIB_nothrow;
 193 #endif
 194
 195 #if _PDCLIB_POSIX_MIN(2008098L) || _PDCLIB_XOPEN_MIN(0)
 196 char * strdup( const char* src ) _PDCLIB_nothrow;
 197 char * strndup( const char* src, size_t n ) _PDCLIB_nothrow;
 198 #endif
 199
 200 #if _PDCLIB_BSD_SOURCE
 201 size_t strlcpy(
 202    char *_PDCLIB_restrict _Dst,
 203    const char *_PDCLIB_restrict _Src,
 204    size_t _DstSize) _PDCLIB_nothrow;
 205
 206 size_t strlcat(
 207    char *_PDCLIB_restrict _Dst,
 208    const char *_PDCLIB_restrict _Src,
 209    size_t _DstSize) _PDCLIB_nothrow;
 210 #endif
 211
 212 #ifdef __cplusplus
 213 }
 214 #endif
 215
 216 #endif