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
31PR_BEGIN_EXTERN_C
32/*
33 * PL_strlen
34 *
35 * Returns the length of the provided string, not including the trailing '\0'.
36 */
37
38PR_EXTERN(PRUint32)
39PL_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
49PR_EXTERN(PRUint32)
50PL_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
60PR_EXTERN(char *)
61PL_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
73PR_EXTERN(char *)
74PL_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
96PR_EXTERN(char *)
97PL_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
110PR_EXTERN(char *)
111PL_strdup(const char *s);
112
113/*
114 * PL_strfree
115 *
116 * Free memory allocated by PL_strdup
117 */
118
119PR_EXTERN(void)
120PL_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
134PR_EXTERN(char *)
135PL_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
146PR_EXTERN(char *)
147PL_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
161PR_EXTERN(char *)
162PL_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
175PR_EXTERN(char *)
176PL_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
187PR_EXTERN(PRIntn)
188PL_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
201PR_EXTERN(PRIntn)
202PL_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
213PR_EXTERN(PRIntn)
214PL_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
225PR_EXTERN(PRIntn)
226PL_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
236PR_EXTERN(char *)
237PL_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
247PR_EXTERN(char *)
248PL_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
259PR_EXTERN(char *)
260PL_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
271PR_EXTERN(char *)
272PL_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
287PR_EXTERN(char *)
288PL_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
298PR_EXTERN(char *)
299PL_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
309PR_EXTERN(char *)
310PL_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
320PR_EXTERN(char *)
321PL_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
330PR_EXTERN(char *)
331PL_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
340PR_EXTERN(char *)
341PL_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
351PR_EXTERN(char *)
352PL_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
362PR_EXTERN(char *)
363PL_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
372PR_EXTERN(char *)
373PL_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
382PR_EXTERN(char *)
383PL_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
393PR_EXTERN(char *)
394PL_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
404PR_EXTERN(char *)
405PL_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
426PR_EXTERN(char *)
427PL_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
435PR_END_EXTERN_C
436
437#endif /* _plstr_h */
438

source code of include/nspr/plstr.h