03

一个类STL的多平台可移植的算法容器库,主要用于嵌入式系统编程时的内存管理等方面

********************************************************************************

typedef  struct dynamic_resource_array_object
{
    void*              m_start;
    void*              m_finish;
    void*              m_utmost;
    size_t             m_element_size;
    ylib_fp_oper_t     m_elmt_init;
    ylib_fp_copy_t     m_elmt_init_copy;
    ylib_fp_copy_t     m_elmt_assign_copy;
    ylib_fp_move_t     m_elmt_init_move;
    ylib_fp_move_t     m_elmt_assign_move;
    ylib_fp_oper_t     m_elmt_destroy;
    ylib_fp_alloc_t    m_alloc;
    ylib_fp_dealloc_t  m_dealloc;
}  dyrscarray;

dyrscarray 声明于头文件 yc_dyrscarr.h 中，实现于文件 yc_dyrscarr.c 中。dyrscarray
结构体的声明如上，dyrscarray 在功能上类似于 C++ STL 中的 vector，它可以管理所有的
数据类型，但是在管理可直接在内存中进行复制的数据类型时效率不如 dymemarray。任何时
候都不要直接对 dyrscarray 的成员执行写操作，应该通过下面介绍的函数对 dyrscarray
进行操作。为了在不支持内联函数的编译器上提高执行效率，在 yc_dyrscarr.h 中提供了
一些内联宏。

********************************************************************************

1、void dyrscarr_init( dyrscarray* uninit_self,
                       size_t element_size,
                       ylib_fp_oper_t elmt_init,
                       ylib_fp_copy_t elmt_init_copy,
                       ylib_fp_copy_t elmt_assign_copy,
                       ylib_fp_move_t elmt_init_move,
                       ylib_fp_move_t elmt_assign_move,
                       ylib_fp_oper_t elmt_destroy,
                       ylib_fp_alloc_t alloc,
                       ylib_fp_dealloc_t dealloc )
功能
    初始化 dyrscarray。
参数
    uninit_self：指向一个未初始化的 dyrscarray；
    element_size：dyrscarray 中元素的大小，单位为字节；
    elmt_init：元素的初始化函数，类似于 C++ 中的默认构造函数；
    elmt_init_copy：将一个已初始化的元素数据复制给另一个未初始化的元素，类似于
                    C++ 中的复制构造函数；
    elmt_assign_copy：将一个已初始化的元素数据复制给另一个已初始化的元素，类似于
                      C++ 中重载的赋值操作符；
    elmt_init_move：将一个已初始化的元素数据移动至另一个未初始化的元素；
    elmt_assign_move：将一个已初始化的元素数据移动至另一个已初始化的元素；
    elmt_destroy：释放元素，类似于 C++ 中的析构函数；
    alloc：负责动态内存分配的函数指针，原型声明为 void* alloc( size_t bytes )，
           参数 bytes 为申请的字节数，执行成功则返回一个指向分配内存块的空指针，
           执行失败则返回 NULL；
    dealloc：负责动态内存释放的函数指针，原型声明为
             void dealloc( void* ptr, size_t bytes )，参数 ptr 指向要释放的动态
             内存，参数 bytes 表示要释放的内存字节数。
备注
    该函数功能类似于 C++ 中类的构造函数，可以把内存池函数 pool_alloc 和
    pool_dealloc 赋值给参数 alloc 和 dealloc。
    ylib_fp_oper_t、ylib_fp_copy_t 和 ylib_fp_move_t 在 yc_definition.h中声明。
    elmt_init、elmt_init_copy、elmt_assign_copy、elmt_init_move、elmt_assign_move、
    elmt_destroy 都必须是运行时安全，能够在函数内部处理所有异常的函数。

********************************************************************************

2、void dyrscarr_reinit( dyrscarray* self,
                         size_t element_size,
                         ylib_fp_oper_t elmt_init,
                         ylib_fp_oper_t elmt_destroy,
                         ylib_fp_copy_t elmt_init_copy,
                         ylib_fp_copy_t elmt_assign_copy,
                         ylib_fp_move_t elmt_init_move,
                         ylib_fp_move_t elmt_assign_move )
