List natives - IS4Code/PawnPlus GitHub Wiki

Construction and destruction

list_new

native List:list_new();
native List:list_new_arr(AnyTag:values[], size=sizeof(values), TagTag:tag_id=tagof(values));
#define list_new_args(%0) list_new_args_packed(_PP@TAGGED_PACK(%0))
native List:list_new_args_str(arg0[], ...);
native List:list_new_args_var(ConstVariantTag:arg0, ConstVariantTag:...);

Creates a new list, optionally from an array of values (must be properly tagged), or an argument list.

list_delete

native list_delete(List:list);

Deletes a list and frees its memory. Required after you're done with the object.

list_delete_deep

native list_delete_deep(List:list);

Deletes a list and frees its memory together with all resources it may contain.

list_valid

native bool:list_valid(List:list);

Returns true if the list pointer is valid.

list_clear

native list_clear(List:list);

Removes all elements in the list.

list_clear_deep

native list_clear_deep(List:list);

Removes all elements in the list and frees all memory owned by them.

list_clone

native List:list_clone(List:list);

Clones a list and all the data it contains (deep copy). You can use list_add_list to copy only the values.

Properties

list_size

native list_size(List:list);

Returns the number of elements in the list.

list_capacity

native list_capacity(List:list);

Returns the number of new elements that can fit in a list before iterators pointing inside the list are invalidated.

list_reserve

native list_reserve(List:list, capacity);

Increases the size of the internal list buffer to be able to hold capacity total elements. If the new capacity is larger than the original one, this causes all iterators to be invalidated.

list_add

native list_add(List:list, AnyTag:value, index=-1, TagTag:tag_id=tagof(value));
native list_add_arr(List:list, const AnyTag:value[], index=-1, size=sizeof(value), TagTag:tag_id=tagof(value));
native list_add_str(List:list, const value[], index=-1);
native list_add_str_s(List:list, ConstStringTag:value, index=-1);
native list_add_var(List:list, ConstVariantTag:value, index=-1);

Adds new elements to a list, constructed either from a single value, an array, a string, or a variant, or a list thereof. Optionally, index can be used to specify the position of the new element in the list. Returns the index of the element.

list_add_args

#define list_add_args(%0,%1) list_add_args_packed(%0,_PP@TAGGED_PACK(%1))
native list_add_args_str(List:list, arg0[], ...);
native list_add_args_var(List:list, ConstVariantTag:arg0, ConstVariantTag:...);

Adds the passed arguments to the list as its elements. Returns the number of added elements.

list_add_list

native list_add_list(List:list, List:range, index=-1);

Copies values from one list into another. Returns the index where the values from range start in list.

list_add_iter

native list_add_iter(List:list, Iter:iter, index=-1);

Copies all remaining values from the iterator to the list. Returns the index where the values start.

list_remove

native list_remove(List:list, index);

Removes an element from the list at a specific index. The following values are moved to fill the gap.

list_remove_deep

native list_remove_deep(List:list, index);

Removes an element from the list at a specific index, and frees all resources held by the element. The following values are moved to fill the gap.

list_remove_range

native list_remove_range(List:list, begin, end);

Removes a specific range of elements from the list starting at begin and ending right before end.

list_remove_range_deep

native list_remove_range_deep(List:list, begin, end);

Removes a specific range of elements from the list starting at begin and ending right before end, and frees all resources held by them.

list_remove_if

native list_remove_if(List:list, Expression:pred);

Removes all elements that satisfy pred.

list_remove_if_deep

native list_remove_if_deep(List:list, Expression:pred);

Removes all elements that satisfy pred, and frees all resources held by them.

list_get

native list_get(List:list, index, offset=0);
native list_get_arr(List:list, index, AnyTag:value[], size=sizeof(value));
native list_get_str(List:list, index, value[], size=sizeof(value)) = list_get_arr;
native String:list_get_str_s(List:list, index);
native Variant:list_get_var(List:list, index);
native bool:list_get_safe(List:list, index, &AnyTag:value, offset=0, TagTag:tag_id=tagof(value));
native list_get_arr_safe(List:list, index, AnyTag:value[], size=sizeof(value), TagTag:tag_id=tagof(value));
native list_get_str_safe(List:list, index, value[], size=sizeof(value));
native String:list_get_str_safe_s(List:list, index);

