vector_helper_try_reserve_element

从指定 Vector 对象实例中尝试预订一个或多个元素

Syntax

bool vector_helper_try_reserve_element
(
	VectorContext* vector_object_context, 
	size_t reserve_element_count, 
	size_t* reserve_element_start_index
);

Parameters

Return Value

类型：bool

描述：成功返回 True，失败返回 False

Remarks

参数 reserve_element_count的值应大于 0，因为您不能从指定 Vector 对象实例中预订 0 个元素。

若您不需要接收被预订的一个或多个元素的起始元素索引号，请将参数 reserve_element_start_index 设置为 NULL。

所预订的元素若不再使用，应调用 vector_helper_handover_element 函数撤销预订，而不是置之不理或调用 vector_helper_remove_element 函数移除它们，否则可能会导致不可预料的异常。

所预订的元素若已经使用，应调用 vector_helper_used_reserve_element 函数来确认使用，否则可能会导致不可预料的异常。

一个设计良好的应用程序应始终遵守如下代码逻辑来使用 Reserve & Handover 特性：

C
size_t reserve_element_index = 0;
if(vector_helper_try_reserve_element(..., ..., &reserve_element_index))
{
    bool operation_result = false; // 这一变量不是必须存在的
    ...
    if(operation_result)
    {
        // 操作成功
        vector_helper_used_reserve_element(..., VECTOR_USED_ALL_RESERVED_ELEMENT);
    }
    else vector_helper_handover_element(..., 0, 0, false); // 操作失败
}

vector_helper_handover_element

从指定 Vector 对象实例中撤销已预订的元素

Syntax

bool vector_helper_handover_element
(
	VectorContext* vector_object_context, 
	size_t reserve_element_start_index,
	size_t handover_element_count, 
	bool used_reserve_element
);

Parameters

Return Value

类型：bool

描述：指定预订元素撤销成功返回 True，失败返回 False。

Remarks

参数 reserve_element_start_index 的值应确保为预订的一个或多个元素的索引号，否则可能会导致不可预料的异常。

参数 handover_element_count 应确保小于等于实际预订元素个数，否则可能会导致不可预料的异常。

若参数 used_reserve_element 的值为 True，则指定待撤销的预订元素在被实际撤销之前，会进行内存区块格式化处理，以免元素值泄漏或被保留。

若参数 reserve_element_start_index 和 handover_element_count的值为 0，则此函数将撤销上一次预订的所有元素，该操作不可重复。一个设计良好的应用程序应确保 Reserve & Handover 操作是对应的、参数 reserve_element_start_index 和 handover_element_count 始终为 0。

vector_helper_used_reserve_element

确认从指定 Vector 对象实例中预订的一个或多个元素已被使用

Syntax

bool vector_helper_used_reserve_element
(
    VectorContext* vector_object_context, 
    size_t used_reserve_element_count
);

Parameters

Return Value

类型：bool

描述：成功确认一个或多个预订元素的使用返回 True，反之返回 False。

Remarks

参数 used_reserve_element_count 的值应小于等于上一次预订元素的个数，否则函数将失败。

若上一次预订的所有元素均已确认使用，请将参数 used_reserve_element_count 的值设置为 0 或 VECTOR_USED_ALL_RESERVED_ELEMENT 宏。

一个设计良好的应用程序应始终确保上一次预订的所有元素均已被使用，并且参数 used_reserve_element_count 被设置为 VECTOR_USED_ALL_RESERVED_ELEMENT 宏。

上一次预订的一个或多个元素确认使用后，将不能被撤销，否则可能会导致不可预料的异常。

​