String Lists

UTF-8 aware string list

Summary

s_str_list_new	Create a new string list.
s_str_list_split	Create a new string list by splitting the given string with the given separator.
s_str_list_delete	Delete the given string list.
s_str_list_find_index	Find the string in the given string list which matches the given string.
s_str_list_find	Find the string list element in the given string list, which matches the given string.
s_str_list_index	Find the index into the given string list of the given string list element.
s_str_list_nth	Find the nth string element in the given string list.
s_str_list_nth_string	Find the nth string in the given string list.
s_str_list_first	Return the first string element in the given string list.
s_str_list_last	Return the last string element in the given string list.
s_str_list_element_get	Get the given string list element’s string.
s_str_list_element_replace	Replace the given string list element’s string.
s_str_list_element_unlink	Unlink the given string list element from it’s parent string list, and return the string list element’s string.
s_str_list_element_delete	Delete the given string list element from it’s parent string list, and free the string list element’s string.
s_str_list_element_next	Return the next string list element in the string list, relative to the given one.
s_str_list_element_prev	Return the previous string list element in the string list, relative to the given one.
s_str_list_isempty	Query if the given string list has any elements.
s_str_list_size	Get the number of elements in the given string list.
s_str_list_push	Push the given string onto end of given string list.
s_str_list_pop	Pop last string from the given string list.
s_str_list_reverse	Reverse the order of the string list elements in the given string list.
s_str_list_prepend	Prepend a string to beginning of the given string list.
s_str_list_append	Append a string to end of the given string list.
s_str_list_insert_before	Insert a string before given string list element.
s_str_list_insert_after	Insert a string after given string list element.
s_str_list_dup	Return a newly allocated copy of the given string list, which must later be freed by the caller.
s_str_list_slice	Return a newly allocated slice of the given string list, which must later be freed by the caller.
s_str_list_cmp	Compare the elements of two string lists.
s_str_list_merge	Merge two string lists.
s_str_list_to_string	Convert the string list to a string with the given separator between elements of the string list.

Definition

typedef s_list s_str_list

Opaque definition of a string list, same as an s_list.

typedef s_list_element s_str_list_element

Opaque definition of a string list element, same as an s_list_element.

The list element represents one element in the string list.

Create/Delete

s_str_list *s_str_list_new(s_erc *error)

Create a new string list.

Parameters:

• error –

  Error code.

Return:

Pointer to the newly created string list.

s_str_list *s_str_list_split(const char *string, const char *separator, s_erc *error)

Create a new string list by splitting the given string with the given separator.

Parameters:

• string –

  The string to split into sub-strings.

• separator –

  The string to split string with.

• error –

  Error code.

Return:

Pointer to the newly created string list.

void s_str_list_delete(s_str_list *self, s_erc *error)

Delete the given string list.

Deletes the list and frees up all the strings contained in the list.

Parameters:

• self –

  The string list to delete.

• error –

  Error code.

Accessing

const s_str_list_element *s_str_list_find_index(const s_str_list *self, const s_str_list_element *f, const char *string, int *index, s_erc *error)

Find the string in the given string list which matches the given string.

Parameters:

• self –

  The string list.

• f –

  Start searching from this string element (including) onwards. If NULL then start from first string element.

• string –

  The string to match.

• index –

  A variable to hold the index of the string element found which matches the data. -1 if not found. Set to NULL if not required.

• error –

  Error code.

Return:

Pointer to the string list element which matches the data, else NULL.

Note:

String lists are indexed starting from 0.

The index variable will be relative if f is notNULL.

macro s_str_list_find(self, string, error)

Find the string list element in the given string list, which matches the given string.

Parameters:

• self –

  The string list.

• string –

  The string to match.

• error –

  Error code.

Return:

Pointer to the string list element which matches the given string, else NULL if no match.

Note:

Returns the first match.

macro s_str_list_index(self, string, index, error)

