/**
 * A heterogeneous array of objects. fx_array only stores references
 * to the objects that it contains, not the object data itself.
 *
 * fx_array stores pointers to objects in a single contiguous array,
 * but this is an implementation detail that may change in the future.
 * Users of fx_array should not rely on this being the case.
 */
#ifndef FX_DS_ARRAY_H_
#define FX_DS_ARRAY_H_

#include <fx/iterator.h>
#include <fx/macros.h>
#include <fx/misc.h>
#include <fx/status.h>

FX_DECLS_BEGIN;

#define FX_TYPE_ARRAY          (fx_array_get_type())
#define FX_TYPE_ARRAY_ITERATOR (fx_array_iterator_get_type())

struct fx_array_p;

FX_DECLARE_TYPE(fx_array);
FX_DECLARE_TYPE(fx_array_iterator);

FX_TYPE_CLASS_DECLARATION_BEGIN(fx_array)
FX_TYPE_CLASS_DECLARATION_END(fx_array)

FX_TYPE_CLASS_DECLARATION_BEGIN(fx_array_iterator)
FX_TYPE_CLASS_DECLARATION_END(fx_array_iterator)

FX_API fx_type fx_array_get_type(void);
FX_API fx_type fx_array_iterator_get_type(void);

FX_TYPE_DEFAULT_CONSTRUCTOR(fx_array, FX_TYPE_ARRAY);

/**
 * Creates an fx_array initialised with the contents of the provided
 * fx_object pointer array. The fx_array will take a reference to each
 * object specified in `values`, and will increment the reference count.
 * The order of objects in the new fx_array will be the same as the order
 * of objects in `values`. Any NULL pointers in the `values` array will
 * be ignored, and will not result in gaps in the created fx_array.
 * However, `nr_values` should be large enough to cover the final
 * non-NULL pointer in `values`, including any NULL pointers in-between.
 *
 * @param values The list of object pointers which should make up the
 * contents of the new fx_array.
 * @param nr_values The size of the `values` array.
 * @return A pointer to the new fx_array, or NULL if an error occurred.
 */
FX_API fx_array *fx_array_create_with_values(
	fx_object *const *values,
	size_t nr_values);

/**
 * Remove all object references from an fx_array, resetting the size of the
 * array to zero. The reference counts of all objects in the array will be
 * decremented.
 *
 * @param array The fx_array to clear.
 */
FX_API void fx_array_clear(fx_array *array);

/**
 * Inserts an object at the end of an fx_array. The reference count of
 * the object will be incremented.
 *
 * @param array The fx_array to append the object to.
 * @param value The object to append.
 * @return FX_SUCCESS if the object was appended successfully, or an
 * error code if an error occurred.
 */
FX_API fx_status fx_array_append(fx_array *array, fx_object *value);

/**
 * Inserts an object at the beginning of an fx_array. The reference count
 * of the object will be incremented. All other objects in the array
 * will be moved to make space for the object being pre-pended.
 *
 * @param array The fx_array to prepend the object to.
 * @param value The object to prepend.
 * @return FX_SUCCESS if the object was prepended successfully, or an
 * error code if an error occurred.
 */
FX_API fx_status fx_array_prepend(fx_array *array, fx_object *value);

/**
 * Inserts an object into an fx_array at a given index. The reference
 * count of the object will be incremented. If the specified index is at
 * the beginning or mid-way through the array (i.e. not at the end),
 * some or all of the objects already in the array will be moved to make
 * space for the object being inserted.
 *
 * @param array The fx_array to insert the object into.
 * @param value The object to insert.
 * @param at The index to insert the object at. If the index is
 * `FX_NPOS`, the object will be inserted at the end of the fx_array.
 * @return FX_SUCCESS if the object was inserted, or a status code
 * describing any error that occurred.
 */
FX_API fx_status fx_array_insert(fx_array *array, fx_object *value, size_t at);

