Ikarus/libikarus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

change error system & function signatures

Browse source 
Signed-off-by: Folling <mail@folling.io>
This commit is contained in:
folling 2024-01-02 15:14:39 +01:00 • committed by Folling
parent ee85c53354
commit e17e346768
Signed by: folling
SSH key fingerprint: SHA256:S9qEx5WCFFLK49tE/LKnKuJYM5sw+++Dn6qJbbyxnCY
28 changed files with 633 additions and 651 deletions
Download patch file Download diff file Expand all files Collapse all files

53
include/ikarus/values/text_value.h
View file

@ -3,6 +3,7 @@
/// \file text_value.h
/// \author Folling <folling@ikarus.world>
#include <ikarus/errors.h>
#include <ikarus/macros.h>
#include <ikarus/stdtypes.h>
@ -14,101 +15,115 @@ IKARUS_BEGIN_HEADER
/// \brief A textual value. For example "Surname" or "Description"
struct IkarusTextValue;
/// \brief Creates a text value.
/// \brief Creates an empty text value.
/// \param error_out \see errors.h
/// \return The value or null if an error occurs.
/// \remark Must be freed with #ikarus_free.
IKA_API IkarusTextValue * ikarus_text_value_create();
IKA_API IkarusTextValue * ikarus_text_value_create(IkarusErrorData * error_out);
/// \brief Fetches the underlying data of a number value at a specific index.
/// \param value The number value.
/// \pre \li Must not be null.
/// \param idx The index of the data to fetch.
/// \pre \li Must be less than the size of the value.
/// \param error_out \see errors.h
/// \return The underlying data or null if an error occurs or the value is undefined.
/// \remark This value is owned by LibIkarus and must not be freed.
IKA_API char const * ikarus_text_value_get(IkarusTextValue * value, size_t idx);
IKA_API char const * const * ikarus_text_value_get(IkarusTextValue const * value, size_t idx, IkarusErrorData * error_out);
/// \brief Fetches the size of the underlying data of a text value.
/// \param value The text value.
/// \pre \li Must not be null.
/// \param error_out \see errors.h
/// \return The size of the underlying data or 0 if an error occurs or the value is undefined.
IKA_API size_t ikarus_text_value_get_size(IkarusTextValue const * value);
IKA_API size_t ikarus_text_value_get_size(IkarusTextValue const * value, IkarusErrorData * error_out);
/// \brief Sets the data of a text value at a specific index.
/// \param value The text value.
/// \pre \li Must not be null.
/// \param idx The index of the data to set.
/// \pre \li Must be less than the size of the value.
/// \param new_data The new data. LibIkarus assumes ownership of this pointer.
IKA_API void ikarus_text_value_set(IkarusTextValue * value, size_t idx, char const * new_data);
/// \param new_data The new data. Ownership remains with the caller.
/// \pre \li Must not be null.
/// \param error_out \see errors.h
IKA_API void ikarus_text_value_set(IkarusTextValue * value, size_t idx, char const * new_data, IkarusErrorData * error_out);
/// \brief Removes a data from a text value.
/// \param value The text value.
/// \pre \li Must not be null.
/// \param idx The index of the data to remove.
/// \pre \li Must be less than the size of the value.
IKA_API void ikarus_text_value_remove(IkarusTextValue * value, size_t idx);
/// \param error_out \see errors.h
IKA_API void ikarus_text_value_remove(IkarusTextValue * value, size_t idx, IkarusErrorData * error_out);
/// \brief Inserts a data into a text value.
/// \param value The text value.
/// \pre \li Must not be null.
/// \param idx The index of the data to insert.
/// \pre \li Must be less than or equal to the size of the value.
/// \param new_data The new data.
IKA_API void ikarus_text_value_insert(IkarusTextValue * value, size_t idx, char const * new_data);
/// \param new_data The new data. Ownership remains with the caller.
/// \pre \li Must not be null.
/// \param error_out \see errors.h
IKA_API void ikarus_text_value_insert(IkarusTextValue * value, size_t idx, char const * new_data, IkarusErrorData * error_out);
/// \brief Clears a text value.
/// \param value The text value.
/// \param error_out \see errors.h
/// \remark Noop if the value is undefined.
IKA_API void ikarus_text_value_clear(IkarusTextValue * value);
IKA_API void ikarus_text_value_clear(IkarusTextValue * value, IkarusErrorData * error_out);
/// \brief Checks if a text value is undefined.
/// \param value The text value.
/// \pre \li Must not be null.
/// \param error_out \see errors.h
/// \return True if the value is undefined, false otherwise.
IKA_API bool ikarus_text_value_is_undefined(IkarusTextValue const * value);
IKA_API bool ikarus_text_value_is_undefined(IkarusTextValue const * value, IkarusErrorData * error_out);
/// \brief Changes a text value's undefined state.
/// \param value The text value.
/// \pre \li Must not be null.
/// \param undefined The new undefined state.
/// \param error_out \see errors.h
/// \remark Noop if the value is already undefined.
/// \remark If the value is set to undefined, all data will be cleared.
/// \remark If the value is set to not undefined, the value is as if newly created.
IKA_API void ikarus_text_value_set_undefined(IkarusTextValue * value, bool undefined);
IKA_API void ikarus_text_value_set_undefined(IkarusTextValue * value, bool undefined, IkarusErrorData * error_out);
/// \brief Converts a text value to a string.
/// \param value The text value to convert.
/// \pre \li Must not be null.
/// \param error_out \see errors.h
/// \return The converted string.
/// \remark Must be freed with #ikarus_free.
/// \remark Undefined if the value is undefined.
IKA_API char const * ikarus_text_value_to_string(IkarusTextValue const * value);
IKA_API char const * ikarus_text_value_to_string(IkarusTextValue const * value, IkarusErrorData * error_out);
/// \brief Checks if two values are equal.
/// \param lhs The left hand side value.
/// \pre \li Must not be null.
/// \param rhs The right hand side value.
/// \pre \li Must not be null.
/// \param error_out \see errors.h
/// \return True if the values' data are equal, false otherwise.
IKA_API bool ikarus_text_value_is_equal(IkarusTextValue const * lhs, IkarusTextValue const * rhs);
IKA_API bool ikarus_text_value_is_equal(IkarusTextValue const * lhs, IkarusTextValue const * rhs, IkarusErrorData * error_out);
/// \brief Creates a copy of a text value.
/// \param value The value to copy.
/// \pre \li Must not be null.
/// \param error_out \see errors.h
/// \return The copied value.
/// \remark Must be freed with #ikarus_free.
IKA_API IkarusTextValue * ikarus_text_value_copy(IkarusTextValue const * value);
IKA_API IkarusTextValue * ikarus_text_value_copy(IkarusTextValue const * value, IkarusErrorData * error_out);
/// \brief Converts a text value to an entity value.
/// \param value The text value to convert.
/// \pre \li Must not be null.
/// \param error_out \see errors.h
/// \return The converted entity value.
/// \remark This is the same pointer, so freeing it implies freeing the original value.
IKA_API struct IkarusValue * ikarus_text_value_to_value(IkarusTextValue * value);
IKA_API struct IkarusValue * ikarus_text_value_to_value(IkarusTextValue * value, IkarusErrorData * error_out);
/// \see ikarus_toggle_value_to_value
IKA_API struct IkarusValue const * ikarus_text_value_to_value_const(IkarusTextValue const * value);
/// \see ikarus_text_value_to_value
IKA_API struct IkarusValue const * ikarus_text_value_to_value_const(IkarusTextValue const * value, IkarusErrorData * error_out);
IKARUS_END_HEADER