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

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