/**
 * @file vector.h
 * @brief Dynamic array (vector) implementation.
 * @details This module provides a generic resizable array data structure
 *          that can store pointers to any data type. The vector automatically
 *          grows as elements are added, using a growth factor to amortize
 *          reallocation costs.
 */

#ifndef VECTOR_H
#define VECTOR_H

#include <stddef.h>

/**
 * @def VECTOR_INITIAL_CAPACITY
 * @brief Initial capacity of a newly created vector.
 * @details The vector will be allocated with space for this many elements
 *          when first created. This value is chosen to balance memory usage
 *          and the number of early reallocations.
 */
#define VECTOR_INITIAL_CAPACITY 10

/**
 * @def VECTOR_GROWTH_FACTOR
 * @brief Multiplicative factor for vector capacity growth.
 * @details When the vector reaches capacity and needs to grow, the new
 *          capacity is calculated as (current_capacity * GROWTH_FACTOR).
 *          A factor of 2 provides good amortized performance.
 */
#define VECTOR_GROWTH_FACTOR 2

/**
 * @struct Vector
 * @brief A dynamic resizable array (vector) of generic pointers.
 * @details The vector maintains an underlying array that grows dynamically
 *          as elements are added. It tracks both the number of elements
 *          currently stored (size) and the total allocated space (capacity).
 */
typedef struct Vector Vector;

/**
 * @struct Vector
 * @brief A dynamic array container structure.
 */
struct Vector {
    /**
     * @brief Array of generic data pointers.
     * @details A dynamically allocated array of (void*) pointers,
     *          referencing to the actual data. The array has space for
     *          at least @p capacity elements. The caller is responsible
     *          for managing the memory that these pointers reference.
     */
    void **data;

    /**
     * @brief The number of elements currently stored in the vector.
     * @details Valid indices range from 0 to (size - 1). This value is
     *          incremented when elements are added and decremented when
     *          elements are removed.
     */
    size_t size;

    /**
     * @brief The total allocated space (in number of elements).
     * @details The underlying @p data array has space for this many pointers.
     *          When size reaches capacity, the vector is reallocated with
     *          a new capacity of (capacity * GROWTH_FACTOR). Always
     *          capacity >= size.
     */
    size_t capacity;
};

/**
 * @brief Allocates and initializes an empty vector.
 *
 * @return A pointer to the newly created vector, or NULL if memory
 *         allocation fails.
 *
 * @note The caller is responsible for freeing the returned vector
 *       using vector_delete().
 */
Vector *vector_new(void);

/**
 * @brief Deallocates the given vector.
 *
 * @param v Pointer to the vector to delete. If NULL, this function
 *          does nothing.
 *
 * @note This function deallocates only the vector structure, not the
 *       data it contains. The caller retains ownership of the data.
 */
void vector_delete(Vector *v);

/**
 * @brief Appends an element to the end of the vector.
 *
 * @param v Pointer to the vector.
 * @param element Pointer to the element to append.
 *
 * @note The vector does not take ownership of the element, only stores
 *       a pointer to it.
 */
void vector_push(Vector *v, void *element);

/**
 * @brief Removes and returns the last element from the vector.
 *
 * @param v Pointer to the vector.
 *
 * @return The data pointer of the removed last element.
 *
 * @pre The vector must not be empty.
 */
void *vector_pop(Vector *v);

/**
 * @brief Returns the element at the given index in the vector.
 *
 * @param v Pointer to the vector.
 * @param index The index of the element to retrieve.
 *
 * @return The data pointer at the given index.
 *
 * @pre The index must be valid (0 <= index < vector_size(v)).
 */
void *vector_get(Vector *v, size_t index);

/**
 * @brief Sets the element at the given index in the vector.
 *
 * @param v Pointer to the vector.
 * @param index The index of the element to set.
 * @param element Pointer to the new element.
 *
 * @pre The index must be valid (0 <= index < vector_size(v)).
 */
void vector_set(Vector *v, size_t index, void *element);

/**
 * @brief Returns the number of elements in the vector.
 *
 * @param v Pointer to the vector.
 *
 * @return The number of elements currently in the vector.
 */
size_t vector_size(Vector *v);

/**
 * @brief Checks if the vector is empty.
 *
 * @param v Pointer to the vector.
 *
 * @return Non-zero if the vector is empty, 0 otherwise.
 */
int vector_is_empty(Vector *v);

/**
 * @brief Removes all elements from the vector.
 *
 * @param v Pointer to the vector.
 *
 * @note This function only clears the vector structure, not the data
 *       it contained. The caller retains ownership of the data.
 */
void vector_clear(Vector *v);

#endif // !VECTOR_H