/**
 * @file vector.h
 * @brief 动态数组（Vector）实现
 * 
 * 提供类型安全的动态数组容器实现，支持自动扩容和基本操作
 */

#ifndef __SMCC_DS_VECTOR_H__
#define __SMCC_DS_VECTOR_H__

#include <lib/rt/rt.h>

/** @defgroup vector_struct 数据结构定义 */

/**
 * @def VECTOR_HEADER(name, type)
 * @brief 声明向量结构体
 * @param name 结构体变量名
 * @param type 存储的数据类型
 * 
 * 生成包含size/cap/data三个字段的结构体定义：
 * - size: 当前元素数量
 * - cap: 数组容量
 * - data: 存储数组指针
 */
#define VECTOR_HEADER(name, type) \
    struct { \
        rt_size_t size;   /**< 当前元素数量 */ \
        rt_size_t cap;    /**< 数组容量 */ \
        type *data;       /**< 数据存储指针 */ \
    } name

/** @defgroup vector_operations 向量操作宏 */

/**
 * @def vector_init(vec)
 * @brief 初始化向量结构体
 * @param vec 要初始化的向量结构体变量
 * 
 * @note 此宏不会分配内存，仅做零初始化
 */
#define vector_init(vec) \
    do { \
        (vec).size = 0, \
        (vec).cap = 0, \
        (vec).data = 0; \
    } while(0)

/**
 * @def vector_push(vec, value)
 * @brief 添加元素到向量末尾
 * @param vec 目标向量结构体
 * @param value 要添加的值（需匹配存储类型）
 * 
 * @note 当容量不足时自动扩容为2倍（初始容量为8）
 * @warning 内存分配失败时会触发LOG_FATAL
 */
#define vector_push(vec, value) \
    do { \
        if (vec.size >= vec.cap) { \
            int cap = vec.cap ? vec.cap * 2 : 8; \
            void* data = salloc_realloc(vec.data, cap * sizeof(*vec.data)); \
            if (!data) { \
                LOG_FATAL("vector_push: rt_realloc failed\n"); \
            } \
            (vec).cap = cap; \
            (vec).data = data; \
        } \
        (vec).data[(vec).size++] = value; \
    } while(0)

/**
 * @def vector_pop(vec)
 * @brief 弹出最后一个元素
 * @param vec 目标向量结构体
 * @return 最后元素的引用
 * @warning 需确保size > 0时使用
 */
#define vector_pop(vec) \
    ((vec).data[--(vec).size])

/**
 * @def vector_at(vec, idx)
 * @brief 获取指定索引元素
 * @param vec 目标向量结构体
 * @param idx 元素索引（0 <= idx < size）
 * @return 对应元素的引用
 */
#define vector_at(vec, idx) \
    (((vec).data)[idx])

/**
 * @def vector_idx(vec, ptr)
 * @brief 获取元素指针对应的索引
 * @param vec 目标向量结构体
 * @param ptr 元素指针（需在data数组范围内）
 * @return 元素索引值
 */
#define vector_idx(vec, ptr) \
    ((ptr) - (vec).data)

/**
 * @def vector_free(vec)
 * @brief 释放向量内存
 * @param vec 目标向量结构体
 * 
 * @note 释放后需重新初始化才能再次使用
 */
#define vector_free(vec) \
    do { \
        salloc_free((vec).data); \
        (vec).data = NULL; \
        (vec).size = (vec).cap = 0; \
    } while(0)

#endif // __SMCC_DS_VECTOR_H__