03

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

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

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

18、bool dyrscarr_empty( dyrscarray* self )
功能
    判断 dyrscarray 是否为空。
参数
    self：指向一个已初始化的 dyrscarray。
返回值
    如果 dyrscarray 为空返回 true，否则返回 false。

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

19、size_t dyrscarr_max_size( dyrscarray* self )
功能
    获取硬件所能支持的 dyrscarray 存储的最大元素个数。
参数
    self：指向一个已初始化的 dyrscarray。
返回值
    返回 dyrscarray 能够存储的最大元素个数。

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

20、size_t dyrscarr_size( dyrscarray* self )
功能
    获取 dyrscarray 存储的元素个数。
参数
    self：指向一个已初始化的 dyrscarray。
返回值
    返回 dyrscarray 当前存储的元素个数。

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

21、size_t dyrscarr_capacity( dyrscarray* self )
功能
    获取 dyrscarray 的容量。
参数
    self：指向一个已初始化的 dyrscarray。
返回值
    返回 dyrscarray 当前能够存储的最大元素个数。

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

22、size_t dyrscarr_space( dyrscarray* self )
功能
    获取 dyrscarray 剩余的容量。
参数
    self：指向一个已初始化的 dyrscarray。
返回值
    返回 dyrscarray 当前还能存储的元素个数。

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

23、void* dyrscarr_begin( dyrscarray* self )
功能
    获取 dyrscarray 首端元素的地址。
参数
    self：指向一个已初始化的 dyrscarray。
返回值
    返回 dyrscarray 首端元素的地址。

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

24、void* dyrscarr_end( dyrscarray* self )
功能
    获取 dyrscarray 尾端的地址。
参数
    self：指向一个已初始化的 dyrscarray。
返回值
    返回 dyrscarray 尾端的地址。
备注
    尾端就是 dyrscarray 最后一个有效元素的末尾，首端和尾端以一个半闭半开的区间来
    表示 dyrscarray 的有效范围：[dyrscarr_begin, dyrscarr_end)。

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

25、void* dyrscarr_front( dyrscarray* self )
功能
    获取第一个元素的地址。
参数
    self：指向一个已初始化的 dyrscarray。
返回值
    返回第一个元素的地址。

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

26、void* dyrscarr_back( dyrscarray* self )
功能
    获取最后一个元素的地址。
参数
    self：指向一个已初始化的 dyrscarray。
返回值
    返回最后一个元素的地址。

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

27、void* dyrscarr_index( dyrscarray* self,
                          size_t index )
功能
    获取 index 处元素的地址。
参数
    self：指向一个已初始化的 dyrscarray；
    index：待访问的元素的索引。
返回值
    返回指定的元素的地址。
备注
    函数不会对 index 的值进行越界检查，如果 index >= dyrscarr_size(self)，返回的
    地址指向的元素将处于未定义状态。

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

28、void* dyrscarr_at( dyrscarray* self,
                       size_t index )
功能
    获取 index 处元素的地址。
参数
    self：指向一个已初始化的 dyrscarray；
    index：待访问的元素的索引。
返回值
    如果 index < dyrscarr_size(self)，则返回指定的元素的地址；否则返回 NULL。
备注
    函数会对 index 的值进行越界检查，所以速度会比 dyrscarr_index 稍慢。

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

29、void dyrscarr_reverse( dyrscarray* self )
功能
    将整个 dyrscarray 反转。
参数
    self：指向一个已初始化的 dyrscarray。

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

                                   内  联  宏

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

30、DYRSCARR_BEGIN( ARRAY, TYPE )
功能
    dyrscarr_begin 函数的内联宏。
参数
    ARRAY：一个已初始化的 dyrscarray 实体；
    TYPE：dyrscarray 中元素的类型。
返回值
    返回一个 TYPE 类型的指针，其指向 dyrscarray 的首端元素。

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

31、DYRSCARR_END( ARRAY, TYPE )
功能
    dyrscarr_end 函数的内联宏。
参数
    ARRAY：一个已初始化的 dyrscarray 实体；
    TYPE：dyrscarray 中元素的类型。
返回值
    返回一个 TYPE 类型的指针，其指向 dyrscarray 的尾端元素。

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

