#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 textual value. For example "Surname" or "Description".
struct IkarusTextValue;

/// \brief Creates a text value from strings.
/// \param data The text data or null if you wish to create an empty value.
/// \details LibIkarus does not take ownership of this array.
/// \param data_size The size of the data array.
/// \return The value or null if an error occurs.
/// \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();

/// \see ikarus_number_value_get
IKA_API char const * const * ikarus_text_value_get(IkarusTextValue const * value, size_t idx);

/// \brief Fetches the size of the underlying data of a text value.
/// \param value The text value.
/// \pre \li Must not be null.
/// \return The size of the underlying data or 0 if an error occurs or the value is indeterminate.
IKA_API size_t ikarus_text_value_get_size(IkarusTextValue const * value);

/// \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.
IKA_API void ikarus_text_value_set(IkarusTextValue * value, size_t idx, char const * new_data);

/// \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.
/// \remark This will shift all data after the index by one to the left.
IKA_API void ikarus_text_value_remove(IkarusTextValue * value, size_t idx);

/// \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.
/// \remark This will shift all data after the index by one to the right.
IKA_API void ikarus_text_insert(IkarusTextValue * value, size_t idx, char const * new_data);

/// \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

/// @}