Strings

struct CowlString : public CowlObject 

The string type.

Public Functions

CowlString *cowl_string(UString string)

Returns a retained string.

Note

The buffer of the raw string must have been dynamically allocated.

Note

Ownership of the raw string is transferred to the newly created CowlString, meaning you must not deinitialize it.

Note

Equivalent to cowl_string_opt(string, COWL_SO_NONE).

Parameters: string – The underlying string object.
Returns: Retained string, or NULL on error.

CowlString *cowl_string_opt(UString string, CowlStringOpts opts)

Returns a retained string.

String creation is governed by the following options:

COWL_SO_COPY: if set, the raw string is copied internally, otherwise it is directly assigned. Note that in the latter case the raw string must have been dynamically allocated, and you must not deinitialize it after passing it to this method.
COWL_SO_INTERN: if set, the CowlString is either created and added to an internal instance pool, or if an instance with the same raw string already exists in the pool, that instance is retained and returned. This entails that all instances created with this flag are guaranteed to be unique in memory.

Parameters

string – The underlying string object.
opts – String creation options.

Returns

Retained string, or NULL on error.

CowlString *cowl_string_empty(void)

Returns a retained empty string.

Returns: Retained string, or NULL on error.

void cowl_string_release(CowlString *string)

Releases the specified string.

Parameters: string – The string.

CowlString *cowl_string_intern(CowlString *string)

Interns the specified string.

The string is either added to an internal instance pool, or if an instance with the same raw string already exists in the pool, that instance is returned.

Note

The reference counts of the original string and that of the returned instance are not changed. This means you are still responsible for releasing the original string if you created it, and you should retain the returned string if you need to keep it alive.

Parameters: string – The string.
Returns: Interned string.

char const *cowl_string_release_copying_cstring(CowlString *string)

Releases the specified string, returning its buffer as a copy.

Note

As an optimization, if the string is deallocated due to the release call, then the original buffer is returned.

Parameters: string – The string.
Returns: The copied buffer.

char const *cowl_string_get_cstring(CowlString *string)

Gets the underlying string buffer.

Parameters: string – The string.
Returns: The buffer.

ulib_uint cowl_string_get_length(CowlString *string)

Gets the length of the string, excluding the NULL terminator.

Parameters: string – The string.
Returns: The length.

UString const *cowl_string_get_raw(CowlString *string)

Gets the underlying string object.

Parameters: string – The string.
Returns: Underlying string object.

bool cowl_string_equals(CowlString *lhs, CowlString *rhs)

Equality function.

Parameters

lhs – LHS of the equality relation.
rhs – RHS of the equality relation.

Returns

True if the equality relation holds, false otherwise.

ulib_uint cowl_string_hash(CowlString *string)

Hash function.

Parameters: string – The string.
Returns: The hash value.

CowlString *cowl_string_with_format(char const *format, ...)

Returns a retained string with the specified format.

Parameters

format – Format string.
... – Format arguments.

Returns

Retained string, or NULL on error.

CowlString *cowl_string_concat(CowlString *lhs, CowlString *rhs)

Returns a retained string obtained by concatenating two strings.

Parameters

lhs – LHS of the concatenation.
rhs – RHS of the concatenation.

Returns

Retained string, or NULL on error.

Public Static Functions

static inline CowlString *cowl_string_retain(CowlString *string)

Retains the specified string.

Parameters: string – The string.
Returns: Retained string.

cowl_string_from_static(CSTR)

Returns a retained string from the specified static string.

Parameters

CSTR – [char const[]] The static string.

Returns

[CowlString *] Retained string, or NULL on error.

cowl_string_to_string(STR)

Returns the string representation of the specified string.

Note

The returned string is retained, so you are responsible for releasing it.

Parameters

STR – [CowlString] The string.

Returns

String representation, or NULL on error.

String creation options

typedef uint8_t CowlStringOpts

String creation options.