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_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.

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.

va_string *va_string_share(const va_string *string)

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.

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.