元素存取与管理

本页将介绍与元素存取与管理相关的 Vector Helper API

vector_helper_push_element

向指定 Vector 对象实例的尾部 Push 一个元素

Syntax

bool vector_helper_push_element
(
	VectorContext* vector_object_context, 
	const void* element_value,
	size_t element_value_size, 
	size_t* push_element_index
);

Parameters

参数名	类型	必选	描述
vector_object_context	Vector	True	指定 Vector 对象实例
element_value	const void*	True	需要 Push 的元素内容
element_value_size	size_t	True	需要 Push 的元素内容大小（byte）
push_element_index	size_t*	False	指向接收新 Push 元素的索引号的变量

Return Value

类型：bool

描述：Push 元素成功返回 True，反之返回 False。

Remarks

您应该检查此函数的返回值来判断其元素是否 Push 成功，而不是假定一定成功。

当函数失败时，参数 push_element_index 指向的变量不会被修改。

若不需要接收 Push 元素的索引号，请将参数 push_element_index 设置为 NULL。

参数 element_value_size的值（byte）应小于等于指定 Vector 对象实例的单个元素大小（byte），否则函数将失败。

该函数适用于向指定 Vector 对象实例 Push 单一元素，若需连续 Push 多个元素，请调用 vector_helper_push_multiple_element 函数以确保操作完整性。

vector_helper_push_multiple_element

向指定 Vector 对象实例的尾部 Push 多个元素，该函数相对于分多次调用 vector_helper_push_element 函数，性能更高。

该函数会确保本次操作的完整性，遵循单个元素 Push 失败则全部失败，因此您不必担心也无需处理在执行 Push Multiple 操作的过程中出现单个元素 Push 失败的情况。

Syntax

bool vector_helper_push_multiple_element
(
	VectorContext* vector_object_context, 
	const void* multiple_element_value, 
	size_t single_element_value_size, 
	size_t push_element_count, 
	size_t* push_start_element_index
);

Parameters

参数名	类型	必选	描述
vector_object_context	Vector	True	指定 Vector 对象实例描述符
multiple_element_value	const void*	True	需要 Push 的多个元素数组
single_element_value_size	size_t	True	需要 Push 的多个元素数组中， 单个元素的大小（byte）
push_element_count	size_t	True	需要 Push 的元素个数
push_start_element_index	size_t*	False	指向接收 Push 的多个元素中 首个元素的索引号

Return Value

类型：bool

描述：若参数 multiple_element_value指向的待 Push 元素数组中指定个数的元素均 Push 成功则返回 True，反之返回 False。

Remarks

若不需要接收 Push 的多个元素中首个元素的索引号，请将参数 push_start_element_index设置为 NULL。

参数 push_element_count 的值应小于等于参数 multiple_element_value 所指向的待 Push 元素数组中实际有效的元素个数，否则可能会导致内存访问异常。

参数 single_element_value_size 的值（byte）应小于等于指定 Vector 对象实例的单个元素大小（byte），否则函数将失败。

当参数 single_element_value_size 的值（byte）等于指定 Vector 对象实例的单个元素大小（byte）时，此函数将进行 Align Push 策略，这有助于提升 Push Multiple 操作的执行性能。一个设计良好的应用程序，应确保会使用 Align Push 策略，而不是 Split Push 策略。

vector_helper_pop_element

从指定 Vector 对象实例的顶端 Pop 一个元素

Syntax

bool vector_helper_pop_element
(
	VectorContext* vector_object_context, 
	void* element_value,
	size_t element_value_size
);

Parameters

参数名	类型	必选	描述
vector_object_context	Vector	True	指定 Vector 对象实例描述符
element_value	void*	True	指向接收 Pop 元素值的缓冲区
element_value_size	size_t	True	接收 Pop 元素值的缓冲区大小（byte）

Return Value

类型：bool

描述：成功返回 True，失败返回 False。

Remarks

参数 element_value_size的值（byte）应大于等于指定 Vector 对象实例单个元素的大小（byte），否则为确保元素完整性，因此元素值不会被截断，函数将失败。

