元素存取与管理
本页将介绍与元素存取与管理相关的 Vector Helper API
向指定 Vector 对象实例的尾部 Push 一个元素
bool vector_helper_push_element
(
VectorContext* vector_object_context,
const void* element_value,
size_t element_value_size,
size_t* push_element_index
);
参数名 | 类型 | 必选 | 描述 |
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 元素的索引号的变量 |
类型:
bool
描述:Push 元素成功返回
True
,反之返回 False
。您应该检查此函数的返回值来判断其元素是否 Push 成功,而不是假定一定成功。
当函数失败时,参数
push_element_index
指向的变量不会被修改。若不需要接收 Push 元素的索引号,请将参数
push_element_index
设置为 NULL。参数
element_value_size
的值(byte)应小于等于指定 Vector 对象实例的单个元素大小(byte),否则函数将失败。该函数适用于向指定 Vector 对象实例 Push 单一元素,若需连续 Push 多个元素,请调用
vector_helper_push_multiple_element
函数以确保操作完整性。向指定 Vector 对象实例的尾部 Push 多个元素,该函数相对于分多次调用
vector_helper_push_element
函数,性能更高。该函数会确保本次操作的完整性,遵循单个元素 Push 失败则全部 失败,因此您不必担心也无需处理在执行 Push Multiple 操作的过程中出现单个元素 Push 失败的情况。
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
);
参数名 | 类型 | 必选 | 描述 |
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 的多个元素中 首个元素的索引号 |
类型:
bool
描述:若参数
multiple_element_value
指向的待 Push 元素数组中指定个数的元素均 Push 成功则返回 True
,反之返回 False
。若不需要接收 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 对象实例的顶端 Pop 一个元素
bool vector_helper_pop_element
(
VectorContext* vector_object_context,
void* element_value,
size_t element_value_size
);
参数名 | 类型 | 必选 | 描述 |
vector_object_context | Vector | True | 指定 Vector 对象实例描述符 |
element_value | void* | True | 指向接收 Pop 元素值的缓冲区 |
element_value_size | size_t | True | 接收 Pop 元素值的缓冲区大小(byte) |
类型:bool
描述:成功返回 True,失败返回 False。
参数
element_value_size
的值(byte)应大于等于指定 Vector 对象实例单个元素的大小(byte),否则为确保元素完整性,因此元素值不会被截断,函数将失败。当指定 Vector 对象实例顶端的元素 Pop 成功后,被 Pop 的元素将从指定 Vector 对象实例中移除。
设置指定 Vector 对象实例中指定元素的值
bool vector_helper_set_element
(
VectorContext* vector_object_context,
size_t element_index,
const void* element_value,
size_t element_value_size
);
参数名 | 类型 | 必选 | 描述 |
vector_object_context | Vector | True | 指定 Vector 对象实例描述符 |
element_index | size_t | True | 需要设置的元素索引号 |
element_value | const void* | True | 指向待设置的元素值缓冲区 |
element_value_size | size_t | True | 待设置的元素值缓冲区大小(byte) |
类型:
bool
描述:成功返回
True
,失败返回 False
参数
element_index
的值应位于指定 Vector 对象实例中有效的元素索引号(从 0 开始,含 0 本身),否则函数将失败。参数
element_value
的值从 Vector Helper 1.0.1 版本起,必须设置为指向待设置的有效元素值缓冲区,不能设置为 NULL
以填空指定元素。若要填空指定元素,应指向空的元素值缓冲区。参数
element_value_size
的值(byte)必须小于等于指定 Vector 对象实例单个元素的大小(byte),否则为确保元素完整性,函数将失败。一个设计良好的应用程序应确保元素值缓冲区大小等于指定 Vector 对象实例单个元素的大小(byte),而不是截断元素值。
从指定 Vector 对象实例中获取指定元素的值
size_t vector_helper_get_element
(
VectorContext* vector_object_context,
size_t element_index,
void* element_value,
size_t element_value_size
);
参数名 | 类型 | 必选 | 描述 |
vector_object_context | Vector | True | 指定 Vector 对象实例描述符 |
element_index | size_t | True | 需要获取元素值的元素索引号 |
element_value | void* | True | 指向接收元素值的缓冲区 |
element_value_size | size_t | True | 接收元素值的缓冲区大小(byte) |
类型:
size_t
描述:成功返回需要获取元素值的大小(byte),失败返回 0
参数
element_index
的值应位于指定 Vector 对象实例中有效的元素索引号(从 0 开始,含 0 本身),否则函数将失败。参数
element_value_size
的值(byte)必须大于等于指定 Vector 对象实例单个元素的大小(byte),否则为确保元素完整性,函数将失败。该函数的返回值不可靠,为确保元素完整性,若获取成功则返回指定 Vector 对象实例单个元素的大小(byte)。
从指定 Vector 对象实例中获取指定元素的值指针
除非必要,否则您不应该使用此函数。因为这是一个 Unsafe 函数,使用此函数时无法确保元素和缓冲区的完整性。您应该使用 vector_helper_get_element 函数来获取指定元素的值。
此函数很有可能在将来的 Vector Helper 版本中被弃用,因为它不符合运行时安全设计。
void* vector_helper_get_element_value
(
VectorContext* vector_object_context,
size_t element_index
);
参数名 | 类型 | 必选 | 描述 |
vector_object_context | Vector | True | 指定 Vector 对象实例描述符 |
element_index | size_t | True | 需要获取指定元素值指针的元素索引 |
类型:
void*
描述:成功返回指定元素值的
void*
指针,失败返回 NULL。除非必要,您应该调用
vector_helper_get_element
函数获取指定元素的值,因为此函数无法确保指定 Vector 对象实例缓冲区及其元素的完整性。此函数的返回值不可靠,为确保内存操作的成功,您应该检查此函数的返回值是否为
NULL
,而不是假定它绝对返回有效指针。从指定 Vector 对象实例中移除指定元素
size_t vector_helper_remove_element
(
VectorContext* vector_object_context,
size_t element_start_index,
size_t remove_count,
bool* remove_result
);
参数名 | 类型 | 必填 | 描述 |
vector_object_context | Vector | True | 指定 Vector 对象实例描述符 |
element_start_index | size_t | True | 需要移除的元素起始索引号 |
remove_count | size_t | True | 需要移除的元素个数 |
remove_result | bool* | False | 指向接收元素移除结果的变量 |
类型:
size_t
描述:成功返回指定 Vector 对象实例中剩余元素个数,失败返回 0。
参数
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 对象实例中快速移除所有元素
bool vector_helper_remove_all_element
(
VectorContext* vector_object_context
);
参数名 | 类型 | 必选 | 描述 |
vector_object_context | Vector | True | 指定 Vector 对象实例描述符 |
类型:
bool
描述:成功返回
True
,失败返回 False
此函数仅尝试快速移除指定 Vector 对象实例中的所有元素,并不会回收其占用的内存空间。若需要强制回收可用的空闲内存空间,请尝试调用
vector_helper_free_available_memory
函数。快速重置指定 Vector 对象实例中所有元素值为空
bool vector_helper_reset_all_element
(
VectorContext* vector_object_context
);
参数名 | 类型 | 必选 | 描述 |
vector_object_context | Vector | True | 指定 Vector 对象实例描述符 |
类型:
bool
描述:成功返回
True
,失败返回 False
此函数仅尝试快速重置指定 Vector 对象实例中所有元素的值为空,并不会移除这些元素,也不会回收其占用的内存空间。
获取指定 Vector 对象实例尾部最后一个元素的索引号
bool vector_helper_get_last_element_index
(
VectorContext* vector_object_context,
size_t* last_element_index
);
参数名 | 类型 | 必选 | 描述 |
vector_object_context | Vector | True | 指定 Vector 对象实例描述符 |
last_element_index | size_t* | True | 指向接收最后一个元素索引号的变量 |
类型:
bool
描述:成功返回
True
,失败返回 False
。验证指定 Vector 对象实例中指定元素索引号是否有效
bool vector_helper_is_valid_element_index
(
VectorContext* vector_object_context,
size_t element_index
);
参数名 | 类型 | 必选 | 描述 |
vector_object_context | Vector | True | 指定 Vector 对象实例描述符 |
element_index | size_t | True | 需要验证的元素索引号 |
类型:
bool
描述:被验证的元素索引号有效则返回
True
,反之返回 False
。验证指定 Vector 对象实例是否为空
bool vector_helper_is_empty
(
VectorContext* vector_object_context
);
参数名 | 类型 | 必选 | 描述 |
vector_object_context | Vector | True | 指定 Vector 对象实例描述符 |
类型:
bool
描述:若指定 Vector 对象实例为空,则返回
True
,反之返回 False
。此函数适用于验证指定 Vector 对象实例中是否包含有效元素,也即元素个数大于 0,并非用于验证指定 Vector 对象是否有效。
Last modified 4yr ago