功能
    对一个已初始化的 dyrscarray 重新构造。
参数
    self：指向一个已初始化的 dyrscarray；
    element_size：新的元素的大小，单位为字节。
    elmt_init：同 dyrscarr_init；
    elmt_init_copy：同 dyrscarr_init；
    elmt_assign_copy：同 dyrscarr_init；
    elmt_init_move：同 dyrscarr_init；
    elmt_assign_move：同 dyrscarr_init；
    elmt_destroy：同 dyrscarr_init。
备注
    该函数先将存储空间内的数据清空，然后在现有的空间内重新构造一个元素大小为
    element_size 的新动态数组，使用该函数可以充分利用现有的资源，不必经常向系统
    申请动态空间。

********************************************************************************

3、void dyrscarr_destroy( dyrscarray* self )
功能
    释放一个 dyrscarray。
参数
    self：指向一个已初始化的 dyrscarray。
备注
    该函数功能类似于 C++ 中类的析构函数。

********************************************************************************

4、int dyrscarr_init_copy( dyrscarray* uninit_self,
                           const dyrscarray* src )
功能
    将一个已初始化的 dyrscarray 内的数据复制到另一个未初始化的 dyrscarray 内。
参数
    uninit_self：指向一个未初始化的 dyrscarray，复制操作的目的地；
    src：指向一个已初始化的 dyrscarray，复制操作的源。
返回值
    < 0：uninit_self 和 src 是同一个 dyrscarray；
    = 0：复制失败；
    > 0：复制成功。
备注
    该函数功能类似于 C++ 中类的复制构造函数。

********************************************************************************

5、int dyrscarr_assign_copy( dyrscarray* self,
                             const dyrscarray* src )
功能
    将一个已初始化的 dyrscarray 内的数据复制到另一个已初始化的 dyrscarray 内。
参数
    self：指向一个已初始化的 dyrscarray，复制操作的目的地；
    src：指向一个已初始化的 dyrscarray，复制操作的源。
返回值
    < 0：self 和 src 是同一个 dyrscarray；
    = 0：复制失败；
    > 0：复制成功。
备注
    该函数功能类似于 C++ 中类的重载赋值操作符。

********************************************************************************

6、void dyrscarr_init_move( dyrscarray* uninit_self,
                            dyrscarray* src )
功能
    将一个已初始化的 dyrscarray 内的数据移动到另一个未初始化的 dyrscarray 内。
参数
    uninit_self：指向一个未初始化的 dyrscarray，移动操作的目的地；
    src：指向一个已初始化的 dyrscarray，移动操作的源。
备注
    该函数执行完后，uninit_self 将拥有原 src 的数据，而 src 将被清空。

********************************************************************************

7、void dyrscarr_assign_move( dyrscarray* self,
                              dyrscarray* src )
功能
    将两个已初始化的 dyrscarray 内的数据交换。
参数
    self：指向一个已初始化的 dyrscarray；
    src：指向一个已初始化的 dyrscarray。
备注
    该函数执行完后，self 将拥有原 src 的数据，而 src 将拥有原 self 的数据。

********************************************************************************

8、bool dyrscarr_reserve( dyrscarray* self,
                          size_t new_capacity )
功能
    预申请指定大小的空间。
参数
    self：指向一个已初始化的 dyrscarray；
    new_capacity：预申请的空间所能容纳的元素个数。
返回值
    申请成功返回 true，失败返回 false。
备注
    已有的数据不会变化。

********************************************************************************

9、void dyrscarr_erase_pos( dyrscarray* self,
                            size_t index )
功能
    删除 index 处的元素。
参数
    self：指向一个已初始化的 dyrscarray；
    index：待删除元素的索引。

********************************************************************************

10、void dyrscarr_erase_range( dyrscarray* self,
                               size_t first_index,
                               size_t last_index )
