cKit/Foundation/c_ArrayList.c

#include <c_ArrayList.h>

c_err_t c_ArrayList_Init(c_ArrayList_t *self, c_size_t item_size, c_size_t capacity, c_Allocator_t *allocator) {
    if (!self || item_size==0) return C_ERR_PARAM;
    self->allocator = (allocator!=NULL)?*allocator:c_DefaultAllocator;
    self->item_size = item_size;
    self->capacity = capacity;
    self->size = 0;

    if (self->capacity==0) {
        self->array = NULL;
    }else {
        self->array = c_Allocator_Alloc(&self->allocator, self->capacity * self->item_size);
        if (!self->array) {
            return C_ERR_NOMEM;
        }
    }
    return C_ERR_OK;
}

void c_ArrayList_Destroy(c_ArrayList_t* self) {
    if (!self) {
        return;
    }
    if (self->array) {
        c_Allocator_Free(&self->allocator, self->array);
        self->array = NULL;
    }
    self->size = 0;
    self->capacity = 0;
}

c_err_t c_ArrayList_Resize(c_ArrayList_t* self, c_size_t new_capacity) {
    if (!self) return C_ERR_PARAM;
    // 情况 1: 如果新旧容量完全相同，无需任何操作，直接返回成功
    if (new_capacity == self->capacity) {
        return C_ERR_OK;
    }
    // 情况 2: 如果新容量为 0，等同于清空并释放内部数据缓冲区
    if (new_capacity==0) {
        if (self->array) {
            c_Allocator_Free(&self->allocator, self->array);
            self->array = NULL;
        }
        self->capacity = 0;
        self->size = 0;
        return C_ERR_OK;
    }

    // 溢出检查：防止 new_capacity * item_size 导致乘法回绕引发堆破坏
    if (new_capacity > (c_size_t)-1 / self->item_size) {
        return C_ERR_OUTOFBOUND;
    }

    const c_size_t old_bytes = self->capacity * self->item_size;
    const c_size_t new_bytes = new_capacity * self->item_size;

    // 调用绑定的自定义/伙伴系统 Realloc 接口
    void* new_array = c_Allocator_Realloc(&self->allocator, self->array, old_bytes, new_bytes);
    if (!new_array) {
        return C_ERR_NOMEM; // 内存分配失败，保持原有状态不变（强异常安全性）
    }

    // 更新内部状态
    self->array = new_array;
    self->capacity = new_capacity;

    // 安全边界截断：如果新容量调小了，且当前已有元素数量超过了新容量，则被迫截断
    if (self->size > new_capacity) {
        self->size = new_capacity;
    }

    return C_ERR_OK;
}

c_err_t c_ArrayList_Add(c_ArrayList_t* self, const void* item) {
    if (!self || !item) return C_ERR_PARAM;
    if (self->size >= self->capacity) {
        return C_ERR_FULL;
    }
    char* target = (char*)self->array + (self->size * self->item_size);
    memcpy(target, item, self->item_size);
    self->size++;
    return C_ERR_OK;
}

void* c_ArrayList_Get(const c_ArrayList_t* self, c_size_t index) {
    if (!self || index>=self->size) return NULL;
    return (uint8_t*)self->array + (index * self->item_size);
}

c_err_t c_ArrayList_Read(const c_ArrayList_t* self, c_size_t index, void* out_item) {
    if (!self || index >= self->size) {
        return C_ERR_PARAM;
    }

    // 计算内部源数据的绝对物理字节地址
    const char* source = (const char*)self->array + (index * self->item_size);

    // 将底层数据值深度拷贝（复制）到用户提供的缓冲区中
    if (out_item) {
        memcpy(out_item, source, self->item_size);
    }

    return C_ERR_OK;
}

c_err_t c_ArrayList_RemoveAt(c_ArrayList_t* self, c_size_t index, void* out_item) {
    if (!self) return C_ERR_PARAM;
    if (self->size == 0) return C_ERR_EMPTY;
    if (index >= self->size) return C_ERR_OUTOFBOUND;

    char* target = (char*)self->array + (index * self->item_size);

    if (out_item) {
        memcpy(out_item, target, self->item_size);
    }

    if (index < self->size - 1) {
        char* next = target + self->item_size;
        c_size_t move_bytes = (self->size - index - 1) * self->item_size;
        memmove(target, next, move_bytes);
    }

    self->size--;
    return C_ERR_OK;
}

c_err_t c_ArrayList_Set(const c_ArrayList_t* self, c_size_t index, const void* item) {
    if (!self || !item) return C_ERR_PARAM;
    if (index >= self->size) return C_ERR_OUTOFBOUND;
    char* target = (char*)self->array + (index * self->item_size);
    memcpy(target, item, self->item_size);
    return C_ERR_OK;
}

c_err_t c_ArrayList_PopBack(c_ArrayList_t* self, void* out_item) {
    if (!self ) return C_ERR_PARAM;
    if (self->size==0) return C_ERR_EMPTY;

    self->size--;

    if (out_item) {
        char* target = (char*)self->array + (self->size) * self->item_size;
        memcpy(out_item, target, self->item_size);
    }

    return C_ERR_OK;
}

c_err_t c_ArrayList_PopBackResize(c_ArrayList_t* self, void* out_item) {
    if (!self ) return C_ERR_PARAM;
    if (self->size==0) return C_ERR_EMPTY;

    self->size--;

    if (out_item) {
        char* target = (char*)self->array + (self->size) * self->item_size;
        memcpy(out_item, target, self->item_size);
    }

    // 🌟【弹性内存缩容锁】：若当前存量过低 (N <= Capacity/4) 且长于基本配额，主动腰斩退还内存给系统
    if (self->size > 0 && self->size <= (self->capacity >> 2)) {
        c_ArrayList_Resize(self, self->capacity >> 1);
    }

    return C_ERR_OK;
}

c_err_t c_ArrayList_ResizeAdd(c_ArrayList_t* self, const void* item) {
    if (!self || !item) return C_ERR_PARAM;

    if (self->size >= self->capacity) {
        c_err_t err = c_ArrayList_Resize(self, (self->capacity==0)?4:(self->capacity<<1));
        if (err!=C_ERR_OK) return err;
    }

    char* target = (char*)self->array + (self->size * self->item_size);
    memcpy(target, item, self->item_size);
    self->size++;
    return C_ERR_OK;
}