Annotation of win32/apache22/srclib/apr/include/apr_strings.h, revision 1.1
1.1 ! moko 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: #if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
! 111: __attribute__((alloc_size(3)))
! 112: #endif
! 113: ;
! 114:
! 115: /**
! 116: * Duplicate at most n characters of a string into memory allocated
! 117: * out of a pool; the new string will be NUL-terminated
! 118: * @param p The pool to allocate out of
! 119: * @param s The string to duplicate
! 120: * @param n The maximum number of characters to duplicate
! 121: * @return The new string
! 122: * @remark The amount of memory allocated from the pool is the length
! 123: * of the returned string including the NUL terminator
! 124: */
! 125: APR_DECLARE(char *) apr_pstrndup(apr_pool_t *p, const char *s, apr_size_t n);
! 126:
! 127: /**
! 128: * Duplicate a block of memory.
! 129: *
! 130: * @param p The pool to allocate from
! 131: * @param m The memory to duplicate
! 132: * @param n The number of bytes to duplicate
! 133: * @return The new block of memory
! 134: */
! 135: APR_DECLARE(void *) apr_pmemdup(apr_pool_t *p, const void *m, apr_size_t n)
! 136: #if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4))
! 137: __attribute__((alloc_size(3)))
! 138: #endif
! 139: ;
! 140:
! 141: /**
! 142: * Concatenate multiple strings, allocating memory out a pool
! 143: * @param p The pool to allocate out of
! 144: * @param ... The strings to concatenate. The final string must be NULL
! 145: * @return The new string
! 146: */
! 147: APR_DECLARE_NONSTD(char *) apr_pstrcat(apr_pool_t *p, ...)
! 148: #if defined(__GNUC__) && __GNUC__ >= 4
! 149: __attribute__((sentinel))
! 150: #endif
! 151: ;
! 152:
! 153: /**
! 154: * Concatenate multiple strings specified in a writev-style vector
! 155: * @param p The pool from which to allocate
! 156: * @param vec The strings to concatenate
! 157: * @param nvec The number of strings to concatenate
! 158: * @param nbytes (output) strlen of new string (pass in NULL to omit)
! 159: * @return The new string
! 160: */
! 161: APR_DECLARE(char *) apr_pstrcatv(apr_pool_t *p, const struct iovec *vec,
! 162: apr_size_t nvec, apr_size_t *nbytes);
! 163:
! 164: /**
! 165: * printf-style style printing routine. The data is output to a string
! 166: * allocated from a pool
! 167: * @param p The pool to allocate out of
! 168: * @param fmt The format of the string
! 169: * @param ap The arguments to use while printing the data
! 170: * @return The new string
! 171: */
! 172: APR_DECLARE(char *) apr_pvsprintf(apr_pool_t *p, const char *fmt, va_list ap);
! 173:
! 174: /**
! 175: * printf-style style printing routine. The data is output to a string
! 176: * allocated from a pool
! 177: * @param p The pool to allocate out of
! 178: * @param fmt The format of the string
! 179: * @param ... The arguments to use while printing the data
! 180: * @return The new string
! 181: */
! 182: APR_DECLARE_NONSTD(char *) apr_psprintf(apr_pool_t *p, const char *fmt, ...)
! 183: __attribute__((format(printf,2,3)));
! 184:
! 185: /**
! 186: * Copy up to dst_size characters from src to dst; does not copy
! 187: * past a NUL terminator in src, but always terminates dst with a NUL
! 188: * regardless.
! 189: * @param dst The destination string
! 190: * @param src The source string
! 191: * @param dst_size The space available in dst; dst always receives
! 192: * NUL termination, so if src is longer than
! 193: * dst_size, the actual number of characters copied is
! 194: * dst_size - 1.
! 195: * @return Pointer to the NUL terminator of the destination string, dst
! 196: * @remark
! 197: * <PRE>
! 198: * Note the differences between this function and strncpy():
! 199: * 1) strncpy() doesn't always NUL terminate; apr_cpystrn() does.
! 200: * 2) strncpy() pads the destination string with NULs, which is often
! 201: * unnecessary; apr_cpystrn() does not.
! 202: * 3) strncpy() returns a pointer to the beginning of the dst string;
! 203: * apr_cpystrn() returns a pointer to the NUL terminator of dst,
! 204: * to allow a check for truncation.
! 205: * </PRE>
! 206: */
! 207: APR_DECLARE(char *) apr_cpystrn(char *dst, const char *src,
! 208: apr_size_t dst_size);
! 209:
! 210: /**
! 211: * Remove all whitespace from a string
! 212: * @param dest The destination string. It is okay to modify the string
! 213: * in place. Namely dest == src
! 214: * @param src The string to rid the spaces from.
! 215: * @return A pointer to the destination string's null terminator.
! 216: */
! 217: APR_DECLARE(char *) apr_collapse_spaces(char *dest, const char *src);
! 218:
! 219: /**
! 220: * Convert the arguments to a program from one string to an array of
! 221: * strings terminated by a NULL pointer
! 222: * @param arg_str The arguments to convert
! 223: * @param argv_out Output location. This is a pointer to an array of strings.
! 224: * @param token_context Pool to use.
! 225: */
! 226: APR_DECLARE(apr_status_t) apr_tokenize_to_argv(const char *arg_str,
! 227: char ***argv_out,
! 228: apr_pool_t *token_context);
! 229:
! 230: /**
! 231: * Split a string into separate null-terminated tokens. The tokens are
! 232: * delimited in the string by one or more characters from the sep
! 233: * argument.
! 234: * @param str The string to separate; this should be specified on the
! 235: * first call to apr_strtok() for a given string, and NULL
! 236: * on subsequent calls.
! 237: * @param sep The set of delimiters
! 238: * @param last Internal state saved by apr_strtok() between calls.
! 239: * @return The next token from the string
! 240: */
! 241: APR_DECLARE(char *) apr_strtok(char *str, const char *sep, char **last);
! 242:
! 243: /**
! 244: * @defgroup APR_Strings_Snprintf snprintf implementations
! 245: * @warning
! 246: * These are snprintf implementations based on apr_vformatter().
! 247: *
! 248: * Note that various standards and implementations disagree on the return
! 249: * value of snprintf, and side-effects due to %n in the formatting string.
! 250: * apr_snprintf (and apr_vsnprintf) behaves as follows:
! 251: *
! 252: * Process the format string until the entire string is exhausted, or
! 253: * the buffer fills. If the buffer fills then stop processing immediately
! 254: * (so no further %n arguments are processed), and return the buffer
! 255: * length. In all cases the buffer is NUL terminated. It will return the
! 256: * number of characters inserted into the buffer, not including the
! 257: * terminating NUL. As a special case, if len is 0, apr_snprintf will
! 258: * return the number of characters that would have been inserted if
! 259: * the buffer had been infinite (in this case, *buffer can be NULL)
! 260: *
! 261: * In no event does apr_snprintf return a negative number.
! 262: * @{
! 263: */
! 264:
! 265: /**
! 266: * snprintf routine based on apr_vformatter. This means it understands the
! 267: * same extensions.
! 268: * @param buf The buffer to write to
! 269: * @param len The size of the buffer
! 270: * @param format The format string
! 271: * @param ... The arguments to use to fill out the format string.
! 272: */
! 273: APR_DECLARE_NONSTD(int) apr_snprintf(char *buf, apr_size_t len,
! 274: const char *format, ...)
! 275: __attribute__((format(printf,3,4)));
! 276:
! 277: /**
! 278: * vsnprintf routine based on apr_vformatter. This means it understands the
! 279: * same extensions.
! 280: * @param buf The buffer to write to
! 281: * @param len The size of the buffer
! 282: * @param format The format string
! 283: * @param ap The arguments to use to fill out the format string.
! 284: */
! 285: APR_DECLARE(int) apr_vsnprintf(char *buf, apr_size_t len, const char *format,
! 286: va_list ap);
! 287: /** @} */
! 288:
! 289: /**
! 290: * create a string representation of an int, 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_itoa(apr_pool_t *p, int n);
! 296:
! 297: /**
! 298: * create a string representation of a long, allocated from a pool
! 299: * @param p The pool from which to allocate
! 300: * @param n The number to format
! 301: * @return The string representation of the number
! 302: */
! 303: APR_DECLARE(char *) apr_ltoa(apr_pool_t *p, long n);
! 304:
! 305: /**
! 306: * create a string representation of an apr_off_t, allocated from a pool
! 307: * @param p The pool from which to allocate
! 308: * @param n The number to format
! 309: * @return The string representation of the number
! 310: */
! 311: APR_DECLARE(char *) apr_off_t_toa(apr_pool_t *p, apr_off_t n);
! 312:
! 313: /**
! 314: * Convert a numeric string into an apr_off_t numeric value.
! 315: * @param offset The value of the parsed string.
! 316: * @param buf The string to parse. It may contain optional whitespace,
! 317: * followed by an optional '+' (positive, default) or '-' (negative)
! 318: * character, followed by an optional '0x' prefix if base is 0 or 16,
! 319: * followed by numeric digits appropriate for base.
! 320: * @param end A pointer to the end of the valid character in buf. If
! 321: * not NULL, it is set to the first invalid character in buf.
! 322: * @param base A numeric base in the range between 2 and 36 inclusive,
! 323: * or 0. If base is zero, buf will be treated as base ten unless its
! 324: * digits are prefixed with '0x', in which case it will be treated as
! 325: * base 16.
! 326: * @bug *end breaks type safety; where *buf is const, *end needs to be
! 327: * declared as const in APR 2.0
! 328: */
! 329: APR_DECLARE(apr_status_t) apr_strtoff(apr_off_t *offset, const char *buf,
! 330: char **end, int base);
! 331:
! 332: /**
! 333: * parse a numeric string into a 64-bit numeric value
! 334: * @param buf The string to parse. It may contain optional whitespace,
! 335: * followed by an optional '+' (positive, default) or '-' (negative)
! 336: * character, followed by an optional '0x' prefix if base is 0 or 16,
! 337: * followed by numeric digits appropriate for base.
! 338: * @param end A pointer to the end of the valid character in buf. If
! 339: * not NULL, it is set to the first invalid character in buf.
! 340: * @param base A numeric base in the range between 2 and 36 inclusive,
! 341: * or 0. If base is zero, buf will be treated as base ten unless its
! 342: * digits are prefixed with '0x', in which case it will be treated as
! 343: * base 16.
! 344: * @return The numeric value of the string. On overflow, errno is set
! 345: * to ERANGE. On success, errno is set to 0.
! 346: */
! 347: APR_DECLARE(apr_int64_t) apr_strtoi64(const char *buf, char **end, int base);
! 348:
! 349: /**
! 350: * parse a base-10 numeric string into a 64-bit numeric value.
! 351: * Equivalent to apr_strtoi64(buf, (char**)NULL, 10).
! 352: * @param buf The string to parse
! 353: * @return The numeric value of the string. On overflow, errno is set
! 354: * to ERANGE. On success, errno is set to 0.
! 355: */
! 356: APR_DECLARE(apr_int64_t) apr_atoi64(const char *buf);
! 357:
! 358: /**
! 359: * Format a binary size (magnitiudes are 2^10 rather than 10^3) from an apr_off_t,
! 360: * as bytes, K, M, T, etc, to a four character compacted human readable string.
! 361: * @param size The size to format
! 362: * @param buf The 5 byte text buffer (counting the trailing null)
! 363: * @return The buf passed to apr_strfsize()
! 364: * @remark All negative sizes report ' - ', apr_strfsize only formats positive values.
! 365: */
! 366: APR_DECLARE(char *) apr_strfsize(apr_off_t size, char *buf);
! 367:
! 368: /** @} */
! 369:
! 370: #ifdef __cplusplus
! 371: }
! 372: #endif
! 373:
! 374: #endif /* !APR_STRINGS_H */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to apr_strings.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / apache22 / srclib / apr / include