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

Macros

Typedefs

Functions