rubbos/app/apache2/include/apr_strings.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /* Portions of this file are covered by */
  18 /* -*- mode: c; c-file-style: "k&r" -*-
  19
  20   strnatcmp.c -- Perform 'natural order' comparisons of strings in C.
  21   Copyright (C) 2000 by Martin Pool <mbp@humbug.org.au>
  22
  23   This software is provided 'as-is', without any express or implied
  24   warranty.  In no event will the authors be held liable for any damages
  25   arising from the use of this software.
  26
  27   Permission is granted to anyone to use this software for any purpose,
  28   including commercial applications, and to alter it and redistribute it
  29   freely, subject to the following restrictions:
  30
  31   1. The origin of this software must not be misrepresented; you must not
  32      claim that you wrote the original software. If you use this software
  33      in a product, an acknowledgment in the product documentation would be
  34      appreciated but is not required.
  35   2. Altered source versions must be plainly marked as such, and must not be
  36      misrepresented as being the original software.
  37   3. This notice may not be removed or altered from any source distribution.
  38 */
  39
  40 #ifndef APR_STRINGS_H
  41 #define APR_STRINGS_H
  42
  43 /**
  44  * @file apr_strings.h
  45  * @brief APR Strings library
  46  */
  47
  48 #include "apr.h"
  49 #include "apr_errno.h"
  50 #include "apr_pools.h"
  51 #define APR_WANT_IOVEC
  52 #include "apr_want.h"
  53
  54 #if APR_HAVE_STDARG_H
  55 #include <stdarg.h>
  56 #endif
  57
  58 #ifdef __cplusplus
  59 extern "C" {
  60 #endif /* __cplusplus */
  61
  62 /**
  63  * @defgroup apr_strings String routines
  64  * @ingroup APR
  65  * @{
  66  */
  67
  68 /**
  69  * Do a natural order comparison of two strings.
  70  * @param a The first string to compare
  71  * @param b The second string to compare
  72  * @return Either <0, 0, or >0.  If the first string is less than the second
  73  *          this returns <0, if they are equivalent it returns 0, and if the
  74  *          first string is greater than second string it retuns >0.
  75  */
  76 APR_DECLARE(int) apr_strnatcmp(char const *a, char const *b);
  77
  78 /**
  79  * Do a natural order comparison of two strings ignoring the case of the
  80  * strings.
  81  * @param a The first string to compare
  82  * @param b The second string to compare
  83  * @return Either <0, 0, or >0.  If the first string is less than the second
  84  *         this returns <0, if they are equivalent it returns 0, and if the
  85  *         first string is greater than second string it retuns >0.
  86  */
  87 APR_DECLARE(int) apr_strnatcasecmp(char const *a, char const *b);
  88
  89 /**
  90  * duplicate a string into memory allocated out of a pool
  91  * @param p The pool to allocate out of
  92  * @param s The string to duplicate
  93  * @return The new string
  94  */
  95 APR_DECLARE(char *) apr_pstrdup(apr_pool_t *p, const char *s);
  96
  97 /**
  98  * Create a null-terminated string by making a copy of a sequence
  99  * of characters and appending a null byte
 100  * @param p The pool to allocate out of
 101  * @param s The block of characters to duplicate
 102  * @param n The number of characters to duplicate
 103  * @return The new string
 104  * @remark This is a faster alternative to apr_pstrndup, for use
 105  *         when you know that the string being duplicated really
 106  *         has 'n' or more characters.  If the string might contain
 107  *         fewer characters, use apr_pstrndup.
 108  */
 109 APR_DECLARE(char *) apr_pstrmemdup(apr_pool_t *p, const char *s, apr_size_t n);
 110
 111 /**
 112  * Duplicate at most n characters of a string into memory allocated
 113  * out of a pool; the new string will be NUL-terminated
 114  * @param p The pool to allocate out of
 115  * @param s The string to duplicate
 116  * @param n The maximum number of characters to duplicate
 117  * @return The new string
 118  * @remark The amount of memory allocated from the pool is the length
 119  *         of the returned string including the NUL terminator
 120  */
 121 APR_DECLARE(char *) apr_pstrndup(apr_pool_t *p, const char *s, apr_size_t n);
 122
 123 /**
 124  * Duplicate a block of memory.
 125  *
 126  * @param p The pool to allocate from
 127  * @param m The memory to duplicate
 128  * @param n The number of bytes to duplicate
 129  * @return The new block of memory
 130  */
 131 APR_DECLARE(void *) apr_pmemdup(apr_pool_t *p, const void *m, apr_size_t n);
 132
 133 /**
 134  * Concatenate multiple strings, allocating memory out a pool
 135  * @param p The pool to allocate out of
 136  * @param ... The strings to concatenate.  The final string must be NULL
 137  * @return The new string
 138  */
 139 APR_DECLARE_NONSTD(char *) apr_pstrcat(apr_pool_t *p, ...);
 140
 141 /**
 142  * Concatenate multiple strings specified in a writev-style vector
 143  * @param p The pool from which to allocate
 144  * @param vec The strings to concatenate
 145  * @param nvec The number of strings to concatenate
 146  * @param nbytes (output) strlen of new string (pass in NULL to omit)
 147  * @return The new string
 148  */
 149 APR_DECLARE(char *) apr_pstrcatv(apr_pool_t *p, const struct iovec *vec,
 150                                  apr_size_t nvec, apr_size_t *nbytes);
 151
 152 /**
 153  * printf-style style printing routine.  The data is output to a string
 154  * allocated from a pool
 155  * @param p The pool to allocate out of
 156  * @param fmt The format of the string
 157  * @param ap The arguments to use while printing the data
 158  * @return The new string
 159  */
 160 APR_DECLARE(char *) apr_pvsprintf(apr_pool_t *p, const char *fmt, va_list ap);
 161
 162 /**
 163  * printf-style style printing routine.  The data is output to a string
 164  * allocated from a pool
 165  * @param p The pool to allocate out of
 166  * @param fmt The format of the string
 167  * @param ... The arguments to use while printing the data
 168  * @return The new string
 169  */
 170 APR_DECLARE_NONSTD(char *) apr_psprintf(apr_pool_t *p, const char *fmt, ...)
 171         __attribute__((format(printf,2,3)));
 172
 173 /**
 174  * copy n characters from src to dst
 175  * @param dst The destination string
 176  * @param src The source string
 177  * @param dst_size The space available in dst; dst always receives
 178  *                 null-termination, so if src is longer than
 179  *                 dst_size, the actual number of characters copied is
 180  *                 dst_size - 1.
 181  * @remark
 182  * <PRE>
 183  * We re-implement this function to implement these specific changes:
 184  *       1) strncpy() doesn't always null terminate and we want it to.
 185  *       2) strncpy() null fills, which is bogus, esp. when copy 8byte strings
 186  *          into 8k blocks.
 187  *       3) Instead of returning the pointer to the beginning of the
 188  *          destination string, we return a pointer to the terminating null
 189  *          to allow us to check for truncation.
 190  * </PRE>
 191  */
 192 APR_DECLARE(char *) apr_cpystrn(char *dst, const char *src,
 193                                 apr_size_t dst_size);
 194
 195 /**
 196  * Strip spaces from a string
 197  * @param dest The destination string.  It is okay to modify the string
 198  *             in place.  Namely dest == src
 199  * @param src The string to rid the spaces from.
 200  */
 201 APR_DECLARE(char *) apr_collapse_spaces(char *dest, const char *src);
 202
 203 /**
 204  * Convert the arguments to a program from one string to an array of
 205  * strings terminated by a NULL pointer
 206  * @param arg_str The arguments to convert
 207  * @param argv_out Output location.  This is a pointer to an array of strings.
 208  * @param token_context Pool to use.
 209  */
 210 APR_DECLARE(apr_status_t) apr_tokenize_to_argv(const char *arg_str,
 211                                                char ***argv_out,
 212                                                apr_pool_t *token_context);
 213
 214 /**
 215  * Split a string into separate null-terminated tokens.  The tokens are
 216  * delimited in the string by one or more characters from the sep
 217  * argument.
 218  * @param str The string to separate; this should be specified on the
 219  *            first call to apr_strtok() for a given string, and NULL
 220  *            on subsequent calls.
 221  * @param sep The set of delimiters
 222  * @param last Internal state saved by apr_strtok() between calls.
 223  * @return The next token from the string
 224  */
 225 APR_DECLARE(char *) apr_strtok(char *str, const char *sep, char **last);
 226
 227 /**
 228  * @defgroup APR_Strings_Snprintf snprintf implementations
 229  * @warning
 230  * These are snprintf implementations based on apr_vformatter().
 231  *
 232  * Note that various standards and implementations disagree on the return
 233  * value of snprintf, and side-effects due to %n in the formatting string.
 234  * apr_snprintf (and apr_vsnprintf) behaves as follows:
 235  *
 236  * Process the format string until the entire string is exhausted, or
 237  * the buffer fills.  If the buffer fills then stop processing immediately
 238  * (so no further %n arguments are processed), and return the buffer
 239  * length.  In all cases the buffer is NUL terminated. It will return the
 240  * number of characters inserted into the buffer, not including the
 241  * terminating NUL. As a special case, if len is 0, apr_snprintf will
 242  * return the number of characters that would have been inserted if
 243  * the buffer had been infinite (in this case, *buffer can be NULL)
 244  *
 245  * In no event does apr_snprintf return a negative number.
 246  * @{
 247  */
 248
 249 /**
 250  * snprintf routine based on apr_vformatter.  This means it understands the
 251  * same extensions.
 252  * @param buf The buffer to write to
 253  * @param len The size of the buffer
 254  * @param format The format string
 255  * @param ... The arguments to use to fill out the format string.
 256  */
 257 APR_DECLARE_NONSTD(int) apr_snprintf(char *buf, apr_size_t len,
 258                                      const char *format, ...)
 259         __attribute__((format(printf,3,4)));
 260
 261 /**
 262  * vsnprintf routine based on apr_vformatter.  This means it understands the
 263  * same extensions.
 264  * @param buf The buffer to write to
 265  * @param len The size of the buffer
 266  * @param format The format string
 267  * @param ap The arguments to use to fill out the format string.
 268  */
 269 APR_DECLARE(int) apr_vsnprintf(char *buf, apr_size_t len, const char *format,
 270                                va_list ap);
 271 /** @} */
 272
 273 /**
 274  * create a string representation of an int, allocated from a pool
 275  * @param p The pool from which to allocate
 276  * @param n The number to format
 277  * @return The string representation of the number
 278  */
 279 APR_DECLARE(char *) apr_itoa(apr_pool_t *p, int n);
 280
 281 /**
 282  * create a string representation of a long, allocated from a pool
 283  * @param p The pool from which to allocate
 284  * @param n The number to format
 285  * @return The string representation of the number
 286  */
 287 APR_DECLARE(char *) apr_ltoa(apr_pool_t *p, long n);
 288
 289 /**
 290  * create a string representation of an apr_off_t, allocated from a pool
 291  * @param p The pool from which to allocate
 292  * @param n The number to format
 293  * @return The string representation of the number
 294  */
 295 APR_DECLARE(char *) apr_off_t_toa(apr_pool_t *p, apr_off_t n);
 296
 297 /**
 298  * parse a numeric string into a 64-bit numeric value
 299  * @param buf The string to parse. It may contain optional whitespace,
 300  *   followed by an optional '+' (positive, default) or '-' (negative)
 301  *   character, followed by an optional '0x' prefix if base is 0 or 16,
 302  *   followed by numeric digits appropriate for base.
 303  * @param end A pointer to the end of the valid character in buf. If
 304  *   not nil, it is set to the first invalid character in buf.
 305  * @param base A numeric base in the range between 2 and 36 inclusive,
 306  *   or 0.  If base is zero, buf will be treated as base ten unless its
 307  *   digits are prefixed with '0x', in which case it will be treated as
 308  *   base 16.
 309  * @return The numeric value of the string.
 310  */
 311 APR_DECLARE(apr_int64_t) apr_strtoi64(const char *buf, char **end, int base);
 312
 313 /**
 314  * parse a base-10 numeric string into a 64-bit numeric value.
 315  * Equivalent to apr_strtoi64(buf, (char**)NULL, 10).
 316  * @param buf The string to parse
 317  * @return The numeric value of the string
 318  */
 319 APR_DECLARE(apr_int64_t) apr_atoi64(const char *buf);
 320
 321 /**
 322  * Format a binary size (magnitiudes are 2^10 rather than 10^3) from an apr_off_t,
 323  * as bytes, K, M, T, etc, to a four character compacted human readable string.
 324  * @param size The size to format
 325  * @param buf The 5 byte text buffer (counting the trailing null)
 326  * @return The buf passed to apr_strfsize()
 327  * @remark All negative sizes report '  - ', apr_strfsize only formats positive values.
 328  */
 329 APR_DECLARE(char *) apr_strfsize(apr_off_t size, char *buf);
 330
 331 /** @} */
 332
 333 #ifdef __cplusplus
 334 }
 335 #endif
 336
 337 #endif  /* !APR_STRINGS_H */