va_string🔗
#include <va_string.h>
Typedefs
-
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* string = va_string_alloc_empty(); va_string* string2 = va_string_join(string, "Raw character sequence."); va_string* string3 = va_string_join("Raw character sequence.", string); va_string_free(string); va_string_free(string2); va_string_free(string3);
Functions
-
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.
va_string* str = va_string_clone("Mämmi on hyvää."); va_string* str2 = va_string_clone(str2); va_string_free(str); va_string_free(str2);
- Return
a dynamically allocated string object or NULL if the allocation fails.
- Parameters
string
: A pointer to a va_string or a UTF-8 encoded sequence of characters.
If string points to a dynamically allocated va_string, increases its reference count and returns string.
If string is a C string returns
va_string_clone(string)
.
-
void
va_string_free
(va_string *string)🔗 Releases the memory allocated by string.
If string points to a C-style character array (see va_string_is_cstring), this function does nothing. If the string is shared (see va_string_share), the memory will be released once the last reference has been freed.
-
size_t
va_string_length
(const va_string *string)🔗 Returns the number of characters in string.
Note that the number of characters is at least one less than the number of bytes required to store the string.
-
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.
-
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); va_string_free(str);
-
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" va_string_free(str1); va_string_free(str2);
-
int
va_string_compare
(const va_string *string1, const va_string *string2)🔗 Compares two strings.
This function is equivalent to strcmp() of UTF-8 encoded C strings: it returns an integer less than, equal to, or greater than zero if string1 is found, respectively, to be less than, to match, or be greater than string2.