Line data Source code
1 : /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 : /* This Source Code Form is subject to the terms of the Mozilla Public
3 : * License, v. 2.0. If a copy of the MPL was not distributed with this
4 : * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5 :
6 : #ifndef _plstr_h
7 : #define _plstr_h
8 :
9 : /*
10 : * plstr.h
11 : *
12 : * This header file exports the API to the NSPR portable library or string-
13 : * handling functions.
14 : *
15 : * This API was not designed as an "optimal" or "ideal" string library; it
16 : * was based on the good ol' unix string.3 functions, and was written to
17 : *
18 : * 1) replace the libc functions, for cross-platform consistency,
19 : * 2) complete the API on platforms lacking common functions (e.g.,
20 : * strcase*), and
21 : * 3) to implement some obvious "closure" functions that I've seen
22 : * people hacking around in our code.
23 : *
24 : * Point number three largely means that most functions have an "strn"
25 : * limited-length version, and all comparison routines have a non-case-
26 : * sensitive version available.
27 : */
28 :
29 : #include "prtypes.h"
30 :
31 : PR_BEGIN_EXTERN_C
32 : /*
33 : * PL_strlen
34 : *
35 : * Returns the length of the provided string, not including the trailing '\0'.
36 : */
37 :
38 : PR_EXTERN(PRUint32)
39 769 : PL_strlen(const char *str);
40 :
41 : /*
42 : * PL_strnlen
43 : *
44 : * Returns the length of the provided string, not including the trailing '\0',
45 : * up to the indicated maximum. The string will not be examined beyond the
46 : * maximum; if no terminating '\0' is found, the maximum will be returned.
47 : */
48 :
49 : PR_EXTERN(PRUint32)
50 0 : PL_strnlen(const char *str, PRUint32 max);
51 :
52 : /*
53 : * PL_strcpy
54 : *
55 : * Copies the source string, up to and including the trailing '\0', into the
56 : * destination buffer. It does not (can not) verify that the destination
57 : * buffer is large enough. It returns the "dest" argument.
58 : */
59 :
60 : PR_EXTERN(char *)
61 0 : PL_strcpy(char *dest, const char *src);
62 :
63 : /*
64 : * PL_strncpy
65 : *
66 : * Copies the source string into the destination buffer, up to and including
67 : * the trailing '\0' or up to and including the max'th character, whichever
68 : * comes first. It does not (can not) verify that the destination buffer is
69 : * large enough. If the source string is longer than the maximum length,
70 : * the result will *not* be null-terminated (JLRU).
71 : */
72 :
73 : PR_EXTERN(char *)
74 0 : PL_strncpy(char *dest, const char *src, PRUint32 max);
75 :
76 : /*
77 : * PL_strncpyz
78 : *
79 : * Copies the source string into the destination buffer, up to and including
80 : * the trailing '\0' or up but not including the max'th character, whichever
81 : * comes first. It does not (can not) verify that the destination buffer is
82 : * large enough. The destination string is always terminated with a '\0',
83 : * unlike the traditional libc implementation. It returns the "dest" argument.
84 : *
85 : * NOTE: If you call this with a source "abcdefg" and a max of 5, the
86 : * destination will end up with "abcd\0" (i.e., its strlen length will be 4)!
87 : *
88 : * This means you can do this:
89 : *
90 : * char buffer[ SOME_SIZE ];
91 : * PL_strncpyz(buffer, src, sizeof(buffer));
92 : *
93 : * and the result will be properly terminated.
94 : */
95 :
96 : PR_EXTERN(char *)
97 140 : PL_strncpyz(char *dest, const char *src, PRUint32 max);
98 :
99 : /*
100 : * PL_strdup
101 : *
102 : * Returns a pointer to a malloc'd extent of memory containing a duplicate
103 : * of the argument string. The size of the allocated extent is one greater
104 : * than the length of the argument string, because of the terminator. A
105 : * null argument, like a zero-length argument, will result in a pointer to
106 : * a one-byte extent containing the null value. This routine returns null
107 : * upon malloc failure.
108 : */
109 :
110 : PR_EXTERN(char *)
111 5025 : PL_strdup(const char *s);
112 :
113 : /*
114 : * PL_strfree
115 : *
116 : * Free memory allocated by PL_strdup
117 : */
118 :
119 : PR_EXTERN(void)
120 22 : PL_strfree(char *s);
121 :
122 : /*
123 : * PL_strndup
124 : *
125 : * Returns a pointer to a malloc'd extent of memory containing a duplicate
126 : * of the argument string, up to the maximum specified. If the argument
127 : * string has a length greater than the value of the specified maximum, the
128 : * return value will be a pointer to an extent of memory of length one
129 : * greater than the maximum specified. A null string, a zero-length string,
130 : * or a zero maximum will all result in a pointer to a one-byte extent
131 : * containing the null value. This routine returns null upon malloc failure.
132 : */
133 :
134 : PR_EXTERN(char *)
135 0 : PL_strndup(const char *s, PRUint32 max);
136 :
137 : /*
138 : * PL_strcat
139 : *
140 : * Appends a copy of the string pointed to by the second argument to the
141 : * end of the string pointed to by the first. The destination buffer is
142 : * not (can not be) checked for sufficient size. A null destination
143 : * argument returns null; otherwise, the first argument is returned.
144 : */
145 :
146 : PR_EXTERN(char *)
147 0 : PL_strcat(char *dst, const char *src);
148 :
149 : /*
150 : * PL_strncat
151 : *
152 : * Appends a copy of the string pointed to by the second argument, up to
153 : * the maximum size specified, to the end of the string pointed to by the
154 : * first. The destination buffer is not (can not be) checked for sufficient
155 : * size. A null destination argument returns null; otherwise, the first
156 : * argument is returned. If the maximum size limits the copy, then the
157 : * result will *not* be null-terminated (JLRU). A null destination
158 : * returns null; otherwise, the destination argument is returned.
159 : */
160 :
161 : PR_EXTERN(char *)
162 0 : PL_strncat(char *dst, const char *src, PRUint32 max);
163 :
164 : /*
165 : * PL_strcatn
166 : *
167 : * Appends a copy of the string pointed to by the third argument, to the
168 : * end of the string pointed to by the first. The second argument specifies
169 : * the maximum size of the destination buffer, including the null termination.
170 : * If the existing string in dst is longer than the max, no action is taken.
171 : * The resulting string will be null-terminated. A null destination returns
172 : * null; otherwise, the destination argument is returned.
173 : */
174 :
175 : PR_EXTERN(char *)
176 0 : PL_strcatn(char *dst, PRUint32 max, const char *src);
177 :
178 : /*
179 : * PL_strcmp
180 : *
181 : * Returns an integer, the sign of which -- positive, zero, or negative --
182 : * reflects the lexical sorting order of the two strings indicated. The
183 : * result is positive if the first string comes after the second. The
184 : * NSPR implementation is not i18n.
185 : */
186 :
187 : PR_EXTERN(PRIntn)
188 472 : PL_strcmp(const char *a, const char *b);
189 :
190 : /*
191 : * PL_strncmp
192 : *
193 : * Returns an integer, the sign of which -- positive, zero, or negative --
194 : * reflects the lexical sorting order of the two strings indicated, up to
195 : * the maximum specified. The result is positive if the first string comes
196 : * after the second. The NSPR implementation is not i18n. If the maximum
197 : * is zero, only the existance or non-existance (pointer is null) of the
198 : * strings is compared.
199 : */
200 :
201 : PR_EXTERN(PRIntn)
202 192081 : PL_strncmp(const char *a, const char *b, PRUint32 max);
203 :
204 : /*
205 : * PL_strcasecmp
206 : *
207 : * Returns an integer, the sign of which -- positive, zero or negative --
208 : * reflects the case-insensitive lexical sorting order of the two strings
209 : * indicated. The result is positive if the first string comes after the
210 : * second. The NSPR implementation is not i18n.
211 : */
212 :
213 : PR_EXTERN(PRIntn)
214 31326 : PL_strcasecmp(const char *a, const char *b);
215 :
216 : /*
217 : * PL_strncasecmp
218 : *
219 : * Returns an integer, the sign of which -- positive, zero or negative --
220 : * reflects the case-insensitive lexical sorting order of the first n characters
221 : * of the two strings indicated. The result is positive if the first string comes
222 : * after the second. The NSPR implementation is not i18n.
223 : */
224 :
225 : PR_EXTERN(PRIntn)
226 14013 : PL_strncasecmp(const char *a, const char *b, PRUint32 max);
227 :
228 : /*
229 : * PL_strchr
230 : *
231 : * Returns a pointer to the first instance of the specified character in the
232 : * provided string. It returns null if the character is not found, or if the
233 : * provided string is null. The character may be the null character.
234 : */
235 :
236 : PR_EXTERN(char *)
237 297 : PL_strchr(const char *s, char c);
238 :
239 : /*
240 : * PL_strrchr
241 : *
242 : * Returns a pointer to the last instance of the specified character in the
243 : * provided string. It returns null if the character is not found, or if the
244 : * provided string is null. The character may be the null character.
245 : */
246 :
247 : PR_EXTERN(char *)
248 0 : PL_strrchr(const char *s, char c);
249 :
250 : /*
251 : * PL_strnchr
252 : *
253 : * Returns a pointer to the first instance of the specified character within the
254 : * first n characters of the provided string. It returns null if the character
255 : * is not found, or if the provided string is null. The character may be the
256 : * null character.
257 : */
258 :
259 : PR_EXTERN(char *)
260 0 : PL_strnchr(const char *s, char c, PRUint32 n);
261 :
262 : /*
263 : * PL_strnrchr
264 : *
265 : * Returns a pointer to the last instance of the specified character within the
266 : * first n characters of the provided string. It returns null if the character is
267 : * not found, or if the provided string is null. The character may be the null
268 : * character.
269 : */
270 :
271 : PR_EXTERN(char *)
272 0 : PL_strnrchr(const char *s, char c, PRUint32 n);
273 :
274 : /*
275 : * NOTE: Looking for strcasechr, strcaserchr, strncasechr, or strncaserchr?
276 : * Use strpbrk, strprbrk, strnpbrk or strnprbrk.
277 : */
278 :
279 : /*
280 : * PL_strpbrk
281 : *
282 : * Returns a pointer to the first instance in the first string of any character
283 : * (not including the terminating null character) of the second string. It returns
284 : * null if either string is null.
285 : */
286 :
287 : PR_EXTERN(char *)
288 48 : PL_strpbrk(const char *s, const char *list);
289 :
290 : /*
291 : * PL_strprbrk
292 : *
293 : * Returns a pointer to the last instance in the first string of any character
294 : * (not including the terminating null character) of the second string. It returns
295 : * null if either string is null.
296 : */
297 :
298 : PR_EXTERN(char *)
299 0 : PL_strprbrk(const char *s, const char *list);
300 :
301 : /*
302 : * PL_strnpbrk
303 : *
304 : * Returns a pointer to the first instance (within the first n characters) of any
305 : * character (not including the terminating null character) of the second string.
306 : * It returns null if either string is null.
307 : */
308 :
309 : PR_EXTERN(char *)
310 0 : PL_strnpbrk(const char *s, const char *list, PRUint32 n);
311 :
312 : /*
313 : * PL_strnprbrk
314 : *
315 : * Returns a pointer to the last instance (within the first n characters) of any
316 : * character (not including the terminating null character) of the second string.
317 : * It returns null if either string is null.
318 : */
319 :
320 : PR_EXTERN(char *)
321 0 : PL_strnprbrk(const char *s, const char *list, PRUint32 n);
322 :
323 : /*
324 : * PL_strstr
325 : *
326 : * Returns a pointer to the first instance of the little string within the
327 : * big one. It returns null if either string is null.
328 : */
329 :
330 : PR_EXTERN(char *)
331 47 : PL_strstr(const char *big, const char *little);
332 :
333 : /*
334 : * PL_strrstr
335 : *
336 : * Returns a pointer to the last instance of the little string within the big one.
337 : * It returns null if either string is null.
338 : */
339 :
340 : PR_EXTERN(char *)
341 0 : PL_strrstr(const char *big, const char *little);
342 :
343 : /*
344 : * PL_strnstr
345 : *
346 : * Returns a pointer to the first instance of the little string within the first
347 : * n characters of the big one. It returns null if either string is null. It
348 : * returns null if the length of the little string is greater than n.
349 : */
350 :
351 : PR_EXTERN(char *)
352 0 : PL_strnstr(const char *big, const char *little, PRUint32 n);
353 :
354 : /*
355 : * PL_strnrstr
356 : *
357 : * Returns a pointer to the last instance of the little string within the first
358 : * n characters of the big one. It returns null if either string is null. It
359 : * returns null if the length of the little string is greater than n.
360 : */
361 :
362 : PR_EXTERN(char *)
363 0 : PL_strnrstr(const char *big, const char *little, PRUint32 max);
364 :
365 : /*
366 : * PL_strcasestr
367 : *
368 : * Returns a pointer to the first instance of the little string within the big one,
369 : * ignoring case. It returns null if either string is null.
370 : */
371 :
372 : PR_EXTERN(char *)
373 34 : PL_strcasestr(const char *big, const char *little);
374 :
375 : /*
376 : * PL_strcaserstr
377 : *
378 : * Returns a pointer to the last instance of the little string within the big one,
379 : * ignoring case. It returns null if either string is null.
380 : */
381 :
382 : PR_EXTERN(char *)
383 0 : PL_strcaserstr(const char *big, const char *little);
384 :
385 : /*
386 : * PL_strncasestr
387 : *
388 : * Returns a pointer to the first instance of the little string within the first
389 : * n characters of the big one, ignoring case. It returns null if either string is
390 : * null. It returns null if the length of the little string is greater than n.
391 : */
392 :
393 : PR_EXTERN(char *)
394 1727 : PL_strncasestr(const char *big, const char *little, PRUint32 max);
395 :
396 : /*
397 : * PL_strncaserstr
398 : *
399 : * Returns a pointer to the last instance of the little string within the first
400 : * n characters of the big one, ignoring case. It returns null if either string is
401 : * null. It returns null if the length of the little string is greater than n.
402 : */
403 :
404 : PR_EXTERN(char *)
405 0 : PL_strncaserstr(const char *big, const char *little, PRUint32 max);
406 :
407 : /*
408 : * PL_strtok_r
409 : *
410 : * Splits the string s1 into tokens, separated by one or more characters
411 : * from the separator string s2. The argument lasts points to a
412 : * user-supplied char * pointer in which PL_strtok_r stores information
413 : * for it to continue scanning the same string.
414 : *
415 : * In the first call to PL_strtok_r, s1 points to a string and the value
416 : * of *lasts is ignored. PL_strtok_r returns a pointer to the first
417 : * token, writes '\0' into the character following the first token, and
418 : * updates *lasts.
419 : *
420 : * In subsequent calls, s1 is null and lasts must stay unchanged from the
421 : * previous call. The separator string s2 may be different from call to
422 : * call. PL_strtok_r returns a pointer to the next token in s1. When no
423 : * token remains in s1, PL_strtok_r returns null.
424 : */
425 :
426 : PR_EXTERN(char *)
427 0 : PL_strtok_r(char *s1, const char *s2, char **lasts);
428 :
429 : /*
430 : * Things not (yet?) included: strspn/strcspn, strsep.
431 : * memchr, memcmp, memcpy, memccpy, index, rindex, bcmp, bcopy, bzero.
432 : * Any and all i18n/l10n stuff.
433 : */
434 :
435 : PR_END_EXTERN_C
436 :
437 : #endif /* _plstr_h */
|
