String routines

Overview

snprintf implementations
// global functions

int
apr_strnatcmp(
    char const* a,
    char const* b
);

int
apr_strnatcasecmp(
    char const* a,
    char const* b
);

char*
apr_pstrdup(
    apr_pool_t* p,
    const char* s
);

char*
apr_pstrmemdup(
    apr_pool_t* p,
    const char* s,
    apr_size_t n
);

char*
apr_pstrndup(
    apr_pool_t* p,
    const char* s,
    apr_size_t n
);

void*
apr_pmemdup(
    apr_pool_t* p,
    const void* m,
    apr_size_t n
);

char*
apr_pstrcat(
    apr_pool_t* p,
    ...
);

char*
apr_pstrcatv(
    apr_pool_t* p,
    const struct iovec* vec,
    apr_size_t nvec,
    apr_size_t* nbytes
);

char*
apr_pvsprintf(
    apr_pool_t* p,
    const char* fmt,
    va_list ap
);

char*
apr_psprintf(
    apr_pool_t* p,
    const char* fmt,
    ...
);

char*
apr_cpystrn(
    char* dst,
    const char* src,
    apr_size_t dst_size
);

char*
apr_collapse_spaces(
    char* dest,
    const char* src
);

apr_status_t
apr_tokenize_to_argv(
    const char* arg_str,
    char*** argv_out,
    apr_pool_t* token_context
);

char*
apr_strtok(
    char* str,
    const char* sep,
    char** last
);

char*
apr_itoa(
    apr_pool_t* p,
    int n
);

char*
apr_ltoa(
    apr_pool_t* p,
    long n
);

char*
apr_off_t_toa(
    apr_pool_t* p,
    apr_off_t n
);

apr_status_t
apr_strtoff(
    apr_off_t* offset,
    const char* buf,
    char** end,
    int base
);

apr_int64_t
apr_strtoi64(
    const char* buf,
    char** end,
    int base
);

apr_int64_t
apr_atoi64(const char* buf);

char*
apr_strfsize(
    apr_off_t size,
    char* buf
);

Detailed Documentation

Global Functions

int
apr_strnatcmp(
    char const* a,
    char const* b
)

Do a natural order comparison of two strings.

Parameters:

a

The first string to compare

b

The second string to compare

Returns:

Either <0, 0, or >0. If the first string is less than the second this returns <0, if they are equivalent it returns 0, and if the first string is greater than second string it retuns >0.

int
apr_strnatcasecmp(
    char const* a,
    char const* b
)

Do a natural order comparison of two strings ignoring the case of the strings.

Parameters:

a

The first string to compare

b

The second string to compare

Returns:

Either <0, 0, or >0. If the first string is less than the second this returns <0, if they are equivalent it returns 0, and if the first string is greater than second string it retuns >0.

char*
apr_pstrdup(
    apr_pool_t* p,
    const char* s
)

duplicate a string into memory allocated out of a pool

Parameters:

p

The pool to allocate out of

s

The string to duplicate

Returns:

The new string or NULL if s == NULL

char*
apr_pstrmemdup(
    apr_pool_t* p,
    const char* s,
    apr_size_t n
)

Create a null-terminated string by making a copy of a sequence of characters and appending a null byte This is a faster alternative to apr_pstrndup, for use when you know that the string being duplicated really has ‘n’ or more characters. If the string might contain fewer characters, use apr_pstrndup.

Parameters:

p

The pool to allocate out of

s

The block of characters to duplicate

n

The number of characters to duplicate

Returns:

The new string or NULL if s == NULL

char*
apr_pstrndup(
    apr_pool_t* p,
    const char* s,
    apr_size_t n
)

Duplicate at most n characters of a string into memory allocated out of a pool; the new string will be NUL-terminated The amount of memory allocated from the pool is the length of the returned string including the NUL terminator

Parameters:

p

The pool to allocate out of

s

The string to duplicate

n

The maximum number of characters to duplicate

Returns:

The new string or NULL if s == NULL

void*
apr_pmemdup(
    apr_pool_t* p,
    const void* m,
    apr_size_t n
)

Duplicate a block of memory.

Parameters:

p

The pool to allocate from

m

The memory to duplicate

n

The number of bytes to duplicate

Returns:

The new block of memory or NULL if m == NULL

char*
apr_pstrcat(
    apr_pool_t* p,
    ...
)

Concatenate multiple strings, allocating memory out a pool

Parameters:

p

The pool to allocate out of

…

The strings to concatenate. The final string must be NULL

Returns:

The new string

char*
apr_pstrcatv(
    apr_pool_t* p,
    const struct iovec* vec,
    apr_size_t nvec,
    apr_size_t* nbytes
)

Concatenate multiple strings specified in a writev-style vector

Parameters:

p

The pool from which to allocate

vec

The strings to concatenate

nvec

The number of strings to concatenate

nbytes

(output) strlen of new string (pass in NULL to omit)

Returns:

The new string

char*
apr_pvsprintf(
    apr_pool_t* p,
    const char* fmt,
    va_list ap
)

printf-style style printing routine. The data is output to a string allocated from a pool

Parameters:

p

The pool to allocate out of

fmt

The format of the string

ap

The arguments to use while printing the data

Returns:

The new string

