string utility functions

Collaboration diagram for string utility functions:

Functions
int	amxc_string_resolve_esc (amxc_string_t *const string)
	Resolves escaped characters in a string. More...
int	amxc_string_esc (amxc_string_t *const string)
	Add escape characters to a string. More...
int	amxc_string_resolve_env (amxc_string_t *const string)
	Resolves environment variables. More...
int	amxc_string_resolve_var (amxc_string_t *const string, const amxc_var_t *const data)
	Resolves variant path variables. More...
int	amxc_string_resolve (amxc_string_t *const string, const amxc_var_t *const data)
	Resolves variant paths and environment variables. More...
int	amxc_string_set_resolved (amxc_string_t *string, const char *text, const amxc_var_t *const data)
	Sets the resolved string. More...
int	amxc_string_new_resolved (amxc_string_t **string, const char *text, const amxc_var_t *const data)
	Sets the resolved string. More...
amxc_llist_it_t *	amxc_llist_add_string (amxc_llist_t *const llist, const char *text)
	Adds a string (char*) to a linked list of amxc_string_t structures. More...
void	amxc_string_list_it_free (amxc_llist_it_t *it)
	Helper function to delete an item in a linked list. More...

Detailed Description

A list of utility functions and macro's that make common string manipulation easier.

Function Documentation

amxc_llist_add_string()

amxc_llist_it_t* amxc_llist_add_string	(	amxc_llist_t *const	llist,
		const char *	text
	)

Adds a string (char*) to a linked list of amxc_string_t structures.

This function will allocate a new amxc_string_t structure and copies the provide string (char*) into the amxc_string_t structure.

The new allocated structure is appended to the provided linked list using amxc_llist_append

Parameters

llist	a pointer to a linked list iterator
text	the string

Returns

The linked list iterator of the new allocated amxc_string_t when successful, NULL otherwise

Definition at line 306 of file amxc_utils.c.

                                                         {
    amxc_llist_it_t* it = NULL;
    amxc_string_t* string = NULL;
 
    when_null(llist, exit);
    when_null(text, exit);
 
    when_failed(amxc_string_new(&string, 0), exit);
    when_failed(amxc_string_append(string, text, strlen(text)), exit);
    amxc_llist_append(llist, &string->it);
 
    it = &string->it;
 
exit:
    if(it == NULL) {
        amxc_string_delete(&string);
    }
    return it;
}

amxc_string_esc()

int amxc_string_esc

(

amxc_string_t *const

string

)

Add escape characters to a string.

Some characters or combinations of characters in a string can have a special purpose i.e. "$(my_env_var)". To avoid that these are replaced by functions like amxc_string_resolve_env or amxc_string_resolve_var, the characters can be escaped with a \ i.e. "\$\‍(my_env_var\‍)". This function can be used to add the escape character.

Only these characters are taken into consideration when removing the escape character: $, (, ), {, }, ", ', .

Parameters

string

an amxc_string_t pointer.

Returns

the number of replacements that have been done.

Definition at line 226 of file amxc_utils.c.

                                                 {
    int retval = 0;
 
    retval += amxc_string_replace(string, "\\", "\\\\", UINT32_MAX);
    retval += amxc_string_replace(string, "(", "\\(", UINT32_MAX);
    retval += amxc_string_replace(string, ")", "\\)", UINT32_MAX);
    retval += amxc_string_replace(string, "{", "\\{", UINT32_MAX);
    retval += amxc_string_replace(string, "}", "\\}", UINT32_MAX);
    retval += amxc_string_replace(string, "\"", "\\\"", UINT32_MAX);
    retval += amxc_string_replace(string, "'", "\\'", UINT32_MAX);
    retval += amxc_string_replace(string, "\n", "\\n", UINT32_MAX);
    retval += amxc_string_replace(string, "\t", "\\t", UINT32_MAX);
 
    return retval;
}

amxc_string_list_it_free()

void amxc_string_list_it_free

(

amxc_llist_it_t *

it

)

Helper function to delete an item in a linked list.

This function can be passed to amxc_llist_delete or amxc_llist_clean if the linked list only contains amxc_string_t structures.

Note

Only use this function when cleaning up a linked list containing only amxc_string_t structures.

Parameters

it	a pointer to a linked list iterator

Definition at line 327 of file amxc_utils.c.

                                                   {
    amxc_string_t* part = amxc_string_from_llist_it(it);
    amxc_string_delete(&part);
}

amxc_string_new_resolved()

int amxc_string_new_resolved	(	amxc_string_t **	string,
		const char *	text,
		const amxc_var_t *const	data
	)

Sets the resolved string.

This function will allocate a new amxc_string_t structure on the heap.

If the provided text contains environment variable references or variant path references, the resolved text is put in the string. it will also remove the escape character '\' when in front of $, (, ), {, }, ", ', .

Parameters

string	an amxc_string_t pointer.
text	the text
data	a variant containing data, preferable a htable or list.

Returns

the number of replacements that have been done.

Definition at line 289 of file amxc_utils.c.

                                                           {
    int retval = -1;
 
    when_null(string, exit);
    when_failed(amxc_string_new(string, 0), exit);
 
    retval = amxc_string_set_resolved(*string, text, data);
    if(retval == 0) {
        amxc_string_delete(string);
    }
 
exit:
    return retval;
}

amxc_string_resolve()

int amxc_string_resolve	(	amxc_string_t *const	string,
		const amxc_var_t *const	data
	)

Resolves variant paths and environment variables.

This functions calls amxc_string_resolve_var and amxc_string_resolve_env to resolve all environment variables and variant paths mentioned in the string.

