尝试 Push & Remove 元素

本页将介绍如何向指定 Vector 对象实例进行元素的 push & remove 操作

前提条件

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

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

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

尝试 Push 元素

现在,我们向 Vector 对象实例 vector_object 来 Push 1 个 int 元素:

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");

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

若您不需要得知新 Push 元素的索引号,函数 vector_helper_push_element 最后一个参数(push_element_index)您可以设置为 NULL。

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

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

尝试 Remove 元素

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

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");
}

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

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

函数 vector_helper_remove_element 会返回调用后 Vector 对象实例中剩余的元素计数(个数),若操作失败则返回 0。值得注意的是,该返回值不可靠,不能依靠判断返回值是否为 0 来验证元素是否被成功移除。若尝试移除 Vector 对象实例中最后一个元素,即使成功也会返回 0,因为 Vector 对象实例中的确已经没有任何元素了(元素个数为 0)。应该通过该函数的最后一个参数 remove_result 来验证移除结果,若元素被成功移除,则该参数指向的 bool 变量会被设置为 true,反之保持初始值不变。

尝试 Remove All 元素

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

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);
}

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

C
vector_helper_remove_all_element(vector_object);

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

最后

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

C
vector_helper_destroy_object(vector_object);
vector_object = NULL;

相关 Vector Helper API 的详细介绍