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