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 // ----------------------------------------------------------------------------
18 // ----------------------------------------------------------------------------
23 // ----------------------------------------------------------------------------
26 /** MEMory search for CHaRacter. Searches a memory area for a character.
27 * @param src The memory area.
28 * @param c The character to look for.
29 * @param n Number of characters to search.
30 * @return A pointer to the first occurrence of c in src, or NULL if no match
34 void * memchr( const void * s, int c, size_t n );
36 /** MEMory CoMPare. Compares two memory areas until a difference is found.
37 * This implementation actually returns the difference of the first differing
39 * This behaviour is implementation-defined and should not be relied upon to
40 * keep your code portable across implementations.
41 * @param src_1 The first memory area.
42 * @param src_2 The second memory area.
43 * @param n Number of bytes to compare.
44 * @return 0, if both areas are identical. If a difference is found, returns a
45 * value < 0 if the byte from memory area src_1 is smaller than that
46 * from src_2, or > 0 if otherwise.
49 int memcmp( const void * s1, const void * s2, size_t n );
51 /** MEMory CoPY. Copies a source memory area of size n into a destination
53 * Should the memory areas pointed to by dest and src overlap, behaviour is
55 * @param dest The destination memory area.
56 * @param src The source memory area.
57 * @param n The size of the source memory area.
58 * @return A pointer to the destination memory area.
61 void * memcpy( void * restrict s1, const void * restrict s2, size_t n );
63 /** MEMory CoPY. Moves a source memory area of size n into a destination
64 * memory area. The memory areas may overlap.
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.
71 void * memmove( void * s1, const void * s2, size_t n );
73 /** MEMory SET. Fills a memory area with a given character.
74 * @param dest The destination memory area.
75 * @param c The character to be written to dest.
76 * @param n The number of characters to be written to dest.
77 * @return A pointer to the destination memory area.
79 void * memset( void * s, int c, size_t n );
81 /** STRing conCATenation. Appends a C string to another. If the memory area
82 * pointed to by 'dest' is not large enough to hold both 'dest' and 'src',
83 * behaviour is undefined.
84 * @param dest The destination string.
85 * @param src The source string.
86 * @return A pointer to the destination string.
89 char * strcat( char * restrict dest, const char * restrict src );
91 /** STRing search for CHaRacter. Searches a C string (including terminating \0)
92 * for a character. If the string is not properly terminated, behaviour is
94 * @param src The source string.
95 * @param c The character to look for.
96 * @return A pointer to the first occurrence of c in src, or NULL if no match
99 char * strchr( const char * src, int c );
101 /** STRing CoMPare. Compares two C strings until two differing characters are
102 * found, or both strings end. If the input strings are not correctly
103 * teminated with \0, behaviour is undefined.
104 * This implementation actually returns the difference of the two characters.
105 * This behaviour is implementation-defined and should not be relied upon to
106 * keep your code portable across implementations.
107 * @param src_1 The first string to be compared.
108 * @param src_2 The second string to be compared.
109 * @return 0, if both strings are identical. If two differing characters are
110 * found, returns a value < 0 if the character from src_1 is smaller
111 * than that from src_2, or > 0 if otherwise.
114 int strcmp( const char * src_1, const char * src_2 );
116 /** STRing COLLate. Compares two C strings until two differing characters are
117 * found, honoring the current locale.
118 * This implementation actually returns the difference of the two characters.
119 * This behaviour is implementation-defined and should not be relied upon to
120 * keep your code portable across implementations.
121 * @param src_1 The first string to be compared.
122 * @param src_2 The second string to be compared.
123 * @return 0, if both strings are identical. If two differing characters are
124 * found, returns a value < 0 if the character from src_1 is smaller
125 * than that from src_2, or > 0 if otherwise.
128 int strcoll( const char * src_1, const char * src_2 );
130 /** STRing CoPY. Copies a source string (including terminating \0) into a
131 * destination string. If the memory area pointed to by dest is not large
132 * enough to hold src, behaviour is undefined. Should the memory areas pointed
133 * to by dest and src overlap, behavious is undefined.
134 * @param dest The destination string.
135 * @param src The source string.
136 * @return A pointer to the destination string.
139 char * strcpy( char * restrict dest, const char * restrict src );
141 /** STRing Character SPaN. Compares two C strings, determining the length of
142 * the substring not containing any character from the second string.
143 * @param src_1 The string to be searched.
144 * @param src_2 The string containing the characters to be searched for.
145 * @return The length of the src_1 substring not containing any character
148 size_t strcspn( const char * src_1, const char * src_2 );
150 /** STRing ERROR. Returns the error message corresponding to an error code.
151 * @param errorcode The error code.
152 * @return The plaintext error message corresponding to the error code.
156 char * strerror( int errorcode );
158 /** STRing LENgth. Returns the number of characters in a C string, not counting
159 * the terminating \0.
160 * @param src The source string.
161 * @return The number of characters in the string, not counting the
164 size_t strlen( const char * src );
166 /** STRing N conCATenate. Appends a C string to another, setting a limit on the
167 * number of characters copied.
168 * @param dest The destination string.
169 * @param src The source string.
170 * @param n The maximum number of characters to be copied.
171 * @return A pointer to the destination string.
174 char * strncat( char * restrict dest, const char * restrict src, size_t n );
176 /** STRing N CoMPare. Compares two C strings until two differing characters are
177 * found, both strings end, or a maximum number of characters has been
179 * This implementation actually returns the difference of the two characters.
180 * This behaviour is implementation-defined and should not be relied upon to
181 * keep your code portable across implementations.
182 * @param src_1 The first string to be compared.
183 * @param src_2 The second string to be compared.
184 * @param n The maximum number of characters to be compared.
185 * @return 0, if both strings are identical. If two differing characters are
186 * found, returns a value < 0 if the character from src_1 is smaller
187 * than that from src_2, or > 0 if otherwise.
190 int strncmp( const char * src_1, const char * src_2, size_t n );
192 /** STRing CoPY. Copies a source string (including terminating \0) into a
193 * destination string, setting a limit on the number of characters copied.
194 * Should the memory areas pointed to by dest and src overlap, behaviour is
196 * @param dest The destination string.
197 * @param src The source string.
198 * @param n The maximum number of characters to be copied.
199 * @return A pointer to the destination string.
202 char * strncpy( char * restrict s1, const char * restrict s2, size_t n );
204 /** STRing SPaN. Compares two C strings, determining the length of the
205 * substring where both strings are equal.
206 * @param src_1 The first string to be compared.
207 * @param src_2 The second string to be compared.
208 * @return The length of the identical substring.
210 size_t strspn( const char * s1, const char * s2 );
212 /** STRing TOKenizer. This (complex and not thread-safe) function allows, by
213 * subsequent calls, to parse a string for tokens. The first parameter to the
214 * function is the C string to be parsed, the second parameter a C string
215 * containing a collection of seperating characters. On first call to the
216 * function, strtok() skips leading seperators, sets the first seperator after
217 * the token to \0, and returns a pointer to the token. Subsequent calls to
218 * strtok() with NULL as the first parameter return pointers to subsequent
219 * tokens, or NULL when all tokens have been parsed.
220 * Beware, this function is not thread-safe.
221 * @param src The string to be parsed (on first call), or NULL (to parse
222 * subsequent tokens).
223 * @param seperators The string containing the seperator(s).
224 * @return The next token parsed, or NULL if parse completed.
226 char * strtok( char * restrict src, const char * restrict seperators );
228 /** STRing X FRoM. This function transforms a C string into another using a
229 * transformation rule depending on the current locale.
230 * @param dest The destination, where the transformed string should be written
232 * @param src The source string to be transformed.
233 * @param n The maximum number of characters to be written to dest. If this
234 * parameter is zero, 'dest' can be a NULL pointer (to determine the
235 * required space before doing the actual transformation).
236 * @return The length of the string after transformation. If return value > n,
237 * the transformed string has not been written, and the contents of
238 * 'dest' are undefined.
242 size_t strxfrm( char * restrict s1, const char * restrict s2, size_t n );
244 /** STRing search, return Pointer to BReaK. Searches a C string (including
245 * terminating \0) for any character contained in a second string. If the
246 * first string is not properly terminated, behaviour is undefined.
247 * @param src_1 The string to be seached.
248 * @param src_2 The string containing the characters to be searched.
249 * @return A pointer into src_1 pointing to the first occurrence of any
250 * character from src_2, or NULL if no match found.
252 char * strpbrk( const char * src_1, const char * src_2 );
254 /** STRing Reverse search for CHaRacter. Searches a C string (including
255 * terminating \0) for a character. If the string is not properly terminated,
256 * behaviour is undefined.
257 * @param src The source string.
258 * @param c The character to look for.
259 * @return A pointer to the last occurrence of c in src, or NULL if no match
262 char * strrchr( const char * s, int c );
264 /** STRing search for STRing. Searches a C string for a substring.
265 * @param src_1 The string to be searched in.
266 * @param src_2 The substring to be searched for.
267 * @return A pointer to the first occurrence of src_2 in src_1, or NULL if no
270 char * strstr( const char * src_1, const char * src_2 );