libfvalue(3)

okay bestie, sit down, hydrate, and get your reading glasses on 👓 because we're doing libfvalue(3) — straight out of the Library Functions Manual — and it is long. Like, "three-parter long" 💀 this is part 1, so no, we're not finishing today, we're just getting comfy. It's the man page for libfvalue.h, a whole library whose entire personality is "support various format value types" ✨ it's giving toolbox, it's giving "I have a function for literally everything", and honestly? iconic.

---

🌸 NAME 🌸

libfvalue.h — the library that supports all your various format value types 💖 no cap, that's the whole job description.

✨ SYNOPSIS ✨

okay so first things first, you gotta invite it in:

#include <libfvalue.h>

aaand then we have what can only be described as a lot of functions. Buckle up buttercup 🎀 we're going group by group, and every single signature is here exactly as it lives.

🫶 Support functions 🫶

just the one, a little solo moment, and honestly she ate:

const char *
libfvalue_get_version(void);

💅 Error functions 💅

the error squad ✨ notice how libfvalue_error_free is the only one returning void — she doesn't report back, she just does the thing 😌 the rest hand you back an int and take either a FILE *stream (for fprint vibes) or a char *string + size_t size (for sprint vibes). And yes, there's a whole backtrace pair for when you need the receipts:

void
libfvalue_error_free(libfvalue_error_t **error);

int
libfvalue_error_fprint(libfvalue_error_t *error, FILE *stream);

int
libfvalue_error_sprint(libfvalue_error_t *error, char *string,
    size_t size);

int
libfvalue_error_backtrace_fprint(libfvalue_error_t *error,
    FILE *stream);

int
libfvalue_error_backtrace_sprint(libfvalue_error_t *error, char *string,
    size_t size);

🦋 Data handle functions 🦋

the data handle girlies are thriving, there's like a dozen of them 🧚 they initialize, free, clone, clear, get and set data, get and set data flags, and then get really into value entries — counting them, grabbing one by index, setting one by index, appending one by index. also, huge shoutout to libfvalue_data_handle_initialize, which makes you hand over a whole read_value_entries callback with its own entire signature. keep that callback exactly like this, bestie, no creative edits 💀

int
libfvalue_data_handle_initialize(libfvalue_data_handle_t **data_handle,
    int (*read_value_entries)( libfvalue_data_handle_t *data_handle, const uint8_t *data, size_t data_size, int encoding, uint32_t data_flags, libfvalue_error_t **error ),
    libfvalue_error_t **error);

int
libfvalue_data_handle_free(libfvalue_data_handle_t **data_handle,
    libfvalue_error_t **error);

int
libfvalue_data_handle_clone(libfvalue_data_handle_t **destination_data_handle,
    libfvalue_data_handle_t *source_data_handle,
    libfvalue_error_t **error);

int
libfvalue_data_handle_clear(libfvalue_data_handle_t *data_handle,
    libfvalue_error_t **error);

int
libfvalue_data_handle_get_data(libfvalue_data_handle_t *data_handle,
    uint8_t **data, size_t *data_size, int *encoding,
    libfvalue_error_t **error);

int
libfvalue_data_handle_set_data(libfvalue_data_handle_t *data_handle,
    const uint8_t *data, size_t data_size, int encoding, uint8_t flags,
    libfvalue_error_t **error);

int
libfvalue_data_handle_get_data_flags(libfvalue_data_handle_t *data_handle,
    uint32_t *data_flags, libfvalue_error_t **error);

int
libfvalue_data_handle_set_data_flags(libfvalue_data_handle_t *data_handle,
    uint32_t data_flags, libfvalue_error_t **error);

int
libfvalue_data_handle_get_number_of_value_entries(libfvalue_data_handle_t *data_handle,
    int *number_of_value_entries, libfvalue_error_t **error);

int
libfvalue_data_handle_get_value_entry_data(libfvalue_data_handle_t *data_handle,
    int value_entry_index, uint8_t **value_entry_data,
    size_t *value_entry_data_size, int *encoding,
    libfvalue_error_t **error);

