> 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/learn/1.md).

# 快速创建与销毁 Vector 对象实例

本页将介绍 Vector Helper 抽象概念

### 如何使用 Vector Helper？

Vector Helper 模块的所有函数与数据类型均声明在 `vector_helper.h` 标头文件中，您只需要在您项目中需要使用 Vector Helper 模块的代码文件中包含 `vector_helper.h` 即可。

{% code title="C/C++" %}

```cpp
#include "vector_helper.h"
```

{% endcode %}

{% hint style="warning" %}
您应该在包含您项目所需的 C/C++ 标头之后再包含 vector\_helper.h
{% endhint %}

### 什么是 Vector 对象实例？

每个 Vector Array 均被抽象描述为 Vector 对象实例，而每个 Vector 对象实例均由 `Vector` 类型所表示，而使用该类型定义的变量均为指针，被抽象描述为 Vector 对象实例描述符，该类型被定义在 `vector_helper.h` 中。

{% code title="C" %}

```c
typedef struct _VectorContext
{
	size_t current_element_count;
	size_t last_reserved_element_count;
	size_t max_element_count;
	size_t current_alloc_count;
	size_t current_alloc_memory_size;
	size_t single_element_size;
	void** element;
} VectorContext, *Vector;
```

{% endcode %}

{% content-ref url="/pages/-LNKKEbVlAuv9wzEX5J4" %}
[数据结构和枚举器](/vector/apis/struct.md)
{% endcontent-ref %}

在您使用 Vector Helper API 时，均需要提供 Vector 对象实例描述符。

{% hint style="warning" %}
除非必要，为了确保 Vector 对象实例完整性，您不应该直接通过 Vector 对象实例描述符指针变量访问 VectorContext 数据结构的成员，应调用 Vector Helper API。
{% endhint %}

### 如何创建与销毁 Vector 对象实例？

您可以通过调用 Vector Helper API 来快速创建一个 Vector 对象实例：

{% code title="C" %}

```c
Vector vector_object = vector_helper_create_object(sizeof(int), 1, 99);
```

{% endcode %}

通过上述代码，我们快速创建了一个 Vector 对象实例，并得到了该 Vector 对象实例的描述符，它包含一个 Vector Int 数组。单个元素大小为 `sizeof(int)`，初始预留 1 个元素大小的容量，最多允许存放 99 个元素。当然，若您不希望设置最大元素个数，可以将最后一个参数设置为 `VECTOR_NO_MAX_ELEMENT` 宏。

{% hint style="info" %}
建议在创建 Vector 对象实例时，预估您可能存放的元素个数，并合理设置初始预留元素数量，这可能会减少内存分配器的运行次数，提升元素存取性能。请注意，初始预留元素个数为预留可容纳指定元素个数的容量（也即内存），并非使用空元素进行填充。
{% endhint %}

现在我们尝试销毁它：

{% code title="C" %}

```c
if(vector_object)
{
    vector_helper_destroy_object(vector_object);
    vector_object = NULL;
}
```

{% endcode %}

现在，我们已销毁了由 `vector_helper_create_object` 创建的 Vector 对象实例和描述符。

{% hint style="warning" %}
值得注意的是，变量 vector\_object 也即 Vector 对象实例描述符所指向的 Vector 对象实例已被销毁，因此该描述符已经不可用（无效指针），应该使用 NULL 赋值。
{% endhint %}

{% content-ref url="/pages/-LNEsm8BfzId72aMy0vo" %}
[Vector 对象实例生命周期](/vector/apis/object.md)
{% endcontent-ref %}