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
17 /* ----------------------------------------------------------------------------
19 * --------------------------------------------------------------------------*/
23 /* ----------------------------------------------------------------------------
25 * --------------------------------------------------------------------------*/
28 #define _SIZE_T _SIZE_T
29 typedef __size_t size_t
32 /* ----------------------------------------------------------------------------
34 * --------------------------------------------------------------------------*/
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
44 void * memchr( const void * src, int c, size_t n );
46 /** MEMory CoMPare. Compares two memory areas until a difference is found.
47 * This implementation actually returns the difference of the first differing
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.
59 int memcmp( const void * src_1, const void * src_2, size_t n );
61 /** MEMory CoPY. Copies a source memory area of size n into a destination
63 * Should the memory areas pointed to by dest and src overlap, behaviour is
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 * memcpy( void * restrict dest, const void * restrict src, size_t n );
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.
81 void * memmove( void * dest, const void * src, size_t n );
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.
89 void * memset( void * dest, int c, size_t n );
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.
99 char * strcat( char * restrict dest, const char * restrict src );
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
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
109 char * strchr( const char * src, int c );
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.
124 int strcmp( const char * src_1, const char * src_2 );
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.
138 int strcoll( const char * src_1, const char * src_2 );
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.
149 char * strcpy( char * restrict dest, const char * restrict src );
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
158 size_t strcspn( const char * src_1, const char * src_2 );
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.
166 char * strerror( int errorcode );
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
174 size_t strlen( const char * src );
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.
184 char * strncat( char * restrict dest, const char * restrict src, size_t n );
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
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.
200 int strncmp( const char * src_1, const char * src_2, size_t n );
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
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.
212 char * strncpy( char * restrict dest, const char * restrict src, size_t n );
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.
220 size_t strspn( const char * src_1, const char * src_2 );
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.
236 char * strtok( char * restrict src, const char * restrict seperators );
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
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.
252 size_t strxfrm( char * restrict dest, const char * restrict src, size_t n );
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.
262 char * strpbrk( const char * src_1, const char * src_2 );
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
272 char * strrchr( const char * src, int c );
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
280 char * strstr( const char * src_1, const char * src_2 );
282 #endif /* _STRING_H */