int
libfvalue_data_handle_set_value_entry_data(libfvalue_data_handle_t *data_handle,
    int value_entry_index, const uint8_t *value_entry_data,
    size_t value_entry_data_size, int encoding,
    libfvalue_error_t **error);

int
libfvalue_data_handle_append_value_entry_data(libfvalue_data_handle_t *data_handle,
    int *value_entry_index, const uint8_t *value_entry_data,
    size_t value_entry_data_size, int encoding,
    libfvalue_error_t **error);

ngl, that uint8_t flags in set_data vs the uint32_t data_flags in the flags getter/setter is right there in the original and we are simply observing it respectfully 👀 don't come for me, I just report the lore.

🔥 Integer functions 🔥

the integer girlies said "we contain multitudes" and then dropped thirteen functions that are basically the same bit of business three times over — once for utf8, once for utf16, once for utf32 — each with a copy_from_integer and a copy_to_integer, plus a with_index flavoured version of each. and before any of that, there's libfvalue_string_size_from_integer so you can ask how much room you need before you start writing. so considerate 💜

every one of them takes string_format_flags and, obviously, the trailing libfvalue_error_t **error:

int
libfvalue_string_size_from_integer(size_t *string_size,
    uint64_t integer_value, size_t integer_value_size,
    uint32_t string_format_flags, libfvalue_error_t **error);

int
libfvalue_utf8_string_copy_from_integer(uint8_t *utf8_string,
    size_t utf8_string_size, uint64_t integer_value,
    size_t integer_value_size, uint32_t string_format_flags,
    libfvalue_error_t **error);

int
libfvalue_utf8_string_with_index_copy_from_integer(uint8_t *utf8_string,
    size_t utf8_string_size, size_t *utf8_string_index,
    uint64_t integer_value, size_t integer_value_size,
    uint32_t string_format_flags, libfvalue_error_t **error);

int
libfvalue_utf8_string_copy_to_integer(const uint8_t *utf8_string,
    size_t utf8_string_length, uint64_t *integer_value,
    size_t integer_value_size, uint32_t string_format_flags,
    libfvalue_error_t **error);

int
libfvalue_utf8_string_with_index_copy_to_integer(const uint8_t *utf8_string,
    size_t utf8_string_length, size_t *utf8_string_index,
    uint64_t *integer_value, size_t integer_value_size,
    uint32_t string_format_flags, libfvalue_error_t **error);

int
libfvalue_utf16_string_copy_from_integer(uint16_t *utf16_string,
    size_t utf16_string_size, uint64_t integer_value,
    size_t integer_value_size, uint32_t string_format_flags,
    libfvalue_error_t **error);

int
libfvalue_utf16_string_with_index_copy_from_integer(uint16_t *utf16_string,
    size_t utf16_string_size, size_t *utf16_string_index,
    uint64_t integer_value, size_t integer_value_size,
    uint32_t string_format_flags, libfvalue_error_t **error);

int
libfvalue_utf16_string_copy_to_integer(const uint16_t *utf16_string,
    size_t utf16_string_length, uint64_t *integer_value,
    size_t integer_value_size, uint32_t string_format_flags,
    libfvalue_error_t **error);

int
libfvalue_utf16_string_with_index_copy_to_integer(const uint16_t *utf16_string,
    size_t utf16_string_length, size_t *utf16_string_index,
    uint64_t *integer_value, size_t integer_value_size,
    uint32_t string_format_flags, libfvalue_error_t **error);

int
libfvalue_utf32_string_copy_from_integer(uint32_t *utf32_string,
    size_t utf32_string_size, uint64_t integer_value,
    size_t integer_value_size, uint32_t string_format_flags,
    libfvalue_error_t **error);

int
libfvalue_utf32_string_with_index_copy_from_integer(uint32_t *utf32_string,
    size_t utf32_string_size, size_t *utf32_string_index,
    uint64_t integer_value, size_t integer_value_size,
    uint32_t string_format_flags, libfvalue_error_t **error);

