1 // ----------------------------------------------------------------------------
3 // ----------------------------------------------------------------------------
4 // Public Domain C Library - http://pdclib.sourceforge.net
5 // This code is Public Domain. Use, modify, and redistribute at will.
6 // ----------------------------------------------------------------------------
8 // ----------------------------------------------------------------------------
11 #define __STRING_H __STRING_H
13 // TODO: Documentation
15 // ----------------------------------------------------------------------------
20 // ----------------------------------------------------------------------------
25 // ----------------------------------------------------------------------------
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 );
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.
41 char * strcat( char * restrict dest, const char * restrict src );
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
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
51 char * strchr( const char * src, int c );
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.
66 int strcmp( const char * src_1, const char * src_2 );
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.
80 int strcoll( const char * src_1, const char * src_2 );
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.
91 char * strcpy( char * restrict dest, const char * restrict src );
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
100 size_t strcspn( const char * src_1, const char * src_2 );
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.
108 char * strerror( int errorcode );
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
116 size_t strlen( const char * src );
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.
126 char * strncat( char * restrict dest, const char * restrict src, size_t n );
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
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.
142 int strncmp( const char * src_1, const char * src_2, size_t n );
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
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.
154 char * strncpy( char * restrict s1, const char * restrict s2, size_t n );
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.
162 size_t strspn( const char * s1, const char * s2 );
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.
178 char * strtok( char * restrict src, const char * restrict seperators );
180 size_t strxfrm( char * restrict s1, const char * restrict s2, size_t n );
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 );