#pragma once

/// \file text_value.h
/// \author Folling <folling@ikarus.world>

#include <ikarus/macros.h>
#include <ikarus/stdtypes.h>

/// \addtogroup values Values
/// @{

IKARUS_BEGIN_HEADER

/// \brief A true/false char const*ean-esque value. For example "Is Dead".
struct IkarusTextValue;

/// \brief Creates a text value from doubles.
/// \param data The text data or null if you wish to clear the data.
/// \details LibIkarus does not take ownership of this array.
/// \param data_size The size of the data array or 0 if you wish to clear the data.
/// \return The value.
/// \remark Must be freed with #ikarus_free.
IKA_API IkarusTextValue * ikarus_text_value_create(char const ** data, size_t data_size);

/// \brief Creates an indeterminate text value.
/// \return The value.
/// \remark Must be freed with #ikarus_free.
IKA_API IkarusTextValue * ikarus_text_value_create_indeterminate();

/// \brief Fetches the underlying data of a text value.
/// \details You may adjust the returned data as per your hearts desire.
/// If you need to grow the data, use #ikarus_text_value_set with a new array.
/// Just remember that IkarusValues are plain objects, so changing them won't affect any state.
/// They will need to be submitted to other functions such as #ikarus_entity_set_value to have any effect.
/// \param value The text value.
/// \pre \li Must not be null.
/// \param data_size_out An out-parameter for the size of the returned array.
/// \remark Ignored if null.
/// \return The underlying data. Owned by LibIkarus, most not be freed.
/// \warning Undefined if the value is indeterminate.
IKA_API char ** ikarus_text_value_get(IkarusTextValue * value, size_t * data_size_out);

/// \see ikarus_text_value_get
char const * const * ikarus_text_value_get_const(IkarusTextValue const * value, size_t * data_size_out);

/// \brief Sets the data of a text value.
/// \param value The text value.
/// \pre \li Must not be null.
/// \param new_data The new data or null if you wish to clear the data.
/// \details LibIkarus does not take ownership of this array.
/// \param new_data_size The size of the new data array or 0 if you wish to clear the data.
IKA_API void ikarus_text_value_set(IkarusTextValue * value, char const ** new_data, size_t new_data_size);

/// \brief Converts a text value to an entity value.
/// \param value The text value to convert.
/// \return The converted entity value.
IKA_API struct IkarusValue * ikarus_text_value_to_value(IkarusTextValue * value);

IKARUS_END_HEADER

/// @}