32、DYRSCARR_FRONT( ARRAY, TYPE )
功能
    dyrscarr_front 函数的内联宏。
参数
    ARRAY：一个已初始化的 dyrscarray 实体；
    TYPE：dyrscarray 中元素的类型。
返回值
    返回一个 TYPE 类型的值，其值等于 dyrscarray 第一个元素的值。

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

33、DYRSCARR_BACK( ARRAY, TYPE )
功能
    dyrscarr_back 函数的内联宏。
参数
    ARRAY：一个已初始化的 dyrscarray 实体；
    TYPE：dyrscarray 中元素的类型。
返回值
    返回一个 TYPE 类型的值，其值等于 dyrscarray 最后一个元素的值。

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

34、DYRSCARR_INDEX( ARRAY, INDEX, TYPE )
功能
    dyrscarr_index 函数的内联宏。
参数
    ARRAY：一个已初始化的 dyrscarray 实体；
    INDEX：待访问的元素的索引；
    TYPE：dyrscarray 中元素的类型。
返回值
    返回一个 TYPE 类型的值，其值等于 dyrscarray 第 INDEX 个元素的值。

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

35、DYRSCARR_SIZE( ARRAY, TYPE )
功能
    dyrscarr_size 函数的内联宏。
参数
    ARRAY：一个已初始化的 dyrscarray 实体；
    TYPE：dyrscarray 中元素的类型。
返回值
    同 dyrscarr_size。

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

36、DYRSCARR_CAPACITY( ARRAY, TYPE )
功能
    dyrscarr_capacity 函数的内联宏。
参数
    ARRAY：一个已初始化的 dyrscarray 实体；
    TYPE：dyrscarray 中元素的类型。
返回值
    同 dyrscarr_capacity。

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

37、DYRSCARR_SPACE( ARRAY, TYPE )
功能
    dyrscarr_space 函数的内联宏。
参数
    ARRAY：一个已初始化的 dyrscarray 实体；
    TYPE：dyrscarray 中元素的类型。
返回值
    同 dyrscarr_space。

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

38、DYRSCARR_POP_BACK_MEM( ARRAY, TYPE )
功能
    dyrscarr_pop_back 函数的内联宏之一。
参数
    ARRAY：一个已初始化的 dyrscarray 实体；
    TYPE：dyrscarray 中元素的类型。
返回值
    同 dyrscarr_pop_back。
备注
    当 dyrscarray 的 m_elmt_destroy 成员为 NULL 才可以调用该宏。

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

39、DYRSCARR_POP_BACK_FUN( ARRAY, TYPE )
功能
    dyrscarr_pop_back 函数的内联宏之二。
参数
    ARRAY：一个已初始化的 dyrscarray 实体；
    TYPE：dyrscarray 中元素的类型。
返回值
    同 dyrscarr_pop_back。
备注
    当 dyrscarray 的 m_elmt_destroy 成员不为 NULL 才可以调用该宏。

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

40、DYRSCARR_PUSH_BACK_MEM( ARRAY, VAL, TYPE, BOOLVAL )
功能
    dyrscarr_push_back 函数的内联宏之一。
参数
    ARRAY：一个已初始化的 dyrscarray 实体；
    VAL：待插入的元素值；
    TYPE：dyrscarray 中元素的类型，
    BOOLVAL：记录插入状态的 bool 值，插入成功该值为 true，否则为 false。
返回值
    无。
备注
    当 dyrscarray 的 m_elmt_init_copy 成员为 NULL 时才可以调用该宏。

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

41、DYRSCARR_PUSH_BACK_FUN( ARRAY, VAL, TYPE, BOOLVAL )
功能
    dyrscarr_push_back 函数的内联宏之一。
参数
    ARRAY：一个已初始化的 dyrscarray 实体；
    VAL：待插入的元素值；
    TYPE：dyrscarray 中元素的类型，
    BOOLVAL：记录插入状态的 bool 值，插入成功该值为 true，否则为 false。
返回值
    无。
备注
    当 dyrscarray 的 m_elmt_init_copy 成员不为 NULL 时才可以调用该宏。

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