Strings
-
struct CowlString
The string type.
Pseudo-extends:
CowlObject
-
CowlString *cowl_string(UString string)
Returns a 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 calling
cowl_string_opt()
withCOWL_SO_NONE
.Note
You must release the returned object via
cowl_release()
.- Parameters:
string – The underlying string object.
- Returns:
String, or NULL on error.
-
CowlString *cowl_string_opt(UString string, CowlStringOpts opts)
Returns a 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.
Note
You must release the returned object via
cowl_release()
.- Parameters:
string – The underlying string object.
opts – String creation options.
- Returns:
String, or NULL on error.
-
CowlString *cowl_string_empty(void)
Returns an empty string.
Note
You must release the returned object via
cowl_release()
.- Returns:
String, or NULL on error.
-
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.
-
UString cowl_string_release_copying_raw(CowlString *string)
Releases the specified string, returning its raw string as a copy.
Note
The returned object must be destroyed by calling
ustring_deinit()
.Note
As an optimization, if the string is deallocated due to the release call, then the original raw string is returned.
- Parameters:
string – The string.
- Returns:
Copy of the underlying string object.
-
char *cowl_string_release_copying_cstring(CowlString *string)
Releases the specified string, returning its buffer as a copy.
Note
The returned object must be destroyed by calling
ulib_free()
.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.
-
CowlString *cowl_string_with_format(char const *format, ...)
Returns a string with the specified format.
Note
You must release the returned object via
cowl_release()
.- Parameters:
format – Format string.
... – Format arguments.
- Returns:
String, or NULL on error.
-
CowlString *cowl_string_concat(CowlString *lhs, CowlString *rhs)
Returns a string obtained by concatenating two strings.
Note
You must release the returned object via
cowl_release()
.- Parameters:
lhs – LHS of the concatenation.
rhs – RHS of the concatenation.
- Returns:
String, or NULL on error.
-
cowl_ret cowl_string_to_int(CowlString *string, ulib_int *out, unsigned base)
Converts the string into an integer.
- Parameters:
string – The string.
out – Output value.
base – Numeric base.
- Returns:
Return code.
-
cowl_ret cowl_string_to_uint(CowlString *string, ulib_uint *out, unsigned base)
Converts the string into an unsigned integer.
- Parameters:
string – The string.
out – Output value.
base – Numeric base.
- Returns:
Return code.
-
cowl_ret cowl_string_to_float(CowlString *string, ulib_float *out)
Converts the string into a float.
- Parameters:
string – The string.
out – Output value.
- Returns:
Return code.
-
cowl_string_from_static(str)
Returns a string from the specified literal string.
Note
You must release the returned object via
cowl_release()
.- Parameters:
str –
char const []
String literal.
- Returns:
CowlString *
String, or NULL on error.
-
COWL_SO_NONE
Empty options.
-
COWL_SO_COPY
Copy the underlying raw string.
-
COWL_SO_INTERN
Intern the resulting string.