Find the index into the given string list of the given string list element.

Parameters:

• self –

  The string list.

• string –

  The string to match.

• index –

  A variable to hold the index of the string element found which matches the data. -1 if not found.

• error –

  Error code.

Return:

Pointer to the string list element which matches the data, else NULL.

Note:

String lists are indexed starting from 0.

const s_str_list_element *s_str_list_nth(const s_str_list *self, uint32 n, s_erc *error)

Find the nth string element in the given string list.

Parameters:

• self –

  The string list.

• n –

  Index of string element to find.

• error –

  Error code.

Return:

Pointer to the nth string list element or NULL if index is out of bounds.

Note:

The string list elements are indexed from 0.

const char *s_str_list_nth_string(const s_str_list *self, uint32 n, s_erc *error)

Find the nth string in the given string list.

Parameters:

• self –

  The string list.

• n –

  Index of string to find.

• error –

  Error code.

Return:

Pointer to the nth string or NULL if index is out of bounds.

Note:

The string list elements are indexed from 0.

const s_str_list_element *s_str_list_first(const s_str_list *self, s_erc *error)

Return the first string element in the given string list.

Parameters:

• self –

  The string list.

• error –

  Error code.

Return:

Pointer to the first string element in the list.

const s_str_list_element *s_str_list_last(const s_str_list *self, s_erc *error)

Return the last string element in the given string list.

Parameters:

• self –

  The string list.

• error –

  Error code.

Return:

Pointer to the last string element in the list.

Element functions

const char *s_str_list_element_get(const s_str_list_element *self, s_erc *error)

Get the given string list element’s string.

Parameters:

• self –

  The string list element.

• error –

  Error code.

Return:

Pointer to the string list element’s string.

void s_str_list_element_replace(s_str_list_element *self, const char *string, s_erc *error)

Replace the given string list element’s string.

The replaced string is freed.

Parameters:

• self –

  The string list element who’s string is to be replaced.

• string –

  The new string list element string.

• error –

  Error code.

Note:

Internally a duplicate of string is made and ownership taken thereof.

char *s_str_list_element_unlink(s_str_list_element *self, s_erc *error)

Unlink the given string list element from it’s parent string list, and return the string list element’s string.

Parameters:

• self –

  The string list element to be unlinked.

• error –

  Error code.

Return:

Pointer to the unlinked string list element’s string.

Note:

Caller is responsible for the returned string’s memory.

s_str_list_element *s_str_list_element_delete(s_str_list_element *self, s_erc *error)

Delete the given string list element from it’s parent string list, and free the string list element’s string.

Parameters:

• self –

  The string list element to be deleted.

• error –

  Error code.

Return:

Pointer to the previous string list element or NULL if none.

const s_str_list_element *s_str_list_element_next(const s_str_list_element *self, s_erc *error)

Return the next string list element in the string list, relative to the given one.

Parameters:

• self –

  Pointer to current position in string list.

• error –

  Error code.

Return:

Pointer to the next string list element in the string list.

const s_str_list_element *s_str_list_element_prev(const s_str_list_element *self, s_erc *error)

Return the previous string list element in the string list, relative to the given one.

Parameters:

• self –

  Pointer to current position in string list.

• error –

  Error code.

Return:

Pointer to the previous string list element in the string list.

Query

s_bool s_str_list_isempty(const s_str_list *self, s_erc *error)

Query if the given string list has any elements.

Parameters:

• self –

  The string list to query.

• error –

  Error code.

Return:

TRUE or FALSE.

uint32 s_str_list_size(const s_str_list *self, s_erc *error)

Get the number of elements in the given string list.

Parameters:

• self –

  The string list to query.

• error –

  Error code.

Return:

The number of elements in the string list.

Queue

void s_str_list_push(s_str_list *self, const char *string, s_erc *error)

Push the given string onto end of given string list.

Same as s_str_list_append.

Parameters:

