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

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