char*
apr_psprintf(
    apr_pool_t* p,
    const char* fmt,
    ...
)

printf-style style printing routine. The data is output to a string allocated from a pool

Parameters:

p

The pool to allocate out of

fmt

The format of the string

…

The arguments to use while printing the data

Returns:

The new string

char*
apr_cpystrn(
    char* dst,
    const char* src,
    apr_size_t dst_size
)

Copy up to dst_size characters from src to dst; does not copy past a NUL terminator in src, but always terminates dst with a NUL regardless… code-block:: none

Note the differences between this function and strncpy():

  1. strncpy() doesn’t always NUL terminate; apr_cpystrn() does.

  2. strncpy() pads the destination string with NULs, which is often unnecessary; apr_cpystrn() does not.

  3. strncpy() returns a pointer to the beginning of the dst string; apr_cpystrn() returns a pointer to the NUL terminator of dst, to allow a check for truncation.

Parameters:

dst

The destination string

src

The source string

dst_size

The space available in dst; dst always receives NUL termination, so if src is longer than dst_size, the actual number of characters copied is dst_size - 1.

Returns:

Pointer to the NUL terminator of the destination string, dst

char*
apr_collapse_spaces(
    char* dest,
    const char* src
)

Remove all whitespace from a string

Parameters:

dest

The destination string. It is okay to modify the string in place. Namely dest == src

src

The string to rid the spaces from.

Returns:

A pointer to the destination string’s null terminator.

apr_status_t
apr_tokenize_to_argv(
    const char* arg_str,
    char*** argv_out,
    apr_pool_t* token_context
)

Convert the arguments to a program from one string to an array of strings terminated by a NULL pointer

Parameters:

arg_str

The arguments to convert

argv_out

Output location. This is a pointer to an array of strings.

token_context

Pool to use.

 
char*
apr_strtok(
    char* str,
    const char* sep,
    char** last
)

Split a string into separate null-terminated tokens. The tokens are delimited in the string by one or more characters from the sep argument.

Note

the ‘last’ state points to the trailing NUL char of the final token, otherwise it points to the character following the current token (all successive or empty occurances of sep are skiped on the subsequent call to apr_strtok). Therefore it is possible to avoid a strlen() determination, with the following logic; toklen = last - retval; if (*last) toklen;

Parameters:

str

The string to separate; this should be specified on the first call to apr_strtok() for a given string, and NULL on subsequent calls.

sep

The set of delimiters

last

State saved by apr_strtok() between calls.

Returns:

The next token from the string

char*
apr_itoa(
    apr_pool_t* p,
    int n
)

create a string representation of an int, allocated from a pool

Parameters:

p

The pool from which to allocate

n

The number to format

Returns:

The string representation of the number

char*
apr_ltoa(
    apr_pool_t* p,
    long n
)

create a string representation of a long, allocated from a pool

Parameters:

p

The pool from which to allocate

n

The number to format

Returns:

The string representation of the number

char*
apr_off_t_toa(
    apr_pool_t* p,
    apr_off_t n
)

create a string representation of an apr_off_t, allocated from a pool

Parameters:

p

The pool from which to allocate

n

The number to format

Returns:

The string representation of the number

apr_status_t
apr_strtoff(
    apr_off_t* offset,
    const char* buf,
    char** end,
    int base
)

Convert a numeric string into an apr_off_t numeric value. Bug *end breaks type safety; where *buf is const, *end needs to be declared as const in APR 2.0

Parameters:

offset

The value of the parsed string.

buf

The string to parse. It may contain optional whitespace, followed by 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 base.

end

A pointer to the end of the valid character in buf. If not NULL, it is set to the first invalid character in buf.

base

A numeric base in the range between 2 and 36 inclusive, or 0. If base is zero, buf will be treated as base ten unless its digits are prefixed with ‘0x’, in which case it will be treated as base 16.

 
apr_int64_t
apr_strtoi64(
    const char* buf,
    char** end,
    int base
)

parse a numeric string into a 64-bit numeric value

Parameters:

buf

The string to parse. It may contain optional whitespace, followed by 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 base.

end

A pointer to the end of the valid character in buf. If not NULL, it is set to the first invalid character in buf.

base

A numeric base in the range between 2 and 36 inclusive, or 0. If base is zero, buf will be treated as base ten unless its digits are prefixed with ‘0x’, in which case it will be treated as base 16.

Returns:

The numeric value of the string. On overflow, errno is set to ERANGE. On success, errno is set to 0.

apr_int64_t
apr_atoi64(const char* buf)

parse a base-10 numeric string into a 64-bit numeric value. Equivalent to apr_strtoi64(buf, (char**)NULL, 10).

Parameters:

buf

The string to parse

Returns:

The numeric value of the string. On overflow, errno is set to ERANGE. On success, errno is set to 0.

char*
apr_strfsize(
    apr_off_t size,
    char* buf
)

Format a binary size (magnitiudes are 2^10 rather than 10^3) from an apr_off_t, as bytes, K, M, T, etc, to a four character compacted human readable string. All negative sizes report ‘ - ‘, apr_strfsize only formats positive values.

Parameters:

size

The size to format

buf

The 5 byte text buffer (counting the trailing null)

Returns:

The buf passed to apr_strfsize()