apr  1.7.0
About: APR (Apache Portable Runtime) project offers software libraries that provide a predictable and consistent interface to underlying platform-specific implementations (APR core library).
  Fossies Dox: apr-1.7.0.tar.bz2  ("inofficial" and yet experimental doxygen-generated source code documentation)  

C (POSIX) locale string functions
Collaboration diagram for C (POSIX) locale string functions:

Functions

 APR_DECLARE (apr_array_header_t *) apr_cstr_split(const char *input
 
 APR_DECLARE (void) apr_cstr_split_append(apr_array_header_t *array
 
 APR_DECLARE (int) apr_cstr_match_glob_list(const char *str
 
 APR_DECLARE (char *) apr_cstr_tokenize(const char *sep
 
 APR_DECLARE (const char *) apr_cstr_skip_prefix(const char *str
 

Variables

const char * sep_chars
 
const char int chop_whitespace
 
const char int apr_pool_tpool
 
const char * input
 
const apr_array_header_tlist
 
char ** str
 
const char * str2
 
const char apr_size_t n
 
const char apr_int64_t minval
 
const char apr_int64_t apr_int64_t maxval
 
const char apr_int64_t apr_int64_t int base
 
const char * prefix
 

Detailed Description

The apr_cstr_* functions provide traditional C char * string text handling, and notabilty they treat all text in the C (a.k.a. POSIX) locale using the minimal POSIX character set, represented in either ASCII or a corresponding EBCDIC subset.

Character values outside of that set are treated as opaque bytes, and all multi-byte character sequences are handled as individual distinct octets.

Multi-byte characters sequences whose octets fall in the ASCII range cause unexpected results, such as in the ISO-2022-JP code page where ASCII octets occur within both shift-state and multibyte sequences.

In the case of the UTF-8 encoding, all multibyte characters all fall outside of the C/POSIX range of characters, so these functions are generally safe to use on UTF-8 strings. The programmer must be aware that each octet may not represent a distinct printable character in such encodings.

The standard C99/POSIX string functions, rather than apr_cstr, should be used in all cases where the current locale and encoding of the text is significant.

Function Documentation

◆ APR_DECLARE() [1/5]

APR_DECLARE ( apr_array_header_t ) const

Divide input into substrings, interpreting any char from sep as a token separator.

Return an array of copies of those substrings (plain const char*), allocating both the array and the copies in pool.

None of the elements added to the array contain any of the characters in sep_chars, and none of the new elements are empty (thus, it is possible that the returned array will have length zero).

If chop_whitespace is TRUE, then remove leading and trailing whitespace from the returned strings.

Since
New in 1.6

◆ APR_DECLARE() [2/5]

APR_DECLARE ( char *  ) const

Get the next token from *str interpreting any char from sep as a token separator. Separators at the beginning of str will be skipped. Returns a pointer to the beginning of the first token in *str or NULL if no token is left. Modifies str such that the next call will return the next token.

Note
The content of *str may be modified by this function.
Since
New in 1.6.

◆ APR_DECLARE() [3/5]

APR_DECLARE ( const char *  ) const

Skip the common prefix prefix from the C string str, and return a pointer to the next character after the prefix. Return NULL if str does not start with prefix.

Since
New in 1.6.

◆ APR_DECLARE() [4/5]

APR_DECLARE ( int  ) const

Return TRUE iff str matches any of the elements of list, a list of zero or more glob patterns.

Since
New in 1.6

Return TRUE iff str exactly matches any of the elements of list.

Since
New in 1.6

Return the number of line breaks in msg, allowing any kind of newline termination (CR, LF, CRLF, or LFCR), even inconsistent.

Since
New in 1.6.

Perform a case-insensitive comparison of two strings atr1 and atr2, treating upper and lower case values of the 26 standard C/POSIX alphabetic characters as equivalent. Extended latin characters outside of this set are treated as unique octets, irrespective of the current locale.

Returns in integer greater than, equal to, or less than 0, according to whether str1 is considered greater than, equal to, or less than str2.

Since
New in 1.6.

Parse the C string str into a 64 bit number, and return it in *n. Assume that the number is represented in base base. Raise an error if conversion fails (e.g. due to overflow), or if the converted number is smaller than minval or larger than maxval.

Leading whitespace in str is skipped in a locale-dependent way. After that, the string may contain an optional '+' (positive, default) or '-' (negative) character, followed by an optional '0x' prefix if base is 0 or 16, followed by numeric digits appropriate for the base. If there are any more characters after the numeric digits, an error is returned.

If base is zero, then a leading '0x' or '0X' prefix means hexadecimal, else a leading '0' means octal (implemented, though not documented, in apr_strtoi64() in APR 0.9.0 through 1.5.0), else use base ten.

Since
New in 1.6.

Parse the C string str into a 64 bit number, and return it in *n. Assume that the number is represented in base 10. Raise an error if conversion fails (e.g. due to overflow).

The behaviour otherwise is as described for apr_cstr_strtoi64().

Since
New in 1.6.

Parse the C string str into a 32 bit number, and return it in *n. Assume that the number is represented in base 10. Raise an error if conversion fails (e.g. due to overflow).

The behaviour otherwise is as described for apr_cstr_strtoi64().

Since
New in 1.6.

Parse the C string str into an unsigned 64 bit number, and return it in *n. Assume that the number is represented in base base. Raise an error if conversion fails (e.g. due to overflow), or if the converted number is smaller than minval or larger than maxval.

Leading whitespace in str is skipped in a locale-dependent way. After that, the string may contain an optional '+' (positive, default) or '-' (negative) character, followed by an optional '0x' prefix if base is 0 or 16, followed by numeric digits appropriate for the base. If there are any more characters after the numeric digits, an error is returned.

If base is zero, then a leading '0x' or '0X' prefix means hexadecimal, else a leading '0' means octal (as implemented, though not documented, in apr_strtoi64(), else use base ten.

Warning
The implementation returns APR_ERANGE if the parsed number is greater than APR_INT64_MAX, even if it is not greater than maxval.
Since
New in 1.6.

Parse the C string str into an unsigned 64 bit number, and return it in *n. Assume that the number is represented in base 10. Raise an error if conversion fails (e.g. due to overflow).

The behaviour otherwise is as described for apr_cstr_strtoui64(), including the upper limit of APR_INT64_MAX.

Since
New in 1.6.

Parse the C string str into an unsigned 32 bit number, and return it in *n. Assume that the number is represented in base 10. Raise an error if conversion fails (e.g. due to overflow).

The behaviour otherwise is as described for apr_cstr_strtoui64(), including the upper limit of APR_INT64_MAX.

Since
New in 1.6.

◆ APR_DECLARE() [5/5]

APR_DECLARE ( void  )

Like apr_cstr_split(), but append to existing array instead of creating a new one. Allocate the copied substrings in pool (i.e., caller decides whether or not to pass array->pool as pool).

Since
New in 1.6

Definition at line 35 of file apr_atomic.c.

Variable Documentation

◆ base

char int base

Definition at line 198 of file apr_cstr.h.

Referenced by APR_DECLARE(), and shm_attach_internal().

◆ chop_whitespace

const char const char int chop_whitespace

Definition at line 82 of file apr_cstr.h.

Referenced by APR_DECLARE().

◆ input

apr_time_exp_t * input

Definition at line 93 of file apr_cstr.h.

Referenced by APR_DECLARE(), and FileTimeToAprTime().

◆ list

◆ maxval

const char apr_uint64_t apr_uint64_t maxval

Definition at line 198 of file apr_cstr.h.

◆ minval

const char apr_uint64_t minval

Definition at line 198 of file apr_cstr.h.

◆ n

apr_off_t n

◆ pool

◆ prefix

const char* prefix

Definition at line 284 of file apr_cstr.h.

Referenced by APR_DECLARE(), and c2x().

◆ sep_chars

const char const char * sep_chars

Definition at line 82 of file apr_cstr.h.

Referenced by APR_DECLARE().

◆ str

const char * str

◆ str2

const char * str2

Definition at line 161 of file apr_cstr.h.