cKit/Foundation/c_SmartPtrVector.c

#include <c_SmartPtrVector.h>

#define DEFAULT_INITIAL_CAPACITY    4
#define DEFAULT_GROW_FACTOR         2

/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

c_err_t c_SmartPtrVector_Init(c_SmartPtrVector_t* vector, c_size_t capacity, c_Allocator_t* allocator) {
    if (!vector) return C_ERR_PARAM;
    vector->allocator = (allocator != NULL) ? *allocator : c_DefaultAllocator;
    vector->size = 0;
    vector->capacity = (capacity > 0) ? capacity : DEFAULT_INITIAL_CAPACITY; // 預留初始 4 個槽位
    vector->array = (c_SmartPtr_t*)c_Allocator_Alloc(&vector->allocator, vector->capacity * sizeof(c_SmartPtr_t));
    if (!vector->array) {
        vector->capacity = 0;
        return C_ERR_NOMEM;
    }

    // 嚴格原位抹零：確保初始狀態下所有槽位的物理指標與引用計數皆為純淨的 0 (NULL)
    memset((void*)vector->array, 0, vector->capacity * sizeof(c_SmartPtr_t));
    return C_ERR_OK;
}

/**
 * @brief 銷毀智慧指標向量
 * @note 閉環契約：必須依序呼叫你定義的 c_SmartPtr_Destroy 遞减引用計數，
 *       若降為 0 則會自動驅使內部的 free_fn，最後再退還 Vector 控制底座記憶體給內置分配器。
 */
void c_SmartPtrVector_Destroy(c_SmartPtrVector_t* vector) {
    if (!vector) return;

    if (vector->array) {
        // ① 依序安全銷毀當前所有有效槽位持有的引用
        for (c_size_t i = 0; i < vector->size; i++) {
            c_SmartPtr_Destroy(&vector->array[i]);
        }
        // ② 歸还底座記憶體給綁定的記憶體池
        c_Allocator_Free(&vector->allocator, vector->array);
        vector->array = NULL;
    }
    vector->size = 0;
    vector->capacity = 0;
}

/**
 * @brief 內部私有自動動態翻倍擴容函數
 * @note 強異常安全性：採用移動語義平移控制權，即使分配失敗，老資料依舊原裝存活
 */
C_STATIC_FORCE_INLINE
bool c_SmartPtrVector_EnsureCapacity(c_SmartPtrVector_t* vector) {
    if (vector->size < vector->capacity) return true;

    c_size_t new_capacity = vector->capacity * 2;

    // 1. 利用內置分配器，在當前專屬記憶體池裡開闢全新的目標緩衝區
    c_SmartPtr_t* new_array = (c_SmartPtr_t*)c_Allocator_Alloc(&vector->allocator, new_capacity * sizeof(c_SmartPtr_t));
    if (!new_array) return false;

    // 清零新緩衝區槽位
    memset((void*)new_array, 0, new_capacity * sizeof(c_SmartPtr_t));

    // 2. 利用你的 c_SmartPtr_Move 將老槽位的所有權絕對安全地轉移過去
    // 你的 Move 內部執行了 *dest = *src 和對 src 的 memset，完美斬斷老位，且引用計數完美保持不變！
    for (c_size_t i = 0; i < vector->size; i++) {
        c_SmartPtr_Move(&new_array[i], &vector->array[i]);
    }

    // 3. 歸还已經被完全掏空、所有指標皆為 NULL 的老緩衝區底座
    c_Allocator_Free(&vector->allocator, vector->array);

    vector->array = new_array;
    vector->capacity = new_capacity;
    return true;
}

// ==================================================================================================================
// 2. 核心元素增删控制操作 API
// ==================================================================================================================

c_err_t c_SmartPtrVector_PushBack(c_SmartPtrVector_t* vector, const c_SmartPtr_t* ptr) {
    if (!vector || !ptr) return C_ERR_PARAM;
    if (!c_SmartPtrVector_EnsureCapacity(vector)) return C_ERR_NOMEM;

    // 使用你的 c_SmartPtr_Copy 進行拷貝：內部會自動對 dest->ref_count 執行原子加一加
    c_err_t err = c_SmartPtr_Copy(&vector->array[vector->size], ptr);
    if (err == C_ERR_OK) {
        vector->size++;
    }
    return err;
}

c_err_t c_SmartPtrVector_PopBack(c_SmartPtrVector_t* vector, c_SmartPtr_t* ptr) {
    if (!vector || vector->size == 0) return C_ERR_OUTOFBOUND;

    vector->size--;
    c_SmartPtr_t* slot = &vector->array[vector->size];

    if (ptr) {
        // 利用你的 c_SmartPtr_Move 轉移所有權給外部接收器，省去不必要的加減計數硬件震盪开销
        c_SmartPtr_Move(ptr, slot);
    } else {
        // 外部若靜默彈出，直接驅動銷毀鏈銷毁
        c_SmartPtr_Destroy(slot);
    }

    return C_ERR_OK;
}

c_err_t c_SmartPtrVector_Insert(c_SmartPtrVector_t* vector, c_size_t index, const c_SmartPtr_t* ptr) {
    if (!vector || !ptr || index > vector->size) return C_ERR_PARAM;
    if (!c_SmartPtrVector_EnsureCapacity(vector)) return C_ERR_NOMEM;

    // 1. 自尾部向左推進，利用你的 c_SmartPtr_Move 將 index 右側的元素整體右推滑移一格
    for (c_size_t i = vector->size; i > index; i--) {
        c_SmartPtr_Move(&vector->array[i], &vector->array[i - 1]);
    }

    // 2. 槽位騰空，使用你的 Copy 深度注入，計數自動原子閉合
    c_err_t err = c_SmartPtr_Copy(&vector->array[index], ptr);
    if (err == C_ERR_OK) {
        vector->size++;
    }
    return err;
}

c_err_t c_SmartPtrVector_RemoveAndTake(c_SmartPtrVector_t* self, c_size_t index, c_SmartPtr_t* ptr) {
    if (!self || index >= self->size) return C_ERR_PARAM;

    c_SmartPtr_t* target_slot = &self->array[index];

    if (ptr) {
        // 所有權剝离，交由外部接管
        c_SmartPtr_Move(ptr, target_slot);
    } else {
        // 靜默抹殺，遞减原子引用計數
        c_SmartPtr_Destroy(target_slot);
    }

    // 3. 自左向右推進，利用你的 Move 將右側後續有效項依序前移填補拓扑空缺
    for (c_size_t i = index; i < self->size - 1; i++) {
        c_SmartPtr_Move(&self->array[i], &self->array[i + 1]);
    }

    // 將滑移後的最後一項殘存記憶體空間強制做乾淨的原位抹零
    memset((void*)&self->array[self->size - 1], 0, sizeof(c_SmartPtr_t));

    self->size--;
    return C_ERR_OK;
}

c_err_t c_SmartPtrVector_Remove(c_SmartPtrVector_t* self, c_size_t index) {
    return c_SmartPtrVector_RemoveAndTake(self, index, NULL);
}