Collaboration diagram for Strings and String arrays:

Classes
struct	string
	Simple string type. More...

struct	strarray
	Array of strings. More...

Functions
strarray *	sa_new (int entries)
	Allocate storage for a new array. More...

bool	sa_init (strarray *dst, const int entries)
	Initialise an already allocated array. More...

bool	sa_copy (strarray dst, const strarray src)
	Copy an array of strings from src to dst. More...

bool	sa_move (strarray dst, strarray src)
	Move strings from one array to another. More...

bool	sa_set_entry (strarray array, const int index, string str)
	Copy a string to a given position in the array. More...

bool	sa_create_entry (strarray array, const int index, const size_t len, const char src)
	Create an string in a given position from a character array and length. More...

void	sa_clear_entry (strarray *array, const int index)
	Clear an array entry. More...

void	sa_destroy (strarray *sa)
	Destroy array and contents. More...

string *	str_new (const size_t len, const char *ca)
	Create new string from character array. More...

bool	str_copy (string dst, const string src)
	Update an existing string by copying the contents from another. More...

string *	str_duplicate (const string *src)
	Allocate a new string containing the contents of another. More...

bool	str_update (string str, const size_t len, const char src)
	Update an existing string from a character array of given length. More...

void	str_destroy (string *str)
	Destroy a string and free its contents. More...

Detailed Description

Function Documentation

◆ sa_clear_entry()

void sa_clear_entry	(	strarray *	array,
		const int	index
	)

Clear an array entry.

Hands off to str_destroy() if the specified index is within the array, and noops if the array is invalid or index is out of bounds

Parameters

[in]	array	Pointer to array being modified
[in]	index	Position in array to clear

Definition at line 163 of file strarray.c.

◆ sa_copy()

bool sa_copy	(	strarray *	dst,
		const strarray *	src
	)

Copy an array of strings from src to dst.

Destroys the existing contents of the destination array, which cannot be restored in the event of an error, and then creates new strings to match the contents of the source array.

Parameters

[out]	dst	Pointer to destination array (all existing data will be lost)
[in]	src	Pointer to source array

Returns: True on success, false on error

Definition at line 76 of file strarray.c.

◆ sa_create_entry()

bool sa_create_entry	(	strarray *	array,
		const int	index,
		const size_t	len,
		const char *	src
	)

Create an string in a given position from a character array and length.

Checks that the array is valid and the index is within bounds, then hands off to str_update() to copy in the new string data.

Parameters

[in]	array	Pointer to array being modified
[in]	index	Position in array to modify
[in]	len	Length of character array
[in]	src	Character array to be copied into array

Returns: Result of str_upate(), or false if parameters are invalid

Definition at line 149 of file strarray.c.

◆ sa_destroy()

void sa_destroy ( strarray * sa )

Destroy array and contents.

Iterates over all array entries and calls str_destroy() for each string before freeing the array's internal storage.

Internal pointer is nulled and number of entries set to zero, so there should be no side effects if called repeatedly on an array, if that should happen for some reason. Don't do it deliberately just to check.

Caller is responsible for freeing the array itself, if required.

Parameters

[in] sa Pointer to array to be destroyed.

Definition at line 182 of file strarray.c.

◆ sa_init()

bool sa_init	(	strarray *	dst,
		const int	entries
	)

Initialise an already allocated array.

Take an array and initialise internal storage for the stated number of entries.

Will destroy existing contents

Parameters

[in]	dst	Pointer to array
[in]	entries	Number of strings to allocate

Returns: True on success, false on error

Definition at line 59 of file strarray.c.

◆ sa_move()

bool sa_move	(	strarray *	dst,
		strarray *	src
	)

Move strings from one array to another.

Moves strings from one array to anther by copying the internal pointer of the source array to the internal pointer of the destination. No additional memory allocations are made.

The source array is invalidated and the internal pointer nulled so that it can be destroyed without affecting the destination array.

Parameters

[out]	dst	Pointer to destination array (all existing data will be lost)
[in]	src	Pointer to source array (will be emptied)

Returns: True on success, false on error.

Definition at line 112 of file strarray.c.

◆ sa_new()

strarray* sa_new ( int entries )

Allocate storage for a new array.

Allocate a new string array and initialise with sa_init()

All allocated data is zeroed.

Must be destroyed with sa_destroy() before being freed.

Parameters

[in] entries Number of entries in array

Returns: Pointer to allocated array. NULL on failure.

Definition at line 37 of file strarray.c.

◆ sa_set_entry()

bool sa_set_entry	(	strarray *	array,
		const int	index,
		string *	str
	)

Copy a string to a given position in the array.

str_copy() does the heavy lifting, with this function performing bounds checks on the string array itself.

Parameters

[in]	array	Pointer to array being modified
[in]	index	Position in array to modify
[in]	str	String to be copied into array

Returns: Result of str_copy(), or false if parameters are invalid

Definition at line 131 of file strarray.c.

◆ str_copy()

bool str_copy	(	string *	dst,
		const string *	src
	)

Update an existing string by copying the contents from another.

Allocates memory and copies the string from src.

No explicit null termination checks, but the source string declared length is used as an upper bound. Uses strncpy() internally, so should be safe enough.

Parameters

[out]	dst	Pointer to destination string (Existing data will be destroyed)
[in]	src	Pointer to source string.

Returns: True on success, false otherwise

Definition at line 253 of file strarray.c.

◆ str_destroy()

void str_destroy ( string * str )

Destroy a string and free its contents.

Frees the internal storage and sets length to zero

Caller is responsible for freeing string itself, if required.

Parameters

[in] str Pointer to string to be destroyed

Definition at line 323 of file strarray.c.

◆ str_duplicate()

string* str_duplicate ( const string * src )

Allocate a new string containing the contents of another.

Wrapper around str_new(), passing it the length and internal character array of the source string.

Parameters

[in] src Pointer to source string

Returns: Return value of str_new()

Definition at line 281 of file strarray.c.

◆ str_new()

string* str_new	(	const size_t	len,
		const char *	ca
	)

Create new string from character array.

Allocates a new string structure and copies in the character array.

If last character of ca is not null then an extra byte is allocated and zeroed. The declared length represents an upper bound on the string length - the copy will stop at the first null byte found (strncpy() used internally)

Parameters

[in]	len	Maximum length of character array to be copied
[in]	ca	Pointer to character array

Returns: Pointer to newly allocated string, or NULL on failure

Definition at line 217 of file strarray.c.

◆ str_update()

bool str_update	(	string *	str,
		const size_t	len,
		const char *	src
	)

Update an existing string from a character array of given length.

Destroys the string, then allocates new memory and copies the array using strncpy() as described for str_new()

Parameters

[out]	str	Pointer to destination string
[in]	len	Maximum length of new character array to copy in
[in]	src	Pointer to source character array

Returns: True on success, false otherwise

Definition at line 294 of file strarray.c.

Classes

Functions

Detailed Description

Function Documentation

◆ sa_clear_entry()

◆ sa_copy()

◆ sa_create_entry()

◆ sa_destroy()

◆ sa_init()

◆ sa_move()

◆ sa_new()

◆ sa_set_entry()

◆ str_copy()

◆ str_destroy()

◆ str_duplicate()

◆ str_new()

◆ str_update()