功能
    删除 [first_index, last_index) 内的元素。
参数
    self：指向一个已初始化的 dyrscarray；
    first_index：待删除区间的第一个元素的索引；
    last_index：待删除区间之后的第一个元素的索引。
备注
    该函数将 [first_index, last_index) 自数组中删除，如果第二个参数可以越界，此
    时将删除自 first_index 开始的所有元素。
    例：dyrscarr_erase_range( arr, 0, SIZE_MAX ) 将清空数组。

********************************************************************************

11、bool dyrscarr_insert_value( dyrscarray* self,
                                size_t index,
                                const void* value,
                                size_t count )
功能
    在 index 之前一个位置插入 count 个值等于 value 的元素。
参数
    self：指向一个已初始化的 dyrscarray；
    index：插入位置的索引；
    value：待插入的元素的值；
    count：待插入的元素的个数。
返回值
    函数执行成功返回 true，失败返回 false。
备注
    若 value 等于 NULL，则 [index, index + count) 之间的元素值将处于未定义状态。

********************************************************************************

12、bool dyrscarr_insert_array( dyrscarray* self,
                                size_t index,
                                const void* src,
                                size_t count )
功能
    在 index 之前一个位置插入 src 的前 count 个元素。
参数
    self：指向一个已初始化的 dyrscarray；
    index：插入位置的索引；
    src：待插入的数组首地址；
    count：待插入的元素的个数。
返回值
    函数执行成功返回 true，失败返回 false。
备注
    若 src 等于 NULL，则 [index, index + count) 之间的元素值将处于未定义状态。

********************************************************************************

13、bool dyrscarr_push_back( dyrscarray* self,
                             const void* value )
功能
    在 dyrscarray 的尾端插入 value。
参数
    self：指向一个已初始化的 dyrscarray；
    value：待插入的元素的值。
返回值
    函数执行成功返回 true，失败返回 false。

********************************************************************************

14、void dyrscarr_pop_back( dyrscarray* self )
功能
    从 dyrscarray 的尾端删除最后一个元素。
参数
    self：指向一个已初始化的 dyrscarray。
备注
    如果 dyrscarray 为空，执行该函数不会出错。

********************************************************************************

15、bool dyrscarr_resize( dyrscarray* self,
                          size_t new_length,
                          const void* value )
功能
    改变 dyrscarray 的大小。
参数
    self：指向一个已初始化的 dyrscarray；
    new_length：重新指定的 dyrscarray 大小；
    value：需要新增元素时填充的值。
返回值
    函数执行成功返回 true，失败返回 false。
备注
    如果 new_length 等于当前 dyrscarray 的大小，则不执行任何操作；
    如果 new_length 大于当前 dyrscarray 的大小，则从尾端开始删除多余的元素；
    如果 new_length 小于当前 dyrscarray 的大小，则从尾端开始插入元素以补足大小，
    插入的元素以 value 的值来填充。

********************************************************************************

16、bool dyrscarr_replace_fill( dyrscarray* self,
                                size_t index,
                                size_t old_count,
                                const void* value,
                                size_t new_count )
功能
    将 [index, index + old_count) 替换为 new_count 个 value。
参数
    self：指向一个已初始化的 dyrscarray；
    index：替换开始位置的索引；
    old_count：从 index 开始被替换的元素个数；
    value：指向待替换的元素的值；
    new_count：操作完成后，从 index 开始值等于 value 的元素的个数。
返回值
    函数执行成功返回 true，失败返回 false。
备注
    如果 new_count = old_count，则只执行元素替换操作；
    如果 new_count < old_count，则先执行元素替换操作，再删除多余的元素；
    如果 new_count > old_count，则先执行元素替换操作，再插入余下的元素；
    若 value 等于 NULL，则 [index, index + new_count) 之间的元素值将处于未定义状态。

********************************************************************************

17、bool dyrscarr_replace_array( dyrscarray* self,
                                 size_t index,
                                 size_t old_count,
                                 const void* src,