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

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