当指定 Vector 对象实例顶端的元素 Pop 成功后，被 Pop 的元素将从指定 Vector 对象实例中移除。

vector_helper_set_element

设置指定 Vector 对象实例中指定元素的值

Syntax

bool vector_helper_set_element
(
	VectorContext* vector_object_context, 
	size_t element_index,
	const void* element_value, 
	size_t element_value_size
);

Parameters

参数名	类型	必选	描述
vector_object_context	Vector	True	指定 Vector 对象实例描述符
element_index	size_t	True	需要设置的元素索引号
element_value	const void*	True	指向待设置的元素值缓冲区
element_value_size	size_t	True	待设置的元素值缓冲区大小（byte）

Return Value

类型：bool

描述：成功返回 True，失败返回 False

Remarks

参数 element_index 的值应位于指定 Vector 对象实例中有效的元素索引号（从 0 开始，含 0 本身），否则函数将失败。

参数 element_value 的值从 Vector Helper 1.0.1 版本起，必须设置为指向待设置的有效元素值缓冲区，不能设置为 NULL 以填空指定元素。若要填空指定元素，应指向空的元素值缓冲区。

参数 element_value_size 的值（byte）必须小于等于指定 Vector 对象实例单个元素的大小（byte），否则为确保元素完整性，函数将失败。

一个设计良好的应用程序应确保元素值缓冲区大小等于指定 Vector 对象实例单个元素的大小（byte），而不是截断元素值。

vector_helper_get_element

从指定 Vector 对象实例中获取指定元素的值

Syntax

size_t vector_helper_get_element
(
	VectorContext* vector_object_context, 
	size_t element_index,
	void* element_value, 
	size_t element_value_size
);

Parameters

参数名	类型	必选	描述
vector_object_context	Vector	True	指定 Vector 对象实例描述符
element_index	size_t	True	需要获取元素值的元素索引号
element_value	void*	True	指向接收元素值的缓冲区
element_value_size	size_t	True	接收元素值的缓冲区大小（byte）

Return Value

类型：size_t

描述：成功返回需要获取元素值的大小（byte），失败返回 0

Remarks

参数 element_index 的值应位于指定 Vector 对象实例中有效的元素索引号（从 0 开始，含 0 本身），否则函数将失败。

参数 element_value_size 的值（byte）必须大于等于指定 Vector 对象实例单个元素的大小（byte），否则为确保元素完整性，函数将失败。

该函数的返回值不可靠，为确保元素完整性，若获取成功则返回指定 Vector 对象实例单个元素的大小（byte）。

vector_helper_get_element_value（Unsafe）

从指定 Vector 对象实例中获取指定元素的值指针

除非必要，否则您不应该使用此函数。因为这是一个 Unsafe 函数，使用此函数时无法确保元素和缓冲区的完整性。您应该使用 vector_helper_get_element 函数来获取指定元素的值。

此函数很有可能在将来的 Vector Helper 版本中被弃用，因为它不符合运行时安全设计。

Syntax

void* vector_helper_get_element_value
(
    VectorContext* vector_object_context, 
    size_t element_index
);

Parameters

参数名	类型	必选	描述
vector_object_context	Vector	True	指定 Vector 对象实例描述符
element_index	size_t	True	需要获取指定元素值指针的元素索引

Return Value

类型：void*

描述：成功返回指定元素值的 void* 指针，失败返回 NULL。

Remarks

除非必要，您应该调用 vector_helper_get_element 函数获取指定元素的值，因为此函数无法确保指定 Vector 对象实例缓冲区及其元素的完整性。

此函数的返回值不可靠，为确保内存操作的成功，您应该检查此函数的返回值是否为 NULL，而不是假定它绝对返回有效指针。

vector_helper_remove_element

从指定 Vector 对象实例中移除指定元素

Syntax

size_t vector_helper_remove_element
(
	VectorContext* vector_object_context, 
	size_t element_start_index,
	size_t remove_count, 
	bool* remove_result
);