int
libfvalue_utf32_string_copy_to_integer(const uint32_t *utf32_string,
    size_t utf32_string_length, uint64_t *integer_value,
    size_t integer_value_size, uint32_t string_format_flags,
    libfvalue_error_t **error);

int
libfvalue_utf32_string_with_index_copy_to_integer(const uint32_t *utf32_string,
    size_t utf32_string_length, size_t *utf32_string_index,
    uint64_t *integer_value, size_t integer_value_size,
    uint32_t string_format_flags, libfvalue_error_t **error);

---

🌈 UTF-8 string functions 🌈

one function, one job, and she's the setup for the next whole group: you give her a string, a size, and a uint8_t delimiter, and she hands back a libfvalue_split_utf8_string_t **split_string. main character energy fr fr ⭐

int
libfvalue_utf8_string_split(const uint8_t *utf8_string,
    size_t utf8_string_size, uint8_t delimiter,
    libfvalue_split_utf8_string_t **split_string,
    libfvalue_error_t **error);

🎀 Split UTF-8 string functions 🎀

the results of that split are their own whole little ecosystem 🍓 you can free the split string, get the whole original string back out of it, count the segments, and get or set a segment by its index:

int
libfvalue_split_utf8_string_free(libfvalue_split_utf8_string_t **split_string,
    libfvalue_error_t **error);

int
libfvalue_split_utf8_string_get_string(libfvalue_split_utf8_string_t *split_string,
    uint8_t **utf8_string, size_t *utf8_string_size,
    libfvalue_error_t **error);

int
libfvalue_split_utf8_string_get_number_of_segments(libfvalue_split_utf8_string_t *split_string,
    int *number_of_segments, libfvalue_error_t **error);

int
libfvalue_split_utf8_string_get_segment_by_index(libfvalue_split_utf8_string_t *split_string,
    int segment_index, uint8_t **utf8_string_segment,
    size_t *utf8_string_segment_size, libfvalue_error_t **error);

int
libfvalue_split_utf8_string_set_segment_by_index(libfvalue_split_utf8_string_t *split_string,
    int segment_index, uint8_t *utf8_string_segment,
    size_t utf8_string_segment_size, libfvalue_error_t **error);

---

🦋 UTF-16 string functions 🦋

same energy, different width 💖 now it's uint16_t, and the delimiter is a uint16_t delimiter too, and the split string type is libfvalue_split_utf16_string_t. consistent queen:

int
libfvalue_utf16_string_split(const uint16_t *utf16_string,
    size_t utf16_string_size, uint16_t delimiter,
    libfvalue_split_utf16_string_t **split_string,
    libfvalue_error_t **error);

🌸 Split UTF-16 string functions 🌸

and the matching five, word for word the UTF-8 pattern but with utf16 all over it — free, get_string, get_number_of_segments, get_segment_by_index, set_segment_by_index:

int
libfvalue_split_utf16_string_free(libfvalue_split_utf16_string_t **split_string,
    libfvalue_error_t **error);

int
libfvalue_split_utf16_string_get_string(libfvalue_split_utf16_string_t *split_string,
    uint16_t **utf16_string, size_t *utf16_string_size,
    libfvalue_error_t **error);

int
libfvalue_split_utf16_string_get_number_of_segments(libfvalue_split_utf16_string_t *split_string,
    int *number_of_segments, libfvalue_error_t **error);

int
libfvalue_split_utf16_string_get_segment_by_index(libfvalue_split_utf16_string_t *split_string,
    int segment_index, uint16_t **utf16_string_segment,
    size_t *utf16_string_segment_size, libfvalue_error_t **error);

int
libfvalue_split_utf16_string_set_segment_by_index(libfvalue_split_utf16_string_t *split_string,
    int segment_index, uint16_t *utf16_string_segment,
    size_t utf16_string_segment_size, libfvalue_error_t **error);

---

👑 Table functions 👑

