PageRenderTime 278ms CodeModel.GetById 101ms app.highlight 104ms RepoModel.GetById 57ms app.codeStats 1ms

/gecko_api/include/plstr.h

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