Parameters

参数名	类型	必填	描述
vector_object_context	Vector	True	指定 Vector 对象实例描述符
element_start_index	size_t	True	需要移除的元素起始索引号
remove_count	size_t	True	需要移除的元素个数
remove_result	bool*	False	指向接收元素移除结果的变量

Return Value

类型：size_t

描述：成功返回指定 Vector 对象实例中剩余元素个数，失败返回 0。

Remarks

参数 element_start_index 的值应位于指定 Vector 对象实例中有效的元素索引号（从 0 开始，含 0 本身），否则函数将失败。

参数 remove_count 的值应大于 0，因为您不能从参数 element_start_index（含自身）向后移除 0 个元素。

若您不需要接收元素的移除结果，应将参数 remove_result 设置为 NULL。

此函数的返回值不可靠，因为若指定 Vector 对象实例最后的一个元素被成功移除，则依旧返回 0，因为指定 Vector 对象实例中的确已无其他元素，因此您不能通过检查此函数的返回值是否为 0 来作为元素是否被成功移除的判断依据，应该使用参数 remove_result 接收移除结果。

此函数仅移除指定范围内的元素，并不会回收其占用的内存空间。若需要强制回收可用的空闲内存空间，请尝试调用 vector_helper_free_available_memory 函数。

vector_helper_remove_all_element

从指定 Vector 对象实例中快速移除所有元素

Syntax

bool vector_helper_remove_all_element
(
    VectorContext* vector_object_context
);

Parameters

参数名	类型	必选	描述
vector_object_context	Vector	True	指定 Vector 对象实例描述符

Return Value

类型：bool

描述：成功返回 True，失败返回 False

Remarks

此函数仅尝试快速移除指定 Vector 对象实例中的所有元素，并不会回收其占用的内存空间。若需要强制回收可用的空闲内存空间，请尝试调用 vector_helper_free_available_memory 函数。

vector_helper_reset_all_element

快速重置指定 Vector 对象实例中所有元素值为空

Syntax

bool vector_helper_reset_all_element
(
    VectorContext* vector_object_context
);

Parameters

参数名	类型	必选	描述
vector_object_context	Vector	True	指定 Vector 对象实例描述符

Return Value

类型：bool

描述：成功返回 True，失败返回 False

Remarks

此函数仅尝试快速重置指定 Vector 对象实例中所有元素的值为空，并不会移除这些元素，也不会回收其占用的内存空间。

vector_helper_get_last_element_index

获取指定 Vector 对象实例尾部最后一个元素的索引号

Syntax

bool vector_helper_get_last_element_index
(
    VectorContext* vector_object_context, 
    size_t* last_element_index
);

Parameters

参数名	类型	必选	描述
vector_object_context	Vector	True	指定 Vector 对象实例描述符
last_element_index	size_t*	True	指向接收最后一个元素索引号的变量

Return Value

类型：bool

描述：成功返回 True，失败返回 False。

vector_helper_is_valid_element_index

验证指定 Vector 对象实例中指定元素索引号是否有效

Syntax

bool vector_helper_is_valid_element_index
(
    VectorContext* vector_object_context, 
    size_t element_index
);

Parameters

参数名	类型	必选	描述
vector_object_context	Vector	True	指定 Vector 对象实例描述符
element_index	size_t	True	需要验证的元素索引号

Return Value

类型：bool

描述：被验证的元素索引号有效则返回 True，反之返回 False。

vector_helper_is_empty

验证指定 Vector 对象实例是否为空

Syntax

bool vector_helper_is_empty
(
    VectorContext* vector_object_context
);

Parameters

参数名	类型	必选	描述
vector_object_context	Vector	True	指定 Vector 对象实例描述符

Return Value

类型：bool

描述：若指定 Vector 对象实例为空，则返回 True，反之返回 False。

Remarks

此函数适用于验证指定 Vector 对象实例中是否包含有效元素，也即元素个数大于 0，并非用于验证指定 Vector 对象是否有效。