Returns the value of an element in a list, at a specific index. The safe versions check the tag of the output. Other semantics same as for variants.

list_set

native list_set(List:list, index, AnyTag:value, TagTag:tag_id=tagof(value));
native list_set_arr(List:list, index, const AnyTag:value[], size=sizeof(value), TagTag:tag_id=tagof(value));
native list_set_str(List:list, index, const value[]);
native list_set_str_s(List:list, index, ConstStringTag:value);
native list_set_var(List:list, index, ConstVariantTag:value);

Replaces a value at a specific position in a list with a new one.

list_set_cell

native list_set_cell(List:list, index, offset, AnyTag:value);
native bool:list_set_cell_safe(List:list, index, offset, AnyTag:value, TagTag:tag_id=tagof(value));

Sets the value of a single cell in an array stored in the list. The safe version checks if the tags are compatible.

list_resize

native list_resize(List:list, newsize, AnyTag:padding, TagTag:tag_id=tagof(padding));
native list_resize_arr(List:list, newsize, const AnyTag:padding[], size=sizeof(padding), TagTag:tag_id=tagof(padding));
native list_resize_str(List:list, newsize, const padding[]);
native list_resize_str_s(List:list, newsize, ConstStringTag:padding);
native list_resize_var(List:list, newsize, ConstVariantTag:padding);

Changes the number of elements in a list to newsize, initilizing the empty slots with padding.

list_find

native list_find(List:list, AnyTag:value, index=0, TagTag:tag_id=tagof(value));
native list_find_arr(List:list, const AnyTag:value[], index=0, size=sizeof(value), TagTag:tag_id=tagof(value));
native list_find_str(List:list, const value[], index=0);
native list_find_str_s(List:list, ConstStringTag:value, index=0);
native list_find_var(List:list, ConstVariantTag:value, index=0);

Finds the first element equal to value in the list and returns its index. The searching starts at index, which can also be negative, denoting a position from the end. Returns -1 if the element was not found.

list_find_last

native list_find_last(List:list, AnyTag:value, index=-1, TagTag:tag_id=tagof(value));
native list_find_last_arr(List:list, const AnyTag:value[], index=-1, size=sizeof(value), TagTag:tag_id=tagof(value));
native list_find_last_str(List:list, const value[], index=-1);
native list_find_last_str_s(List:list, ConstStringTag:value, index=0);
native list_find_last_var(List:list, ConstVariantTag:value, index=-1);

Finds the last element equal to value in the list and returns its index. The searching starts at index, which can also be negative, denoting a position from the end. Returns -1 if the element was not found.

list_find_if

native list_find_if(List:list, Expression:pred, index=0);

Finds the first element that satisfies pred, starting at index, and returns its index, or -1 if no such element is present in the list.

list_find_last_if

native list_find_last_if(List:list, Expression:pred, index=-1);

Finds the last element that satisfies pred, starting at index, and returns its index, or -1 if no such element is present in the list.

list_count

native list_count(List:list, AnyTag:value, TagTag:tag_id=tagof(value));
native list_count_arr(List:list, const AnyTag:value[], size=sizeof(value), TagTag:tag_id=tagof(value));
native list_count_str(List:list, const value[]);
native list_count_str_s(List:list, ConstStringTag:value);
native list_count_var(List:list, ConstVariantTag:value);

Counts the number of occurences of a specific element.

list_count_if

native list_count_if(List:list, Expression:pred);

Counts the number of elements in the list that satisfy pred.

list_sort

native list_sort(List:list, offset=0, size=-1, bool:reverse=false, bool:stable=true);

Sorts the elements in a list in an ascending order (descending if reverse is false). If stable is false, equal elements are permitted to be reordered.

list_sort_expr

native list_sort_expr(List:list, Expression:expr, bool:reverse=false, bool:stable=true);

Sorts the elements in a list with a custom ordering expression. The expression is executed for pairs of elements and its boolean result determines whether the first element shall come before the second element (or after if reverse is true).

list_tagof

native list_tagof(List:list, index);

Returns the tag of an element in the list.

list_sizeof

native list_sizeof(List:list, index);

Returns the size of an element in the list.

list_iter

native Iter:list_iter(List:list, index=0);

Creates a new iterator pointing to an element in the list.