okay this group is huge and honestly serving main character energy 👑 tables get initialized with number_of_values, freed, emptied, resized, cloned, and asked how many values they've got. then the identifier girlies show up: libfvalue_table_get_index_by_identifier and libfvalue_table_get_value_by_identifier both take an identifier + identifier_size + a uint8_t flags, while the index versions (get_value_by_index, set_value_by_index) just take an int value_index. then there's plain libfvalue_table_set_value, and finally libfvalue_table_copy_from_utf8_xml_string, which takes the string plus a table_name + table_name_length 🧚 cute.

int
libfvalue_table_initialize(libfvalue_table_t **table,
    int number_of_values, libfvalue_error_t **error);

int
libfvalue_table_free(libfvalue_table_t **table,
    libfvalue_error_t **error);

int
libfvalue_table_empty(libfvalue_table_t *table,
    libfvalue_error_t **error);

int
libfvalue_table_resize(libfvalue_table_t *table, int number_of_values,
    libfvalue_error_t **error);

int
libfvalue_table_clone(libfvalue_table_t **destination_table,
    libfvalue_table_t *source_table, libfvalue_error_t **error);

int
libfvalue_table_get_number_of_values(libfvalue_table_t *table,
    int *number_of_values, libfvalue_error_t **error);

int
libfvalue_table_get_index_by_identifier(libfvalue_table_t *table,
    const uint8_t *identifier, size_t identifier_size, int *value_index,
    uint8_t flags, libfvalue_error_t **error);

int
libfvalue_table_get_value_by_index(libfvalue_table_t *table,
    int value_index, libfvalue_value_t **value,
    libfvalue_error_t **error);

int
libfvalue_table_get_value_by_identifier(libfvalue_table_t *table,
    const uint8_t *identifier, size_t identifier_size,
    libfvalue_value_t **value, uint8_t flags,
    libfvalue_error_t **error);

int
libfvalue_table_set_value_by_index(libfvalue_table_t *table,
    int value_index, libfvalue_value_t *value,
    libfvalue_error_t **error);

int
libfvalue_table_set_value(libfvalue_table_t *table,
    libfvalue_value_t *value, libfvalue_error_t **error);

int
libfvalue_table_copy_from_utf8_xml_string(libfvalue_table_t *table,
    const uint8_t *utf8_string, size_t utf8_string_size,
    const uint8_t *table_name, size_t table_name_length,
    libfvalue_error_t **error);

---

💜 Value functions 💜

…and that's exactly where part 1 ✨dips✨ — the value girls are up next and they get their own whole section, so hold that thought, bestie, part 2 picks it right back up 🫶💖

Okay so the SYNOPSIS keeps going and honestly? It's giving encore. Bestie, buckle up, because libfvalue_value has a lot of functions and every single one of them is about to be listed in full 💅

---

First up, the big one. The main character. The one with more callback pointers than your fyp has edits:

int
libfvalue_value_initialize(libfvalue_value_t **value,
    const char *type_string, const char *type_description,
    libfvalue_data_handle_t *data_handle,
    int (*initialize_instance)( intptr_t **instance, libfvalue_error_t **error ),
    int (*free_instance)( intptr_t **instance, libfvalue_error_t **error ),
    int (*clone_instance)( intptr_t **destination_instance, intptr_t *source_instance, libfvalue_error_t **error ),
    int (*copy_from_byte_stream)( intptr_t *instance, const uint8_t *byte_stream, size_t byte_stream_size, int encoding, libfvalue_error_t **error ),
    int (*copy_to_byte_stream)( intptr_t *instance, uint8_t *byte_stream, size_t byte_stream_size, int encoding, libfvalue_error_t **error ),
    int (*copy_from_integer)( intptr_t *instance, uint64_t integer_value, size_t integer_value_size, libfvalue_error_t **error ),
    int (*copy_to_integer)( intptr_t *instance, uint64_t *integer_value, size_t *integer_value_size, libfvalue_error_t **error ),
    int (*copy_from_floating_point)( intptr_t *instance, double floating_point_value, size_t floating_point_value_size, libfvalue_error_t **error ),
    int (*copy_to_floating_point)( intptr_t *instance, double *floating_point_value, size_t *floating_point_value_size, libfvalue_error_t **error ),
    int (*copy_from_utf8_string_with_index)( intptr_t *instance, const uint8_t *utf8_string, size_t utf8_string_length, size_t *utf8_string_index, uint32_t string_format_flags, libfvalue_error_t **error ),
    int (*get_utf8_string_size)( intptr_t *instance, size_t *utf8_string_size, uint32_t string_format_flags, libfvalue_error_t **error ),
    int (*copy_to_utf8_string_with_index)( intptr_t *instance, uint8_t *utf8_string, size_t utf8_string_size, size_t *utf8_string_index, uint32_t string_format_flags, libfvalue_error_t **error ),
    int (*copy_from_utf16_string_with_index)( intptr_t *instance, const uint16_t *utf16_string, size_t utf16_string_length, size_t *utf16_string_index, uint32_t string_format_flags, libfvalue_error_t **error ),
    int (*get_utf16_string_size)( intptr_t *instance, size_t *utf16_string_size, uint32_t string_format_flags, libfvalue_error_t **error ),
    int (*copy_to_utf16_string_with_index)( intptr_t *instance, uint16_t *utf16_string, size_t utf16_string_size, size_t *utf16_string_index, uint32_t string_format_flags, libfvalue_error_t **error ),
    int (*copy_from_utf32_string_with_index)( intptr_t *instance, const uint32_t *utf32_string, size_t utf32_string_length, size_t *utf32_string_index, uint32_t string_format_flags, libfvalue_error_t **error ),
    int (*get_utf32_string_size)( intptr_t *instance, size_t *utf32_string_size, uint32_t string_format_flags, libfvalue_error_t **error ),
    int (*copy_to_utf32_string_with_index)( intptr_t *instance, uint32_t *utf32_string, size_t utf32_string_size, size_t *utf32_string_index, uint32_t string_format_flags, libfvalue_error_t **error ),
    uint8_t flags, libfvalue_error_t **error);

Not me counting the callbacks like it's a stan list. Like, breathe for a sec and look at what's in there — you've got initialize_instance, free_instance, clone_instance living their little lifecycle moment, then copy_from_byte_stream / copy_to_byte_stream, then copy_from_integer / copy_to_integer, then copy_from_floating_point / copy_to_floating_point, and then the utf trio — utf8, utf16, utf32 — each one serving copy_from_..._with_index, get_..._size and copy_to_..._with_index with their string_format_flags in hand ✨ And every single one of them ends in libfvalue_error_t **error. Every. Single. One. Consistency is such a slay.

---

Now the sensible little housekeeping crew 🎀

int
libfvalue_value_free(libfvalue_value_t **value,
    libfvalue_error_t **error);

int
libfvalue_value_clone(libfvalue_value_t **destination_value,
    libfvalue_value_t *source_value, libfvalue_error_t **error);

int
libfvalue_value_clear(libfvalue_value_t *value,
    libfvalue_error_t **error);

free, clone, clear — the holy trinity of "girl, clean up after yourself". Note that clone takes a destination_value and a source_value, because copying isn't just vibes, it needs both halves.

---

Then the identity era 💖 who am I, what am I, what do I carry:

int
libfvalue_value_get_type(libfvalue_value_t *value, int *value_type,
    libfvalue_error_t **error);

int
libfvalue_value_get_identifier(libfvalue_value_t *value,
    uint8_t **identifier, size_t *identifier_size,
    libfvalue_error_t **error);

int
libfvalue_value_set_identifier(libfvalue_value_t *value,
    const uint8_t *identifier, size_t identifier_size, uint8_t flags,
    libfvalue_error_t **error);

get_type hands you back an int *value_type. get_identifier and set_identifier are the classic duo — and heads up, set_identifier takes an extra uint8_t flags, so it's got range 🙈

---

The data-flags-and-bytes section, aka the ✨main event✨ of this whole API:

int
libfvalue_value_get_data_flags(libfvalue_value_t *value,
    uint32_t *data_flags, libfvalue_error_t **error);

int
libfvalue_value_set_data_flags(libfvalue_value_t *value,
    uint32_t data_flags, libfvalue_error_t **error);

