02

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

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

typedef  struct dynamic_memory_array_object
{
    void*              m_start;
    void*              m_finish;
    void*              m_utmost;
    size_t             m_element_size;
    ylib_fp_alloc_t    m_alloc;
    ylib_fp_dealloc_t  m_dealloc;
}  dymemarray;

dymemarray 声明于头文件 yc_dymemarr.h 中，实现于文件 yc_dymemarr.c 中。dymemarray
结构体的声明如上，dymemarray 在功能上类似于 C++ STL 中的 vector，但是它只能对能
直接在内存中进行复制的数据类型进行管理，也就是 C++ 中所说的 POD 类型，例如：int
或 struct point { int x; int y; }等。任何时候都不要直接对 dymemarray 的成员执行
写操作，应该通过下面介绍的函数对 dymemarray 进行操作。为了在不支持内联函数的编译
器上提高执行效率，在 yc_dymemarr.h 中提供了一些内联宏。

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

1、void dymemarr_init( dymemarray* uninit_self,
                       size_t element_size,
                       ylib_fp_alloc_t alloc,
                       ylib_fp_dealloc_t dealloc )
功能
    初始化 dymemarray。
参数
    uninit_self：指向一个未初始化的 dymemarray；
    element_size：dymemarray 中元素的大小，单位为字节；
    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。

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

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

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

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

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

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

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

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

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

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

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

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

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

8、void* dymemarr_to_string( dymemarray* self,
                             const void* end_of_str )
功能
    尝试将一个 dymemarray 转换为字符串。
参数
    self：指向一个已初始化的 dymemarray；
    end_of_str：指向一个字符串的结束符，可以为 NULL。
返回值
    不论能否转换均返回动态数组的首地址。
备注
    当存储的元素类型为各类字符时，可以调用该函数在末尾加上结束符变成字符串。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

17、bool dymemarr_replace_fill( dymemarray* self,
                                size_t index,
                                size_t old_count,
                                const void* value,
                                size_t new_count )
功能
    将 [index, index + old_count) 替换为 new_count 个 value。
参数
    self：指向一个已初始化的 dymemarray；
    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) 之间的元素值将处于未定义状态。

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

18、bool dymemarr_replace_array( dymemarray* self,