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

# 尝试 Push & Remove 元素

### 前提条件

首先，我们需要创建一个 Vector 对象实例，以便我们进行 push & remove 元素操作。

{% code title="C" %}

```c
Vector vector_object = vector_helper_create_object(sizeof(int), 1, 99);
if(!vector_object)
{
    printf("main -> vector_helper_create_object error");
}
```

{% endcode %}

好的，我们已创建了一个包含 Vector Int Array 的 Vector 对象实例，并验证了 Vector 对象实例描述符的有效性。该 Vector 对象实例初始可容纳元素个数为 1 个，最大可存放 99 个元素。

### 尝试 Push 元素

现在，我们向 Vector 对象实例 vector\_object 来 Push 1 个 int 元素：

{% code title="C" %}

```c
int element_value = 10;
size_t push_element_index = 0;
if(vector_helper_push_element(vector_object, &element_value, sizeof(element_value), 
    &push_element_index))
{
    printf("push element success, index = %zd", push_element_index);
}
else printf("main -> vector_helper_push_element error");
    
```

{% endcode %}

现在我们已经向 Vector 对象实例 push 了 1 个 int 元素，值为 `(int)10`。

{% hint style="info" %}
若您不需要得知新 Push 元素的索引号，函数 vector\_helper\_push\_element 最后一个参数（push\_element\_index）您可以设置为 NULL。
{% endhint %}

变量 `element_value` 为需要 Push 元素的值，应小于等于 Vector 对象实例单个元素大小，否则函数 `vector_helper_push_element` 为确保元素完整性而失败。

变量 `push_element_index` 为新 Push 元素的索引号，若函数 `vector_helper_push_element` 成功，则该变量将保存新 Push 进 Vector 对象实例的元素索引号。

### 尝试 Remove 元素

现在我们尝试 Remove 刚才 Push 的元素：

{% code title="C" %}

```c
bool remove_element_result = false;
vector_helper_remove_element(vector_object, push_element_index, 1, 
    &remove_element_result);
if(!remove_element_result)
{
    printf("main -> vector_helper_remove_element error");
}
```

{% endcode %}

我们已通过调用 `vector_helper_remove_element` 函数将刚才 Push 的元素从 Vector 对象实例中移除。

变量 `remove_element_result` 为函数 `vector_helper_remove_element`的执行结果，若元素被移除则该变量会被设置为 `true`，反之保持初始值不变。

{% hint style="warning" %}
函数 vector\_helper\_remove\_element 会返回调用后 Vector 对象实例中剩余的元素计数（个数），若操作失败则返回 0。值得注意的是，该返回值不可靠，不能依靠判断返回值是否为 0 来验证元素是否被成功移除。若尝试移除 Vector 对象实例中最后一个元素，即使成功也会返回 0，因为 Vector 对象实例中的确已经没有任何元素了（元素个数为 0）。应该通过该函数的最后一个参数 remove\_result 来验证移除结果，若元素被成功移除，则该参数指向的 bool 变量会被设置为 true，反之保持初始值不变。
{% endhint %}

### 尝试 Remove All 元素

假定，我们所创建的 Vector 对象实例中存在多个元素，但我们需要将这些元素全部 Remove，您可能会直接调用 `vector_helper_remove_element` 函数并这么做：

{% code title="C" %}

```c
size_t element_count = vector_helper_get_count(vector_object, 
    VectorCountType::kCurrentElementCount); // 得到指定 Vector 对象实例中有效的元素个数
if(element_count > 0) // 指定 Vector 对象实例是否不为空？
{
    // 从第 0 个元素索引号开始移除 element_count 个元素
    vector_helper_remove_element(vector_object, 0, element_count, NULL);
}
```

{% endcode %}

以上方式确实可以将 Vector 对象实例中的所有元素移除，但并不是最佳实现。您应该调用 `vector_helper_remove_all_element` 函数来快速移除所有元素：

{% code title="C" %}

```c
vector_helper_remove_all_element(vector_object);
```

{% endcode %}

从代码行数上，我们可以直观的看到差距，这有助于代码维护。而性能上函数 `vector_helper_remove_all_element` 的执行性能要比 `vector_helper_remove_element` 更快，同时您也不必计算当前 Vector 对象实例中的元素个数，从而减少了一次函数调用所带来的开销。

### 最后

最后不要忘记销毁我们所创建的 Vector 对象实例：

{% code title="C" %}

```c
vector_helper_destroy_object(vector_object);
vector_object = NULL;
```

{% endcode %}

### 相关 Vector Helper API 的详细介绍

{% content-ref url="/pages/-LNF20OR75BM43QDyMSS" %}
[元素存取与管理](/vector/apis/element.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://smallso.gitbook.io/vector/learn/2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.