gimbal_string_list.h File Reference

Go to the source code of this file.

Macros
#define	GBL_STRING_LIST_NPOS

Typedefs
typedef GblBool(*	GblStringListIterFn) (GblStringRef *pRef, void *pClosure)
typedef GblRingList	GblStringList

Functions
Lifetime Management
Methods for creating, referencing, and unreferencing lists
GblStringList *	GblStringList_createEmpty (void)
GblStringList *	GblStringList_create (const char *pFirst,...)
GblStringList *	GblStringList_createVa (const char *pFirst, va_list *pVa)
GblStringList *	GblStringList_createWithRefs (GblStringRef *pFirst,...)
GblStringList *	GblStringList_createWithRefsVa (GblStringRef *pFirst, va_list *pVa)
GblStringList *	GblStringList_createWithViews (const char *pFirst, size_t firstLen,...)
GblStringList *	GblStringList_createWithViewsVa (const char *pFirst, size_t firstLen, va_list *pVa)
GblStringList *	GblStringList_createWithArray (const char **ppStr, size_t size)
GblStringList *	GblStringList_createSplit (const char *pStr, const char *pDelim, size_t strLen, size_t delimLen)
GblStringList *	GblStringList_createCopy (const GblStringList *pSrc, intptr_t startIdx, size_t count)
GblStringList *	GblStringList_createFilter (const GblStringList *pSrc, const char *pPat)
GblStringList *	GblStringList_ref (const GblStringList *pSelf)
GblRefCount	GblStringList_unref (GblStringList *pSelf)
Operators
Methods implementing basic operations
int	GblStringList_compare (const GblStringList *pSelf, const GblStringList *pOther, GblBool matchCase)
GblBool	GblStringList_equals (const GblStringList *pSelf, const GblStringList *pOther, GblBool matchCase)
int	GblStringList_compareStrs (const GblStringList *pSelf, int matchCase,...)
GblBool	GblStringList_equalsStrs (const GblStringList *pSelf, int matchCase,...)
int	GblStringList_compareStrsVa (const GblStringList *pSelf, int matchCase, va_list *pVa)
GblBool	GblStringList_equalsStrsVa (const GblStringList *pSelf, int matchCase, va_list *pVa)
Properties
Methods for accessing properties and derived data
GblRefCount	GblStringList_refCount (const GblStringList *pSelf)
size_t	GblStringList_size (const GblStringList *pSelf)
GblBool	GblStringList_empty (const GblStringList *pSelf)
GblStringRef *	GblStringList_front (const GblStringList *pSelf)
GblStringRef *	GblStringList_back (const GblStringList *pSelf)
GblStringRef *	GblStringList_at (const GblStringList *pSelf, intptr_t index)
Searching
Methods for finding, counting, and replacing strings
size_t	GblStringList_find (const GblStringList *pSelf, const char *pStr, GblBool matchCase, size_t offset, size_t strLen)
size_t	GblStringList_rfind (const GblStringList *pSelf, const char *pStr, GblBool matchCase, size_t offset, size_t strLen)
GblBool	GblStringList_contains (const GblStringList *pSelf, const char *pStr, GblBool matchCase, size_t strLen)
size_t	GblStringList_count (const GblStringList *pSelf, const char *pStr, GblBool matchCase, size_t strLen)
Assigning
Methods for setting elements
GBL_RESULT	GblStringList_set (GblStringList *pSelf, intptr_t index, const char *pStr, size_t strLen)
GBL_RESULT	GblStringList_setRef (GblStringList *pSelf, intptr_t index, GblStringRef *pRef)
Adding
Methods for appending and inserting strings
GBL_RESULT	GblStringList_pushBack (GblStringList *pSelf,...)
GBL_RESULT	GblStringList_pushBackVa (GblStringList *pSelf, va_list *pVa)
GBL_RESULT	GblStringList_pushBackRefs (GblStringList *pSelf,...)
GBL_RESULT	GblStringList_pushBackRefsVa (GblStringList *pSelf, va_list *pVa)
GBL_RESULT	GblStringList_pushBackViews (GblStringList *pSelf,...)
GBL_RESULT	GblStringList_pushBackViewsVa (GblStringList *pSelf, va_list *pVa)
GBL_RESULT	GblStringList_pushBackArray (GblStringList *pSelf, const char **ppStrArray, size_t len)
GBL_RESULT	GblStringList_pushFront (GblStringList *pSelf,...)
GBL_RESULT	GblStringList_pushFrontVa (GblStringList *pSelf, va_list *pVa)
GBL_RESULT	GblStringList_pushFrontRefs (GblStringList *pSelf,...)
GBL_RESULT	GblStringList_pushFrontRefsVa (GblStringList *pSelf, va_list *pVa)
GBL_RESULT	GblStringList_pushFrontViews (GblStringList *pSelf,...)
GBL_RESULT	GblStringList_pushFrontViewsVa (GblStringList *pSelf, va_list *pVa)
GBL_RESULT	GblStringList_pushFrontArray (GblStringList *pSelf, const char **ppStrArray, size_t len)
GBL_RESULT	GblStringList_insert (GblStringList *pSelf, intptr_t index,...)
GBL_RESULT	GblStringList_insertVa (GblStringList *pSelf, intptr_t index, va_list *pVa)
GBL_RESULT	GblStringList_insertRefs (GblStringList *pSelf, intptr_t index,...)
GBL_RESULT	GblStringList_insertRefsVa (GblStringList *pSelf, intptr_t index, va_list *pVa)
GBL_RESULT	GblStringList_insertViews (GblStringList *pSelf, intptr_t index,...)
GBL_RESULT	GblStringList_insertViewsVa (GblStringList *pSelf, intptr_t index, va_list *pVa)
GBL_RESULT	GblStringList_insertArray (GblStringList *pSelf, intptr_t index, const char **ppStrArray, size_t len)
Removing
Methods for popping and erasing strings
GblStringRef *	GblStringList_popBack (GblStringList *pSelf)
GblStringRef *	GblStringList_popFront (GblStringList *pSelf)
GBL_RESULT	GblStringList_erase (GblStringList *pSelf, intptr_t index, size_t count)
size_t	GblStringList_remove (GblStringList *pSelf, const char *pStr, GblBool matchCase, size_t strLen)
GblStringRef *	GblStringList_extract (GblStringList *pSelf, GblStringList *pNode)
GBL_RESULT	GblStringList_deduplicate (GblStringList *pSelf, GblBool matchCase)
GBL_RESULT	GblStringList_clear (GblStringList *pSelf)
Miscellaneous
Methods for replacing, sorting, and other utilities
size_t	GblStringList_replace (GblStringList *pSelf, const char *pOld, const char *pNew, GblBool matchCase, size_t limit, size_t oldLen, size_t newLen)
size_t	GblStringList_replaceWithRef (GblStringList *pSelf, const char *pOld, GblStringRef *pNew, GblBool matchCase, size_t limit, size_t oldLen)
GBL_RESULT	GblStringList_splice (GblStringList *pSelf, GblStringList *pOther, intptr_t index)
GblStringRef *	GblStringList_join (const GblStringList *pSelf, const char *pSeparator, size_t sepLen)
void	GblStringList_sort (GblStringList *pSelf, GblBool descending)
void	GblStringList_rotate (GblStringList *pSelf, intptr_t n)
void	GblStringList_reverse (GblStringList *pSelf)
GblBool	GblStringList_foreach (GblStringList *pSelf, GblStringListIterFn pFnIt, void *pCl)

