libuna(3)
NAME π
okay so bestie, welcome to libuna(3) β straight from the Library Functions Manual β and this is the manual page for libuna.h β Library to support Unicode and ASCII (byte stream) conversions. periodt, that's the whole vibe of this library: converting between Unicode and ASCII byte streams, and looking cute doing it. π
SYNOPSIS β¨
First things first, here's the include you need, no cap:
#include <libuna.h>
Then the whole function roster rolls up like a group chat. Keep every name, type, argument, and line exactly as written β no renaming, no merging, no βfixing,β fr fr. π
Support functions π«Ά
Support functions, aka the little helpers:
const char *
libuna_get_version(void);
Error functions π
Error-handling girlies, assemble:
void
libuna_error_free(libuna_error_t **error);
int
libuna_error_fprint(libuna_error_t *error, FILE *stream);
int
libuna_error_sprint(libuna_error_t *error, char *string, size_t size);
int
libuna_error_backtrace_fprint(libuna_error_t *error, FILE *stream);
int
libuna_error_backtrace_sprint(libuna_error_t *error, char *string,
size_t size);
Unicode character functions π₯
These are the Unicode character functions β main character energy of the whole roster, ngl:
int
libuna_unicode_character_size_to_byte_stream(libuna_unicode_character_t unicode_character,
int codepage, size_t *byte_stream_character_size,
libuna_error_t **error);
int
libuna_unicode_character_copy_from_byte_stream(libuna_unicode_character_t *unicode_character,
const uint8_t *byte_stream, size_t byte_stream_size,
size_t *byte_stream_index, int codepage, libuna_error_t **error);
int
libuna_unicode_character_copy_to_byte_stream(libuna_unicode_character_t unicode_character,
uint8_t *byte_stream, size_t byte_stream_size,
size_t *byte_stream_index, int codepage, libuna_error_t **error);
int
libuna_unicode_character_size_to_ucs2(libuna_unicode_character_t *unicode_character,
size_t *ucs2_string_size, libuna_error_t **error);
int
libuna_unicode_character_copy_from_ucs2(libuna_unicode_character_t *unicode_character,
const libuna_utf16_character_t *ucs2_string,
size_t ucs2_string_size, size_t *ucs2_string_index,
libuna_error_t **error);
int
libuna_unicode_character_copy_to_ucs2(libuna_unicode_character_t unicode_character,
libuna_utf16_character_t *ucs2_string, size_t ucs2_string_size,
size_t *ucs2_string_index, libuna_error_t **error);
int
libuna_unicode_character_size_to_ucs4(libuna_unicode_character_t *unicode_character,
size_t *ucs4_string_size, libuna_error_t **error);
int
libuna_unicode_character_copy_from_ucs4(libuna_unicode_character_t *unicode_character,
const libuna_utf32_character_t *ucs4_string,
size_t ucs4_string_size, size_t *ucs4_string_index,
libuna_error_t **error);
int
libuna_unicode_character_copy_to_ucs4(libuna_unicode_character_t unicode_character,
libuna_utf32_character_t *ucs4_string, size_t ucs4_string_size,
size_t *ucs4_string_index, libuna_error_t **error);
int
libuna_unicode_character_copy_from_utf7_stream(libuna_unicode_character_t *unicode_character,
const uint8_t *utf7_stream, size_t utf7_stream_size,
size_t *utf7_stream_index, uint32_t *utf7_stream_base64_data,
libuna_error_t **error);
int
libuna_unicode_character_copy_to_utf7_stream(libuna_unicode_character_t unicode_character,
uint8_t *utf7_stream, size_t utf7_stream_size,
size_t *utf7_stream_index, uint32_t *utf7_stream_base64_data,
libuna_error_t **error);
int
libuna_unicode_character_size_to_utf8(libuna_unicode_character_t *unicode_character,
size_t *utf8_string_size, libuna_error_t **error);
int
libuna_unicode_character_copy_from_utf8(libuna_unicode_character_t *unicode_character,
const libuna_utf8_character_t *utf8_string, size_t utf8_string_size,
size_t *utf8_string_index, libuna_error_t **error);
int
libuna_unicode_character_copy_to_utf8(libuna_unicode_character_t unicode_character,
libuna_utf8_character_t *utf8_string, size_t utf8_string_size,
size_t *utf8_string_index, libuna_error_t **error);
int
libuna_unicode_character_size_to_utf8_rfc2279(libuna_unicode_character_t *unicode_character,
size_t *utf8_string_size, libuna_error_t **error);
int
libuna_unicode_character_copy_from_utf8_rfc2279(libuna_unicode_character_t *unicode_character,
const libuna_utf8_character_t *utf8_string, size_t utf8_string_size,
size_t *utf8_string_index, libuna_error_t **error);
int
libuna_unicode_character_copy_to_utf8_rfc2279(libuna_unicode_character_t unicode_character,
libuna_utf8_character_t *utf8_string, size_t utf8_string_size,
size_t *utf8_string_index, libuna_error_t **error);
int
libuna_unicode_character_size_to_utf16(libuna_unicode_character_t *unicode_character,
size_t *utf16_string_size, libuna_error_t **error);
int
libuna_unicode_character_copy_from_utf16(libuna_unicode_character_t *unicode_character,
const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf16_string_index,
libuna_error_t **error);
int
libuna_unicode_character_copy_to_utf16(libuna_unicode_character_t unicode_character,
libuna_utf16_character_t *utf16_string, size_t utf16_string_size,
size_t *utf16_string_index, libuna_error_t **error);
int
libuna_unicode_character_copy_from_utf16_stream(libuna_unicode_character_t *unicode_character,
const uint8_t *utf16_stream, size_t utf16_stream_size,
size_t *utf16_stream_index, int byte_order, libuna_error_t **error);
int
libuna_unicode_character_copy_to_utf16_stream(libuna_unicode_character_t unicode_character,
uint8_t *utf16_stream, size_t utf16_stream_size,
size_t *utf16_stream_index, int byte_order, libuna_error_t **error);
int
libuna_unicode_character_size_to_utf32(libuna_unicode_character_t *unicode_character,
size_t *utf32_string_size, libuna_error_t **error);
int
libuna_unicode_character_copy_from_utf32(libuna_unicode_character_t *unicode_character,
const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf32_string_index,
libuna_error_t **error);
int
libuna_unicode_character_copy_to_utf32(libuna_unicode_character_t unicode_character,
libuna_utf32_character_t *utf32_string, size_t utf32_string_size,
size_t *utf32_string_index, libuna_error_t **error);
int
libuna_unicode_character_copy_from_utf32_stream(libuna_unicode_character_t *unicode_character,
const uint8_t *utf32_stream, size_t utf32_stream_size,
size_t *utf32_stream_index, int byte_order, libuna_error_t **error);
int
libuna_unicode_character_copy_to_utf32_stream(libuna_unicode_character_t unicode_character,
uint8_t *utf32_stream, size_t utf32_stream_size,
size_t *utf32_stream_index, int byte_order, libuna_error_t **error);
Byte stream functions π
Byte stream functions, coming through β lowkey iconic:
int
libuna_byte_stream_size_from_utf8(const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, int codepage, size_t *byte_stream_size,
libuna_error_t **error);
int
libuna_byte_stream_copy_from_utf8(uint8_t *byte_stream,
size_t byte_stream_size, int codepage,
const libuna_utf8_character_t *utf8_string, size_t utf8_string_size,
libuna_error_t **error);
int
libuna_byte_stream_size_from_utf16(const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, int codepage, size_t *byte_stream_size,
libuna_error_t **error);
int
libuna_byte_stream_copy_from_utf16(uint8_t *byte_stream,
size_t byte_stream_size, int codepage,
const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, libuna_error_t **error);
int
libuna_byte_stream_size_from_utf32(const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, int codepage, size_t *byte_stream_size,
libuna_error_t **error);
int
libuna_byte_stream_copy_from_utf32(uint8_t *byte_stream,
size_t byte_stream_size, int codepage,
const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, libuna_error_t **error);
UTF-7 stream functions π¦
UTF-7 stream functions β yes, UTF-7 is still here, and we're respecting it:
int
libuna_utf7_stream_size_from_utf8(const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, size_t *utf7_stream_size,
libuna_error_t **error);
int
libuna_utf7_stream_copy_from_utf8(uint8_t *utf7_stream,
size_t utf7_stream_size, const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, libuna_error_t **error);
int
libuna_utf7_stream_size_from_utf16(const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf7_stream_size,
libuna_error_t **error);
int
libuna_utf7_stream_copy_from_utf16(uint8_t *utf7_stream,
size_t utf7_stream_size,
const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, libuna_error_t **error);
int
libuna_utf7_stream_size_from_utf32(const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf7_stream_size,
libuna_error_t **error);
int
libuna_utf7_stream_copy_from_utf32(uint8_t *utf7_stream,
size_t utf7_stream_size,
const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, libuna_error_t **error);
UTF-8 stream functions π
UTF-8 stream functions, slaying as usual:
int
libuna_utf8_stream_copy_byte_order_mark(uint8_t *utf8_stream,
size_t utf8_stream_size, size_t *utf8_stream_index,
libuna_error_t **error);
int
libuna_utf8_stream_size_from_utf8(const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, size_t *utf8_stream_size,
libuna_error_t **error);
int
libuna_utf8_stream_copy_from_utf8(uint8_t *utf8_stream,
size_t utf8_stream_size, const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, libuna_error_t **error);
int
libuna_utf8_stream_size_from_utf16(const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf8_stream_size,
libuna_error_t **error);
int
libuna_utf8_stream_copy_from_utf16(uint8_t *utf8_stream,
size_t utf8_stream_size,
const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, libuna_error_t **error);
int
libuna_utf8_stream_size_from_utf32(const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf8_stream_size,
libuna_error_t **error);
int
libuna_utf8_stream_copy_from_utf32(uint8_t *utf8_stream,
size_t utf8_stream_size,
const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, libuna_error_t **error);
UTF-8 string functions π
UTF-8 string functions β the way that these convert byte streams is honestly iconic:
int
libuna_utf8_string_size_from_byte_stream(const uint8_t *byte_stream,
size_t byte_stream_size, int codepage, size_t *utf8_string_size,
libuna_error_t **error);
int
libuna_utf8_string_copy_from_byte_stream(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, const uint8_t *byte_stream,
size_t byte_stream_size, int codepage, libuna_error_t **error);
libuna_utf8_string_with_index_copy_from_byte_streamπ β the same byte-stream copy but it keeps a running index for youlibuna_utf8_string_compare_with_byte_streamπ β checks whether the UTF-8 string matches the byte stream (with a codepage)
int
libuna_utf8_string_with_index_copy_from_byte_stream(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, size_t *utf8_string_index,
const uint8_t *byte_stream, size_t byte_stream_size, int codepage,
libuna_error_t **error);
int
libuna_utf8_string_compare_with_byte_stream(const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, const uint8_t *byte_stream,
size_t byte_stream_size, int codepage, libuna_error_t **error);
Ok so now we're in the UTF-7 neighborhood, bestie, and it's the exact same little squad of four you already know β size, copy, with_index_copy, compare β just pointing at a UTF-7 stream instead. Iconic consistency, honestly π
int
libuna_utf8_string_size_from_utf7_stream(const uint8_t *utf7_stream,
size_t utf7_stream_size, size_t *utf8_string_size,
libuna_error_t **error);
int
libuna_utf8_string_copy_from_utf7_stream(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, const uint8_t *utf7_stream,
size_t utf7_stream_size, libuna_error_t **error);
int
libuna_utf8_string_with_index_copy_from_utf7_stream(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, size_t *utf8_string_index,
const uint8_t *utf7_stream, size_t utf7_stream_size,
libuna_error_t **error);
int
libuna_utf8_string_compare_with_utf7_stream(const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, const uint8_t *utf7_stream,
size_t utf7_stream_size, libuna_error_t **error);
Then we hit UTF-8 β UTF-8, which lowkey sounds like doing nothing but it fr fr is not the same thing β a stream is not a string, ok? π¦ Same four moves:
int
libuna_utf8_string_size_from_utf8_stream(const uint8_t *utf8_stream,
size_t utf8_stream_size, size_t *utf8_string_size,
libuna_error_t **error);
int
libuna_utf8_string_copy_from_utf8_stream(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, const uint8_t *utf8_stream,
size_t utf8_stream_size, libuna_error_t **error);
int
libuna_utf8_string_with_index_copy_from_utf8_stream(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, size_t *utf8_string_index,
const uint8_t *utf8_stream, size_t utf8_stream_size,
libuna_error_t **error);
int
libuna_utf8_string_compare_with_utf8_stream(const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, const uint8_t *utf8_stream,
size_t utf8_stream_size, libuna_error_t **error);
And now UTF-16 β UTF-8, where the input is a real libuna_utf16_character_t string, no byte order shenanigans in sight:
int
libuna_utf8_string_size_from_utf16(const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf8_string_size,
libuna_error_t **error);
int
libuna_utf8_string_copy_from_utf16(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size,
const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, libuna_error_t **error);
int
libuna_utf8_string_with_index_copy_from_utf16(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, size_t *utf8_string_index,
const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, libuna_error_t **error);
int
libuna_utf8_string_compare_with_utf16(const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size,
const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, libuna_error_t **error);
β¨ Now with the stream version of UTF-16 the flavour changes, because a raw UTF-16 stream could be either endianness β so yes, byte_order shows up in all four signatures. Do not forget it, bestie, it's literally in every single one π«Ά
int
libuna_utf8_string_size_from_utf16_stream(const uint8_t *utf16_stream,
size_t utf16_stream_size, int byte_order, size_t *utf8_string_size,
libuna_error_t **error);
int
libuna_utf8_string_copy_from_utf16_stream(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, const uint8_t *utf16_stream,
size_t utf16_stream_size, int byte_order, libuna_error_t **error);
int
libuna_utf8_string_with_index_copy_from_utf16_stream(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, size_t *utf8_string_index,
const uint8_t *utf16_stream, size_t utf16_stream_size,
int byte_order, libuna_error_t **error);
int
libuna_utf8_string_compare_with_utf16_stream(const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, const uint8_t *utf16_stream,
size_t utf16_stream_size, int byte_order, libuna_error_t **error);
UTF-32 string version, no byte_order (string, not stream, remember that vibe check π₯):
int
libuna_utf8_string_size_from_utf32(const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf8_string_size,
libuna_error_t **error);
int
libuna_utf8_string_copy_from_utf32(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size,
const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, libuna_error_t **error);
int
libuna_utf8_string_with_index_copy_from_utf32(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, size_t *utf8_string_index,
const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, libuna_error_t **error);
int
libuna_utf8_string_compare_with_utf32(const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size,
const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, libuna_error_t **error);
UTF-32 stream version β byte_order is back in the building, all four of them, no exceptions π
int
libuna_utf8_string_size_from_utf32_stream(const uint8_t *utf32_stream,
size_t utf32_stream_size, int byte_order, size_t *utf8_string_size,
libuna_error_t **error);
int
libuna_utf8_string_copy_from_utf32_stream(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, const uint8_t *utf32_stream,
size_t utf32_stream_size, int byte_order, libuna_error_t **error);
int
libuna_utf8_string_with_index_copy_from_utf32_stream(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, size_t *utf8_string_index,
const uint8_t *utf32_stream, size_t utf32_stream_size,
int byte_order, libuna_error_t **error);
int
libuna_utf8_string_compare_with_utf32_stream(const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, const uint8_t *utf32_stream,
size_t utf32_stream_size, int byte_order, libuna_error_t **error);
And the last UTF-8 group of this stretch: SCSU π§ (yes it's a real encoding, no I will not be taking questions). Notice it's only the three β size, copy, with_index_copy. There's no compare_with_scsu_stream in the list, so don't go looking for one, bestie, that's not on the menu π
int
libuna_utf8_string_size_from_scsu_stream(const uint8_t *scsu_stream,
size_t scsu_stream_size, size_t *utf8_string_size,
libuna_error_t **error);
int
libuna_utf8_string_copy_from_scsu_stream(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, const uint8_t *scsu_stream,
size_t scsu_stream_size, libuna_error_t **error);
int
libuna_utf8_string_with_index_copy_from_scsu_stream(libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, size_t *utf8_string_index,
const uint8_t *scsu_stream, size_t scsu_stream_size,
libuna_error_t **error);
π¦ UTF-16 stream functions π¦
New section, new me, new streams. Ok so first up there's this little icon β it writes a byte order mark into your UTF-16 stream for you π
int
libuna_utf16_stream_copy_byte_order_mark(uint8_t *utf16_stream,
size_t utf16_stream_size, size_t *utf16_stream_index,
int byte_order, libuna_error_t **error);
Then the classic two-piece combo for getting a UTF-16 stream out of other things: one call tells you how big the stream needs to be, the next one actually fills it. From a UTF-8 string:
int
libuna_utf16_stream_size_from_utf8(const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, size_t *utf16_stream_size,
libuna_error_t **error);
int
libuna_utf16_stream_copy_from_utf8(uint8_t *utf16_stream,
size_t utf16_stream_size, int byte_order,
const libuna_utf8_character_t *utf8_string, size_t utf8_string_size,
libuna_error_t **error);
From a UTF-16 string (again: string β stream, not a no-op, promise πΈ):
int
libuna_utf16_stream_size_from_utf16(const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf16_stream_size,
libuna_error_t **error);
int
libuna_utf16_stream_copy_from_utf16(uint8_t *utf16_stream,
size_t utf16_stream_size, int byte_order,
const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, libuna_error_t **error);
And from a UTF-32 string, same deal, byte_order present in both:
int
libuna_utf16_stream_size_from_utf32(const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf16_stream_size,
libuna_error_t **error);
int
libuna_utf16_stream_copy_from_utf32(uint8_t *utf16_stream,
size_t utf16_stream_size, int byte_order,
const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, libuna_error_t **error);
π UTF-16 string functions π
Back to strings bestie, and it's the byte stream quartet first β size, copy, with_index_copy, compare β all taking that codepage argument because a raw byte stream doesn't know what it is until you tell it π
int
libuna_utf16_string_size_from_byte_stream(const uint8_t *byte_stream,
size_t byte_stream_size, int codepage, size_t *utf16_string_size,
libuna_error_t **error);
int
libuna_utf16_string_copy_from_byte_stream(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, const uint8_t *byte_stream,
size_t byte_stream_size, int codepage, libuna_error_t **error);
int
libuna_utf16_string_with_index_copy_from_byte_stream(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf16_string_index,
const uint8_t *byte_stream, size_t byte_stream_size, int codepage,
libuna_error_t **error);
int
libuna_utf16_string_compare_with_byte_stream(const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, const uint8_t *byte_stream,
size_t byte_stream_size, int codepage, libuna_error_t **error);
UTF-7 stream in, UTF-16 string out β all four, and no byte_order because UTF-7 is a byte-level thing, not a wide-char stream, iykyk β
int
libuna_utf16_string_size_from_utf7_stream(const uint8_t *utf7_stream,
size_t utf7_stream_size, size_t *utf16_string_size,
libuna_error_t **error);
int
libuna_utf16_string_copy_from_utf7_stream(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, const uint8_t *utf7_stream,
size_t utf7_stream_size, libuna_error_t **error);
int
libuna_utf16_string_with_index_copy_from_utf7_stream(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf16_string_index,
const uint8_t *utf7_stream, size_t utf7_stream_size,
libuna_error_t **error);
int
libuna_utf16_string_compare_with_utf7_stream(const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, const uint8_t *utf7_stream,
size_t utf7_stream_size, libuna_error_t **error);
UTF-8 string β UTF-16 string. Careful here ngl, this group is only three functions β size, copy, with_index_copy. There is no compare_with_utf8 in this block, ok? Don't invent one π
int
libuna_utf16_string_size_from_utf8(const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, size_t *utf16_string_size,
libuna_error_t **error);
int
libuna_utf16_string_copy_from_utf8(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size,
const libuna_utf8_character_t *utf8_string, size_t utf8_string_size,
libuna_error_t **error);
int
libuna_utf16_string_with_index_copy_from_utf8(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf16_string_index,
const libuna_utf8_character_t *utf8_string, size_t utf8_string_size,
libuna_error_t **error);
And finally the UTF-8 stream β UTF-16 string trio, also just three, also no compare. Look at you, still reading. Queen behaviour honestly ππ
int
libuna_utf16_string_size_from_utf8_stream(const uint8_t *utf8_stream,
size_t utf8_stream_size, size_t *utf16_string_size,
libuna_error_t **error);
int
libuna_utf16_string_copy_from_utf8_stream(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, const uint8_t *utf8_stream,
size_t utf8_stream_size, libuna_error_t **error);
int
libuna_utf16_string_with_index_copy_from_utf8_stream(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf16_string_index,
const uint8_t *utf8_stream, size_t utf8_stream_size,
libuna_error_t **error);
And that's where this stretch lands β the prototypes keep going, so don't wander off yet π¦
...and we're still deep in UTF-16 territory, bestie, no escape yet π these are the compare-and-convert girlies that take a UTF-16 string and hold it up against literally everything else:
int
libuna_utf16_string_compare_with_utf8_stream(const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, const uint8_t *utf8_stream,
size_t utf8_stream_size, libuna_error_t **error);
int
libuna_utf16_string_size_from_utf16_stream(const uint8_t *utf16_stream,
size_t utf16_stream_size, int byte_order, size_t *utf16_string_size,
libuna_error_t **error);
int
libuna_utf16_string_copy_from_utf16_stream(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, const uint8_t *utf16_stream,
size_t utf16_stream_size, int byte_order, libuna_error_t **error);
int
libuna_utf16_string_with_index_copy_from_utf16_stream(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf16_string_index,
const uint8_t *utf16_stream, size_t utf16_stream_size,
int byte_order, libuna_error_t **error);
int
libuna_utf16_string_compare_with_utf16_stream(const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, const uint8_t *utf16_stream,
size_t utf16_stream_size, int byte_order, libuna_error_t **error);
Ngl the utf16_string β utf16_stream glow-up is so real β same letters, whole different vibe. Note that every single stream-flavoured one of these carries a byte_order argument, because endianness is that one friend who always shows up uninvited π
Then UTF-32 rolls in and it's giving "we have main character energy too":
int
libuna_utf16_string_size_from_utf32(const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf16_string_size,
libuna_error_t **error);
int
libuna_utf16_string_copy_from_utf32(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size,
const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, libuna_error_t **error);
int
libuna_utf16_string_with_index_copy_from_utf32(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf16_string_index,
const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, libuna_error_t **error);
int
libuna_utf16_string_compare_with_utf32(const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size,
const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, libuna_error_t **error);
int
libuna_utf16_string_size_from_utf32_stream(const uint8_t *utf32_stream,
size_t utf32_stream_size, int byte_order, size_t *utf16_string_size,
libuna_error_t **error);
int
libuna_utf16_string_copy_from_utf32_stream(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, const uint8_t *utf32_stream,
size_t utf32_stream_size, int byte_order, libuna_error_t **error);
int
libuna_utf16_string_with_index_copy_from_utf32_stream(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf16_string_index,
const uint8_t *utf32_stream, size_t utf32_stream_size,
int byte_order, libuna_error_t **error);
int
libuna_utf16_string_compare_with_utf32_stream(const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, const uint8_t *utf32_stream,
size_t utf32_stream_size, int byte_order, libuna_error_t **error);
The squad is literally always the same four: size_from_* tells you how much room you need, copy_from_* does the actual glow-up, with_index_copy_from_* is the same but keeps a utf16_string_index so you can keep going, and compare_with_* is the vibe check π«Ά
And closing out the UTF-16 era, SCSU slides in β iconique, misunderstood, only got the size / copy / with-index trio, no compare:
int
libuna_utf16_string_size_from_scsu_stream(const uint8_t *scsu_stream,
size_t scsu_stream_size, size_t *utf16_string_size,
libuna_error_t **error);
int
libuna_utf16_string_copy_from_scsu_stream(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, const uint8_t *scsu_stream,
size_t scsu_stream_size, libuna_error_t **error);
int
libuna_utf16_string_with_index_copy_from_scsu_stream(libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf16_string_index,
const uint8_t *scsu_stream, size_t scsu_stream_size,
libuna_error_t **error);
π UTF-32 stream functions π
Okay so now we flip it β UTF-32 going out as a raw byte stream. First up, the byte order mark plug, because somebosy has to write the β¨littleβ¨ marker:
int
libuna_utf32_stream_copy_byte_order_mark(uint8_t *utf32_stream,
size_t utf32_stream_size, size_t *utf32_stream_index,
int byte_order, libuna_error_t **error);
Then the classic size_from / copy_from duo, three whole times, once per source encoding. UTF-8 first (the people's champ):
int
libuna_utf32_stream_size_from_utf8(const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, size_t *utf32_stream_size,
libuna_error_t **error);
int
libuna_utf32_stream_copy_from_utf8(uint8_t *utf32_stream,
size_t utf32_stream_size, int byte_order,
const libuna_utf8_character_t *utf8_string, size_t utf8_string_size,
libuna_error_t **error);
Then UTF-16:
int
libuna_utf32_stream_size_from_utf16(const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf32_stream_size,
libuna_error_t **error);
int
libuna_utf32_stream_copy_from_utf16(uint8_t *utf32_stream,
size_t utf32_stream_size, int byte_order,
const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, libuna_error_t **error);
And UTF-32 β UTF-32 stream, the "copying myself but as bytes" moment π
int
libuna_utf32_stream_size_from_utf32(const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf32_stream_size,
libuna_error_t **error);
int
libuna_utf32_stream_copy_from_utf32(uint8_t *utf32_stream,
size_t utf32_stream_size, int byte_order,
const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, libuna_error_t **error);
Heads up bestie: all three copy_from girls take byte_order, so pick your endianness before you commit, fr fr.
π§ UTF-32 string functions π§
And now the BIG one. UTF-32 string functions is honestly the longest guest list at this party, so buckle up π It starts with byte streams and a codepage, because legacy encodings are still invited:
int
libuna_utf32_string_size_from_byte_stream(const uint8_t *byte_stream,
size_t byte_stream_size, int codepage, size_t *utf32_string_size,
libuna_error_t **error);
int
libuna_utf32_string_copy_from_byte_stream(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, const uint8_t *byte_stream,
size_t byte_stream_size, int codepage, libuna_error_t **error);
int
libuna_utf32_string_with_index_copy_from_byte_stream(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf32_string_index,
const uint8_t *byte_stream, size_t byte_stream_size, int codepage,
libuna_error_t **error);
int
libuna_utf32_string_compare_with_byte_stream(const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, const uint8_t *byte_stream,
size_t byte_stream_size, int codepage, libuna_error_t **error);
Full quartet here β size, copy, with-index copy, and compare. Not SCSU being left on read with only three, we see you π
Then UTF-7 shows up (yes, UTF-7 is still a thing, don't @ me) and gets the full four too:
int
libuna_utf32_string_size_from_utf7_stream(const uint8_t *utf7_stream,
size_t utf7_stream_size, size_t *utf32_string_size,
libuna_error_t **error);
int
libuna_utf32_string_copy_from_utf7_stream(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, const uint8_t *utf7_stream,
size_t utf7_stream_size, libuna_error_t **error);
int
libuna_utf32_string_with_index_copy_from_utf7_stream(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf32_string_index,
const uint8_t *utf7_stream, size_t utf7_stream_size,
libuna_error_t **error);
int
libuna_utf32_string_compare_with_utf7_stream(const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, const uint8_t *utf7_stream,
size_t utf7_stream_size, libuna_error_t **error);
UTF-8 next, and here's a plot twist β it comes in two flavours: the string kind and the stream kind. String kind first:
int
libuna_utf32_string_size_from_utf8(const libuna_utf8_character_t *utf8_string,
size_t utf8_string_size, size_t *utf32_string_size,
libuna_error_t **error);
int
libuna_utf32_string_copy_from_utf8(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size,
const libuna_utf8_character_t *utf8_string, size_t utf8_string_size,
libuna_error_t **error);
int
libuna_utf32_string_with_index_copy_from_utf8(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf32_string_index,
const libuna_utf8_character_t *utf8_string, size_t utf8_string_size,
libuna_error_t **error);
Note there's no compare_with_utf8 in there β compare only exists for the stream version. Scroll down, it's there, promise π
Stream kind (and here the output size param is literally named utf32_stream_size, not utf32_string_size β read carefully, bestie, copy-paste will betray you):
int
libuna_utf32_string_size_from_utf8_stream(const uint8_t *utf8_stream,
size_t utf8_stream_size, size_t *utf32_stream_size,
libuna_error_t **error);
int
libuna_utf32_string_copy_from_utf8_stream(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, const uint8_t *utf8_stream,
size_t utf8_stream_size, libuna_error_t **error);
int
libuna_utf32_string_with_index_copy_from_utf8_stream(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf32_string_index,
const uint8_t *utf8_stream, size_t utf8_stream_size,
libuna_error_t **error);
int
libuna_utf32_string_compare_with_utf8_stream(const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, const uint8_t *utf8_stream,
size_t utf8_stream_size, libuna_error_t **error);
UTF-16 next, same deal β string flavour:
int
libuna_utf32_string_size_from_utf16(const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, size_t *utf32_string_size,
libuna_error_t **error);
int
libuna_utf32_string_copy_from_utf16(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size,
const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, libuna_error_t **error);
int
libuna_utf32_string_with_index_copy_from_utf16(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf32_string_index,
const libuna_utf16_character_t *utf16_string,
size_t utf16_string_size, libuna_error_t **error);
...and stream flavour, this time with the byte_order cameo:
int
libuna_utf32_string_size_from_utf16_stream(const uint8_t *utf16_stream,
size_t utf16_stream_size, int byte_order, size_t *utf32_string_size,
libuna_error_t **error);
int
libuna_utf32_string_copy_from_utf16_stream(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, const uint8_t *utf16_stream,
size_t utf16_stream_size, int byte_order, libuna_error_t **error);
int
libuna_utf32_string_with_index_copy_from_utf16_stream(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf32_string_index,
const uint8_t *utf16_stream, size_t utf16_stream_size,
int byte_order, libuna_error_t **error);
int
libuna_utf32_string_compare_with_utf16_stream(const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, const uint8_t *utf16_stream,
size_t utf16_stream_size, int byte_order, libuna_error_t **error);
And finally UTF-32 stream β UTF-32 string, the full quartet one last time, byte_order included because of course it is π
int
libuna_utf32_string_size_from_utf32_stream(const uint8_t *utf32_stream,
size_t utf32_stream_size, int byte_order, size_t *utf32_string_size,
libuna_error_t **error);
int
libuna_utf32_string_copy_from_utf32_stream(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, const uint8_t *utf32_stream,
size_t utf32_stream_size, int byte_order, libuna_error_t **error);
int
libuna_utf32_string_with_index_copy_from_utf32_stream(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf32_string_index,
const uint8_t *utf32_stream, size_t utf32_stream_size,
int byte_order, libuna_error_t **error);
int
libuna_utf32_string_compare_with_utf32_stream(const libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, const uint8_t *utf32_stream,
size_t utf32_stream_size, int byte_order, libuna_error_t **error);
That's the whole prototype parade for this chunk β take a breath, hydrate, and keep scrolling because we are not done yet π
int
libuna_utf32_string_size_from_scsu_stream(const uint8_t *scsu_stream,
size_t scsu_stream_size, size_t *utf32_string_size,
libuna_error_t **error);
int
libuna_utf32_string_copy_from_scsu_stream(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, const uint8_t *scsu_stream,
size_t scsu_stream_size, libuna_error_t **error);
int
libuna_utf32_string_with_index_copy_from_scsu_stream(libuna_utf32_character_t *utf32_string,
size_t utf32_string_size, size_t *utf32_string_index,
const uint8_t *scsu_stream, size_t scsu_stream_size,
libuna_error_t **error);
π Base16 stream functions π
okay so base16 is just hex, bestie β two characters per byte, the whole "deadbeef" vibe. here's the entire squad:
int
libuna_base16_stream_size_to_byte_stream(const uint8_t *base16_stream,
size_t base16_stream_size, size_t *byte_stream_size,
uint32_t base16_variant, uint8_t flags, libuna_error_t **error);
int
libuna_base16_stream_copy_to_byte_stream(const uint8_t *base16_stream,
size_t base16_stream_size, uint8_t *byte_stream,
size_t byte_stream_size, uint32_t base16_variant, uint8_t flags,
libuna_error_t **error);
int
libuna_base16_stream_size_from_byte_stream(const uint8_t *byte_stream,
size_t byte_stream_size, size_t *base16_stream_size,
uint32_t base16_variant, libuna_error_t **error);
int
libuna_base16_stream_copy_from_byte_stream(uint8_t *base16_stream,
size_t base16_stream_size, const uint8_t *byte_stream,
size_t byte_stream_size, uint32_t base16_variant,
libuna_error_t **error);
int
libuna_base16_stream_with_index_copy_from_byte_stream(uint8_t *base16_stream,
size_t base16_stream_size, size_t *base16_stream_index,
const uint8_t *byte_stream, size_t byte_stream_size,
uint32_t base16_variant, libuna_error_t **error);
notice the pattern? _size_ to figure out how much room you need, _copy_ to actually do the thing, _with_index_ when you're appending to something already in progress and need the index tracked. that's the whole family recipe, no cap π
πΈ Base32 stream functions πΈ
base32 is the "quintuplet" girlie β five bits at a time, five characters per five bytes-ish, and yes the word quintuplet is iconic and i will not be apologizing for it. first, the low-level chunk-movers:
int
libuna_base32_quintuplet_copy_from_base32_stream(uint64_t *base32_quintuplet,
const uint8_t *base32_stream, size_t base32_stream_size,
size_t *base32_stream_index, uint8_t *padding_size,
uint32_t base32_variant, libuna_error_t **error);
int
libuna_base32_quintuplet_copy_to_base32_stream(uint64_t base32_quintuplet,
uint8_t *base32_stream, size_t base32_stream_size,
size_t *base32_stream_index, uint8_t padding_size,
uint32_t base32_variant, libuna_error_t **error);
int
libuna_base32_quintuplet_copy_from_byte_stream(uint64_t *base32_quintuplet,
const uint8_t *byte_stream, size_t byte_stream_size,
size_t *byte_stream_index, uint8_t *padding_size,
libuna_error_t **error);
int
libuna_base32_quintuplet_copy_to_byte_stream(uint64_t base32_quintuplet,
uint8_t *byte_stream, size_t byte_stream_size,
size_t *byte_stream_index, uint8_t padding_size,
libuna_error_t **error);
and then the stream-level glow-ups that use them:
int
libuna_base32_stream_size_to_byte_stream(const uint8_t *base32_stream,
size_t base32_stream_size, size_t *byte_stream_size,
uint32_t base32_variant, uint8_t flags, libuna_error_t **error);
int
libuna_base32_stream_copy_to_byte_stream(const uint8_t *base32_stream,
size_t base32_stream_size, uint8_t *byte_stream,
size_t byte_stream_size, uint32_t base32_variant, uint8_t flags,
libuna_error_t **error);
int
libuna_base32_stream_size_from_byte_stream(const uint8_t *byte_stream,
size_t byte_stream_size, size_t *base32_stream_size,
uint32_t base32_variant, libuna_error_t **error);
int
libuna_base32_stream_copy_from_byte_stream(uint8_t *base32_stream,
size_t base32_stream_size, const uint8_t *byte_stream,
size_t byte_stream_size, uint32_t base32_variant,
libuna_error_t **error);
int
libuna_base32_stream_with_index_copy_from_byte_stream(uint8_t *base32_stream,
size_t base32_stream_size, size_t *base32_stream_index,
const uint8_t *byte_stream, size_t byte_stream_size,
uint32_t base32_variant, libuna_error_t **error);
π Base64 stream functions π
and the main character herself: base64, triplets, the one everybody actually knows. three bytes β four characters, padding_size handling the leftovers, base64_variant deciding which alphabet we're serving tonight. low-level first:
int
libuna_base64_triplet_copy_from_base64_stream(uint32_t *base64_triplet,
const uint8_t *base64_stream, size_t base64_stream_size,
size_t *base64_stream_index, uint8_t *padding_size,
uint32_t base64_variant, libuna_error_t **error);
int
libuna_base64_triplet_copy_to_base64_stream(uint32_t base64_triplet,
uint8_t *base64_stream, size_t base64_stream_size,
size_t *base64_stream_index, uint8_t padding_size,
uint32_t base64_variant, libuna_error_t **error);
int
libuna_base64_triplet_copy_from_byte_stream(uint32_t *base64_triplet,
const uint8_t *byte_stream, size_t byte_stream_size,
size_t *byte_stream_index, uint8_t *padding_size,
libuna_error_t **error);
int
libuna_base64_triplet_copy_to_byte_stream(uint32_t base64_triplet,
uint8_t *byte_stream, size_t byte_stream_size,
size_t *byte_stream_index, uint8_t padding_size,
libuna_error_t **error);
and the stream-level ones, same recipe as her sisters:
int
libuna_base64_stream_size_to_byte_stream(const uint8_t *base64_stream,
size_t base64_stream_size, size_t *byte_stream_size,
uint32_t base64_variant, uint8_t flags, libuna_error_t **error);
int
libuna_base64_stream_copy_to_byte_stream(const uint8_t *base64_stream,
size_t base64_stream_size, uint8_t *byte_stream,
size_t byte_stream_size, uint32_t base64_variant, uint8_t flags,
libuna_error_t **error);
int
libuna_base64_stream_size_from_byte_stream(const uint8_t *byte_stream,
size_t byte_stream_size, size_t *base64_stream_size,
uint32_t base64_variant, libuna_error_t **error);
int
libuna_base64_stream_copy_from_byte_stream(uint8_t *base64_stream,
size_t base64_stream_size, const uint8_t *byte_stream,
size_t byte_stream_size, uint32_t base64_variant,
libuna_error_t **error);
int
libuna_base64_stream_with_index_copy_from_byte_stream(uint8_t *base64_stream,
size_t base64_stream_size, size_t *base64_stream_index,
const uint8_t *byte_stream, size_t byte_stream_size,
uint32_t base64_variant, libuna_error_t **error);
β¨ DESCRIPTION β¨
okay so the actual prose part, and it's short and sweet: the libuna_get_version() function is what you call to retrieve the library version. that's it. that's the description. she's lowkey humble π«Ά
π RETURN VALUES π
most of the functions return NULL or -1 on error, dependent on the return type. so like, don't assume it's always the same failure value β check your actual return type, bestie.
for the actual return values, see "libuna.h". that's the source of truth, periodt.
π¦ ENVIRONMENT π¦
None
like, literally none. no environment variables, nothing to export, go touch grass π±
π FILES π
None
no config files, no dotfiles to babysit. iconic behaviour honestly.
π BUGS π
please report bugs of any kind on the project issue tracker:
https://github.com/libyal/libuna/issues
any kind, fr fr β don't be shy, don't gaslight yourself into thinking it's your fault π
π AUTHOR π
these man pages are generated from "libuna.h". so like, the header is the author, technically. respect the source of truth β¨
π COPYRIGHT π
Copyright (C) 2008-2024, Joachim Metz <joachim.metz@gmail.com>.
This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
read that warranty part again, bestie. NO warranty. not even for MERCHANTABILITY. not even for FITNESS FOR A PARTICULAR PURPOSE. she said what she said π
π SEE ALSO π
- the
libuna.hinclude file
that's the whole see-also list. one entry. main character energy π
and that's a wrap on libuna(3)! this page is from the libuna crew, dated July 2, 2023, and it lives in section 3 of the manual. go forth, convert your encodings, and stay hydrated ππ
π¦ where this page comes from
- opensuse-leap 16.0: libuna-devel 20240414-bp160.1.12 Β· LGPL-3.0-or-later
- opensuse-leap 16.0: libuna-devel 20240414-bp160.1.12 Β· LGPL-3.0-or-later
- opensuse-leap 16.0: libuna-devel 20240414-bp160.1.12 Β· LGPL-3.0-or-later
- opensuse-leap 16.0: libuna-devel 20240414-bp160.1.12 Β· LGPL-3.0-or-later
- opensuse-leap 16.0: libuna-mini-devel 20240414-bp160.1.10 Β· LGPL-3.0-or-later
- opensuse-leap 16.0: libuna-mini-devel 20240414-bp160.1.10 Β· LGPL-3.0-or-later
- opensuse-leap 16.0: libuna-mini-devel 20240414-bp160.1.10 Β· LGPL-3.0-or-later
- opensuse-leap 16.0: libuna-mini-devel 20240414-bp160.1.10 Β· LGPL-3.0-or-later
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms