> For the complete documentation index, see [llms.txt](https://smallso.gitbook.io/vector/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://smallso.gitbook.io/vector/apis/reserve.md).

# 元素预订与撤销

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

## vector\_helper\_try\_reserve\_element

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

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

#### Syntax

```c
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 | <p>指向接收被预订的单个或多个元素</p><p>的起始索引号的变量</p> |

#### 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** 特性：

{% code title="C" %}

```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); // 操作失败
}
```

{% endcode %}

## vector\_helper\_handover\_element

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

#### Syntax

```c
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。

{% hint style="info" %}
当参数 reserve\_element\_start\_index 和 handover\_element\_count 均为 0 时，此函数将采用快速撤销策略，这有助于确保 **Reserve & Handover** 操作的完整性及执行性能。
{% endhint %}

## vector\_helper\_used\_reserve\_element

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

#### Syntax

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

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