int
libfvalue_value_has_data(libfvalue_value_t *value,
    libfvalue_error_t **error);

int
libfvalue_value_initialize_data(libfvalue_value_t *value,
    size_t data_size, libfvalue_error_t **error);

int
libfvalue_value_get_data_size(libfvalue_value_t *value,
    size_t *data_size, libfvalue_error_t **error);

int
libfvalue_value_get_data(libfvalue_value_t *value, uint8_t **data,
    size_t *data_size, int *encoding, libfvalue_error_t **error);

int
libfvalue_value_set_data(libfvalue_value_t *value, const uint8_t *data,
    size_t data_size, int encoding, uint8_t flags,
    libfvalue_error_t **error);

int
libfvalue_value_copy_data(libfvalue_value_t *value, uint8_t *data,
    size_t data_size, libfvalue_error_t **error);

Obsessed with how get_data and set_data both speak in encoding 🦋 and set_data also takes uint8_t flags because it simply can't be normal about anything. has_data returns an int — that's your little "do I have anything for you" check-in. initialize_data wants a data_size, get_data_size gives one back, and copy_data just wants data + data_size.

---

Format flags + the entry-by-entry life 🌸

int
libfvalue_value_get_format_flags(libfvalue_value_t *value,
    uint32_t *format_flags, libfvalue_error_t **error);

int
libfvalue_value_set_format_flags(libfvalue_value_t *value,
    uint32_t format_flags, libfvalue_error_t **error);

int
libfvalue_value_get_number_of_value_entries(libfvalue_value_t *value,
    int *number_of_value_entries, libfvalue_error_t **error);

int
libfvalue_value_get_entry_data(libfvalue_value_t *value,
    int value_entry_index, uint8_t **entry_data,
    size_t *entry_data_size, int *encoding, libfvalue_error_t **error);

int
libfvalue_value_set_entry_data(libfvalue_value_t *value,
    int value_entry_index, const uint8_t *entry_data,
    size_t entry_data_size, int encoding, libfvalue_error_t **error);

int
libfvalue_value_append_entry_data(libfvalue_value_t *value,
    int *value_entry_index, const uint8_t *entry_data,
    size_t entry_data_size, int encoding, libfvalue_error_t **error);

format_flags get/set — cute, symmetric, no notes. Then get_number_of_value_entries tells you how many value_entry_index slots you're dealing with, and get_entry_data / set_entry_data / append_entry_data are the trio that actually touches them. Notice that get_entry_data has an int value_entry_index and also hands back int *encoding, while append_entry_data takes int *value_entry_index as a pointer — she's writing back where she appended, iykyk 💅

---

Now the typed-value ladder — we're going boolean → 8bit → 16bit → 32bit → 64bit → float → double, each one with a copy_from_ and a copy_to_, all keyed by value_entry_index:

int
libfvalue_value_copy_from_boolean(libfvalue_value_t *value,
    int value_entry_index, uint8_t value_boolean,
    libfvalue_error_t **error);

int
libfvalue_value_copy_to_boolean(libfvalue_value_t *value,
    int value_entry_index, uint8_t *value_boolean,
    libfvalue_error_t **error);

int
libfvalue_value_copy_from_8bit(libfvalue_value_t *value,
    int value_entry_index, uint8_t value_8bit,
    libfvalue_error_t **error);

int
libfvalue_value_copy_to_8bit(libfvalue_value_t *value,
    int value_entry_index, uint8_t *value_8bit,
    libfvalue_error_t **error);

int
libfvalue_value_copy_from_16bit(libfvalue_value_t *value,
    int value_entry_index, uint16_t value_16bit,
    libfvalue_error_t **error);

int
libfvalue_value_copy_to_16bit(libfvalue_value_t *value,
    int value_entry_index, uint16_t *value_16bit,
    libfvalue_error_t **error);

int
libfvalue_value_copy_from_32bit(libfvalue_value_t *value,
    int value_entry_index, uint32_t value_32bit,
    libfvalue_error_t **error);

int
libfvalue_value_copy_to_32bit(libfvalue_value_t *value,
    int value_entry_index, uint32_t *value_32bit,
    libfvalue_error_t **error);

