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

   1 /* ----------------------------------------------------------------------------
   2  * $Id$
   3  * ----------------------------------------------------------------------------
   4  * Public Domain C Library - http://pdclib.sourceforge.net
   5  * This code is Public Domain. Use, modify, and redistribute at will.
   6  * ----------------------------------------------------------------------------
   7  * String handling
   8  * --------------------------------------------------------------------------*/
   9
  10 #ifndef _STRING_H
  11 #define _STRING_H _STRING_H
  12
  13 #ifndef _NULL
  14 #include "__intern.h"
  15 #endif /* _NULL */
  16
  17 /* ----------------------------------------------------------------------------
  18  * MACROS
  19  * --------------------------------------------------------------------------*/
  20
  21 #define NULL _NULL
  22
  23 /* ----------------------------------------------------------------------------
  24  * TYPEDEFS
  25  * --------------------------------------------------------------------------*/
  26
  27 #ifndef _SIZE_T
  28 #define _SIZE_T _SIZE_T
  29 typedef __size_t size_t
  30 #endif /* _SIZE_T */
  31
  32 /* ----------------------------------------------------------------------------
  33  * FUNCTIONS
  34  * --------------------------------------------------------------------------*/
  35
  36 /** MEMory search for CHaRacter. Searches a memory area for a character.
  37  *  @param src The memory area.
  38  *  @param c The character to look for.
  39  *  @param n Number of characters to search.
  40  *  @return A pointer to the first occurrence of c in src, or NULL if no match
  41  *          found.
  42  *  @see strchr()
  43  */
  44 void * memchr( const void * src, int c, size_t n );
  45
  46 /** MEMory CoMPare. Compares two memory areas until a difference is found.
  47  *  This implementation actually returns the difference of the first differing
  48  *  byte.
  49  *  This behaviour is implementation-defined and should not be relied upon to
  50  *  keep your code portable across implementations.
  51  *  @param src_1 The first memory area.
  52  *  @param src_2 The second memory area.
  53  *  @param n Number of bytes to compare.
  54  *  @return 0, if both areas are identical. If a difference is found, returns a
  55  *          value < 0 if the byte from memory area src_1 is smaller than that
  56  *          from src_2, or > 0 if otherwise.
  57  *  @see strncmp()
  58  */
  59 int memcmp( const void * src_1, const void * src_2, size_t n );
  60
  61 /** MEMory CoPY. Copies a source memory area of size n into a destination
  62  *  memory area.
  63  *  Should the memory areas pointed to by dest and src overlap, behaviour is
  64  *  undefined.
  65  *  @param dest The destination memory area.
  66  *  @param src The source memory area.
  67  *  @param n The size of the source memory area.
  68  *  @return A pointer to the destination memory area.
  69  *  @see strncpy()
  70  */
  71 void * memcpy( void * restrict dest, const void * restrict src, size_t n );
  72
  73 /** MEMory CoPY. Moves a source memory area of size n into a destination
  74  *  memory area. The memory areas may overlap.
  75  *  @param dest The destination memory area.
  76  *  @param src The source memory area.
  77  *  @param n The size of the source memory area.
  78  *  @return A pointer to the destination memory area.
  79  *  @see strncpy()
  80  */
  81 void * memmove( void * dest, const void * src, size_t n );
  82
  83 /** MEMory SET. Fills a memory area with a given character.
  84  *  @param dest The destination memory area.
  85  *  @param c The character to be written to dest.
  86  *  @param n The number of characters to be written to dest.
  87  *  @return A pointer to the destination memory area.
  88  */
  89 void * memset( void * dest, int c, size_t n );
  90
  91 /** STRing conCATenation. Appends a C string to another. If the memory area
  92  *  pointed to by 'dest' is not large enough to hold both 'dest' and 'src',
  93  *  behaviour is undefined.
  94  *  @param dest The destination string.
  95  *  @param src The source string.
  96  *  @return A pointer to the destination string.
  97  *  @see strncat()
  98  */
  99 char * strcat( char * restrict dest, const char * restrict src );
 100
 101 /** STRing search for CHaRacter. Searches a C string (including terminating \0)
 102  *  for a character. If the string is not properly terminated, behaviour is
 103  *  undefined.
 104  *  @param src The source string.
 105  *  @param c The character to look for.
 106  *  @return A pointer to the first occurrence of c in src, or NULL if no match
 107  *          found.
 108  */
 109 char * strchr( const char * src, int c );
 110
 111 /** STRing CoMPare. Compares two C strings until two differing characters are
 112  *  found, or both strings end. If the input strings are not correctly
 113  *  teminated with \0, behaviour is undefined.
 114  *  This implementation actually returns the difference of the two characters.
 115  *  This behaviour is implementation-defined and should not be relied upon to
 116  *  keep your code portable across implementations.
 117  *  @param src_1 The first string to be compared.
 118  *  @param src_2 The second string to be compared.
 119  *  @return 0, if both strings are identical. If two differing characters are
 120  *          found, returns a value < 0 if the character from src_1 is smaller
 121  *          than that from src_2, or > 0 if otherwise.
 122  *  @see strncmp()
 123  */
 124 int strcmp( const char * src_1, const char * src_2 );
 125
 126 /** STRing COLLate. Compares two C strings until two differing characters are
 127  *  found, honoring the current locale.
 128  *  This implementation actually returns the difference of the two characters.
 129  *  This behaviour is implementation-defined and should not be relied upon to
 130  *  keep your code portable across implementations.
 131  *  @param src_1 The first string to be compared.
 132  *  @param src_2 The second string to be compared.
 133  *  @return 0, if both strings are identical. If two differing characters are
 134  *          found, returns a value < 0 if the character from src_1 is smaller
 135  *          than that from src_2, or > 0 if otherwise.
 136  *  @see locale.h
 137  */
 138 int strcoll( const char * src_1, const char * src_2 );
 139
 140 /** STRing CoPY. Copies a source string (including terminating \0) into a
 141  *  destination string. If the memory area pointed to by dest is not large
 142  *  enough to hold src, behaviour is undefined. Should the memory areas pointed
 143  *  to by dest and src overlap, behavious is undefined.
 144  *  @param dest The destination string.
 145  *  @param src The source string.
 146  *  @return A pointer to the destination string.
 147  *  @see strncpy()
 148  */
 149 char * strcpy( char * restrict dest, const char * restrict src );
 150
 151 /** STRing Character SPaN. Compares two C strings, determining the length of
 152  *  the substring not containing any character from the second string.
 153  *  @param src_1 The string to be searched.
 154  *  @param src_2 The string containing the characters to be searched for.
 155  *  @return The length of the src_1 substring not containing any character
 156  *          from src_2.
 157  */
 158 size_t strcspn( const char * src_1, const char * src_2 );
 159
 160 /** STRing ERROR. Returns the error message corresponding to an error code.
 161  *  @param errorcode The error code.
 162  *  @return The plaintext error message corresponding to the error code.
 163  *  @see errno.h
 164  *  @see fenv.h
 165  */
 166 char * strerror( int errorcode );
 167
 168 /** STRing LENgth. Returns the number of characters in a C string, not counting
 169  *  the terminating \0.
 170  *  @param src The source string.
 171  *  @return The number of characters in the string, not counting the
 172  *          terminating \0.
 173  */
 174 size_t strlen( const char * src );
 175
 176 /** STRing N conCATenate. Appends a C string to another, setting a limit on the
 177  *  number of characters copied.
 178  *  @param dest The destination string.
 179  *  @param src The source string.
 180  *  @param n The maximum number of characters to be copied.
 181  *  @return A pointer to the destination string.
 182  *  @see strcat()
 183  */
 184 char * strncat( char * restrict dest, const char * restrict src, size_t n );
 185
 186 /** STRing N CoMPare. Compares two C strings until two differing characters are
 187  *  found, both strings end, or a maximum number of characters has been
 188  *  compared.
 189  *  This implementation actually returns the difference of the two characters.
 190  *  This behaviour is implementation-defined and should not be relied upon to
 191  *  keep your code portable across implementations.
 192  *  @param src_1 The first string to be compared.
 193  *  @param src_2 The second string to be compared.
 194  *  @param n The maximum number of characters to be compared.
 195  *  @return 0, if both strings are identical. If two differing characters are
 196  *          found, returns a value < 0 if the character from src_1 is smaller
 197  *          than that from src_2, or > 0 if otherwise.
 198  *  @see strcmp()
 199  */
 200 int strncmp( const char * src_1, const char * src_2, size_t n );
 201
 202 /** STRing CoPY. Copies a source string (including terminating \0) into a
 203  *  destination string, setting a limit on the number of characters copied.
 204  *  Should the memory areas pointed to by dest and src overlap, behaviour is
 205  *  undefined.
 206  *  @param dest The destination string.
 207  *  @param src The source string.
 208  *  @param n The maximum number of characters to be copied.
 209  *  @return A pointer to the destination string.
 210  *  @see strcpy()
 211  */
 212 char * strncpy( char * restrict dest, const char * restrict src, size_t n );
 213
 214 /** STRing SPaN. Compares two C strings, determining the length of the
 215  *  substring containing only characters from the second string.
 216  *  @param src_1 The first string to be compared.
 217  *  @param src_2 The second string to be compared.
 218  *  @return The length of the identical substring.
 219  */
 220 size_t strspn( const char * src_1, const char * src_2 );
 221
 222 /** STRing TOKenizer. This (complex and not thread-safe) function allows, by
 223  *  subsequent calls, to parse a string for tokens. The first parameter to the
 224  *  function is the C string to be parsed, the second parameter a C string
 225  *  containing a collection of seperating characters. On first call to the
 226  *  function, strtok() skips leading seperators, sets the first seperator after
 227  *  the token to \0, and returns a pointer to the token. Subsequent calls to
 228  *  strtok() with NULL as the first parameter return pointers to subsequent
 229  *  tokens, or NULL when all tokens have been parsed.
 230  *  Beware, this function is not thread-safe.
 231  *  @param src The string to be parsed (on first call), or NULL (to parse
 232  *         subsequent tokens).
 233  *  @param seperators The string containing the seperator(s).
 234  *  @return The next token parsed, or NULL if parse completed.
 235  */
 236 char * strtok( char * restrict src, const char * restrict seperators );
 237
 238 /** STRing X FRoM. This function transforms a C string into another using a
 239  *  transformation rule depending on the current locale.
 240  *  @param dest The destination, where the transformed string should be written
 241  *         to.
 242  *  @param src The source string to be transformed.
 243  *  @param n The maximum number of characters to be written to dest. If this
 244  *         parameter is zero, 'dest' can be a NULL pointer (to determine the
 245  *         required space before doing the actual transformation).
 246  *  @return The length of the string after transformation. If return value > n,
 247  *          the transformed string has not been written, and the contents of
 248  *          'dest' are undefined.
 249  *  @see locale.h
 250  *  @see strcoll()
 251  */
 252 size_t strxfrm( char * restrict dest, const char * restrict src, size_t n );
 253
 254 /** STRing search, return Pointer to BReaK. Searches a C string (including
 255  *  terminating \0) for any character contained in a second string. If the
 256  *  first string is not properly terminated, behaviour is undefined.
 257  *  @param src_1 The string to be seached.
 258  *  @param src_2 The string containing the characters to be searched.
 259  *  @return A pointer into src_1 pointing to the first occurrence of any
 260  *          character from src_2, or NULL if no match found.
 261  */
 262 char * strpbrk( const char * src_1, const char * src_2 );
 263
 264 /** STRing Reverse search for CHaRacter. Searches a C string (including
 265  *  terminating \0) for a character. If the string is not properly terminated,
 266  *  behaviour is undefined.
 267  *  @param src The source string.
 268  *  @param c The character to look for.
 269  *  @return A pointer to the last occurrence of c in src, or NULL if no match
 270  *          found.
 271  */
 272 char * strrchr( const char * src, int c );
 273
 274 /** STRing search for STRing. Searches a C string for a substring.
 275  *  @param src_1 The string to be searched in.
 276  *  @param src_2 The substring to be searched for.
 277  *  @return A pointer to the first occurrence of src_2 in src_1, or NULL if no
 278  *          match found.
 279  */
 280 char * strstr( const char * src_1, const char * src_2 );
 281
 282 #endif /* _STRING_H */