String

String

Typedefs

typedef void va_string

Functions

va_string* va_string_alloc_empty()
va_string* va_string_clone(const va_string* string)
va_string* va_string_from_pointer(const va_string* string)
void va_string_free(va_string* string)
size_t va_string_length(const va_string* string)
size_t va_string_utf8_length(const va_string* string)
size_t va_string_to_utf8(const va_string* string, char* buffer, size_t length)
va_string* va_string_join(const va_string* string1, const va_string* string2)
int va_string_is_cstring(const va_string* string)

Typedef Documentation

typedef void va_string

Strings are represented as opaque pointers that may point either to UTF-8-encoded character arrays or dynamically allocated string objects. A "string" passed as an argument to any of the string API functions can be either a pointer to a raw UTF-8-encoded character sequence or a pointer to a dynamically allocated va_string. The functions detect the type of the pointed-to object and act accordingly.

va_string* string2 = va_string_join(string, "Raw character sequence.");
va_string* string3 = va_string_join("Raw character sequence.", string);
va_string_free(string2);
va_string_free(string3);

Function Documentation

va_string* va_string_alloc_empty()

Returns an empty string or NULL if memory allocation fails.

va_string* va_string_clone(const va_string* string)

Returns a copy of string or NULL if memory allocation fails. NULL will also be returned if string is NULL.

Parameters
stringA pointer to a va_string or a UTF-8 encoded sequence of characters.
Returns
a dynamically allocated string object or NULL if the allocation fails.
va_string* str = va_string_clone("Mämmi on hyvää.");
va_string* str2 = va_string_clone(str2);
void va_string_free(va_string* string)

Releases the memory allocated by string.

va_string* va_string_from_pointer(const va_string* string)

If string points to a va_string, returns string. Otherwise assumes that string points to a sequence of characters and returns va_string_clone(data).

int va_string_is_cstring(const va_string* string)

If string is not NULL and points to a byte with a value other than 0xff, returns a non-zero value. Otherwise returns zero.

va_string* va_string_join(const va_string* string1, const va_string* string2 )

Joins two strings and returns a newly allocated string. Both strings can be either pointers to UTF-8-encoded character arrays or pointers to va_string. On failure returns NULL.

va_string* str1 = va_string_join("ABC", "DEF"); // "ABCDEF"
va_string* str2 = va_string_join(str1, "GHI"); // "ABCDEFGHI"
size_t va_string_length(const va_string* string)

Returns the number of characters in string. Note that the number of characters is less than the number of bytes required to store the string.

size_t va_string_to_utf8(const va_string* string, char* buffer, size_t length )

Converts string to a zero-terminated UTF-8 character sequence. The given buffer needs to be able to hold at least length bytes.

The function returns the actual length of the UTF-8-encoded byte sequence, including the trailing zero byte. Note that the returned value may be larger than length, in which case the buffer wasn't big enough. In this case the contents of buffer will be unspecified. Use va_string_utf8_length to count the required number of bytes in advance.

const va_string* str = va_string_from_utf8("Töytäisemättäköhän?");
// ×2 is usually enough, use ×4 to be sure
size_t estimatedLength = va_string_length(str) * 2;
char* buffer = (char*)malloc(estimatedLength);
size_t length = va_string_to_utf8(str, buffer, estimatedLength);
if (length > estimatedLength)
{
buffer = (char*)realloc(buffer, length);
va_string_to_utf8(str, buffer, length);
}
printf("%s\n", buffer);
free(buffer);
size_t va_string_utf8_length(const va_string* string)

Returns the number of bytes required to store string as a zero-terminated UTF-8 character sequence, including the trailing zero byte.