int
libfvalue_value_copy_from_64bit(libfvalue_value_t *value,
    int value_entry_index, uint64_t value_64bit,
    libfvalue_error_t **error);

int
libfvalue_value_copy_to_64bit(libfvalue_value_t *value,
    int value_entry_index, uint64_t *value_64bit,
    libfvalue_error_t **error);

int
libfvalue_value_copy_from_float(libfvalue_value_t *value,
    int value_entry_index, float value_float,
    libfvalue_error_t **error);

int
libfvalue_value_copy_to_float(libfvalue_value_t *value,
    int value_entry_index, float *value_float,
    libfvalue_error_t **error);

int
libfvalue_value_copy_from_double(libfvalue_value_t *value,
    int value_entry_index, double value_double,
    libfvalue_error_t **error);

int
libfvalue_value_copy_to_double(libfvalue_value_t *value,
    int value_entry_index, double *value_double,
    libfvalue_error_t **error);

The way this is so satisfyingly regular 😭 _from_ takes the value by value, _to_ takes it by pointer. Eight-bit, sixteen-bit, thirty-two, sixty-four. Then float, then double. The symmetry is genuinely iconic, ate and left no crumbs.

---

And now the string section, in all three encodings, because we contain multitudes 🦋🌈

int
libfvalue_value_copy_from_utf8_string(libfvalue_value_t *value,
    int value_entry_index, const uint8_t *utf8_string,
    size_t utf8_string_length, libfvalue_error_t **error);

int
libfvalue_value_get_utf8_string_size(libfvalue_value_t *value,
    int value_entry_index, size_t *utf8_string_size,
    libfvalue_error_t **error);

int
libfvalue_value_copy_to_utf8_string(libfvalue_value_t *value,
    int value_entry_index, uint8_t *utf8_string,
    size_t utf8_string_size, libfvalue_error_t **error);

int
libfvalue_value_copy_to_utf8_string_with_index(libfvalue_value_t *value,
    int value_entry_index, uint8_t *utf8_string,
    size_t utf8_string_size, size_t *utf8_string_index,
    libfvalue_error_t **error);

int
libfvalue_value_copy_from_utf16_string(libfvalue_value_t *value,
    int value_entry_index, const uint16_t *utf16_string,
    size_t utf16_string_length, libfvalue_error_t **error);

int
libfvalue_value_get_utf16_string_size(libfvalue_value_t *value,
    int value_entry_index, size_t *utf16_string_size,
    libfvalue_error_t **error);

int
libfvalue_value_copy_to_utf16_string(libfvalue_value_t *value,
    int value_entry_index, uint16_t *utf16_string,
    size_t utf16_string_size, libfvalue_error_t **error);

int
libfvalue_value_copy_to_utf16_string_with_index(libfvalue_value_t *value,
    int value_entry_index, uint16_t *utf16_string,
    size_t utf16_string_size, size_t *utf16_string_index,
    libfvalue_error_t **error);

int
libfvalue_value_copy_from_utf32_string(libfvalue_value_t *value,
    int value_entry_index, const uint32_t *utf32_string,
    size_t utf32_string_length, libfvalue_error_t **error);

int
libfvalue_value_get_utf32_string_size(libfvalue_value_t *value,
    int value_entry_index, size_t *utf32_string_size,
    libfvalue_error_t **error);

int
libfvalue_value_copy_to_utf32_string(libfvalue_value_t *value,
    int value_entry_index, uint32_t *utf32_string,
    size_t utf32_string_size, libfvalue_error_t **error);

int
libfvalue_value_copy_to_utf32_string_with_index(libfvalue_value_t *value,
    int value_entry_index, uint32_t *utf32_string,
    size_t utf32_string_size, size_t *utf32_string_index,
    libfvalue_error_t **error);

