Typedefs
typedef const char	GblStringRef

Functions
Lifetime Management
Methods for managing GblStringRef references
GblStringRef *	GblStringRef_create (const char pString, size_t len, GblContext pCtx)

GblStringRef *	GblStringRef_ref (GblStringRef *pRef)

GblRefCount	GblStringRef_unref (GblStringRef *pRef)

Properties
Methods for reading stored and derived data
GblContext *	GblStringRef_context (const GblStringRef *pSelf)

GblRefCount	GblStringRef_refCount (const GblStringRef *pSelf)

size_t	GblStringRef_length (const GblStringRef *pSelf)

GblBool	GblStringRef_valid (const GblStringRef *pSelf)

GblBool	GblStringRef_empty (const GblStringRef *pSelf)

GblBool	GblStringRef_blank (const GblStringRef *pSelf)

GblHash	GblStringRef_hash (const GblStringRef *pSelf)

Accessors
Methods for accessing character and substrings
char	GblStringRef_at (const GblStringRef *pSelf, size_t idx)

GblStringView	GblStringRef_view (const GblStringRef *pSelf, size_t offset, size_t len)

Detailed Description

GblStringRef type and related functions

GblStringRef is a read-only, reference-counted string used to efficiently store, reference, and copy strings. It is also type-compatible with const char*, so it masquerades as a regular C-string to conveniently support regular C string APIs and character array accesses.

Note: GblStringRef also stores its length internally, so the GblStringRef_length() function and GblStringRef_view() functions are extremely efficient. Favor this over strlen(), when you know you're working with a GblStringRef.

The following example illustrates how it may be used:

GblStringRef* pRef = GblStringRef_create("lolol");

// Look, I'm a regular C string!
assert(pRef[0] == 'l');
assert(strlen(pRef) == 5);
assert(strcmp(pRef, "lolol") == 0);

// owait, no, I'm not.
GblStringRef* pRef2 = GblStringRef_ref(pRef);
assert(GblStringRef_refCount(pRef2) == 2);

// even stores length to save on strlen() / StringView time
assert(GblStringRef_length(pRef2) == 5);

// no strlen() happening here, fast.
GblStringView view = GblStringRef_view(pRef);

GblStringRef_unref(pRef);  // now refCount is 1
GblStringRef_unref(pRef2); // now it's deleted

Author: 2023 Falco Girgis

Copyright: MIT License

Definition in file gimbal_string_ref.h.

Function Documentation

◆ GblStringRef_create()

GblStringRef * GblStringRef_create	(	const char *	pString,
		size_t	len,
		GblContext *	pCtx )

Creates and returns a reference containing pString, with optional length and context.

◆ GblStringRef_ref()

GblStringRef * GblStringRef_ref ( GblStringRef * pRef )

Returns a new reference to pRef, incrementing its internal reference count rather than actually copying.

◆ GblStringRef_unref()

GblRefCount GblStringRef_unref ( GblStringRef * pRef )

Releases a reference to pRef, freeing the allocation if it was the last, returning the new refCount.

◆ GblStringRef_context()

GblContext * GblStringRef_context ( const GblStringRef * pSelf )

Returns the GblContext that was created with the given GblStringRef.

◆ GblStringRef_refCount()

GblRefCount GblStringRef_refCount ( const GblStringRef * pSelf )

Returns the number of active references remaining to the given GblStringRef.

◆ GblStringRef_length()

size_t GblStringRef_length ( const GblStringRef * pSelf )

Returns the cached length of the given GblStringRef.

◆ GblStringRef_valid()

GblBool GblStringRef_valid ( const GblStringRef * pSelf )

Returns whether the given GblStringRef is valid (not NULL)

◆ GblStringRef_empty()

GblBool GblStringRef_empty ( const GblStringRef * pSelf )

Returns whether the given GblStringRef is empty, with nothing but a NULL terminator.

◆ GblStringRef_blank()

GblBool GblStringRef_blank ( const GblStringRef * pSelf )

Returns whether the given GblStringRef is blank, containing only NULL or spacing characters.

◆ GblStringRef_hash()

GblHash GblStringRef_hash ( const GblStringRef * pSelf )

Calculates and returns the 32-bit hash value associated with the givne GblStringRef.

◆ GblStringRef_at()

char GblStringRef_at	(	const GblStringRef *	pSelf,
		size_t	idx )

Returns the character located at position idx, raising an error upon out-of-range.

◆ GblStringRef_view()

GblStringView GblStringRef_view	(	const GblStringRef *	pSelf,
		size_t	offset,
		size_t	len )

Returns a GblStringView containing the character window given by offset and len.

Typedefs

Functions