元素预订与撤销

本页将介绍与元素存取高级特性相关的 Vector Helper API

vector_helper_try_reserve_element

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

此函数已确保本次 Reserve & Handover 操作的完整性，因此当指定个数的元素预订成功后，您无需担心也不需要处理对预订元素的 Set 操作失败的情况。

Syntax

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

Parameters

参数名	类型	必选	描述
vector_object_context	Vector	True	指定 Vector 对象实例描述符
reserve_element_count	size_t	True	需要预订的元素个数
reserve_element_start_index	size_t*	False	指向接收被预订的单个或多个元素 的起始索引号的变量

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

参数名	类型	必选	描述
vector_object_context	Vector	True	指定 Vector 对象实例描述符
reserve_element_start_index	size_t	False	需要撤销的预订元素起始元素索引号
handover_element_count	size_t	False	需要撤销的预订元素个数
used_reserve_element	size_t	True	被撤销的预订元素是否已经被使用

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。

当参数 reserve_element_start_index 和 handover_element_count 均为 0 时，此函数将采用快速撤销策略，这有助于确保 Reserve & Handover 操作的完整性及执行性能。

vector_helper_used_reserve_element

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

Syntax

bool vector_helper_used_reserve_element
(
    VectorContext* vector_object_context, 
    size_t used_reserve_element_count
);

Parameters

参数名	类型	必选	描述
vector_object_context	Vector	True	指定 Vector 对象实例
used_reserve_element_count	size_t	False	已使用的预订元素个数

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 宏。

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