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

finalise interface & documentation

Browse source 
Signed-off-by: Folling <mail@folling.io>
This commit is contained in:
Folling 2023-11-06 13:14:39 +01:00 • committed by Folling
parent 521c61c8fb
commit eb1f414fc4
No known key found for this signature in database
56 changed files with 2074 additions and 780 deletions
Download patch file Download diff file Expand all files Collapse all files

182
include/ikarus/values/value.h
View file

@ -3,10 +3,10 @@
// IMPLEMENTATION_DETAIL_PROPERTY_TYPES
/// \file value.h
/// \author Folling <mail@folling.io>
/// \author Folling <folling@ikarus.world>
#include <ikarus/macros.h>
#include <ikarus/objects/property.h>
#include <ikarus/objects/property_type.h>
#include <ikarus/stdtypes.h>
IKARUS_BEGIN_HEADER
@ -15,149 +15,115 @@ IKARUS_BEGIN_HEADER
/// \brief The values stored in entities.
/// \details Each entity has a value for each property it is associated with.
/// The value is of the type specified by the property and constrained by the property's settings.
/// A value may be indeterminate which means it is unknown or not specified.
/// \see PropertyType PropertySettings
/// @{
/// \brief A true/false boolean-like value. For example "IsDead".
struct IkarusToggleValue {
/// \private \brief The value of the property.
bool _value;
};
struct IkarusToggleValue;
/// \brief An arbitrary numeric value. For example "Age".
struct IkarusNumberValue {
/// \private \brief The value of the property.
long double _value;
};
struct IkarusNumberValue;
/// \brief An arbitrary textual value. For example "First Name".
struct IkarusTextValue {
/// \private \brief The value of the property.
char const * _value;
};
/// \private \brief The data for a value.
union IkarusEntityValueData {
/// \private \brief The value as a toggle.
IkarusToggleValue toggle;
/// \private \brief The value as a number.
IkarusNumberValue number;
/// \private \brief The value as text.
IkarusTextValue text;
};
/// \brief The state of an entity value.
/// \details States provide insight into the nature of a value.
enum IkarusEntityValueState {
/// \brief The value is invalid.
IkarusEntityValueState_Invalid,
/// \brief The value is normal and can be used as-is.
IkarusEntityValueState_Normal,
/// \brief The value is unknown.
IkarusEntityValueState_Indeterminate,
};
struct IkarusTextValue;
/// \brief The value of an entity associated with a property.
struct IkarusEntityValue {
/// \private \brief The type of the value.
IkarusPropertyType _type;
/// \private \brief The data for the value.p
IkarusEntityValueData _data;
/// \private \brief The state of the value.
IkarusEntityValueState _state;
};
struct IkarusEntityValue;
/// \brief Creates an entity value from a toggle value.
/// \brief Creates a toggle value from a boolean.
/// \param value The toggle value.
/// \return The entity value.
IKA_API IkarusEntityValue ikarus_value_create_toggle(bool value);
/// \brief Creates an entity value from a number value.
/// \remark Must be freed with #ikarus_free.
IKA_API IkarusToggleValue * ikarus_toggle_value_create(bool value);
/// \brief Creates an indeterminate toggle value.
/// \return The entity value.
/// \remark Must be freed with #ikarus_free.
IKA_API IkarusToggleValue * ikarus_toggle_value_create_indeterminate();
/// \brief Sets the value of a toggle value.
/// \param value The toggle value.
/// \pre Must not be null.
/// \param new_value The new value.
IKA_API void ikarus_toggle_value_set(IkarusToggleValue * value, bool new_value);
/// \brief Creates a number value from a number.
/// \param value The number value.
/// \pre Must be finite & not NaN.
/// \return The entity value.
/// \remark If the value is NaN or infinity an InvalidEntityValue is returned.
IKA_API IkarusEntityValue ikarus_value_create_number(long double value);
/// \brief Creates an entity value from a text value.
/// \remark Must be freed with #ikarus_free.
IKA_API IkarusNumberValue * ikarus_number_value_create(long double value);
/// \brief Creates an indeterminate number value.
/// \return The entity value.
/// \remark Must be freed with #ikarus_free.
IKA_API IkarusNumberValue * ikarus_number_value_create_indeterminate();
/// \brief Sets the value of a number value.
/// \param value The number value.
/// \pre Must not be null.
/// \param new_value The new value.
IKA_API void ikarus_number_value_set(IkarusNumberValue * value, bool new_value);
/// \brief Creates a text value from string.
/// \param value The text value.
/// \pre Must not be null.
/// \return The entity value.
/// \remark If the value is null an InvalidEntityValue is returned.
IKA_API IkarusEntityValue ikarus_value_create_text(char const * value);
/// \brief Creates an indeterminate entity value of a given type.
/// \param type The type of the value.
/// \remark Must be freed with #ikarus_free.
IKA_API IkarusTextValue * ikarus_text_value_create(char const * value);
/// \brief Creates an indeterminate text value.
/// \return The entity value.
IKA_API IkarusEntityValue ikarus_value_create_indeterminate(IkarusPropertyType type);
/// \remark Must be freed with #ikarus_free.
IKA_API IkarusTextValue * ikarus_text_value_create_indeterminate();
/// \brief Sets the value of a text value.
/// \param value The text value.
/// \pre Must not be null.
/// \param new_value The new value.
IKA_API void ikarus_text_value_set(IkarusTextValue * value, bool new_value);
/// \brief Fetches the default value for a property type.
/// \remark Not to be confused with the default value of a property. See ikarus_property_get_default_value
/// \param type The property type.
/// \return The default value for the property type.
IKA_API IkarusEntityValue ikarus_value_get_default(IkarusPropertyType type);
/// \brief Checks if a toggle value is indeterminate.
/// \param value The toggle value.
/// \pre Must not be null.
/// \return True if the value is indeterminate, false otherwise.
IKA_API bool ikarus_toggle_value_is_indeterminate(IkarusToggleValue const * value);
/// \brief Checks if a number value is indeterminate.
/// \param value The number value.
/// \pre Must not be null.
/// \return True if the value is indeterminate, false otherwise.
IKA_API bool ikarus_number_value_is_indeterminate(IkarusNumberValue const * value);
/// \brief Checks if a text value is indeterminate.
/// \param value The text value.
/// \pre Must not be null.
/// \return True if the value is indeterminate, false otherwise.
IKA_API bool ikarus_text_value_is_indeterminate(IkarusTextValue const * value);
/// \brief Fetches the underlying value of a toggle value.
/// \param value The toggle value.
/// \return The underlying value.
/// \warning If the value is indeterminate, false is returned.
IKA_API bool ikarus_toggle_value_get_underlying(IkarusToggleValue const * value);
/// \brief Fetches the underlying value of a number value.
/// \param value The number value.
/// \return The underlying value.
/// \warning If the value is indeterminate, 0.0 is returned.
IKA_API long double ikarus_number_value_get_underlying(IkarusNumberValue const * value);
/// \brief Fetches the underlying value of a text value.
/// \param value The text value.
/// \return The underlying value.
/// \return A copy of the underlying value.
/// \remark The returned value is a copy and owned by the caller.
/// \warning If the value is indeterminate, an empty string is returned.
IKA_API char const * ikarus_text_value_get_underlying(IkarusTextValue const * value);
/// \brief Checks if a toggle value is equal to a boolean.
/// \param value The toggle value.
/// \param check The boolean value.
/// \return False if value is null. True if it is equal to check, false otherwise.
IKA_API bool ikarus_toggle_value_is_equal(IkarusToggleValue const * value, bool check);
/// \brief Checks if a number value is equal to a number.
/// \param value The number value.
/// \param check The number value.
/// \return False if value is null. True if it is equal to check, false otherwise.
IKA_API bool ikarus_number_value_is_equal(IkarusNumberValue const * value, long double check);
/// \brief Checks if a text value is equal to a string.
/// \param value The text value.
/// \param check The string value.
/// \return False if value or check are null. True if it is equal to check, false otherwise.
IKA_API bool ikarus_text_value_is_equal(IkarusTextValue const * value, char const * check);
/// \brief Checks if two entity values are equal.
/// \details Two entity values are equal if they are of the same type and their value is considered equal.
/// Note that floating point values can only be checked for approximate equality.
/// \param left The left-hand entity value.
/// \param right The right-hand entity value.
/// \return True if the values are considered equal, false otherwise.
/// \remark Null values compare false to all other values. As do invalid values. Indeterminate values however, compare true to
/// other indeterminate values of the same type.
IKA_API bool ikarus_value_is_equal(IkarusEntityValue const * left, IkarusEntityValue const * right);
/// \brief Checks if an entity value is invalid.
/// \param value The entity value.
/// \return True if the value is invalid or null, false otherwise.
IKA_API bool ikarus_value_is_invalid(IkarusEntityValue const * value);
/// \brief Fetches the type of an entity value.
/// \param value The entity value.
/// \return The type of the entity value.
IKA_API IkarusPropertyType ikarus_value_get_type(IkarusEntityValue const * value);
/// \brief Visits an entity value, calling the appropriate function for the value's type.
/// \param value The entity value to visit.
/// \param toggle The function to call if the value is a toggle value.
/// \param number The function to call if the value is a number value.
/// \param text The function to call if the value is a text value.
/// \param data The data to pass to the functions.
/// \remark function pointers may be null in which case they are not called.
/// \param toggle The function to call if the value is a toggle value. Skipped if null.
/// \param number The function to call if the value is a number value. Skipped if null.
/// \param text The function to call if the value is a text value. Skipped if null.
/// \param data The data passed to the visitor functions.
IKA_API void ikarus_value_visit(
IkarusEntityValue const * value,
void (*toggle)(IkarusToggleValue const *, void *),
void (*number)(IkarusNumberValue const *, void *),
void (*text)(IkarusTextValue const *, void *),
IkarusEntityValue * value,
void (*toggle)(IkarusToggleValue *, void *),
void (*number)(IkarusNumberValue *, void *),
void (*text)(IkarusTextValue *, void *),
void * data
);