plstr.h
上传用户:goldcmy89
上传日期:2017-12-03
资源大小:2246k
文件大小:15k
源码类别:

PlugIns编程

开发平台:

Visual C++

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