Detailed Description

GblStringList structure and related functions.

This file contains the definition of GblStringList and its related API. A GblStringList is a container for conveniently working with multiple separate strings.

See also

GblStringList

Todo:

• Add pattern matching API
• replaceInStrings
• GblStringList_createSplitPattern()
• test any "view" method
• make splice take a range
• compare/equals strings/arrays/views
• pushBack/pushFront arrays
• insert arrays

Author

2023 Falco Girgis

Copyright

MIT License

Definition in file gimbal_string_list.h.

Macro Definition Documentation

GBL_STRING_LIST_NPOS

#define GBL_STRING_LIST_NPOS

Represents the last position or an invalid index in a GblStringList.

Definition at line 32 of file gimbal_string_list.h.

Typedef Documentation

GblStringListIterFn

typedef GblBool(* GblStringListIterFn) (GblStringRef *pRef, void *pClosure)

Iterator function used with GblStringList_foreach()

Callback used when iterating over a GblStringList, getting passed a reference to each GblStringRef within the list, along with an optional closure/capture value that can be passed in.

Returning GBL_TRUE will cause iteration to cease early.

Definition at line 46 of file gimbal_string_list.h.

Function Documentation

GblStringList_createEmpty()

GblStringList * GblStringList_createEmpty

(

void

)