• self –

  The string list.

• string –

  The string to append.

• error –

  Error code.

Note:

Internally a duplicate of string is made and ownership taken thereof.

char *s_str_list_pop(s_str_list *self, s_erc *error)

Pop last string from the given string list.

Removes last string list element from the string list and returns the string list element’s string.

Parameters:

• self –

  The string list.

• error –

  Error code.

Return:

Pointer to popped string.

Note:

The caller is responsible for the memory of the returned string.

void s_str_list_reverse(s_str_list *self, s_erc *error)

Reverse the order of the string list elements in the given string list.

Parameters:

• self –

  The string list to reverse.

• error –

  Error code.

Note:

The string list element’s strings are not reversed.

Insertion

void s_str_list_prepend(s_str_list *self, const char *string, s_erc *error)

Prepend a string to beginning of the given string list.

Parameters:

• self –

  The string list.

• string –

  The string to prepend.

• error –

  Error code.

Note:

Internally a duplicate of string is made and ownership taken thereof.

void s_str_list_append(s_str_list *self, const char *string, s_erc *error)

Append a string to end of the given string list.

Parameters:

• self –

  The string list.

• string –

  The string to append.

• error –

  Error code.

Note:

Internally a duplicate of string is made and ownership taken thereof.

const s_str_list_element *s_str_list_insert_before(s_str_list_element *self, const char *string, s_erc *error)

Insert a string before given string list element.

Return reference to inserted string element.

Parameters:

• self –

  The string list element before which the string must be inserted.

• string –

  The string to be inserted.

• error –

  Error code.

Return:

Pointer to the inserted string list element.

Note:

Internally a duplicate of string is made and ownership taken thereof.

const s_str_list_element *s_str_list_insert_after(s_str_list_element *self, const char *string, s_erc *error)

Insert a string after given string list element.

Return reference to inserted string element.

Parameters:

• self –

  The string list element after which the string must be inserted.

• string –

  The string to be inserted.

• error –

  Error code.

Return:

Pointer to the inserted string list element.

Note:

Internally a duplicate of string is made and ownership taken thereof.

Copy

s_str_list *s_str_list_dup(const s_str_list *src, s_erc *error)

Return a newly allocated copy of the given string list, which must later be freed by the caller.

Parameters:

• src –

  The source string list.

• error –

  Error code.

Return:

A copy of src.

Note:

This is a deep copy .

s_str_list *s_str_list_slice(const s_str_list *src, uint32 a, sint32 b, s_erc *error)

Return a newly allocated slice of the given string list, which must later be freed by the caller.

Parameters:

• src –

  The source string list.

• a –

  Start position of the slice in the source string list. If a is greater than or equal to the list size then NULL is returned.

• b –

  End position of the slice in the source string list. If b = -1, or b is greater than the number of elements in the source string list then the slice is to the end of the source string list

• error –

  Error code.

Return:

A slice of src.

Note:

This is a deep copy .

Miscellaneous

sint32 s_str_list_cmp(const s_str_list *sl1, const s_str_list *sl2, s_erc *error)

Compare the elements of two string lists.

Parameters:

• sl1 –

  First string list.

• sl2 –

  Second string list.

• error –

  Error code.

Return:

-1 if lists compare exactly, else the number of elements that compare.

void s_str_list_merge(s_str_list *self, const s_str_list *with, s_erc *error)

Merge two string lists.

Append all the string list elements of one list onto another list.

Parameters:

• self –

  The string list that with is merged with.

• with –

  The string list to merge with self.

• error –

  Error code.

char *s_str_list_to_string(s_str_list *self, const char *separator, s_erc *error)

Convert the string list to a string with the given separator between elements of the string list.

Parameters:

• self –

  The string list.

• separator –

  The separator to put between the string elements.

• error –

  Error code.

Return:

The string list as a string.

Note:

The caller is responsible for the memory of the returned string.