plstr.h [include/nspr/plstr.h] - Woboq Code Browser

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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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 */
438