Creates and returns a new, empty GblStringList reference with a size of 0.

GblStringList_create()

GblStringList * GblStringList_create	(	const char *	pFirst,
			...
	)

Creates and returns a new GblStringList reference, populating it with a list of C strings (auto NULL-terminated)

GblStringList_createVa()

GblStringList * GblStringList_createVa	(	const char *	pFirst,
		va_list *	pVa
	)

Equivalent to GblStringList_create(), except for strings N+1 are all passed via a va_list pointer.

GblStringList_createWithRefs()

GblStringList * GblStringList_createWithRefs	(	GblStringRef *	pFirst,
			...
	)

Equivalent to GblStringList_create(), except for the strings are provided as GblStringRefs (which will be referenced again)

GblStringList_createWithRefsVa()

GblStringList * GblStringList_createWithRefsVa	(	GblStringRef *	pFirst,
		va_list *	pVa
	)

Equivalent to GblStringList_createWithRefs(), except for strings N+1 are all passed via a va_list pointer.

GblStringList_createWithViews()

GblStringList * GblStringList_createWithViews	(	const char *	pFirst,
		size_t	firstLen,
			...
	)

Creates and returns a new GblStringList reference, populating it with the (auto) NULL-terminated list of (string, length) pairs.

GblStringList_createWithViewsVa()

GblStringList * GblStringList_createWithViewsVa	(	const char *	pFirst,
		size_t	firstLen,
		va_list *	pVa
	)

Equivalent to GblStringList_createWithViews(), except for views N+1 are all passed via a va_list pointer.

GblStringList_createWithArray()

GblStringList * GblStringList_createWithArray	(	const char **	ppStr,
		size_t	size
	)

Creates and returns a new GblStringList, populated by an array of const char* pointers, with either a size or NULL terminator (default)

GblStringList_createSplit()

GblStringList * GblStringList_createSplit	(	const char *	pStr,
		const char *	pDelim,
		size_t	strLen,
		size_t	delimLen
	)

Creates and returns a new GblStringList, populating it with pStr split up by every occurence of pDelim.

GblStringList_createCopy()

GblStringList * GblStringList_createCopy	(	const GblStringList *	pSrc,
		intptr_t	startIdx,
		size_t	count
	)

Deep copies an existing GblStringList, creating a duplicated list populated by references to the values held by pSrc.

GblStringList_createFilter()

GblStringList * GblStringList_createFilter	(	const GblStringList *	pSrc,
		const char *	pPat
	)

Creates and returns a new GblStringList, populated only by those strings from pSrc which match the given pattern, pPat.

GblStringList_ref()

GblStringList * GblStringList_ref

(

const GblStringList *

pSelf

)

Returns a reference to an existing GblStringList, incrementing its reference count and returning it back.

GblStringList_unref()

GblRefCount GblStringList_unref

(

GblStringList *

pSelf

)

Releases a reference to the given GblStringList, decrementing and returning its remaining refCount, destroying it upon hitting 0.

GblStringList_compare()

int GblStringList_compare	(	const GblStringList *	pSelf,
		const GblStringList *	pOther,
		GblBool	matchCase
	)

Returns the lexicographical difference between the two lists, optionally doing so case insensitively.

GblStringList_equals()

GblBool GblStringList_equals	(	const GblStringList *	pSelf,
		const GblStringList *	pOther,
		GblBool	matchCase
	)

Returns GBL_TRUE if the given list is lexicographically equal to the pOther list, optionally ignoring case.

GblStringList_compareStrs()

int GblStringList_compareStrs	(	const GblStringList *	pSelf,
		int	matchCase,
			...
	)

Equivalent to GblStringList_compare(), except that an (auto) NULL-terminated list of C strings is the other value being compared.

