String

Collaboration diagram for String:

Modules
	Join composite types into a single string
	Split a string into a composite type
	string utility functions

Data Structures
struct	_amxc_string
	The string structure. More...

Macros
#define	amxc_string_from_llist_it(ll_it)    amxc_container_of(ll_it, amxc_string_t, it)
	Get the pointer to a string structure from an amxc linked list iterator. More...

Typedefs
typedef struct _amxc_string	amxc_string_t
	The string structure. More...
typedef enum _amxc_string_flags	amxc_string_flags_t
	amxc_string_set_at possible flags More...
typedef int(*	amxc_string_is_char_fn_t) (int c)
	Definition of the signature of the "is char" callback function. More...
typedef bool(*	amxc_string_is_safe_cb_t) (const char *replacement)
	Checks if given replacement is safe to be included in a bigger string in a particular language. More...

Enumerations
enum	_amxc_string_flags { amxc_string_no_flags = 0x00 , amxc_string_insert = 0x00 , amxc_string_overwrite = 0x01 }
	amxc_string_set_at possible flags More...

Functions
int	amxc_string_new (amxc_string_t **string, const size_t length)
	Allocates a string. More...
void	amxc_string_delete (amxc_string_t **string)
	Frees the previously allocated string. More...
int	amxc_string_init (amxc_string_t *const string, const size_t length)
	Initializes a string. More...
void	amxc_string_clean (amxc_string_t *const string)
	Frees the string buffer and reset length attributes. More...
void	amxc_string_reset (amxc_string_t *const string)
	Resets the buffer, reset the content to all 0. More...
int	amxc_string_copy (amxc_string_t *const dest, const amxc_string_t *const src)
	Copies the content. More...
int	amxc_string_grow (amxc_string_t *const string, const size_t length)
	Grows the string buffer. More...
int	amxc_string_shrink (amxc_string_t *const string, const size_t length)
	Shrinks the string buffer. More...
int	amxc_string_set_at (amxc_string_t *const string, const size_t pos, const char *const text, const size_t length, const amxc_string_flags_t flags)
	Set text in the string buffer at a certain position. More...
int	amxc_string_remove_at (amxc_string_t *const string, const size_t pos, size_t length)
	Removes part of the text in the string buffer. More...
const char *	amxc_string_get (const amxc_string_t *const string, const size_t offset)
	Gets the content of the string buffer. More...
char *	amxc_string_take_buffer (amxc_string_t *const string)
	Takes the string buffer. More...
int	amxc_string_push_buffer (amxc_string_t *const string, char *buffer, size_t length)
	Sets the string buffer. More...
char *	amxc_string_dup (const amxc_string_t *const string, const size_t start, size_t length)
	Creates a full or partial copy of the text in the string buffer. More...
void	amxc_string_triml (amxc_string_t *const string, amxc_string_is_char_fn_t fn)
	Trim left. More...
void	amxc_string_trimr (amxc_string_t *const string, amxc_string_is_char_fn_t fn)
	Trim right. More...
void	amxc_string_trim (amxc_string_t *const string, amxc_string_is_char_fn_t fn)
	Trim. More...
int	amxc_string_vsetf (amxc_string_t *const string, const char *fmt, va_list ap)
	Sets the content of the string using printf like formatting. More...
