Apache Portable Runtime
|
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more 00002 * contributor license agreements. See the NOTICE file distributed with 00003 * this work for additional information regarding copyright ownership. 00004 * The ASF licenses this file to You under the Apache License, Version 2.0 00005 * (the "License"); you may not use this file except in compliance with 00006 * the License. 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 at most n characters of a string into memory allocated 00113 * out of a pool; the new string will be NUL-terminated 00114 * @param p The pool to allocate out of 00115 * @param s The string to duplicate 00116 * @param n The maximum number of characters to duplicate 00117 * @return The new string 00118 * @remark The amount of memory allocated from the pool is the length 00119 * of the returned string including the NUL terminator 00120 */ 00121 APR_DECLARE(char *) apr_pstrndup(apr_pool_t *p, const char *s, apr_size_t n); 00122 00123 /** 00124 * Duplicate a block of memory. 00125 * 00126 * @param p The pool to allocate from 00127 * @param m The memory to duplicate 00128 * @param n The number of bytes to duplicate 00129 * @return The new block of memory 00130 */ 00131 APR_DECLARE(void *) apr_pmemdup(apr_pool_t *p, const void *m, apr_size_t n); 00132 00133 /** 00134 * Concatenate multiple strings, allocating memory out a pool 00135 * @param p The pool to allocate out of 00136 * @param ... The strings to concatenate. The final string must be NULL 00137 * @return The new string 00138 */ 00139 APR_DECLARE_NONSTD(char *) apr_pstrcat(apr_pool_t *p, ...) 00140 #if defined(__GNUC__) && __GNUC__ >= 4 00141 __attribute__((sentinel)) 00142 #endif 00143 ; 00144 00145 /** 00146 * Concatenate multiple strings specified in a writev-style vector 00147 * @param p The pool from which to allocate 00148 * @param vec The strings to concatenate 00149 * @param nvec The number of strings to concatenate 00150 * @param nbytes (output) strlen of new string (pass in NULL to omit) 00151 * @return The new string 00152 */ 00153 APR_DECLARE(char *) apr_pstrcatv(apr_pool_t *p, const struct iovec *vec, 00154 apr_size_t nvec, apr_size_t *nbytes); 00155 00156 /** 00157 * printf-style style printing routine. The data is output to a string 00158 * allocated from a pool 00159 * @param p The pool to allocate out of 00160 * @param fmt The format of the string 00161 * @param ap The arguments to use while printing the data 00162 * @return The new string 00163 */ 00164 APR_DECLARE(char *) apr_pvsprintf(apr_pool_t *p, const char *fmt, va_list ap); 00165 00166 /** 00167 * printf-style style printing routine. The data is output to a string 00168 * allocated from a pool 00169 * @param p The pool to allocate out of 00170 * @param fmt The format of the string 00171 * @param ... The arguments to use while printing the data 00172 * @return The new string 00173 */ 00174 APR_DECLARE_NONSTD(char *) apr_psprintf(apr_pool_t *p, const char *fmt, ...) 00175 __attribute__((format(printf,2,3))); 00176 00177 /** 00178 * Copy up to dst_size characters from src to dst; does not copy 00179 * past a NUL terminator in src, but always terminates dst with a NUL 00180 * regardless. 00181 * @param dst The destination string 00182 * @param src The source string 00183 * @param dst_size The space available in dst; dst always receives 00184 * NUL termination, so if src is longer than 00185 * dst_size, the actual number of characters copied is 00186 * dst_size - 1. 00187 * @return Pointer to the NUL terminator of the destination string, dst 00188 * @remark 00189 * <PRE> 00190 * Note the differences between this function and strncpy(): 00191 * 1) strncpy() doesn't always NUL terminate; apr_cpystrn() does. 00192 * 2) strncpy() pads the destination string with NULs, which is often 00193 * unnecessary; apr_cpystrn() does not. 00194 * 3) strncpy() returns a pointer to the beginning of the dst string; 00195 * apr_cpystrn() returns a pointer to the NUL terminator of dst, 00196 * to allow a check for truncation. 00197 * </PRE> 00198 */ 00199 APR_DECLARE(char *) apr_cpystrn(char *dst, const char *src, 00200 apr_size_t dst_size); 00201 00202 /** 00203 * Remove all whitespace from a string 00204 * @param dest The destination string. It is okay to modify the string 00205 * in place. Namely dest == src 00206 * @param src The string to rid the spaces from. 00207 * @return A pointer to the destination string's null terminator. 00208 */ 00209 APR_DECLARE(char *) apr_collapse_spaces(char *dest, const char *src); 00210 00211 /** 00212 * Convert the arguments to a program from one string to an array of 00213 * strings terminated by a NULL pointer 00214 * @param arg_str The arguments to convert 00215 * @param argv_out Output location. This is a pointer to an array of strings. 00216 * @param token_context Pool to use. 00217 */ 00218 APR_DECLARE(apr_status_t) apr_tokenize_to_argv(const char *arg_str, 00219 char ***argv_out, 00220 apr_pool_t *token_context); 00221 00222 /** 00223 * Split a string into separate null-terminated tokens. The tokens are 00224 * delimited in the string by one or more characters from the sep 00225 * argument. 00226 * @param str The string to separate; this should be specified on the 00227 * first call to apr_strtok() for a given string, and NULL 00228 * on subsequent calls. 00229 * @param sep The set of delimiters 00230 * @param last Internal state saved by apr_strtok() between calls. 00231 * @return The next token from the string 00232 */ 00233 APR_DECLARE(char *) apr_strtok(char *str, const char *sep, char **last); 00234 00235 /** 00236 * @defgroup APR_Strings_Snprintf snprintf implementations 00237 * @warning 00238 * These are snprintf implementations based on apr_vformatter(). 00239 * 00240 * Note that various standards and implementations disagree on the return 00241 * value of snprintf, and side-effects due to %n in the formatting string. 00242 * apr_snprintf (and apr_vsnprintf) behaves as follows: 00243 * 00244 * Process the format string until the entire string is exhausted, or 00245 * the buffer fills. If the buffer fills then stop processing immediately 00246 * (so no further %n arguments are processed), and return the buffer 00247 * length. In all cases the buffer is NUL terminated. It will return the 00248 * number of characters inserted into the buffer, not including the 00249 * terminating NUL. As a special case, if len is 0, apr_snprintf will 00250 * return the number of characters that would have been inserted if 00251 * the buffer had been infinite (in this case, *buffer can be NULL) 00252 * 00253 * In no event does apr_snprintf return a negative number. 00254 * @{ 00255 */ 00256 00257 /** 00258 * snprintf routine based on apr_vformatter. This means it understands the 00259 * same extensions. 00260 * @param buf The buffer to write to 00261 * @param len The size of the buffer 00262 * @param format The format string 00263 * @param ... The arguments to use to fill out the format string. 00264 */ 00265 APR_DECLARE_NONSTD(int) apr_snprintf(char *buf, apr_size_t len, 00266 const char *format, ...) 00267 __attribute__((format(printf,3,4))); 00268 00269 /** 00270 * vsnprintf routine based on apr_vformatter. This means it understands the 00271 * same extensions. 00272 * @param buf The buffer to write to 00273 * @param len The size of the buffer 00274 * @param format The format string 00275 * @param ap The arguments to use to fill out the format string. 00276 */ 00277 APR_DECLARE(int) apr_vsnprintf(char *buf, apr_size_t len, const char *format, 00278 va_list ap); 00279 /** @} */ 00280 00281 /** 00282 * create a string representation of an int, allocated from a pool 00283 * @param p The pool from which to allocate 00284 * @param n The number to format 00285 * @return The string representation of the number 00286 */ 00287 APR_DECLARE(char *) apr_itoa(apr_pool_t *p, int n); 00288 00289 /** 00290 * create a string representation of a long, allocated from a pool 00291 * @param p The pool from which to allocate 00292 * @param n The number to format 00293 * @return The string representation of the number 00294 */ 00295 APR_DECLARE(char *) apr_ltoa(apr_pool_t *p, long n); 00296 00297 /** 00298 * create a string representation of an apr_off_t, allocated from a pool 00299 * @param p The pool from which to allocate 00300 * @param n The number to format 00301 * @return The string representation of the number 00302 */ 00303 APR_DECLARE(char *) apr_off_t_toa(apr_pool_t *p, apr_off_t n); 00304 00305 /** 00306 * Convert a numeric string into an apr_off_t numeric value. 00307 * @param offset The value of the parsed string. 00308 * @param buf The string to parse. It may contain optional whitespace, 00309 * followed by an optional '+' (positive, default) or '-' (negative) 00310 * character, followed by an optional '0x' prefix if base is 0 or 16, 00311 * followed by numeric digits appropriate for base. 00312 * @param end A pointer to the end of the valid character in buf. If 00313 * not NULL, it is set to the first invalid character in buf. 00314 * @param base A numeric base in the range between 2 and 36 inclusive, 00315 * or 0. If base is zero, buf will be treated as base ten unless its 00316 * digits are prefixed with '0x', in which case it will be treated as 00317 * base 16. 00318 * @bug *end breaks type safety; where *buf is const, *end needs to be 00319 * declared as const in APR 2.0 00320 */ 00321 APR_DECLARE(apr_status_t) apr_strtoff(apr_off_t *offset, const char *buf, 00322 char **end, int base); 00323 00324 /** 00325 * parse a numeric string into a 64-bit numeric value 00326 * @param buf The string to parse. It may contain optional whitespace, 00327 * followed by an optional '+' (positive, default) or '-' (negative) 00328 * character, followed by an optional '0x' prefix if base is 0 or 16, 00329 * followed by numeric digits appropriate for base. 00330 * @param end A pointer to the end of the valid character in buf. If 00331 * not NULL, it is set to the first invalid character in buf. 00332 * @param base A numeric base in the range between 2 and 36 inclusive, 00333 * or 0. If base is zero, buf will be treated as base ten unless its 00334 * digits are prefixed with '0x', in which case it will be treated as 00335 * base 16. 00336 * @return The numeric value of the string. On overflow, errno is set 00337 * to ERANGE. On success, errno is set to 0. 00338 */ 00339 APR_DECLARE(apr_int64_t) apr_strtoi64(const char *buf, char **end, int base); 00340 00341 /** 00342 * parse a base-10 numeric string into a 64-bit numeric value. 00343 * Equivalent to apr_strtoi64(buf, (char**)NULL, 10). 00344 * @param buf The string to parse 00345 * @return The numeric value of the string. On overflow, errno is set 00346 * to ERANGE. On success, errno is set to 0. 00347 */ 00348 APR_DECLARE(apr_int64_t) apr_atoi64(const char *buf); 00349 00350 /** 00351 * Format a binary size (magnitiudes are 2^10 rather than 10^3) from an apr_off_t, 00352 * as bytes, K, M, T, etc, to a four character compacted human readable string. 00353 * @param size The size to format 00354 * @param buf The 5 byte text buffer (counting the trailing null) 00355 * @return The buf passed to apr_strfsize() 00356 * @remark All negative sizes report ' - ', apr_strfsize only formats positive values. 00357 */ 00358 APR_DECLARE(char *) apr_strfsize(apr_off_t size, char *buf); 00359 00360 /** @} */ 00361 00362 #ifdef __cplusplus 00363 } 00364 #endif 00365 00366 #endif /* !APR_STRINGS_H */