GblStringList_equalsStrs()

GblBool GblStringList_equalsStrs	(	const GblStringList *	pSelf,
		int	matchCase,
			...
	)

Equivalent to GblStringList_equals(), except that an (auto) NULL-terminated list of C strings is the value being compared.

GblStringList_compareStrsVa()

int GblStringList_compareStrsVa	(	const GblStringList *	pSelf,
		int	matchCase,
		va_list *	pVa
	)

Equivalent to GblStringList_compareStrs(), except the NULL-terminated list of C strings is passed through a va_list pointer.

GblStringList_equalsStrsVa()

GblBool GblStringList_equalsStrsVa	(	const GblStringList *	pSelf,
		int	matchCase,
		va_list *	pVa
	)

Equivalent to GblStringList_equalsStrs(), except the NULL-terminated list of C strings is passed through a va_list pointer.

GblStringList_refCount()

GblRefCount GblStringList_refCount

(

const GblStringList *

pSelf

)

Returns the number of active references to the given GblStringList.

GblStringList_size()

size_t GblStringList_size

(

const GblStringList *

pSelf

)

Returns the number of string elements contained by the the given GblStringList.

GblStringList_empty()

GblBool GblStringList_empty

(

const GblStringList *

pSelf

)

Returns whether the given GblStringList contains any string elements or not.

GblStringList_front()

GblStringRef * GblStringList_front

(

const GblStringList *

pSelf

)

Returns the first string (element 0) contained within the given GblStringList or NULL if it's empty.

GblStringList_back()

GblStringRef * GblStringList_back

(

const GblStringList *

pSelf

)

Returns the last string (element -1) contained within the given GblStringList or NULL if it's empty.

GblStringList_at()

GblStringRef * GblStringList_at	(	const GblStringList *	pSelf,
		intptr_t	index
	)

Returns the string contained at the given signedindex within the GblStringList or NULL if invalid.

GblStringList_find()

size_t GblStringList_find	(	const GblStringList *	pSelf,
		const char *	pStr,
		GblBool	matchCase,
		size_t	offset,
		size_t	strLen
	)

Searches the list for pStr, starting at offset, returning its index if found, or GBL_RING_LIST_NPOS otherwise.

GblStringList_rfind()

size_t GblStringList_rfind	(	const GblStringList *	pSelf,
		const char *	pStr,
		GblBool	matchCase,
		size_t	offset,
		size_t	strLen
	)

This function is equivalent to GblStringList_find(), except that it searches from the last to first element.

GblStringList_contains()

GblBool GblStringList_contains	(	const GblStringList *	pSelf,
		const char *	pStr,
		GblBool	matchCase,
		size_t	strLen
	)

Searches the given list for the first instance of pStr, returning its index or GBL_RING_LIST_NPOS if it wasn't found.

GblStringList_count()

size_t GblStringList_count	(	const GblStringList *	pSelf,
		const char *	pStr,
		GblBool	matchCase,
		size_t	strLen
	)

Searches the given list for the number of occurences of pStr, optionally doing case insensitive comparisons.

GblStringList_set()

GBL_RESULT GblStringList_set	(	GblStringList *	pSelf,
		intptr_t	index,
		const char *	pStr,
		size_t	strLen
	)

Sets the string contained at the given signed index to pStr, returning a result code.

GblStringList_setRef()

GBL_RESULT GblStringList_setRef	(	GblStringList *	pSelf,
		intptr_t	index,
		GblStringRef *	pRef
	)

Sets the string located at the given signed index to a new reference to pRef, returning a result code.

GblStringList_pushBack()

GBL_RESULT GblStringList_pushBack	(	GblStringList *	pSelf,
			...
	)

Appends the given (auto) NULL-terminated list of C strings to the back of the list, returning a status code.

GblStringList_pushBackVa()

GBL_RESULT GblStringList_pushBackVa	(	GblStringList *	pSelf,
		va_list *	pVa
	)

Equivalent to GblStringList_pushBack(), except the C strings are passed through a va_list pointer.

GblStringList_pushBackRefs()

GBL_RESULT GblStringList_pushBackRefs	(	GblStringList *	pSelf,
			...
	)

