Function

uni_convert

Convert encoding forms.

Since v1.0

unistat uni_convert(

const void *src, unisize src_len, uniattr src_attr, void *dst, unisize *dst_len, uniattr dst_attr)

Parameters 🔗

src	in	Input text.
src_len	in	Number of code units in `src` or `-1` if `src` is null terminated.
src_attr	in	Attributes of `src`.
dst	out	Will contain the re-encoded `src` text; can be `NULL`.
dst_len	inout	Code unit capacity of `dst` on input; number of code units written to `dst` on output.
dst_attr	in	Attributes of `dst`.

Return Value 🔗

UNI_OK	On success.
UNI_BAD_OPERATION	If `src` or `dest_len` are `NULL`.
UNI_BAD_ENCODING	If `src` is not well-formed (checks are omitted if `src_attr` has UNI_TRUST).
UNI_NO_SPACE	If `dest` is too small.
UNI_FEATURE_DISABLED	If the `src_attr` and `dst_attr` encoding forms are disabled.

Discussion 🔗

Convert the text pointed to by src, which is in the encoding form specified by src_attr, to the encoding specified by dst_attr and write the result to dst. If src_len is -1, then src is assumed to be null terminated.

If dst isn’t large enough to contain the re-encoded src text, then it will be truncated to the nearest code point boundary and UNI_NO_SPACE will be returned. If dst is large enough, then UNI_OK is returned.

If dst is NULL and dst_len is zero, then the implementation writes to dst_len the number of code units in the fully re-encoded text and returns UNI_OK. Call the function this way to compute the total length of the destination buffer before calling it again with a sufficiently sized buffer.

If src_attr and dst_attr are identical, then this function behaves like memcpy.

Examples 🔗

This example re-encodes text from UTF-32 to UTF-8. It uses char32_t and 'U' literal strings from C11.

#include <unicorn.h>
#include <uchar.h>
#include <stdio.h>

int main(void)
{
    const char32_t in[] = U"👨🏻‍🚀🧑🏼‍🚀 landed on the 🌕 in 1969.";
    char out[64];
    unisize outlen = sizeof(out);

    if (uni_convert(in, -1, UNI_UTF32, out, &outlen, UNI_UTF8) != UNI_OK)
    {
        // something went wrong
        return 1;
    }

    printf("%.*s", outlen, out);
    return 0;
}

Manual