1339228Speter/* ==================================================================== 2339228Speter * Licensed to the Apache Software Foundation (ASF) under one 3339228Speter * or more contributor license agreements. See the NOTICE file 4339228Speter * distributed with this work for additional information 5339228Speter * regarding copyright ownership. The ASF licenses this file 6339228Speter * to you under the Apache License, Version 2.0 (the 7339228Speter * "License"); you may not use this file except in compliance 8339228Speter * with the License. You may obtain a copy of the License at 9339228Speter * 10339228Speter * http://www.apache.org/licenses/LICENSE-2.0 11339228Speter * 12339228Speter * Unless required by applicable law or agreed to in writing, 13339228Speter * software distributed under the License is distributed on an 14339228Speter * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15339228Speter * KIND, either express or implied. See the License for the 16339228Speter * specific language governing permissions and limitations 17339228Speter * under the License. 18339228Speter * ==================================================================== 19339228Speter */ 20339228Speter 21339228Speter/** 22339228Speter * @file apr_cstr.h 23339228Speter * @brief C string goodies. 24339228Speter */ 25339228Speter 26339228Speter#ifndef APR_CSTR_H 27339228Speter#define APR_CSTR_H 28339228Speter 29339228Speter#include <apr.h> /* for apr_size_t */ 30339228Speter#include <apr_pools.h> /* for apr_pool_t */ 31339228Speter#include <apr_tables.h> /* for apr_array_header_t */ 32339228Speter 33339228Speter#ifdef __cplusplus 34339228Speterextern "C" { 35339228Speter#endif /* __cplusplus */ 36339228Speter 37339228Speter/** 38339228Speter * @defgroup apr_cstr C (POSIX) locale string functions 39339228Speter * @ingroup apr_strings 40339228Speter * 41339228Speter * The apr_cstr_* functions provide traditional C char * string text handling, 42339228Speter * and notabilty they treat all text in the C (a.k.a. POSIX) locale using the 43339228Speter * minimal POSIX character set, represented in either ASCII or a corresponding 44339228Speter * EBCDIC subset. 45339228Speter * 46339228Speter * Character values outside of that set are treated as opaque bytes, and all 47339228Speter * multi-byte character sequences are handled as individual distinct octets. 48339228Speter * 49339228Speter * Multi-byte characters sequences whose octets fall in the ASCII range cause 50339228Speter * unexpected results, such as in the ISO-2022-JP code page where ASCII octets 51339228Speter * occur within both shift-state and multibyte sequences. 52339228Speter * 53339228Speter * In the case of the UTF-8 encoding, all multibyte characters all fall outside 54339228Speter * of the C/POSIX range of characters, so these functions are generally safe 55339228Speter * to use on UTF-8 strings. The programmer must be aware that each octet may 56339228Speter * not represent a distinct printable character in such encodings. 57339228Speter * 58339228Speter * The standard C99/POSIX string functions, rather than apr_cstr, should be 59339228Speter * used in all cases where the current locale and encoding of the text is 60339228Speter * significant. 61339228Speter * @{ 62339228Speter */ 63339228Speter 64339228Speter 65339228Speter/** Divide @a input into substrings, interpreting any char from @a sep 66339228Speter * as a token separator. 67339228Speter * 68339228Speter * Return an array of copies of those substrings (plain const char*), 69339228Speter * allocating both the array and the copies in @a pool. 70339228Speter * 71339228Speter * None of the elements added to the array contain any of the 72339228Speter * characters in @a sep_chars, and none of the new elements are empty 73339228Speter * (thus, it is possible that the returned array will have length 74339228Speter * zero). 75339228Speter * 76339228Speter * If @a chop_whitespace is TRUE, then remove leading and trailing 77339228Speter * whitespace from the returned strings. 78339228Speter * 79339228Speter * @since New in 1.6 80339228Speter */ 81339228SpeterAPR_DECLARE(apr_array_header_t *) apr_cstr_split(const char *input, 82339228Speter const char *sep_chars, 83339228Speter int chop_whitespace, 84339228Speter apr_pool_t *pool); 85339228Speter 86339228Speter/** Like apr_cstr_split(), but append to existing @a array instead of 87339228Speter * creating a new one. Allocate the copied substrings in @a pool 88339228Speter * (i.e., caller decides whether or not to pass @a array->pool as @a pool). 89339228Speter * 90339228Speter * @since New in 1.6 91339228Speter */ 92339228SpeterAPR_DECLARE(void) apr_cstr_split_append(apr_array_header_t *array, 93339228Speter const char *input, 94339228Speter const char *sep_chars, 95339228Speter int chop_whitespace, 96339228Speter apr_pool_t *pool); 97339228Speter 98339228Speter 99339228Speter/** Return @c TRUE iff @a str matches any of the elements of @a list, a list 100339228Speter * of zero or more glob patterns. 101339228Speter * 102339228Speter * @since New in 1.6 103339228Speter */ 104339228SpeterAPR_DECLARE(int) apr_cstr_match_glob_list(const char *str, 105339228Speter const apr_array_header_t *list); 106339228Speter 107339228Speter/** Return @c TRUE iff @a str exactly matches any of the elements of @a list. 108339228Speter * 109339228Speter * @since New in 1.6 110339228Speter */ 111339228SpeterAPR_DECLARE(int) apr_cstr_match_list(const char *str, 112339228Speter const apr_array_header_t *list); 113339228Speter 114339228Speter/** 115339228Speter * Get the next token from @a *str interpreting any char from @a sep as a 116339228Speter * token separator. Separators at the beginning of @a str will be skipped. 117339228Speter * Returns a pointer to the beginning of the first token in @a *str or NULL 118339228Speter * if no token is left. Modifies @a str such that the next call will return 119339228Speter * the next token. 120339228Speter * 121339228Speter * @note The content of @a *str may be modified by this function. 122339228Speter * 123339228Speter * @since New in 1.6. 124339228Speter */ 125339228SpeterAPR_DECLARE(char *) apr_cstr_tokenize(const char *sep, char **str); 126339228Speter 127339228Speter/** 128339228Speter * Return the number of line breaks in @a msg, allowing any kind of newline 129339228Speter * termination (CR, LF, CRLF, or LFCR), even inconsistent. 130339228Speter * 131339228Speter * @since New in 1.6. 132339228Speter */ 133339228SpeterAPR_DECLARE(int) apr_cstr_count_newlines(const char *msg); 134339228Speter 135339228Speter#if 0 /* XXX: stringbuf logic is not present in APR */ 136339228Speter/** 137339228Speter * Return a cstring which is the concatenation of @a strings (an array 138339228Speter * of char *) each followed by @a separator (that is, @a separator 139339228Speter * will also end the resulting string). Allocate the result in @a pool. 140339228Speter * If @a strings is empty, then return the empty string. 141339228Speter * 142339228Speter * @since New in 1.6. 143339228Speter */ 144339228SpeterAPR_DECLARE(char *) apr_cstr_join(const apr_array_header_t *strings, 145339228Speter const char *separator, 146339228Speter apr_pool_t *pool); 147339228Speter#endif 148339228Speter 149339228Speter/** 150339228Speter * Perform a case-insensitive comparison of two strings @a atr1 and @a atr2, 151339228Speter * treating upper and lower case values of the 26 standard C/POSIX alphabetic 152339228Speter * characters as equivalent. Extended latin characters outside of this set 153339228Speter * are treated as unique octets, irrespective of the current locale. 154339228Speter * 155339228Speter * Returns in integer greater than, equal to, or less than 0, 156339228Speter * according to whether @a str1 is considered greater than, equal to, 157339228Speter * or less than @a str2. 158339228Speter * 159339228Speter * @since New in 1.6. 160339228Speter */ 161339228SpeterAPR_DECLARE(int) apr_cstr_casecmp(const char *str1, const char *str2); 162339228Speter 163339228Speter/** 164339228Speter * Perform a case-insensitive comparison of two strings @a atr1 and @a atr2, 165339228Speter * treating upper and lower case values of the 26 standard C/POSIX alphabetic 166339228Speter * characters as equivalent. Extended latin characters outside of this set 167339228Speter * are treated as unique octets, irrespective of the current locale. 168339228Speter * 169339228Speter * Returns in integer greater than, equal to, or less than 0, 170339228Speter * according to whether @a str1 is considered greater than, equal to, 171339228Speter * or less than @a str2. 172339228Speter * 173339228Speter * @since New in 1.6. 174339228Speter */ 175339228SpeterAPR_DECLARE(int) apr_cstr_casecmpn(const char *str1, 176339228Speter const char *str2, 177339228Speter apr_size_t n); 178339228Speter 179339228Speter/** 180339228Speter * Parse the C string @a str into a 64 bit number, and return it in @a *n. 181339228Speter * Assume that the number is represented in base @a base. 182339228Speter * Raise an error if conversion fails (e.g. due to overflow), or if the 183339228Speter * converted number is smaller than @a minval or larger than @a maxval. 184339228Speter * 185339228Speter * Leading whitespace in @a str is skipped in a locale-dependent way. 186339228Speter * After that, the string may contain an optional '+' (positive, default) 187339228Speter * or '-' (negative) character, followed by an optional '0x' prefix if 188339228Speter * @a base is 0 or 16, followed by numeric digits appropriate for the base. 189339228Speter * If there are any more characters after the numeric digits, an error is 190339228Speter * returned. 191339228Speter * 192339228Speter * If @a base is zero, then a leading '0x' or '0X' prefix means hexadecimal, 193339228Speter * else a leading '0' means octal (implemented, though not documented, in 194339228Speter * apr_strtoi64() in APR 0.9.0 through 1.5.0), else use base ten. 195339228Speter * 196339228Speter * @since New in 1.6. 197339228Speter */ 198339228SpeterAPR_DECLARE(apr_status_t) apr_cstr_strtoi64(apr_int64_t *n, const char *str, 199339228Speter apr_int64_t minval, 200339228Speter apr_int64_t maxval, 201339228Speter int base); 202339228Speter 203339228Speter/** 204339228Speter * Parse the C string @a str into a 64 bit number, and return it in @a *n. 205339228Speter * Assume that the number is represented in base 10. 206339228Speter * Raise an error if conversion fails (e.g. due to overflow). 207339228Speter * 208339228Speter * The behaviour otherwise is as described for apr_cstr_strtoi64(). 209339228Speter * 210339228Speter * @since New in 1.6. 211339228Speter */ 212339228SpeterAPR_DECLARE(apr_status_t) apr_cstr_atoi64(apr_int64_t *n, const char *str); 213339228Speter 214339228Speter/** 215339228Speter * Parse the C string @a str into a 32 bit number, and return it in @a *n. 216339228Speter * Assume that the number is represented in base 10. 217339228Speter * Raise an error if conversion fails (e.g. due to overflow). 218339228Speter * 219339228Speter * The behaviour otherwise is as described for apr_cstr_strtoi64(). 220339228Speter * 221339228Speter * @since New in 1.6. 222339228Speter */ 223339228SpeterAPR_DECLARE(apr_status_t) apr_cstr_atoi(int *n, const char *str); 224339228Speter 225339228Speter/** 226339228Speter * Parse the C string @a str into an unsigned 64 bit number, and return 227339228Speter * it in @a *n. Assume that the number is represented in base @a base. 228339228Speter * Raise an error if conversion fails (e.g. due to overflow), or if the 229339228Speter * converted number is smaller than @a minval or larger than @a maxval. 230339228Speter * 231339228Speter * Leading whitespace in @a str is skipped in a locale-dependent way. 232339228Speter * After that, the string may contain an optional '+' (positive, default) 233339228Speter * or '-' (negative) character, followed by an optional '0x' prefix if 234339228Speter * @a base is 0 or 16, followed by numeric digits appropriate for the base. 235339228Speter * If there are any more characters after the numeric digits, an error is 236339228Speter * returned. 237339228Speter * 238339228Speter * If @a base is zero, then a leading '0x' or '0X' prefix means hexadecimal, 239339228Speter * else a leading '0' means octal (as implemented, though not documented, in 240339228Speter * apr_strtoi64(), else use base ten. 241339228Speter * 242339228Speter * @warning The implementation returns APR_ERANGE if the parsed number 243339228Speter * is greater than APR_INT64_MAX, even if it is not greater than @a maxval. 244339228Speter * 245339228Speter * @since New in 1.6. 246339228Speter */ 247339228SpeterAPR_DECLARE(apr_status_t) apr_cstr_strtoui64(apr_uint64_t *n, const char *str, 248339228Speter apr_uint64_t minval, 249339228Speter apr_uint64_t maxval, 250339228Speter int base); 251339228Speter 252339228Speter/** 253339228Speter * Parse the C string @a str into an unsigned 64 bit number, and return 254339228Speter * it in @a *n. Assume that the number is represented in base 10. 255339228Speter * Raise an error if conversion fails (e.g. due to overflow). 256339228Speter * 257339228Speter * The behaviour otherwise is as described for apr_cstr_strtoui64(), 258339228Speter * including the upper limit of APR_INT64_MAX. 259339228Speter * 260339228Speter * @since New in 1.6. 261339228Speter */ 262339228SpeterAPR_DECLARE(apr_status_t) apr_cstr_atoui64(apr_uint64_t *n, const char *str); 263339228Speter 264339228Speter/** 265339228Speter * Parse the C string @a str into an unsigned 32 bit number, and return 266339228Speter * it in @a *n. Assume that the number is represented in base 10. 267339228Speter * Raise an error if conversion fails (e.g. due to overflow). 268339228Speter * 269339228Speter * The behaviour otherwise is as described for apr_cstr_strtoui64(), 270339228Speter * including the upper limit of APR_INT64_MAX. 271339228Speter * 272339228Speter * @since New in 1.6. 273339228Speter */ 274339228SpeterAPR_DECLARE(apr_status_t) apr_cstr_atoui(unsigned int *n, const char *str); 275339228Speter 276339228Speter/** 277339228Speter * Skip the common prefix @a prefix from the C string @a str, and return 278339228Speter * a pointer to the next character after the prefix. 279339228Speter * Return @c NULL if @a str does not start with @a prefix. 280339228Speter * 281339228Speter * @since New in 1.6. 282339228Speter */ 283339228SpeterAPR_DECLARE(const char *) apr_cstr_skip_prefix(const char *str, 284339228Speter const char *prefix); 285339228Speter 286339228Speter/** @} */ 287339228Speter 288339228Speter#ifdef __cplusplus 289339228Speter} 290339228Speter#endif /* __cplusplus */ 291339228Speter 292339228Speter#endif /* SVN_STRING_H */ 293