Appends new references to a list of (auto) NULL-terminated GblStringRefs to the end of the given list, returning a status code.

GblStringList_pushBackRefsVa()

GBL_RESULT GblStringList_pushBackRefsVa	(	GblStringList *	pSelf,
		va_list *	pVa
	)

Equivalent to GblStringList_pushBackRefs(), except the GblStringRefs are passed through a va_list pointer.

GblStringList_pushBackViews()

GBL_RESULT GblStringList_pushBackViews	(	GblStringList *	pSelf,
			...
	)

Appends the given (auto) NULL-terminated list of (string, length) pairs to the back of the list, returning a status code.

GblStringList_pushBackViewsVa()

GBL_RESULT GblStringList_pushBackViewsVa	(	GblStringList *	pSelf,
		va_list *	pVa
	)

Equivalent to GblStringList_pushBackViews(), except the (string, length) pairs are passed through a va_list pointer.

GblStringList_pushBackArray()

GBL_RESULT GblStringList_pushBackArray	(	GblStringList *	pSelf,
		const char **	ppStrArray,
		size_t	len
	)

Appends the given optionally NULL-terminated array of C strings to the back of the given list, returning a status code.

GblStringList_pushFront()

GBL_RESULT GblStringList_pushFront	(	GblStringList *	pSelf,
			...
	)

Prepends the given (auto) NULL-terminated list of C strings to the front of the list, returning a status code.

GblStringList_pushFrontVa()

GBL_RESULT GblStringList_pushFrontVa	(	GblStringList *	pSelf,
		va_list *	pVa
	)

Equivalent to GblStringList_pushFront(), except the C strings are passed through a va_list pointer.

GblStringList_pushFrontRefs()

GBL_RESULT GblStringList_pushFrontRefs	(	GblStringList *	pSelf,
			...
	)

Prepends new references to a list of (auto) NULL-terminated GblStringRefs to the front of the given list, returning a status code.

GblStringList_pushFrontRefsVa()

GBL_RESULT GblStringList_pushFrontRefsVa	(	GblStringList *	pSelf,
		va_list *	pVa
	)

Equivalent to GblStringList_pushFrontRefs(), except the GblStringRefs are passed through a va_list pointer.

GblStringList_pushFrontViews()

GBL_RESULT GblStringList_pushFrontViews	(	GblStringList *	pSelf,
			...
	)

Prepends the given (auto) NULL-terminated list of (string, length) pairs to the front of the list, returning a status code.

GblStringList_pushFrontViewsVa()

GBL_RESULT GblStringList_pushFrontViewsVa	(	GblStringList *	pSelf,
		va_list *	pVa
	)

Equivalent to GblStringList_pushFrontViews(), except the (string, length) pairs are passed through a va_list pointer.

GblStringList_pushFrontArray()

GBL_RESULT GblStringList_pushFrontArray	(	GblStringList *	pSelf,
		const char **	ppStrArray,
		size_t	len
	)

Prepends the given optionally NULL-terminated array of C strings to the front of the given list, returning a status code.

GblStringList_insert()

GBL_RESULT GblStringList_insert	(	GblStringList *	pSelf,
		intptr_t	index,
			...
	)

Inserts a(n auto) NULL-terminated list of C strings to the signed index of the list, returning a status code.

GblStringList_insertVa()

GBL_RESULT GblStringList_insertVa	(	GblStringList *	pSelf,
		intptr_t	index,
		va_list *	pVa
	)

Equivalent to GblStringList_insert(), except the list of C strings is passed through a va_list pointer.

GblStringList_insertRefs()

GBL_RESULT GblStringList_insertRefs	(	GblStringList *	pSelf,
		intptr_t	index,
			...
	)

Inserts new references to a(n auto) NULL-terminated list of GblStringRefs to index, returning a status code.

GblStringList_insertRefsVa()

GBL_RESULT GblStringList_insertRefsVa	(	GblStringList *	pSelf,
		intptr_t	index,
		va_list *	pVa
	)

Equivalent to GblStringList_insertRefs(), except the list of GblStringRefs is passed through a va_list pointer.

GblStringList_insertViews()

GBL_RESULT GblStringList_insertViews	(	GblStringList *	pSelf,
		intptr_t	index,
			...
	)