The escape character '\' will be removed using amxc_string_resolve_esc when in front of $, (, ), {, }, ", ', .

Parameters

string	an amxc_string_t pointer.
data	a variant containing data, preferable a htable or list.

Returns

the number of replacements that have been done.

Definition at line 242 of file amxc_utils.c.

                                                      {
    int changes = 0;
    int total = 0;
    do {
        total += changes;
        changes = 0;
        changes += amxc_string_resolve_env(string);
        changes += amxc_string_resolve_var(string, data);
    } while(changes > 0);
 
    total += amxc_string_resolve_esc(string);
 
    return total;
}

amxc_string_resolve_env()

int amxc_string_resolve_env

(

amxc_string_t *const

string

)

Resolves environment variables.

Replaces the environment variable with its value. The name of the environment variable must be put between $( and ). This function will get the value of the environment variable and replaces the $(<NAME>) with the value.

If the environment variable does not exist, it will be replaced with an empty string. If no environment variables are available in the string, the string is not changed.

Parameters

string

an amxc_string_t pointer.

Returns

the number of replacements that have been done.

Definition at line 148 of file amxc_utils.c.

                                                         {
    int retval = 0;
 
    when_null(string, exit);
    when_true(amxc_string_is_empty(string), exit);
 
    retval = amxc_string_generic_resolve(string,
                                         "$(",
                                         ")",
                                         amxc_string_resolve_replace_env,
                                         NULL);
 
exit:
    return retval;
}

amxc_string_resolve_esc()

int amxc_string_resolve_esc

(

amxc_string_t *const

string

)

Resolves escaped characters in a string.

Some characters or combinations of characters in a string can have a special purpose i.e. "$(my_env_var)". To avoid that these are replaced by functions like amxc_string_resolve_env or amxc_string_resolve_var, the characters can be escaped with a \ i.e. "\$\‍(my_env_var\‍)". This function can be used to remove the escape character from the string.

Only these characters are taken into consideration when removing the escape character: $, (, ), {, }, ", ', .

Parameters

string

an amxc_string_t pointer.

Returns

the number of replacements that have been done.

Definition at line 183 of file amxc_utils.c.

                                                         {
    int retval = 0;
    amxc_string_t resolved;
    size_t length = 0;
    char* buffer = NULL;
 
    amxc_string_init(&resolved, amxc_string_buffer_length(string));
    for(uint32_t i = 0; i < amxc_string_text_length(string); i++) {
        if(string->buffer[i] != '\\') {
            amxc_string_append(&resolved, string->buffer + i, 1);
            continue;
        }
        if(i + 1 >= amxc_string_text_length(string)) {
            amxc_string_append(&resolved, string->buffer, 1);
            break;
        }
        switch(string->buffer[i + 1]) {
        case 'n':
            amxc_string_append(&resolved, "\n", 1);
            i++;
            retval++;
            break;
        case 't':
            amxc_string_append(&resolved, "\t", 1);
            i++;
            retval++;
            break;
        default:
            amxc_string_append(&resolved, string->buffer + i + 1, 1);
            i++;
            retval++;
            break;
        }
    }
 
    length = amxc_string_buffer_length(&resolved);
    buffer = amxc_string_take_buffer(&resolved);
    amxc_string_push_buffer(string, buffer, length);
 
    amxc_string_clean(&resolved);
    return retval;
}

amxc_string_resolve_var()

int amxc_string_resolve_var	(	amxc_string_t *const	string,
		const amxc_var_t *const	data
	)

Resolves variant path variables.

Replaces the variant path with its value. The variant path must be put between ${ and }. This function will get the value of that path and replaces the ${<PATH>} with the value.

If the path does not exist, it will be replaced with an empty string. If no variant paths are available in the string, the string is not changed.

Parameters

string	an amxc_string_t pointer.
data	a variant containing data, preferable a htable or list.

Returns

the number of replacements that have been done.

Definition at line 164 of file amxc_utils.c.

                                                          {
    int retval = 0;
 
    when_null(string, exit);
    when_true(amxc_string_is_empty(string), exit);
    when_null(data, exit);
    when_true(amxc_var_type_of(data) != AMXC_VAR_ID_HTABLE, exit);
 
    retval = amxc_string_generic_resolve(string,
                                         "${",
                                         "}",
                                         amxc_string_resolve_replace_var,
                                         data);
 
exit:
    return retval;
}

amxc_string_set_resolved()

int amxc_string_set_resolved	(	amxc_string_t *	string,
		const char *	text,
		const amxc_var_t *const	data
	)

Sets the resolved string.

This function will always clear the content of the provided amxc_string_t structure (resets it to an empty string).

If the provided text contains environment variable references or variant path references, the resolved text is put in the string, it will also remove the escape character '\' when in front of $, (, ), {, }, ", ', .

Parameters

string	an amxc_string_t pointer.
text	the text
data	a variant containing data, preferable a htable or list.

Returns

the number of replacements that have been done.

Definition at line 258 of file amxc_utils.c.

                                                           {
    int retval = 0;
    size_t length = 0;
    size_t i = 0;
 
    when_null(text, exit);
    when_true(*text == 0, exit);
    when_null(string, exit);
 
    amxc_string_reset(string);
    length = strlen(text);
    for(i = 0; i < length; i++) {
        if(text[i] == '$') {
            break;
        }
    }
 
    if(i < length) {
        amxc_string_appendf(string, "%s", text);
        retval = amxc_string_resolve(string, data);
        if(retval == 0) {
            amxc_string_reset(string);
        }
    }
 
exit:
    return retval;
}