元素预订与撤销

本页将介绍与元素存取高级特性相关的 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_indexhandover_element_count的值为 0,则此函数将撤销上一次预订的所有元素,该操作不可重复。一个设计良好的应用程序应确保 Reserve & Handover 操作是对应的、参数 reserve_element_start_indexhandover_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 宏。

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