Inserts the given (auto) NULL-terminated list of (string, length) pairs into index in the list, returning a status code.

GblStringList_insertViewsVa()

GBL_RESULT GblStringList_insertViewsVa	(	GblStringList *	pSelf,
		intptr_t	index,
		va_list *	pVa
	)

Equivalent to GblStringList_insertViews(), except the list of pairs is provided through a va_list pointer.

GblStringList_insertArray()

GBL_RESULT GblStringList_insertArray	(	GblStringList *	pSelf,
		intptr_t	index,
		const char **	ppStrArray,
		size_t	len
	)

Inserts the given optionally NULL-terminated list of C strings at into index in the list, returning a status code.

GblStringList_popBack()

GblStringRef * GblStringList_popBack

(

GblStringList *

pSelf

)

Pops a reference to the last string in the list off of the end, returning it or NULL if empty.

GblStringList_popFront()

GblStringRef * GblStringList_popFront

(

GblStringList *

pSelf

)

Pops a reference to the first string in the list off the front, returning it or NULL if empty.

GblStringList_erase()

GBL_RESULT GblStringList_erase	(	GblStringList *	pSelf,
		intptr_t	index,
		size_t	count
	)

Erases count (default 1) entries from the list, starting at index, returning a status code.

GblStringList_remove()

size_t GblStringList_remove	(	GblStringList *	pSelf,
		const char *	pStr,
		GblBool	matchCase,
		size_t	strLen
	)

Removes all instances of pStr, optionally ignoring case, from the given list, returning the number removed.

GblStringList_extract()

GblStringRef * GblStringList_extract	(	GblStringList *	pSelf,
		GblStringList *	pNode
	)

Extracts the given node from the given list, returning its internally contained GblStringRef.

GblStringList_deduplicate()

GBL_RESULT GblStringList_deduplicate	(	GblStringList *	pSelf,
		GblBool	matchCase
	)

Removes all duplicate copies of any strings contained within the given list, returning a status code.

GblStringList_clear()

GBL_RESULT GblStringList_clear

(

GblStringList *

pSelf

)

Clears the given list, removing all string elements it contains, and returning a status code.

GblStringList_replace()

size_t GblStringList_replace	(	GblStringList *	pSelf,
		const char *	pOld,
		const char *	pNew,
		GblBool	matchCase,
		size_t	limit,
		size_t	oldLen,
		size_t	newLen
	)

Replaces limit instances of pOld with pNew found within the list, returning the number found.

GblStringList_replaceWithRef()

size_t GblStringList_replaceWithRef	(	GblStringList *	pSelf,
		const char *	pOld,
		GblStringRef *	pNew,
		GblBool	matchCase,
		size_t	limit,
		size_t	oldLen
	)

Equivalent to GblStringList_replace(), except the replacement is a new reference to the given GblStringRef.

GblStringList_splice()

GBL_RESULT GblStringList_splice	(	GblStringList *	pSelf,
		GblStringList *	pOther,
		intptr_t	index
	)

Splices the contents of pOther into pSelf at index, returning a result code.

GblStringList_join()

GblStringRef * GblStringList_join	(	const GblStringList *	pSelf,
		const char *	pSeparator,
		size_t	sepLen
	)

Joins together all strings within the list into a single string, separated by pSeparator, returning a new reference.

GblStringList_sort()

void GblStringList_sort	(	GblStringList *	pSelf,
		GblBool	descending
	)

Sorts the given list alphabetically in ascending order (by default) or descending order.

GblStringList_rotate()

void GblStringList_rotate	(	GblStringList *	pSelf,
		intptr_t	n
	)

Rotates entries of the given list either forward or backwards, wrapping them back around as necessary.

GblStringList_reverse()

void GblStringList_reverse

(

GblStringList *

pSelf

)

Reverses the order of all entries within the given list, so that the old front is back and vice versa.

GblStringList_foreach()

GblBool GblStringList_foreach	(	GblStringList *	pSelf,
		GblStringListIterFn	pFnIt,
		void *	pCl
	)

Iterates over every string within the list, passing it and pCl (optional) to pFnInit, see.

See also

GblStringListIterFn