Okay but the pattern here is SO clean: for each of utf8, utf16, utf32 you get a copy_from_..._string (takes ..._string_length, no with_index), a get_..._string_size, a plain copy_to_..._string, and then a copy_to_..._string_with_index that also carries a size_t *..._string_index. Three encodings, four functions each, twelve functions total, and not one of them is doing too much. 🎀 Also note utf8 uses uint8_t, utf16 uses uint16_t, utf32 uses uint32_t — matching widths, as they should, periodt.

---

Stream time 🌊 (these two return ssize_t, bestie, ssize_t, not int):

ssize_t
libfvalue_value_read_from_file_stream(libfvalue_value_t *value,
    FILE *file_stream, libfvalue_error_t **error);

ssize_t
libfvalue_value_write_to_file_stream(libfvalue_value_t *value,
    FILE *file_stream, libfvalue_error_t **error);

Read from a FILE *file_stream, write to a FILE *file_stream. File stream girlies, this one's for you.

---

🦋 Value type functions 🦋

A whole little subsection just for the type-initializing girlies 💜

int
libfvalue_value_type_initialize(libfvalue_value_t **value, int type,
    libfvalue_error_t **error);

int
libfvalue_value_type_initialize_with_data_handle(libfvalue_value_t **value,
    int type, libfvalue_data_handle_t *data_handle, uint8_t flags,
    libfvalue_error_t **error);

Two of them: the plain libfvalue_value_type_initialize that takes value + int type, and the deluxe libfvalue_value_type_initialize_with_data_handle which also brings a libfvalue_data_handle_t *data_handle and a uint8_t flags to the function. Same energy, more parameters. ✨

ssize_t
libfvalue_value_type_set_data_string(libfvalue_value_t *value,
    const uint8_t *data, size_t data_size, int encoding, uint8_t flags,
    libfvalue_error_t **error);

ssize_t
libfvalue_value_type_append_data_string(libfvalue_value_t *value,
    const uint8_t *data, size_t data_size, int encoding,
    libfvalue_error_t **error);

ssize_t
libfvalue_value_type_set_data_strings_array(libfvalue_value_t *value,
    const uint8_t *data, size_t data_size, int encoding,
    libfvalue_error_t **error);

okay and that's the last of the prototypes, bestie, we made it 🎀

---

💜 DESCRIPTION 💜

So like — the whole point of this one, the little main character of the whole page, is:

• libfvalue_get_version() — this function is literally just there to retrieve the library version. that's it. that's the whole job. she shows up, tells you the version, slays, leaves ✨

like yes she's lowkey doing the least but we still appreciate her 🫶

---

😭 RETURN VALUES 😭

okay so vibe check on returns — most of the functions are gonna hand you back NULL or -1 when something goes wrong, and which one you get depends on the return type of the function you called (because obviously a pointer can't return -1 and a number can't return NULL, that's just logic 💀).

for the actual return values, you gotta go look at "libfvalue.h" — that's the real source of truth, no cap. i'm not gonna sit here and invent numbers for you 🙈

---

🌸 ENVIRONMENT 🌸

None

literally nothing. no env vars, no sneaky little variables hiding in your shell. clean girl aesthetic 🧚

---

🦋 FILES 🦋

None

also nothing. she doesn't touch your filesystem. she's not that kind of library 💅

---

💀 BUGS 💀

found a bug? bestie please don't suffer in silence 😭 report bugs of any kind on the project issue tracker:

https://github.com/libyal/libfvalue/issues

any kind. truly any. they want to hear it 🔥

---

👑 AUTHOR 👑

these man pages are generated from "libfvalue.h". so like, the header file is the parent and the man page is the child, iykyk ✨

---

🌈 COPYRIGHT 🌈

Copyright (C) 2010-2024, Joachim Metz <joachim.metz@gmail.com>.

this is free software; see the source for copying conditions. and listen — there is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. like none. zero. not even the tiny implied ones. so don't come crying to anyone if it breaks, fr fr 😭

---

⭐ SEE ALSO ⭐

• the libfvalue.h include file — that's the whole list, she keeps her circle small 💜

---

and that's a wrap on the whole page, bestie 🎀 this one came from the libfvalue source, dated April 4, 2019, and it's the libfvalue(3) manual page — go forth and value your values 💅✨