Re: apr_token_* conclusions (was: Better casecmpstr[n]?)

William A Rowe Jr Tue, 26 Jan 2016 12:58:39 -0800

On Thu, Jan 21, 2016 at 4:18 PM, William A Rowe Jr <wr...@rowe-clan.net>
wrote:


> This is as far as I got on my last iteration, electing what appear
> to be 'normal string' handling functions that are part of svn.
>
> Based on apr's short-name preference, I had yet to redecorate
> these functions as apr_cstr_* functions, but that I will get to
> tomorrow.  If you see something that doesn't fall into the normal
> string / general purpose criteria, feel free to holler before the first
> commit...
>

This is what is going in shortly... we don't have an svn_boolean_t
so those become int's, while svn_error_t * becomes an apr_status_t.

I'll proceed to commit this full set for scrutiny before digging through
for the various overlapping functions within apr and even across httpd.

Title: Apache Portable Runtime: C (POSIX locale) string functions

Apache Portable Runtime

Functions
apr_array_header_t *	apr_cstr_split (const char input, const char sep_chars, int chop_whitespace, apr_pool_t *pool)

void	apr_cstr_split_append (apr_array_header_t array, const char input, const char sep_chars, int chop_whitespace, apr_pool_t pool)

int	apr_cstr_match_glob_list (const char str, const apr_array_header_t list)

int	apr_cstr_match_list (const char str, const apr_array_header_t list)

char *	apr_cstr_tokenize (const char sep, char *str)

int	apr_cstr_count_newlines (const char *msg)

char *	apr_cstr_join (const apr_array_header_t strings, const char separator, apr_pool_t *pool)

int	apr_cstr_casecmp (const char str1, const char str2)

apr_status_t	apr_cstr_strtoi64 (apr_int64_t n, const char str, apr_int64_t minval, apr_int64_t maxval, int base)

apr_status_t	apr_cstr_atoi64 (apr_int64_t n, const char str)

apr_status_t	apr_cstr_atoi (int n, const char str)

apr_status_t	apr_cstr_strtoui64 (apr_uint64_t n, const char str, apr_uint64_t minval, apr_uint64_t maxval, int base)

apr_status_t	apr_cstr_atoui64 (apr_uint64_t n, const char str)

apr_status_t	apr_cstr_atoui (unsigned int n, const char str)

const char *	apr_cstr_skip_prefix (const char str, 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_status_t apr_cstr_atoi	(	int *	n,
		const char *	str
	)

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.

apr_status_t apr_cstr_atoi64	(	apr_int64_t *	n,
		const char *	str
	)

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.

apr_status_t apr_cstr_atoui	(	unsigned int *	n,
		const char *	str
	)

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_status_t apr_cstr_atoui64	(	apr_uint64_t *	n,
		const char *	str
	)

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.

int apr_cstr_casecmp	(	const char *	str1,
		const char *	str2
	)

Compare two strings atr1 and atr2, treating case-equivalent unaccented Latin (ASCII subset) letters as equal.

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.

int apr_cstr_count_newlines ( const char * msg )

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.

char* apr_cstr_join	(	const apr_array_header_t *	strings,
		const char *	separator,
		apr_pool_t *	pool
	)

Return a cstring which is the concatenation of strings (an array of char *) each followed by separator (that is, separator will also end the resulting string). Allocate the result in pool. If strings is empty, then return the empty string.

Since: New in 1.6.

int apr_cstr_match_glob_list	(	const char *	str,
		const apr_array_header_t *	list
	)

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

int apr_cstr_match_list	(	const char *	str,
		const apr_array_header_t *	list
	)

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

Since: new in 1.7

const char* apr_cstr_skip_prefix	(	const char *	str,
		const char *	prefix
	)

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_array_header_t* apr_cstr_split	(	const char *	input,
		const char *	sep_chars,
		int	chop_whitespace,
		apr_pool_t *	pool
	)

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.

void apr_cstr_split_append	(	apr_array_header_t *	array,
		const char *	input,
		const char *	sep_chars,
		int	chop_whitespace,
		apr_pool_t *	pool
	)

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).

apr_status_t apr_cstr_strtoi64	(	apr_int64_t *	n,
		const char *	str,
		apr_int64_t	minval,
		apr_int64_t	maxval,
		int	base
	)

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.

apr_status_t apr_cstr_strtoui64	(	apr_uint64_t *	n,
		const char *	str,
		apr_uint64_t	minval,
		apr_uint64_t	maxval,
		int	base
	)

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.

Warning: The implementation used since version 1.7 returns an error if the parsed number is greater than APR_INT64_MAX, even if it is not greater than maxval.

Since: New in 1.6.

char* apr_cstr_tokenize	(	const char *	sep,
		char **	str
	)

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.

Re: apr_token_* conclusions (was: Better casecmpstr[n]?)

Functions

Detailed Description

Function Documentation

Reply via email to