int	amxc_string_setf (amxc_string_t *const string, const char *fmt,...) __attribute__((format(printf
	Sets the content of the string using printf like formatting. More...
int int	amxc_string_vsetf_checked (amxc_string_t *const string, amxc_string_is_safe_cb_t is_safe_cb, const char *fmt, va_list args)
	va_list version of amxc_string_setf_checked More...
int	amxc_string_setf_checked (amxc_string_t *target_string, amxc_string_is_safe_cb_t is_safe_cb, const char *fmt,...) __attribute__((format(printf
	Sets the content of a string using printf like formatting while performing safety checks on the replacements. More...
int int	amxc_string_vappendf (amxc_string_t *const string, const char *fmt, va_list ap)
	Appends a formatted string to a string. More...
int	amxc_string_appendf (amxc_string_t *const string, const char *fmt,...) __attribute__((format(printf
	Appends a formatted string to a string. More...
int int	amxc_string_vappendf_checked (amxc_string_t *target_string, amxc_string_is_safe_cb_t is_safe_cb, const char *fmt, va_list args)
	va_list version of amxc_string_appendf_checked More...
int	amxc_string_appendf_checked (amxc_string_t *string, amxc_string_is_safe_cb_t is_safe_cb, const char *fmt,...) __attribute__((format(printf
	Appends a formatted string while performing safety checks on the replacements. More...
int int	amxc_string_vprependf (amxc_string_t *const string, const char *fmt, va_list ap)
	Prepends a formatted string to a string. More...
int	amxc_string_prependf (amxc_string_t *const string, const char *fmt,...) __attribute__((format(printf
	Prepends a formatted string to a string. More...
int bool	amxc_string_is_numeric (const amxc_string_t *const string)
	Checks if a string is fully numeric. More...
int	amxc_string_search (const amxc_string_t *const string, const char *needle, uint32_t start_pos)
	Searches a sub-string in a string. More...
int	amxc_string_replace (amxc_string_t *const string, const char *needle, const char *newstr, uint32_t max)
	Replaces a number of sub-string occurrences in a string. More...
int	amxc_string_to_upper (amxc_string_t *const string)
	Converts all lower case characters to upper case. More...
int	amxc_string_to_lower (amxc_string_t *const string)
	Converts all upper case characters to lower case. More...
AMXC_INLINE int	amxc_string_append (amxc_string_t *const string, const char *const text, const size_t length)
	Appends text to the end of the current content of the string buffer. More...
AMXC_INLINE int	amxc_string_prepend (amxc_string_t *const string, const char *const text, const size_t length)
	Inserts text at the beginning of the current content of the string buffer. More...
AMXC_INLINE size_t	amxc_string_buffer_length (const amxc_string_t *const string)
	Gets the current size of the allocate string buffer. More...
AMXC_INLINE size_t	amxc_string_text_length (const amxc_string_t *const string)
	Gets the current size of the used string buffer. More...
AMXC_INLINE bool	amxc_string_is_empty (const amxc_string_t *const string)
	Checks if the string is empty. More...
AMXC_INLINE int	amxc_string_insert_at (amxc_string_t *const string, const size_t pos, const char *text, size_t length)
	Inserts a string of the given length into a string at a certain position. More...
size_t	amxc_string_set (amxc_string_t *const string, const char *text)
	Sets a 0 terminated string in the string buffer. More...
int	amxc_string_bytes_2_hex_binary (amxc_string_t *const string, const char bytes[], const uint32_t len, const char *sep)
	Creates a hexbinary string from an array of bytes. More...
int	amxc_string_hex_binary_2_bytes (const amxc_string_t *const string, char **bytes, uint32_t *len, const char *sep)
	Creates an array of bytes from a hex binary string. More...

Detailed Description

Macro Definition Documentation

amxc_string_from_llist_it

#define amxc_string_from_llist_it

(

ll_it

)

amxc_container_of(ll_it, amxc_string_t, it)

Get the pointer to a string structure from an amxc linked list iterator.

The linked list iterator given, must be an linked list iterator of a string structure.

Gives the pointer to the string structure.

Definition at line 95 of file amxc_string.h.

Typedef Documentation

amxc_string_flags_t

typedef enum _amxc_string_flags amxc_string_flags_t

amxc_string_set_at possible flags

One of these flags can be passed to the amxc_string_set_at function as the flags argument.

amxc_string_is_char_fn_t

typedef int(* amxc_string_is_char_fn_t) (int c)

Definition of the signature of the "is char" callback function.

Some of the string functions needs to know if certain character matches a criteria. You can provide your own matching function or use any of the standard c library functions for this, like is_space, ...

The functions using such a callback function are:

• amxc_string_triml
• amxc_string_trimr
• amxc_string_trim

Parameters

c	the character

Returns

Callback functions must return non zero when the given character matches

Definition at line 145 of file amxc_string.h.

amxc_string_is_safe_cb_t

typedef bool(* amxc_string_is_safe_cb_t) (const char *replacement)

Checks if given replacement is safe to be included in a bigger string in a particular language.

See amxc_string_appendf_checked for the background on this.

Returns

true if and only if the given replacement is considered safe in the language that this callback is for.

Definition at line 158 of file amxc_string.h.

amxc_string_t

typedef struct _amxc_string amxc_string_t

The string structure.

Enumeration Type Documentation

_amxc_string_flags

enum _amxc_string_flags

amxc_string_set_at possible flags

One of these flags can be passed to the amxc_string_set_at function as the flags argument.

Enumerator
amxc_string_no_flags	Use default behavior (insert)
amxc_string_insert	Insert the string
amxc_string_overwrite	Overwrite the existing string with the given string

Definition at line 120 of file amxc_string.h.

                                {
    amxc_string_no_flags  = 0x00,   
    amxc_string_insert = 0x00,      
    amxc_string_overwrite = 0x01    
} amxc_string_flags_t;

Function Documentation

amxc_string_append()

AMXC_INLINE int amxc_string_append	(	amxc_string_t *const	string,
		const char *const	text,
		const size_t	length
	)

Appends text to the end of the current content of the string buffer.

This method uses amxc_string_set_at with the pos argument set to the last used position of the string buffer.

When the size of the current buffer is insufficient, the buffer will grow.

Note

The provided text block must at least contain as much data as specified in the length argument. If the provide text block is smaller, the function will go out of boundery.

Parameters

string	a pointer to the string structure
text	the text block that needs to be inserted
length	the length of the text block

Returns

0 on success. -1 if an error has occurred

Definition at line 920 of file amxc_string.h.

                                            {
    return amxc_string_set_at(string,
                              string != NULL ? string->last_used : 0,
                              text,
                              length,
                              amxc_string_no_flags);
}

amxc_string_appendf()

int amxc_string_appendf	(	amxc_string_t *const	string,
		const char *	fmt,
			...
	)

Appends a formatted string to a string.

Using a string literal that can contain printf like formatting a string is added to the end of the string.

If needed memory is allocated or the already allocated buffer grows so the new content can be added.

The variadic arguments must match the printf formatting placeholders in the format string literal

Parameters

string	a pointer to the string structure
fmt	string literal that can contain printf formatting

Returns

0 when the new content is added

amxc_string_appendf_checked()

int amxc_string_appendf_checked	(	amxc_string_t *	string,
		amxc_string_is_safe_cb_t	is_safe_cb,
		const char *	fmt,
			...
	)

Appends a formatted string while performing safety checks on the replacements.

The specifications from amxc_string_appendf apply here, but an additional safety check is performed. If this check fail, non 0 is returned and the given string is cleared.

The safety check consists of calling the given is_safe_cb callback on each replacement. The safety check is considered failed if is_safe_cb fails on at least one replacement. For example:

amxc_string_t str;
amxc_string_init(&str);
amxc_string_appendf_checked(&str, html_is_safe_replacement, "<html><body>Hello %s!", username);

Here, if the replacement, i.e. username, is Bob, then the string becomes

<html><body>Hello Bob!

If the replacement is Bob<script>transfer_money("Alice", "Bob", 1000000);</script> then without safety checks the string would become

<html><body>Hello Bob<script>transfer_money("Alice", "Bob", 1000000);</script>!

This is undesired, so html_is_safe_replacement is supposed to return false on Bob<script>transfer_money("Alice", "Bob", 1000000);</script>, and then amxc_string_appendf_checked will return non 0 and make the string empty.

Note that there is no universal is_safe_cb since it depends on the language (HTML, SQL, amx expression, ...) and even on the role of the replacement in the language (HTML body vs tag field, string literal vs comment, ...).

is_safe_cb is also called if the format string placeholder is not s.

Only the following format string placeholders (and the non-placeholder "%%") are supported: "%s","%d", "%lld", "%ld", "%i", "%lli", "%li", "%u", "%llu", "%lu", "%x", "%llx", "%lx", "%%", "%c", "%f", "%F", "%X".

Note that all other format string placeholders are not supported. So all other type characters, all flags, all width, and all precision format specifications are not supported. For example, "%20s", "%.2f", "%03d", "%1$d", "%2$.*3$d", "%4$.*3$d", etc. are not supported. In case an unsupported format string placeholder is used, non 0 is returned and the string is cleared.

Parameters

string	a pointer to the string structure
fmt	string literal that can contain printf formatting
is_safe_cb	validator of whether a string is safe to build a bigger expression with. If NULL, then every string is assumed to be safe.

Returns

0 when success, none 0 on failure including failed safety check.

amxc_string_buffer_length()

AMXC_INLINE size_t amxc_string_buffer_length

(

const amxc_string_t *const

string

)

Gets the current size of the allocate string buffer.

The allocated string buffer size is not the same as the used buffer size (or text length). Use amxc_string_text_length to get the current used buffer size. The allocated buffer size and the used buffer size can be the same length, but the used buffer size can never be higher then the allocated buffer size.

Parameters

string

a pointer to the string structure

Returns

The size in bytes of the allocated memory for the string buffer.

Definition at line 976 of file amxc_string.h.

                                                                    {
    return string != NULL ? string->length : 0;
}

amxc_string_bytes_2_hex_binary()

int amxc_string_bytes_2_hex_binary	(	amxc_string_t *const	string,
		const char	bytes[],
		const uint32_t	len,
		const char *	sep
	)

Creates a hexbinary string from an array of bytes.

A hexbinary string is a hexadecimal representation of the bytes in the byte array. Each byte will be represented by 2 hexadecimal characters.

Parameters

string	a pointer to the string structure
bytes	the array of bytes
len	length of the byte array
sep	an optional separator string that is put between the bytes, can be NULL

Returns

Non zero value when building of the hexbinary string failed

Definition at line 870 of file amxc_string.c.

                                                    {
    int retval = -1;
    const char* s = "";
 
    when_null(string, exit);
 
    amxc_string_reset(string);
 
    when_null(bytes, exit);
    when_true(len == 0, exit);
 
    for(uint32_t i = 0; i < len; i++) {
        retval = amxc_string_appendf(string, "%s%2.2X", s, (unsigned char) bytes[i]);
        if(retval != 0) {
            amxc_string_reset(string);
            goto exit;
        }
        if(sep != NULL) {
            s = sep;
        }
    }
 
    retval = 0;
 
exit:
    return retval;
}

amxc_string_clean()

void amxc_string_clean

(

amxc_string_t *const

string

)

Frees the string buffer and reset length attributes.

Parameters

string

a pointer to the string structure

Definition at line 189 of file amxc_string.c.

                                                    {
    when_null(string, exit);
 
    amxc_llist_it_take(&string->it);
 
    free(string->buffer);
    string->buffer = NULL;
    string->last_used = 0;
    string->length = 0;
 
exit:
    return;
}

amxc_string_copy()

int amxc_string_copy	(	amxc_string_t *const	dest,
		const amxc_string_t *const	src
	)

Copies the content.

Parameters

dest	a pointer to the destination string structure
src	a pointer to the source string structure

Returns

0 on success. -1 if a NULL pointer is given.

Definition at line 215 of file amxc_string.c.

                                                     {
    int retval = -1;
    when_null(dest, exit);
    when_null(src, exit);
 
    amxc_string_reset(dest);
 
    if(src->length == 0) {
        dest->last_used = 0;
        retval = 0;
        goto exit;
    }
 
    amxc_string_realloc(dest, src->length);
    when_null(dest->buffer, exit);
    memcpy(dest->buffer, src->buffer, src->length);
    dest->last_used = src->last_used;
 
    retval = 0;
 
exit:
    return retval;
}

amxc_string_delete()

void amxc_string_delete

(

amxc_string_t **

string

)

Frees the previously allocated string.

Frees the allocated memory and sets the pointer to the string to NULL.

Note

Only call this function for string that are allocated on the heap using amxc_string_new

Parameters

string

a pointer to the location where the pointer to the string is stored

Definition at line 150 of file amxc_string.c.

                                                {
    when_null(string, exit);
    when_null((*string), exit);
 
    amxc_llist_it_take(&(*string)->it);
    free((*string)->buffer);
    free(*string);
    *string = NULL;
 
exit:
    return;
}

amxc_string_dup()

char* amxc_string_dup	(	const amxc_string_t *const	string,
		const size_t	start,
		size_t	length
	)

Creates a full or partial copy of the text in the string buffer.

A new memory block is allocated on the heap. The full content of the string buffer or partial content of the string buffer is copied in this new allocated memory block.

The start position can not be higher then the last used position. If the length (Starting to count for the start position), is going over the last used position, the length is re-calculated so it matches the last used position.

Note

The returned pointer must be freed. Failing to free the allocated memory, will result in a memory leak.

Parameters

string	a pointer to the string structure
start	the position in the string buffer
length	the length of the text block

Returns

Pointer to the string buffer or NULL when no buffer was available or the start position is over the last used position in the buffer.

Definition at line 400 of file amxc_string.c.

                                     {
 
    char* text = NULL;
    when_null(string, exit);
    when_true(start > string->last_used, exit);
    when_true(length == 0, exit);
 
    if((length == SIZE_MAX) ||
       ( start + length > string->last_used)) {
        length = string->last_used - start;
    }
 
    text = (char*) calloc(length + 1, sizeof(char));
    when_null(text, exit);
    memcpy(text, string->buffer + start, length);
    text[length] = 0;
 
exit:
    return text;
}

amxc_string_get()

const char* amxc_string_get	(	const amxc_string_t *const	string,
		const size_t	offset
	)

Gets the content of the string buffer.

Get the content from the string buffer. The pointer returned is the actual string buffer, or an offset of it.

The offset can not be higher then the value return by amxc_string_text_length.

If no buffer is allocated this function will return an empty string.

Parameters

string	a pointer to the string structure
offset	the offset

Returns

Pointer to the string buffer, or a NULL pointer if no buffer is available

Definition at line 339 of file amxc_string.c.

                                                 {
    const char* text = NULL;
    when_null(string, exit);
    when_true(string->buffer != NULL && offset > string->last_used, exit);
 
    if(string->buffer == NULL) {
        text = "";
    } else {
        string->buffer[string->last_used] = 0;
        text = string->buffer + offset;
    }
 
exit:
    return text;
}

amxc_string_grow()

int amxc_string_grow	(	amxc_string_t *const	string,
		const size_t	length
	)

Grows the string buffer.

Grows the string buffer by the given number of bytes. Extra memory is allocated to be able to store the number of bytes requested.

Parameters

string	a pointer to the string structure
length	the number of bytes the string buffer has to grow

Returns

0 on success. -1 if an error has occurred.

Definition at line 240 of file amxc_string.c.

                                                                       {
    int retval = -1;
    size_t old_length = 0;
    when_null(string, exit);
 
    if(length == 0) {
        retval = 0;
        goto exit;
    }
 
    old_length = string->length;
    when_failed(amxc_string_realloc(string, old_length + length), exit);
    when_null(string->buffer, exit);
    memset(string->buffer + old_length, 0, length);
    retval = 0;
 
exit:
    return retval;
}

amxc_string_hex_binary_2_bytes()

int amxc_string_hex_binary_2_bytes	(	const amxc_string_t *const	string,
		char **	bytes,
		uint32_t *	len,
		const char *	sep
	)

Creates an array of bytes from a hex binary string.

A hexbinary string is a hexadecimal representation of bytes. Each byte will be represented by 2 hexadecimal characters.

This function will allocate a buffer and converts the string to an array of bytes.

The function will fail if the string contains invalid characters. Valid characters are [0-9], [a-f], [A-F].

Parameters

string	a pointer to the string structure
bytes	the allocated of bytes
len	length of the byte array
sep	the separator between the bytes or NULL when no separator is used

Returns

Non zero value when building of the byte array fails.

Definition at line 901 of file amxc_string.c.

                                                    {
    int retval = -1;
    uint32_t str_len = 0;
    uint32_t pos = 0;
    uint32_t sep_count = 0;
    const char* hex_binary = NULL;
    uint32_t sep_len = sep == NULL ? 0 : strlen(sep);
    char* buffer = NULL;
 
    when_true(amxc_string_is_empty(string), exit);
    when_null(bytes, exit);
    when_null(len, exit);
 
    str_len = amxc_string_text_length(string);
    *len = (str_len + 1) >> 1;
    buffer = (char*) calloc(1, *len);
 
    when_null(buffer, exit);
    hex_binary = amxc_string_get(string, 0);
 
    for(uint32_t i = 0; i < str_len; i++) {
        int shift = 0;
        if((sep != NULL) && (sep_len != 0) &&
           ( strncmp(hex_binary + i, sep, sep_len) == 0)) {
            sep_count++;
            continue;
        }
        if(((i - sep_count) % 2 == 0) && ((i + 1) != str_len)) {
            shift = 4;
        }
        if((hex_binary[i] >= '0') && (hex_binary[i] <= '9')) {
            buffer[pos] |= (hex_binary[i] - '0') << shift;
        } else if((hex_binary[i] >= 'A') && (hex_binary[i] <= 'F')) {
            buffer[pos] |= (hex_binary[i] - 'A' + 10) << shift;
        } else if((hex_binary[i] >= 'a') && (hex_binary[i] <= 'f')) {
            buffer[pos] |= (hex_binary[i] - 'a' + 10) << shift;
        } else {
            // invalid character
            goto exit;
        }
        if((i - sep_count) % 2 != 0) {
            pos++;
        }
    }
 
    if(sep_count != 0) {
        char* tmp = NULL;
        *len -= (((sep_len * sep_count) + 1) >> 1);
        *bytes = buffer;
        tmp = (char*) realloc(buffer, *len);
        if(tmp != NULL) {
            *bytes = tmp;
        }
    } else {
        *bytes = buffer;
    }
    retval = 0;
 
exit:
    if(retval != 0) {
        free(buffer);
        if(bytes != NULL) {
            *bytes = NULL;
        }
        if(len != NULL) {
            *len = 0;
        }
    }
    return retval;
}

amxc_string_init()

int amxc_string_init	(	amxc_string_t *const	string,
		const size_t	length
	)

Initializes a string.

Initializes the string structure. Memory is allocated from the heap to be able to store a string.

This function is typically called for string objects that are on the stack. Allocating and initializing a string object on the heap can be done using amxc_string_new

Note

When calling this function on an already initialized string objects, the string is reset and the previous content is gone. The string buffer resizes to the size given.

Use amxc_string_clean to clean the string buffer without resizing.

Parameters

string	a pointer to the string structure.
length	the size of the string buffer in number of items

Returns

0 on success. -1 if a NULL pointer is given.

Definition at line 163 of file amxc_string.c.

                                                                       {
    int retval = -1;
    when_null(string, exit);
 
    string->buffer = NULL;
    string->length = 0;
    string->last_used = 0;
 
    amxc_llist_it_init(&string->it);
 
    // if no items need to be pre-allocated, leave
    if(length == 0) {
        retval = 0;
        goto exit;
    }
 
    amxc_string_realloc(string, length);
    when_null(string->buffer, exit);
    string->length = length;
 
    retval = 0;
 
exit:
    return retval;
}

amxc_string_insert_at()

AMXC_INLINE int amxc_string_insert_at	(	amxc_string_t *const	string,
		const size_t	pos,
		const char *	text,
		size_t	length
	)

Inserts a string of the given length into a string at a certain position.

Inserts text of a certain length at a given position in the string

Parameters

string	a pointer to the string structure
pos	position in the string
text	the text that needs to be inserted
length	the length of the text

Returns

0 when the text is inserted

Definition at line 1035 of file amxc_string.h.

                                         {
    return amxc_string_set_at(string, pos, text, length, amxc_string_insert);
}

amxc_string_is_empty()

AMXC_INLINE bool amxc_string_is_empty

(

const amxc_string_t *const

string

)

Checks if the string is empty.

A string is considered empty if the length of the string is 0 or when the internal buffer pointer is NULL.

Parameters

string

a pointer to the string structure

Returns

true when empty or false otherwise

Definition at line 1015 of file amxc_string.h.

                                                             {
    return string != NULL ? (string->last_used == 0) : true;
}

amxc_string_is_numeric()

int bool amxc_string_is_numeric

(

const amxc_string_t *const

string

)

Checks if a string is fully numeric.

If all characters in the string are numeric this function returns true.

Parameters

string

a pointer to the string structure

Returns

true when all characters in the string are numeric.

Definition at line 746 of file amxc_string.c.

                                                               {
    bool retval = false;
    char* data = NULL;
 
    when_true(amxc_string_is_empty(string), exit);
 
    data = string->buffer;
    while((*data) != '\0') {
        if(isdigit(*data) == 0) {
            goto exit;
        }
        data++;
    }
 
    retval = true;
exit:
    return retval;
}

amxc_string_new()

int amxc_string_new	(	amxc_string_t **	string,
		const size_t	length
	)

Allocates a string.

Allocates and initializes memory to store a string. This function allocates memory from the heap, if a string is on the stack, it can be initialized using function amxc_string_init

The size of the string buffer is not fixed and can be changed with the functions amxc_string_grow or amxc_string_shrink

The string buffer will grow automatically when adding text to it.

The size of the string is expressed in number of bytes that can be stored in the buffer.

Note

The allocated memory must be freed when not used anymore, use amxc_string_delete to free the memory

Parameters

string	a pointer to the location where the pointer to the new string can be stored
length	the size of the string in number of bytes

Returns

-1 if an error occured. 0 on success

Definition at line 118 of file amxc_string.c.

                                                                 {
    int retval = -1;
    when_null(string, exit);
 
    /* allocate the array structure */
    *string = (amxc_string_t*) calloc(1, sizeof(amxc_string_t));
    when_null(*string, exit);
 
    /* set the number of items in the array */
    (*string)->length = length;
    (*string)->last_used = 0;
 
    /* if no buffer needs to pre-allocated, leave */
    if(length == 0) {
        retval = 0;
        goto exit;
    }
 
    /* allocate the buffer */
    amxc_string_realloc(*string, length);
    when_null(*string, exit);
 
    retval = 0;
 
exit:
    if((retval != 0) && (string != NULL)) {
        free(*string);
        *string = NULL;
    }
    return retval;
}

amxc_string_prepend()

AMXC_INLINE int amxc_string_prepend	(	amxc_string_t *const	string,
		const char *const	text,
		const size_t	length
	)

Inserts text at the beginning of the current content of the string buffer.

This method uses amxc_string_set_at with the pos argument set to 0.

When the size of the current buffer is insufficient, the buffer will grow.

Note

The provided text block must at least contain as much data as specified in the length argument. If the provide text block is smaller, the function will go out of boundary.

Parameters

string	a pointer to the string structure
text	the text block that needs to be inserted
length	the length of the text block

Returns

0 on success. -1 if an error has occured

Definition at line 953 of file amxc_string.h.

                                             {
    return amxc_string_set_at(string, 0, text, length, amxc_string_no_flags);
}

amxc_string_prependf()

int amxc_string_prependf	(	amxc_string_t *const	string,
		const char *	fmt,
			...
	)

Prepends a formatted string to a string.

Using a string literal that can contain printf like formatting a string is added to the beginning of the string.

If needed memory is allocated or the already allocated buffer grows so the new content can be added.

The variadic arguments must match the printf formatting placeholders in the format string literal

Parameters

string	a pointer to the string structure
fmt	string literal that can contain printf formatting

Returns

0 when the new content is added

amxc_string_push_buffer()

int amxc_string_push_buffer	(	amxc_string_t *const	string,
		char *	buffer,
		size_t	length
	)

Sets the string buffer.

Replaces the string buffer with the given one. If the string object is containing a buffer, the buffer is freed and the given buffer is used.

Note

When calling this function the string object takes ownership of the given pointer. Do not modify the content of the buffer, unless using the amxc_string functions. Do not free the buffer directly, use amxc_string_clean or amxc_string_delete

Parameters

string	a pointer to the string structure
buffer	a pointer to the buffer
length	the length of the allocated memory (not the string length)

Returns

0 when successful, none 0 otherwise.

Definition at line 372 of file amxc_string.c.

                                           {
    int retval = -1;
    char* original = NULL;
    when_null(string, exit);
 
    original = string->buffer;
 
    if(buffer != NULL) {
        when_true(length < strlen(buffer) + 1, exit);
        string->buffer = buffer;
        string->last_used = strlen(buffer);
        string->length = length;
    } else {
        string->buffer = NULL;
        string->last_used = 0;
        string->length = 0;
    }
 
    free(original);
 
    retval = 0;
 
exit:
    return retval;
}

amxc_string_remove_at()

int amxc_string_remove_at	(	amxc_string_t *const	string,
		const size_t	pos,
		size_t	length
	)

Removes part of the text in the string buffer.

This method removes 1 or more characters from the string buffer. The text right from the removed blocked is moved to the start of the removed block.

It is not possible to remove blocks after the last used position. If the length provided (counting from the given position), is over the last used position, all text from the given position to the end of the used buffer is removed.

Parameters

string	a pointer to the string structure
pos	the position in the string buffer
length	the length of the text block

Returns

0 on success. -1 if an error has occurred

Definition at line 314 of file amxc_string.c.

                                         {
    int retval = -1;
    size_t bytes_to_move = 0;
    when_null(string, exit);
    when_null(string->buffer, exit);
    when_true(length == 0, exit);
    when_true(pos > string->last_used, exit);
 
    if((length == SIZE_MAX) ||
       ( pos + length > string->last_used)) {
        length = string->last_used - pos;
    }
 
    bytes_to_move = string->last_used - (pos + length);
    memmove(string->buffer + pos, string->buffer + pos + length, bytes_to_move);
    string->last_used -= length;
    string->buffer[string->last_used] = 0;
    retval = 0;
 
exit:
    return retval;
}

amxc_string_replace()

int amxc_string_replace	(	amxc_string_t *const	string,
		const char *	needle,
		const char *	newstr,
		uint32_t	max
	)

Replaces a number of sub-string occurrences in a string.

Searches a sub-string in a string starting from beginning and replaces a certain number of the sub-string with another string.

When the newstr is empty all occurrences of the sub-string are removed from the string.

When max is set to UINT32_MAX all occurrences of the sub-string are replaced.

Parameters

string	a pointer to the string structure
needle	the sub-string to be searched
newstr	the replacement string
max	the maximum number of replacements, use UINT32_MAX for all

Returns

the number of replacements done

Definition at line 789 of file amxc_string.c.

                                      {
    int retval = 0;
    int pos = 0;
    size_t needle_len = 0;
    size_t newstr_len = 0;
 
    when_null(string, exit);
    when_null(string->buffer, exit);
    when_true(string->last_used == 0, exit);
    when_true(needle == NULL || *needle == 0, exit);
    when_null(newstr, exit);
 
    needle_len = strlen(needle);
    newstr_len = strlen(newstr);
 
    when_true(needle_len > string->last_used, exit);
 
    pos = amxc_string_search(string, needle, pos);
    while(pos != -1 && max > 0) {
        amxc_string_remove_at(string, pos, needle_len);
        if(newstr_len != 0) {
            amxc_string_insert_at(string, pos, newstr, newstr_len);
        }
        retval++;
        if(max != UINT32_MAX) {
            max--;
        }
        pos = amxc_string_search(string, needle, pos + newstr_len);
    }
 
exit:
    return retval;
}

amxc_string_reset()

void amxc_string_reset

(

amxc_string_t *const

string

)

Resets the buffer, reset the content to all 0.

Parameters

string

a pointer to the string structure

Definition at line 203 of file amxc_string.c.

                                                    {
    when_null(string, exit);
 
    if(string->buffer) {
        string->buffer[0] = 0;
    }
    string->last_used = 0;
 
exit:
    return;
}

amxc_string_search()

int amxc_string_search	(	const amxc_string_t *const	string,
		const char *	needle,
		uint32_t	start_pos
	)

Searches a sub-string in a string.

Searches a sub-string in a string starting from the start_pos.

When no occurrence is found the function returns -1, otherwise it returns the position in the string where the sub-string starts.

Parameters

string	a pointer to the string structure
needle	the sub-string to be searched
start_pos	the search start position in the string

Returns

-1 when the substring is not found, otherwise the position where the sub-string starts.

Definition at line 765 of file amxc_string.c.

                                           {
    int retval = -1;
    size_t needle_len = 0;
    const char* needle_loc = NULL;
 
    when_null(string, exit);
    when_null(string->buffer, exit);
    when_true(string->last_used == 0, exit);
    when_true(needle == NULL || *needle == 0, exit);
 
    needle_len = strlen(needle);
    when_true(start_pos + needle_len > string->last_used, exit);
 
    needle_loc = strstr(string->buffer + start_pos, needle);
    if(needle_loc != NULL) {
        retval = needle_loc - string->buffer;
    }
 
exit:
    return retval;
}

amxc_string_set()

size_t amxc_string_set	(	amxc_string_t *const	string,
		const char *	text
	)

Sets a 0 terminated string in the string buffer.

The current content of amxc_string_t will be removed. The provided 0 terminated string is copied into the buffer.

Parameters

string	a pointer to the string structure
text	the text that needs to be set

Returns

number of bytes written in to the string buffer.

Definition at line 826 of file amxc_string.c.

                                                                      {
    size_t retval = 0;
 
    when_null(string, exit);
    amxc_string_reset(string);
    when_null(data, exit);
 
    retval = strlen(data);
    if(amxc_string_insert_at(string, 0, data, retval) != 0) {
        retval = 0;
    }
 
exit:
    return retval;
}

amxc_string_set_at()

int amxc_string_set_at	(	amxc_string_t *const	string,
		const size_t	pos,
		const char *const	text,
		const size_t	length,
		const amxc_string_flags_t	flags
	)

Set text in the string buffer at a certain position.

A block of text can be inserted at a certain position, or can overwrite the current content of the string buffer at the given position.

When the size of the current buffer is insufficient, the buffer will grow. It is not possible to insert a text block after the current last used byte in the buffer.

Note

The provided text block must at least contain as much data as specified in the length argument. If the provide text block is smaller, the function will go out of boundary.

Parameters

string	a pointer to the string structure
pos	the position in the string buffer
text	the text block that needs to be inserted
length	the length of the text block
flags	TODO:not documented yet

Returns

0 on success. -1 if an error has occurred

Definition at line 276 of file amxc_string.c.

                                                        {
    int retval = -1;
    when_null(string, exit);
    when_null(text, exit);
    when_true(length == 0, exit);
    when_true(pos > string->last_used, exit);
 
    if((flags & amxc_string_overwrite) == amxc_string_overwrite) {
        if(pos + length > string->length) {
            when_failed(amxc_string_realloc(string,
                                            pos + length), exit);
            when_null(string->buffer, exit);
        }
        string->last_used = pos + length > string->last_used ? pos + length : string->last_used;
    } else {
        if(length + string->last_used >= string->length) {
            when_failed(amxc_string_realloc(string,
                                            length + string->last_used + 1), exit);
            when_null(string->buffer, exit);
        }
        memmove(string->buffer + pos + length,
                string->buffer + pos,
                string->last_used - pos);
        string->last_used += length;
    }
 
    memcpy(string->buffer + pos, text, length);
    string->buffer[string->last_used] = 0;
    retval = 0;
 
exit:
    return retval;
}

amxc_string_setf()

int amxc_string_setf	(	amxc_string_t *const	string,
		const char *	fmt,
			...
	)

Sets the content of the string using printf like formatting.

Using a string literal that can contain printf like formatting the content of the string is filled.

If needed memory is allocated or the already allocated buffer grows so the new content can be stored.

The variadic arguments must match the printf formatting placeholders in the format string literal

Parameters

string	a pointer to the string structure
fmt	string literal that can contain printf formatting

Returns

0 when the new content is set

amxc_string_setf_checked()

int amxc_string_setf_checked	(	amxc_string_t *	target_string,
		amxc_string_is_safe_cb_t	is_safe_cb,
		const char *	fmt,
			...
	)

Sets the content of a string using printf like formatting while performing safety checks on the replacements.

The specifications from amxc_string_setf apply here, but an additional safety check is performed. If this check fail, non 0 is returned and the given string is cleared.

The safety check consists of calling the given is_safe_cb callback on each replacement. The safety check is considered failed if is_safe_cb fails on at least one replacement. For example:

amxc_string_t str;
amxc_string_init(&str);
amxc_string_appendf_checked(&str, html_is_safe_replacement, "<html><body>Hello %s!", username);

Here, if the replacement, i.e. username, is Bob, then the string becomes

<html><body>Hello Bob!

If the replacement is Bob<script>transfer_money("Alice", "Bob", 1000000);</script> then without safety checks the string would become

<html><body>Hello Bob<script>transfer_money("Alice", "Bob", 1000000);</script>!

This is undesired, so html_is_safe_replacement is supposed to return false on Bob<script>transfer_money("Alice", "Bob", 1000000);</script>, and then amxc_string_appendf_checked will return non 0 and make the string empty.

Note that there is no universal is_safe_cb since it depends on the language (HTML, SQL, amx expression, ...) and even on the role of the replacement in the language (HTML body vs tag field, string literal vs comment, ...).

is_safe_cb is also called if the format string placeholder is not s.

Only the following format string placeholders (and the non-placeholder "%%") are supported: "%s","%d", "%lld", "%ld", "%i", "%lli", "%li", "%u", "%llu", "%lu", "%x", "%llx", "%lx", "%%", "%c", "%f", "%F", "%X".

Note that all other format string placeholders are not supported. So all other type characters, all flags, all width, and all precision format specifications are not supported. For example, "%20s", "%.2f", "%03d", "%1$d", "%2$.*3$d", "%4$.*3$d", etc. are not supported. In case an unsupported format string placeholder is used, non 0 is returned and the string is cleared.

Parameters

string	a pointer to the string structure
fmt	string literal that can contain printf formatting
is_safe_cb	validator of whether a string is safe to build a bigger expression with. If NULL, then every string is assumed to be safe.

Returns

0 when success, none 0 on failure including failed safety check.

amxc_string_shrink()

int amxc_string_shrink	(	amxc_string_t *const	string,
		const size_t	length
	)

Shrinks the string buffer.

Shrinks the string by the given number of bytes.

Note

Shrinking the string buffer can lead to data loss. Data loss will happen at the end of the string.

Parameters

string	a pointer to the string structure
length	the number of bytes the string buffer has to shrink

Returns

0 on success. -1 if an error has occurred

Definition at line 260 of file amxc_string.c.

                                                                         {
    int retval = -1;
    when_null(string, exit);
    when_true(length > string->length, exit); // out of range
 
    if(length == 0) {
        retval = 0;
        goto exit;
    }
 
    retval = amxc_string_realloc(string, string->length - length);
 
exit:
    return retval;
}

amxc_string_take_buffer()

char* amxc_string_take_buffer

(

amxc_string_t *const

string

)

Takes the string buffer.

Takes the string buffer (char *) from the string object. The string object is reset.

Note

When calling this function the ownership of the pointer is moved. Calling amxc_string_clean will not free the buffer. You need to free the allocated memory (returned pointer) by yourself. The returned pointer must be freed. Failing to free the allocated memory, will result in a memory leak.

Parameters

string

a pointer to the string structure

Returns

Pointer to the string buffer, or a NULL pointer if no buffer is available

Definition at line 356 of file amxc_string.c.

                                                           {
    char* buffer = NULL;
    when_null(string, exit);
 
    if(string->buffer != NULL) {
        string->buffer[string->last_used] = 0;
    }
    buffer = string->buffer;
    string->buffer = NULL;
    string->last_used = 0;
    string->length = 0;
 
exit:
    return buffer;
}

amxc_string_text_length()

AMXC_INLINE size_t amxc_string_text_length

(

const amxc_string_t *const

string

)

Gets the current size of the used string buffer.

The used string buffer size is not the same as the allocated buffer size. Use amxc_string_buffer_length to get the allocated buffer size. The allocated buffer size and the used buffer size can be the same length, but the used buffer size can never be higher then the allocated buffer size.

Parameters

string

a pointer to the string structure

Returns

The size in bytes of the allocated memory for the string buffer.

Definition at line 997 of file amxc_string.h.

                                                                  {
    return string != NULL ? string->last_used : 0;
}

amxc_string_to_lower()

int amxc_string_to_lower

(

amxc_string_t *const

string

)

Converts all upper case characters to lower case.

Only upper case text characters are modified, all other characters are not changed.

Parameters

string

a pointer to the string structure

Returns

0 on success, any other value indicates failure.

Definition at line 856 of file amxc_string.c.

                                                      {
    int retval = -1;
 
    when_null(string, exit);
 
    for(uint32_t i = 0; i <= string->last_used; i++) {
        string->buffer[i] = tolower(string->buffer[i]);
    }
    retval = 0;
 
exit:
    return retval;
}

amxc_string_to_upper()

int amxc_string_to_upper

(

amxc_string_t *const

string

)

Converts all lower case characters to upper case.

Only lower case text characters are modified, all other characters are not changed.

Parameters

string

a pointer to the string structure

Returns

0 on success, any other value indicates failure.

Definition at line 842 of file amxc_string.c.

                                                      {
    int retval = -1;
 
    when_null(string, exit);
 
    for(uint32_t i = 0; i <= string->last_used; i++) {
        string->buffer[i] = toupper(string->buffer[i]);
    }
    retval = 0;
 
exit:
    return retval;
}

amxc_string_trim()

void amxc_string_trim	(	amxc_string_t *const	string,
		amxc_string_is_char_fn_t	fn
	)

Trim.

Removes trailing and leading characters from the string. The characters that will be removed are defined by the provided character classification function.

If no character classification function is provided the "isspace" function is used by default.

You can provide any character classification function or create your own. Such a function must return a none zero value when the character must be removed from the string.

Parameters

string	a pointer to the string structure
fn	a pointer to a character classification function or NULL

Definition at line 471 of file amxc_string.c.

                                                                                {
    amxc_string_trimr(string, fn);
    amxc_string_triml(string, fn);
}

amxc_string_triml()

void amxc_string_triml	(	amxc_string_t *const	string,
		amxc_string_is_char_fn_t	fn
	)

Trim left.

Removes leading characters from the string. The characters that will be removed are defined by the provided character classification function.

If no character classification function is provided the "isspace" function is used by default.

You can provide any character classification function or create your own. Such a function must return a none zero value when the character must be removed from the string.

Parameters

string	a pointer to the string structure
fn	a pointer to a character classification function or NULL

Definition at line 423 of file amxc_string.c.

                                                                                 {
    uint32_t pos = 0;
    when_null(string, exit);
    when_true(string->last_used == 0, exit);
 
    if(fn == NULL) {
        fn = isspace;
    }
 
    while(pos <= string->last_used &&
          fn(string->buffer[pos]) != 0) {
        pos++;
    }
 
    if(pos >= string->last_used) {
        string->last_used = 0;
        string->buffer[0] = 0;
        goto exit;
    }
 
    if(pos > 0) {
        memmove(string->buffer, string->buffer + pos, string->last_used - pos);
        string->last_used -= pos;
    }
    string->buffer[string->last_used] = 0;
 
exit:
    return;
}

amxc_string_trimr()

void amxc_string_trimr	(	amxc_string_t *const	string,
		amxc_string_is_char_fn_t	fn
	)

Trim right.

Removes trailing characters from the string. The characters that will be removed are defined by the provided character classification function.

If no character classification function is provided the "isspace" function is used by default.

You can provide any character classification function or create your own. Such a function must return a none zero value when the character must be removed from the string.

Parameters

string	a pointer to the string structure
fn	a pointer to a character classification function or NULL

Definition at line 453 of file amxc_string.c.

                                                                                 {
    when_null(string, exit);
    when_true(string->last_used == 0, exit);
 
    if(fn == NULL) {
        fn = isspace;
    }
 
    while(string->last_used > 0 &&
          fn(string->buffer[string->last_used - 1]) != 0) {
        string->last_used--;
    }
    string->buffer[string->last_used] = 0;
 
exit:
    return;
}

amxc_string_vappendf()

int int amxc_string_vappendf	(	amxc_string_t *const	string,
		const char *	fmt,
		va_list	ap
	)

Appends a formatted string to a string.

Using a string literal that can contain printf like formatting a string is added to the end of the string.

If needed memory is allocated or the already allocated buffer grows so the new content can be added.

The variadic arguments must match the printf formatting placeholders in the format string literal

Parameters

string	a pointer to the string structure
fmt	string literal that can contain printf formatting
ap	a va_list, containing the values for the printf formatting

Returns

0 when the new content is added

Definition at line 537 of file amxc_string.c.

                                       {
 
    int retval = -1;
    int size_needed = 0;
    va_list copy;
 
    when_null(string, exit);
    when_null(fmt, exit);
 
    va_copy(copy, args);
    size_needed = vsnprintf(NULL, 0, fmt, args) + 1;
 
    if(string->length < string->last_used + size_needed) {
        size_t grow = (string->last_used + size_needed - string->length);
        when_failed(amxc_string_grow(string, grow), exit);
    }
 
    size_needed = vsnprintf(string->buffer + string->last_used,
                            size_needed,
                            fmt,
                            copy);
    string->buffer[string->length] = 0;
 
    string->last_used += size_needed;
 
    retval = 0;
 
exit:
    return retval;
}

amxc_string_vappendf_checked()

int int amxc_string_vappendf_checked	(	amxc_string_t *	target_string,
		amxc_string_is_safe_cb_t	is_safe_cb,
		const char *	fmt,
		va_list	args
	)

va_list version of amxc_string_appendf_checked

See also

amxc_string_appendf_checked

Definition at line 600 of file amxc_string.c.

                                                                {
 
    const char* pos = fmt;
    int status = -1;
    when_null(string, error);
    when_null(fmt, error);
    while(*pos != '\0') {
        size_t len_pos_old = 0;
        size_t len_new_fixed = 0;
        const char* placeholder = NULL;
        const char* placeholder_in_pos = strchr(pos, '%');
        bool placeholder_handled = false;
 
        // If no "%" left, add all the rest:
        if(placeholder_in_pos == NULL) {
            status = amxc_string_append(string, pos, strlen(pos));
            when_failed(status, error);
            return 0;
        }
 
        // Add the fixed part, i.e. until "%":
        len_new_fixed = placeholder_in_pos - pos;
        if(len_new_fixed != 0) {
            status = amxc_string_append(string, pos, len_new_fixed);
            when_failed(status, error);
        }
 
        // Identify placeholder (e.g. "%i"):
        placeholder = s_get_format_placeholder(placeholder_in_pos);
        if(placeholder == NULL) {
            goto error; // unsupported placeholder.
        }
        len_pos_old = amxc_string_text_length(string);
 
        // Add replacement
        // Note: Unfortunately, we cannot make this more clean by splitting off functions
        //   because "If [the va_list] is passed to a function that uses va_arg(ap,type), then
        //   the value of ap is undefined after the return of that function." (man va_arg(3))
        //   and because getting an item from a va_list requires hardcoding its type.
        placeholder_handled = REPLACE_PLACEHOLDER(string, placeholder, status, args, "%s", const char*)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%d", int)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%lld", long long int)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%ld", long int)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%i", int)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%lli", long long int)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%li", long int)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%u", unsigned int)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%llu", long long unsigned int)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%lu", long unsigned int)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%x", unsigned int)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%llx", long long unsigned int)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%lx", long unsigned int)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%c", int) // unsigned char promoted to int
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%f", double)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%F", double)
            || REPLACE_PLACEHOLDER(string, placeholder, status, args, "%X", unsigned int)
            || s_replace_percentage(string, placeholder, &status);
 
        when_false(placeholder_handled, error);
 
        when_failed(status, error);
 
        // Check if added string safe:
        if((is_safe_cb != NULL) && !is_safe_cb(amxc_string_get(string, len_pos_old))) {
            goto error;
        }
 
        pos += len_new_fixed + strlen(placeholder);
    }
    return 0;
 
error:
    amxc_string_clean(string);
    return -1;
}

amxc_string_vprependf()

int int amxc_string_vprependf	(	amxc_string_t *const	string,
		const char *	fmt,
		va_list	ap
	)

Prepends a formatted string to a string.

Using a string literal that can contain printf like formatting a string is added to the beginning of the string.

If needed memory is allocated or the already allocated buffer grows so the new content can be added.

The variadic arguments must match the printf formatting placeholders in the format string literal

Parameters

string	a pointer to the string structure
fmt	string literal that can contain printf formatting
ap	a va_list, containing the values for the printf formatting

Returns

0 when the new content is added

Definition at line 692 of file amxc_string.c.

                                        {
 
    int retval = -1;
    int size_needed = 0;
    char first_char = 0;
    va_list copy;
 
    when_null(string, exit);
    when_null(fmt, exit);
 
    va_copy(copy, args);
    size_needed = vsnprintf(NULL, 0, fmt, args) + 1;
 
    if(string->length < string->last_used + size_needed) {
        size_t grow = (string->last_used + size_needed - string->length);
        when_failed(amxc_string_grow(string, grow), exit);
    }
    first_char = string->buffer[0];
 
    if(string->last_used > 0) {
        memmove(string->buffer + size_needed - 1,
                string->buffer,
                string->last_used);
    }
 
    size_needed = vsnprintf(string->buffer,
                            size_needed,
                            fmt,
                            copy);
    string->buffer[size_needed] = first_char;
    string->last_used += size_needed;
 
    retval = 0;
 
exit:
    return retval;
}

amxc_string_vsetf()

int amxc_string_vsetf	(	amxc_string_t *const	string,
		const char *	fmt,
		va_list	ap
	)

Sets the content of the string using printf like formatting.

Using a string literal that can contain printf like formatting the content of the string is filled.

If needed memory is allocated or the already allocated buffer grows so the new content can be stored.

Parameters

string	a pointer to the string structure
fmt	string literal that can contain printf formatting
ap	a va_list, containing the values for the printf formatting

Returns

0 when the new content is set

Definition at line 476 of file amxc_string.c.

                                    {
    int retval = -1;
 
    when_null(string, exit);
    when_null(fmt, exit);
 
    amxc_string_reset(string);
    retval = amxc_string_vappendf(string, fmt, args);
 
exit:
    return retval;
}

amxc_string_vsetf_checked()

int int amxc_string_vsetf_checked	(	amxc_string_t *const	string,
		amxc_string_is_safe_cb_t	is_safe_cb,
		const char *	fmt,
		va_list	args
	)

va_list version of amxc_string_setf_checked

See also

amxc_string_setf_checked

Definition at line 505 of file amxc_string.c.

                                            {
    int retval = -1;
 
    when_null(string, exit);
    when_null(fmt, exit);
 
    amxc_string_reset(string);
    retval = amxc_string_vappendf_checked(string, is_safe_cb, fmt, args);
 
exit:
    return retval;
}