00001 /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as 00002 * applicable. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 /* Portions of this file are covered by */ 00018 /* -*- mode: c; c-file-style: "k&r" -*- 00019 00020 strnatcmp.c -- Perform 'natural order' comparisons of strings in C. 00021 Copyright (C) 2000 by Martin Pool <mbp@humbug.org.au> 00022 00023 This software is provided 'as-is', without any express or implied 00024 warranty. In no event will the authors be held liable for any damages 00025 arising from the use of this software. 00026 00027 Permission is granted to anyone to use this software for any purpose, 00028 including commercial applications, and to alter it and redistribute it 00029 freely, subject to the following restrictions: 00030 00031 1. The origin of this software must not be misrepresented; you must not 00032 claim that you wrote the original software. If you use this software 00033 in a product, an acknowledgment in the product documentation would be 00034 appreciated but is not required. 00035 2. Altered source versions must be plainly marked as such, and must not be 00036 misrepresented as being the original software. 00037 3. This notice may not be removed or altered from any source distribution. 00038 */ 00039 00040 #ifndef APR_STRINGS_H 00041 #define APR_STRINGS_H 00042 00043 /** 00044 * @file apr_strings.h 00045 * @brief APR Strings library 00046 */ 00047 00048 #include "apr.h" 00049 #include "apr_errno.h" 00050 #include "apr_pools.h" 00051 #define APR_WANT_IOVEC 00052 #include "apr_want.h" 00053 00054 #if APR_HAVE_STDARG_H 00055 #include <stdarg.h> 00056 #endif 00057 00058 #ifdef __cplusplus 00059 extern "C" { 00060 #endif /* __cplusplus */ 00061 00062 /** 00063 * @defgroup apr_strings String routines 00064 * @ingroup APR 00065 * @{ 00066 */ 00067 00068 /** 00069 * Do a natural order comparison of two strings. 00070 * @param a The first string to compare 00071 * @param b The second string to compare 00072 * @return Either <0, 0, or >0. If the first string is less than the second 00073 * this returns <0, if they are equivalent it returns 0, and if the 00074 * first string is greater than second string it retuns >0. 00075 */ 00076 APR_DECLARE(int) apr_strnatcmp(char const *a, char const *b); 00077 00078 /** 00079 * Do a natural order comparison of two strings ignoring the case of the 00080 * strings. 00081 * @param a The first string to compare 00082 * @param b The second string to compare 00083 * @return Either <0, 0, or >0. If the first string is less than the second 00084 * this returns <0, if they are equivalent it returns 0, and if the 00085 * first string is greater than second string it retuns >0. 00086 */ 00087 APR_DECLARE(int) apr_strnatcasecmp(char const *a, char const *b); 00088 00089 /** 00090 * duplicate a string into memory allocated out of a pool 00091 * @param p The pool to allocate out of 00092 * @param s The string to duplicate 00093 * @return The new string 00094 */ 00095 APR_DECLARE(char *) apr_pstrdup(apr_pool_t *p, const char *s); 00096 00097 /** 00098 * Create a null-terminated string by making a copy of a sequence 00099 * of characters and appending a null byte 00100 * @param p The pool to allocate out of 00101 * @param s The block of characters to duplicate 00102 * @param n The number of characters to duplicate 00103 * @return The new string 00104 * @remark This is a faster alternative to apr_pstrndup, for use 00105 * when you know that the string being duplicated really 00106 * has 'n' or more characters. If the string might contain 00107 * fewer characters, use apr_pstrndup. 00108 */ 00109 APR_DECLARE(char *) apr_pstrmemdup(apr_pool_t *p, const char *s, apr_size_t n); 00110 00111 /** 00112 * duplicate the first n characters of a string into memory allocated 00113 * out of a pool; the new string will be null-terminated 00114 * @param p The pool to allocate out of 00115 * @param s The string to duplicate 00116 * @param n The number of characters to duplicate 00117 * @return The new string 00118 */ 00119 APR_DECLARE(char *) apr_pstrndup(apr_pool_t *p, const char *s, apr_size_t n); 00120 00121 /** 00122 * Duplicate a block of memory. 00123 * 00124 * @param p The pool to allocate from 00125 * @param m The memory to duplicate 00126 * @param n The number of bytes to duplicate 00127 * @return The new block of memory 00128 */ 00129 APR_DECLARE(void *) apr_pmemdup(apr_pool_t *p, const void *m, apr_size_t n); 00130 00131 /** 00132 * Concatenate multiple strings, allocating memory out a pool 00133 * @param p The pool to allocate out of 00134 * @param ... The strings to concatenate. The final string must be NULL 00135 * @return The new string 00136 */ 00137 APR_DECLARE_NONSTD(char *) apr_pstrcat(apr_pool_t *p, ...); 00138 00139 /** 00140 * Concatenate multiple strings specified in a writev-style vector 00141 * @param p The pool from which to allocate 00142 * @param vec The strings to concatenate 00143 * @param nvec The number of strings to concatenate 00144 * @param nbytes (output) strlen of new string (pass in NULL to omit) 00145 * @return The new string 00146 */ 00147 APR_DECLARE(char *) apr_pstrcatv(apr_pool_t *p, const struct iovec *vec, 00148 apr_size_t nvec, apr_size_t *nbytes); 00149 00150 /** 00151 * printf-style style printing routine. The data is output to a string 00152 * allocated from a pool 00153 * @param p The pool to allocate out of 00154 * @param fmt The format of the string 00155 * @param ap The arguments to use while printing the data 00156 * @return The new string 00157 */ 00158 APR_DECLARE(char *) apr_pvsprintf(apr_pool_t *p, const char *fmt, va_list ap); 00159 00160 /** 00161 * printf-style style printing routine. The data is output to a string 00162 * allocated from a pool 00163 * @param p The pool to allocate out of 00164 * @param fmt The format of the string 00165 * @param ... The arguments to use while printing the data 00166 * @return The new string 00167 */ 00168 APR_DECLARE_NONSTD(char *) apr_psprintf(apr_pool_t *p, const char *fmt, ...) 00169 __attribute__((format(printf,2,3))); 00170 00171 /** 00172 * Copy up to dst_size characters from src to dst; does not copy 00173 * past a NUL terminator in src, but always terminates dst with a NUL 00174 * regardless. 00175 * @param dst The destination string 00176 * @param src The source string 00177 * @param dst_size The space available in dst; dst always receives 00178 * NUL termination, so if src is longer than 00179 * dst_size, the actual number of characters copied is 00180 * dst_size - 1. 00181 * @return Pointer to the NUL terminator of the destination string, dst 00182 * @remark 00183 * <PRE> 00184 * Note the differences between this function and strncpy(): 00185 * 1) strncpy() doesn't always NUL terminate; apr_cpystrn() does. 00186 * 2) strncpy() pads the destination string with NULs, which is often 00187 * unnecessary; apr_cpystrn() does not. 00188 * 3) strncpy() returns a pointer to the beginning of the dst string; 00189 * apr_cpystrn() returns a pointer to the NUL terminator of dst, 00190 * to allow a check for truncation. 00191 * </PRE> 00192 */ 00193 APR_DECLARE(char *) apr_cpystrn(char *dst, const char *src, 00194 apr_size_t dst_size); 00195 00196 /** 00197 * Strip spaces from a string 00198 * @param dest The destination string. It is okay to modify the string 00199 * in place. Namely dest == src 00200 * @param src The string to rid the spaces from. 00201 * @return The destination string, dest. 00202 */ 00203 APR_DECLARE(char *) apr_collapse_spaces(char *dest, const char *src); 00204 00205 /** 00206 * Convert the arguments to a program from one string to an array of 00207 * strings terminated by a NULL pointer 00208 * @param arg_str The arguments to convert 00209 * @param argv_out Output location. This is a pointer to an array of strings. 00210 * @param token_context Pool to use. 00211 */ 00212 APR_DECLARE(apr_status_t) apr_tokenize_to_argv(const char *arg_str, 00213 char ***argv_out, 00214 apr_pool_t *token_context); 00215 00216 /** 00217 * Split a string into separate null-terminated tokens. The tokens are 00218 * delimited in the string by one or more characters from the sep 00219 * argument. 00220 * @param str The string to separate; this should be specified on the 00221 * first call to apr_strtok() for a given string, and NULL 00222 * on subsequent calls. 00223 * @param sep The set of delimiters 00224 * @param last Internal state saved by apr_strtok() between calls. 00225 * @return The next token from the string 00226 */ 00227 APR_DECLARE(char *) apr_strtok(char *str, const char *sep, char **last); 00228 00229 /** 00230 * @defgroup APR_Strings_Snprintf snprintf implementations 00231 * @warning 00232 * These are snprintf implementations based on apr_vformatter(). 00233 * 00234 * Note that various standards and implementations disagree on the return 00235 * value of snprintf, and side-effects due to %n in the formatting string. 00236 * apr_snprintf (and apr_vsnprintf) behaves as follows: 00237 * 00238 * Process the format string until the entire string is exhausted, or 00239 * the buffer fills. If the buffer fills then stop processing immediately 00240 * (so no further %n arguments are processed), and return the buffer 00241 * length. In all cases the buffer is NUL terminated. It will return the 00242 * number of characters inserted into the buffer, not including the 00243 * terminating NUL. As a special case, if len is 0, apr_snprintf will 00244 * return the number of characters that would have been inserted if 00245 * the buffer had been infinite (in this case, *buffer can be NULL) 00246 * 00247 * In no event does apr_snprintf return a negative number. 00248 * @{ 00249 */ 00250 00251 /** 00252 * snprintf routine based on apr_vformatter. This means it understands the 00253 * same extensions. 00254 * @param buf The buffer to write to 00255 * @param len The size of the buffer 00256 * @param format The format string 00257 * @param ... The arguments to use to fill out the format string. 00258 */ 00259 APR_DECLARE_NONSTD(int) apr_snprintf(char *buf, apr_size_t len, 00260 const char *format, ...) 00261 __attribute__((format(printf,3,4))); 00262 00263 /** 00264 * vsnprintf routine based on apr_vformatter. This means it understands the 00265 * same extensions. 00266 * @param buf The buffer to write to 00267 * @param len The size of the buffer 00268 * @param format The format string 00269 * @param ap The arguments to use to fill out the format string. 00270 */ 00271 APR_DECLARE(int) apr_vsnprintf(char *buf, apr_size_t len, const char *format, 00272 va_list ap); 00273 /** @} */ 00274 00275 /** 00276 * create a string representation of an int, allocated from a pool 00277 * @param p The pool from which to allocate 00278 * @param n The number to format 00279 * @return The string representation of the number 00280 */ 00281 APR_DECLARE(char *) apr_itoa(apr_pool_t *p, int n); 00282 00283 /** 00284 * create a string representation of a long, allocated from a pool 00285 * @param p The pool from which to allocate 00286 * @param n The number to format 00287 * @return The string representation of the number 00288 */ 00289 APR_DECLARE(char *) apr_ltoa(apr_pool_t *p, long n); 00290 00291 /** 00292 * create a string representation of an apr_off_t, allocated from a pool 00293 * @param p The pool from which to allocate 00294 * @param n The number to format 00295 * @return The string representation of the number 00296 */ 00297 APR_DECLARE(char *) apr_off_t_toa(apr_pool_t *p, apr_off_t n); 00298 00299 /** 00300 * Convert a numeric string into an apr_off_t numeric value. 00301 * @param offset The value of the parsed string. 00302 * @param buf The string to parse. It may contain optional whitespace, 00303 * followed by an optional '+' (positive, default) or '-' (negative) 00304 * character, followed by an optional '0x' prefix if base is 0 or 16, 00305 * followed by numeric digits appropriate for base. 00306 * @param end A pointer to the end of the valid character in buf. If 00307 * not NULL, it is set to the first invalid character in buf. 00308 * @param base A numeric base in the range between 2 and 36 inclusive, 00309 * or 0. If base is zero, buf will be treated as base ten unless its 00310 * digits are prefixed with '0x', in which case it will be treated as 00311 * base 16. 00312 */ 00313 APR_DECLARE(apr_status_t) apr_strtoff(apr_off_t *offset, const char *buf, 00314 char **end, int base); 00315 00316 /** 00317 * parse a numeric string into a 64-bit numeric value 00318 * @param buf The string to parse. It may contain optional whitespace, 00319 * followed by an optional '+' (positive, default) or '-' (negative) 00320 * character, followed by an optional '0x' prefix if base is 0 or 16, 00321 * followed by numeric digits appropriate for base. 00322 * @param end A pointer to the end of the valid character in buf. If 00323 * not NULL, it is set to the first invalid character in buf. 00324 * @param base A numeric base in the range between 2 and 36 inclusive, 00325 * or 0. If base is zero, buf will be treated as base ten unless its 00326 * digits are prefixed with '0x', in which case it will be treated as 00327 * base 16. 00328 * @return The numeric value of the string. On overflow, errno is set 00329 * to ERANGE. 00330 */ 00331 APR_DECLARE(apr_int64_t) apr_strtoi64(const char *buf, char **end, int base); 00332 00333 /** 00334 * parse a base-10 numeric string into a 64-bit numeric value. 00335 * Equivalent to apr_strtoi64(buf, (char**)NULL, 10). 00336 * @param buf The string to parse 00337 * @return The numeric value of the string 00338 */ 00339 APR_DECLARE(apr_int64_t) apr_atoi64(const char *buf); 00340 00341 /** 00342 * Format a binary size (magnitiudes are 2^10 rather than 10^3) from an apr_off_t, 00343 * as bytes, K, M, T, etc, to a four character compacted human readable string. 00344 * @param size The size to format 00345 * @param buf The 5 byte text buffer (counting the trailing null) 00346 * @return The buf passed to apr_strfsize() 00347 * @remark All negative sizes report ' - ', apr_strfsize only formats positive values. 00348 */ 00349 APR_DECLARE(char *) apr_strfsize(apr_off_t size, char *buf); 00350 00351 /** @} */ 00352 00353 #ifdef __cplusplus 00354 } 00355 #endif 00356 00357 #endif /* !APR_STRINGS_H */