/**
 * Removes the object at the specified index from an fx_array. The
 * reference count of the removed object will be decremented. If the
 * specified index is at the beginning or mid-way through the array
 * (i.e. not at the end), the remaining objects will be moved to fill
 * the empty space created by the object's removal.
 *
 * @param array The fx_array to remove the object from.
 * @param at The index of the object to be removed.
 * @return FX_SUCCESS if the object was removed, or a status code
 * describing any error that occurred.
 */
FX_API fx_status fx_array_remove(fx_array *array, size_t at);

/**
 * Removes the object at the beginning of an fx_array. The reference count
 * of the removed object will be decremented. The remaining objects will be
 * moved to fill the empty space created by the object's removal.
 *
 * @param array The fx_array to remove the object from.
 * @return FX_SUCCESS if the object was removed, or a status code describing any
 * error that occurred.
 */
FX_API fx_status fx_array_remove_front(fx_array *array);

/**
 * Removes the object at the end of an fx_array. The reference count
 * of the removed object will be decremented.
 *
 * @param array The fx_array to remove the object from.
 * @return FX_SUCCESS if the object was removed, or a status code describing any
 * error that occurred.
 */
FX_API fx_status fx_array_remove_back(fx_array *array);

/**
 * Removes the object at the specified index of an fx_array, and returns
 * a pointer to it. The reference count of the removed object will NOT
 * be decremented. The caller becomes the owner of the array's reference
 * to the object. If the specified index is at the beginning or mid-way
 * through the array (i.e. not at the end), the remaining objects will
 * be moved to fill the empty space created by the object's removal.
 *
 * @param array The fx_array to remove the object from.
 * @param at The index of the object to be removed.
 * @return An pointer to the removed object. This pointer is owned by
 * the caller. Returns NULL if an error occurred.
 */
FX_API fx_object *fx_array_pop(fx_array *array, size_t at);

/**
 * Removes the object at the beginning of an fx_array, and returns a
 * pointer to it. The reference count of the removed object will NOT be
 * decremented. The caller becomes the owner of the array's reference to
 * the object. The remaining objects in the fx_array will be moved to
 * fill the empty space left by the removed object.
 *
 * @param array The fx_array to remove the object from.
 * @return An pointer to the removed object. This pointer is owned by
 * the caller. Returns NULL if an error occurred.
 */
FX_API fx_object *fx_array_pop_front(fx_array *array);

/**
 * Removes the object at the end of an fx_array, and returns a pointer to it.
 * The reference count of the removed object will NOT be decremented. The caller
 * becomes the owner of the array's reference to the object.
 *
 * @param array The fx_array to remove the object from.
 * @return An pointer to the removed object. This pointer is owned by the
 * caller. Returns NULL if an error occurred.
 */
FX_API fx_object *fx_array_pop_back(fx_array *array);

/**
 * Returns an unowned pointer to the object at the given index of an fx_array.
 * The caller does not own the returned pointer, and MUST NOT release it.
 *
 * @param array The fx_array.
 * @param at The index of the object to return.
 * @return A pointer to the object at the given index. This pointer is NOT owned
 * by the caller. Returns NULL if an error occurred.
 */
FX_API fx_object *fx_array_at(const fx_array *array, size_t at);

/**
 * Returns an owned pointer to the object at the given index of an
 * fx_array. The caller owns the returned pointer, and must release it
 * when they are finished with it.
 *
 * @param array The fx_array.
 * @param at The index of the object to return.
 * @return A pointer to the object at the given index. This pointer is
 * owned by the caller. Returns NULL if an error occurred.
 */
FX_API fx_object *fx_array_get(fx_array *array, size_t at);

/**
 * Returns the number of objects contained in an fx_array.
 *
 * @param array The fx_array.
 * @return The number of objects contained in the fx_array.
 */
FX_API size_t fx_array_size(const fx_array *array);

/**
 * Returns the current maximum capacity of an fx_array. This represents
 * the number of objects that can be stored in an fx_array before its
 * internal buffer would need to be re-sized.
 *
 * @param array The fx_array.
 * @return The maximum capacity of the fx_array.
 */
FX_API size_t fx_array_capacity(const fx_array *array);

FX_DECLS_END;

#endif