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 // TODO: Documentation
  14
  15 // ----------------------------------------------------------------------------
  16 // MACROS
  17
  18 #include "__NULL.h"
  19
  20 // ----------------------------------------------------------------------------
  21 // TYPEDEFS
  22
  23 #include "__size_t.h"
  24
  25 // ----------------------------------------------------------------------------
  26 // FUNCTIONS
  27
  28 int memcmp( const void * s1, const void * s2, size_t n );
  29 void * memcpy( void * restrict s1, const void * restrict s2, size_t n );
  30 void * memmove( void * s1, const void * s2, size_t n );
  31 void * memset( void * s, int c, size_t n );
  32
  33 /** STRing conCATenation. Appends a C string to another. If the memory area
  34  *  pointed to by 'dest' is not large enough to hold both 'dest' and 'src',
  35  *  behaviour is undefined.
  36  *  @param dest The destination string.
  37  *  @param src The source string.
  38  *  @return A pointer to the destination string.
  39  *  @see strncat()
  40  */
  41 char * strcat( char * restrict dest, const char * restrict src );
  42
  43 /** STRing search for CHaRacter. Searches a C string (including terminating \0)
  44  *  for a character. If the string is not properly terminated, behaviour is
  45  *  undefined.
  46  *  @param src The source string.
  47  *  @param c The character to look for.
  48  *  @return A pointer to the first occurrence of c in src, or NULL if no match
  49  *          found.
  50  */
  51 char * strchr( const char * src, int c );
  52
  53 /** STRing CoMPare. Compares two C strings until two differing characters are
  54  *  found, or both strings end. If the input strings are not correctly
  55  *  teminated with \0, behaviour is undefined.
  56  *  This implementation actually returns the difference of the two characters.
  57  *  This behaviour is implementation-defined and should not be relied upon to
  58  *  keep your code portable across implementations.
  59  *  @param src_1 The first string to be compared.
  60  *  @param src_2 The second string to be compared.
  61  *  @return 0, if both strings are identical. If two differing characters are
  62  *          found, returns a value < 0 if the character from src_1 is smaller
  63  *          than that from src_2, or > 0 if otherwise.
  64  *  @see strncmp()
  65  */
  66 int strcmp( const char * src_1, const char * src_2 );
  67
  68 /** STRing COLLate. Compares two C strings until two differing characters are
  69  *  found, honoring the current locale.
  70  *  This implementation actually returns the difference of the two characters.
  71  *  This behaviour is implementation-defined and should not be relied upon to
  72  *  keep your code portable across implementations.
  73  *  @param src_1 The first string to be compared.
  74  *  @param src_2 The second string to be compared.
  75  *  @return 0, if both strings are identical. If two differing characters are
  76  *          found, returns a value < 0 if the character from src_1 is smaller
  77  *          than that from src_2, or > 0 if otherwise.
  78  *  @see locale.h
  79  */
  80 int strcoll( const char * src_1, const char * src_2 );
  81
  82 /** STRing CoPY. Copies a source string (including terminating \0) into a
  83  *  destination string. If the memory area pointed to by dest is not large
  84  *  enough to hold src, behaviour is undefined. Should the memory areas pointed
  85  *  to by dest and src overlap, behavious is undefined.
  86  *  @param dest The destination string.
  87  *  @param src The source string.
  88  *  @return A pointer to the destination string.
  89  *  @see strncpy()
  90  */
  91 char * strcpy( char * restrict dest, const char * restrict src );
  92
  93 /** STRing Character SPaN. Compares two C strings, determining the length of
  94  *  the substring not containing any character from the second string.
  95  *  @param src_1 The string to be searched.
  96  *  @param src_2 The string containing the characters to be searched for.
  97  *  @return The length of the src_1 substring not containing any character
  98  *          from src_2.
  99  */
 100 size_t strcspn( const char * src_1, const char * src_2 );
 101
 102 /** STRing ERROR. Returns the error message corresponding to an error code.
 103  *  @param errorcode The error code.
 104  *  @return The plaintext error message corresponding to the error code.
 105  *  @see errno.h
 106  *  @see fenv.h
 107  */
 108 char * strerror( int errorcode );
 109
 110 /** STRing LENgth. Returns the number of characters in a C string, not counting
 111  *  the terminating \0.
 112  *  @param src The source string.
 113  *  @return The number of characters in the string, not counting the
 114  *          terminating \0.
 115  */
 116 size_t strlen( const char * src );
 117
 118 /** STRing N conCATenate. Appends a C string to another, setting a limit on the
 119  *  number of characters copied.
 120  *  @param dest The destination string.
 121  *  @param src The source string.
 122  *  @param n The maximum number of characters to be copied.
 123  *  @return A pointer to the destination string.
 124  *  @see strcat()
 125  */
 126 char * strncat( char * restrict dest, const char * restrict src, size_t n );
 127
 128 /** STRing CoMPare. Compares two C strings until two differing characters are
 129  *  found, both strings end, or a maximum number of characters has been
 130  *  compared.
 131  *  This implementation actually returns the difference of the two characters.
 132  *  This behaviour is implementation-defined and should not be relied upon to
 133  *  keep your code portable across implementations.
 134  *  @param src_1 The first string to be compared.
 135  *  @param src_2 The second string to be compared.
 136  *  @param n The maximum number of characters to be compared.
 137  *  @return 0, if both strings are identical. If two differing characters are
 138  *          found, returns a value < 0 if the character from src_1 is smaller
 139  *          than that from src_2, or > 0 if otherwise.
 140  *  @see strcmp()
 141  */
 142 int strncmp( const char * src_1, const char * src_2, size_t n );
 143
 144 /** STRing CoPY. Copies a source string (including terminating \0) into a
 145  *  destination string, setting a limit on the number of characters copied.
 146  *  Should the memory areas pointed to by dest and src overlap, behaviour is
 147  *  undefined.
 148  *  @param dest The destination string.
 149  *  @param src The source string.
 150  *  @param n The maximum number of characters to be copied.
 151  *  @return A pointer to the destination string.
 152  *  @see strcpy()
 153  */
 154 char * strncpy( char * restrict s1, const char * restrict s2, size_t n );
 155
 156 /** STRing SPaN. Compares two C strings, determining the length of the
 157  *  substring where both strings are equal.
 158  *  @param src_1 The first string to be compared.
 159  *  @param src_2 The second string to be compared.
 160  *  @return The length of the identical substring.
 161  */
 162 size_t strspn( const char * s1, const char * s2 );
 163
 164 /** STRing TOKenizer. This (complex and not thread-safe) function allows, by
 165  *  subsequent calls, to parse a string for tokens. The first parameter to the
 166  *  function is the C string to be parsed, the second parameter a C string
 167  *  containing a collection of seperating characters. On first call to the
 168  *  function, strtok() skips leading seperators, sets the first seperator after
 169  *  the token to \0, and returns a pointer to the token. Subsequent calls to
 170  *  strtok() with NULL as the first parameter return pointers to subsequent
 171  *  tokens, or NULL when all tokens have been parsed.
 172  *  Beware, this function is not thread-safe.
 173  *  @param src The string to be parsed (on first call), or NULL (to parse
 174  *         subsequent tokens).
 175  *  @param seperators The string containing the seperator(s).
 176  *  @return The next token parsed, or NULL if parse completed.
 177  */
 178 char * strtok( char * restrict src, const char * restrict seperators );
 179
 180 size_t strxfrm( char * restrict s1, const char * restrict s2, size_t n );
 181
 182 void * memchr( const void * s, int c, size_t n );
 183 char * strpbrk( const char *s1, const char * s2 );
 184 char * strrchr( const char * s, int c );
 185 char * strstr( const char * s1, const char * s2 );
 186
 187 #endif // __STRING_H