Iterator natives - IS4Code/PawnPlus GitHub Wiki

Construction and destruction

iter_range

native Iter:iter_range(AnyTag:start, count, skip=1, tag_id=tagof(start));
native Iter:iter_range_arr(const AnyTag:start[], count, skip=1, size=sizeof(start), tag_id=tagof(start));
native Iter:iter_range_str(const start[], count, skip=1);
native Iter:iter_range_str_s(ConstStringTag:value, count, skip=1);
native Iter:iter_range_var(ConstVariantTag:start, count, skip=1);

Creates a read-only iterator containing an increasing sequence of count elements starting at start, increasing its value every skip steps.

iter_repeat

native Iter:iter_repeat(AnyTag:value, count, tag_id=tagof(value));
native Iter:iter_repeat_arr(const AnyTag:value[], count, size=sizeof(value), tag_id=tagof(value));
native Iter:iter_repeat_str(const value[], count);
native Iter:iter_repeat_str_s(ConstStringTag:value, count);
native Iter:iter_repeat_var(ConstVariantTag:value, count);

Creates a read-only iterator containing a sequence of count elements of value.

iter_filter

native Iter:iter_filter(IterTag:iter, Expression:expr, Map:env=INVALID_MAP);

Creates a new filter iterator which captures iter and exposes only elements that match a boolean expression expr, which is executed every time the iterator is moved to another element. Optionally, env may be provided to specify the environment in which expr is executed. $arg0 in expr corresponds to the value of the element, $arg1 corresponds to the key (if present).

iter_project

native Iter:iter_project(IterTag:iter, Expression:expr, Map:env=INVALID_MAP);

Creates a new project iterator which captures iter and runs expr every time the value is obtained to determine the result. Optionally, env may be provided to specify the environment in which expr is executed. $arg0 in expr corresponds to the value of the element, $arg1 corresponds to the key (if present).

iter_valid

native bool:iter_valid(IterTag:iter);

Returns true if the iterator points to a valid object.

iter_acquire

native Iter:iter_acquire(IterTag:iter);

Increases the reference count in the iterator object. See garbage collection and resource management for more information.

iter_release

native Iter:iter_release(IterTag:iter);

Decreases the reference count in the iterator object. See garbage collection and resource management for more information.

iter_delete

native iter_delete(IterTag:iter);

Deletes an iterator.

iter_linked

native bool:iter_linked(IterTag:iter);

Returns true if the iterator points to an existing collection.

iter_inside

native bool:iter_inside(IterTag:iter);

Returns true if the iterator points to a valid location in a collection.

iter_empty

native bool:iter_empty(IterTag:iter);

Returns true if the iterator doesn't point to an existing element in the collection, i.e. when iter_linked or iter_inside are false, or if the iterator points to an unoccupied location in the collection after iter_erase was used.

iter_type

native iter_type(IterTag:iter);

Returns a number that uniquely identifies the type of the iterator. The result is not guaranteed to be consistent across platforms, versions, or unique instances of the plugin.

iter_type_str

native iter_type_str(IterTag:iter, type[], size=sizeof(type));
native String:iter_type_str_s(IterTag:iter);

Returns a string representation of the type of the iterator. The result is not guaranteed to be consistent across platforms, versions, or unique instances of the plugin.

iter_clone

native Iter:iter_clone(IterTag:iter);

Clones the iterator. The clone will point to the same element in the same collection, but will be independent on the source.

Properties

iter_erase

native Iter:iter_erase(IterTag:iter, bool:stay=false);

Removes the element the iterator points to from the collection. The iterator will point to the element following the removed one, unless stay is set to true, in which case the iterator will occupy the "hole" left after the removed element, until moved via iter_move_next. Raises an error on failure.

iter_erase_deep

native Iter:iter_erase_deep(IterTag:iter, bool:stay=false);

Removes the element the iterator points to from the collection and frees the resources owned by the element. The iterator will point to the element following the removed one, unless stay is set to true, in which case the iterator will occupy the "hole" left after the removed element, until moved via iter_move_next. Raises an error on failure.

iter_reset

native Iter:iter_reset(IterTag:iter);

Resets the iterator, making it point to no element. Raises an error on failure.

iter_move_next

native Iter:iter_move_next(IterTag:iter, steps=1);

Moves the iterator to the next element in the collection after steps steps. Returns ITER_NULL if the iterator cannot be moved or the next element doesn't exist.

iter_move_previous

native Iter:iter_move_previous(IterTag:iter, steps=1);

Moves the iterator to the previous element in the collection after steps steps. Returns ITER_NULL if the iterator cannot be moved or the previous element doesn't exist.

iter_to_first

native Iter:iter_to_first(IterTag:iter, index=0);

Moves the iterator to the element at index from the beginning of the collection. Returns ITER_NULL if the iterator cannot be moved or the first element doesn't exist.

iter_to_last

native Iter:iter_to_last(IterTag:iter, index=0);

Moves the iterator to the element at index from the end of the collection. Returns ITER_NULL if the iterator cannot be moved or the last element doesn't exist.

iter_can_reset

native bool:iter_can_reset(IterTag:iter);

Returns true if the iterator supports being reset.

iter_can_insert

native bool:iter_can_insert(IterTag:iter);

Returns true if the iterator supports inserting new elements.

iter_can_erase

native bool:iter_can_erase(IterTag:iter);

Returns true if the iterator supports erasing the element.

iter_swap

native iter_swap(IterTag:iter1, IterTag:iter2);

Swaps the values the two iterators are pointing to.

iter_eq

native bool:iter_eq(IterTag:iter1, IterTag:iter2);

Returns true if the two iterators point to the same element in the same collection.

iter_get

native iter_get(IterTag:iter, offset=0);
native iter_get_arr(IterTag:iter, AnyTag:value[], size=sizeof(value));
native iter_get_str(IterTag:iter, value[], size=sizeof(value)) = iter_get_arr;
native String:iter_get_str_s(IterTag:iter);
native Variant:iter_get_var(IterTag:iter);
native bool:iter_get_safe(IterTag:iter, &AnyTag:value, offset=0, TagTag:tag_id=tagof(value));
native iter_get_arr_safe(IterTag:iter, AnyTag:value[], size=sizeof(value), TagTag:tag_id=tagof(value));
native iter_get_str_safe(IterTag:iter, value[], size=sizeof(value));
native String:iter_get_str_safe_s(IterTag:iter);
native iter_get_md(IterTag:iter, const offsets[], offsets_size=sizeof(offsets));
native iter_get_md_arr(IterTag:iter, const offsets[], AnyTag:value[], size=sizeof(value), offsets_size=sizeof(offsets));
native iter_get_md_str(IterTag:iter, const offsets[], value[], size=sizeof(value), offsets_size=sizeof(offsets)) = iter_get_md_arr;
native String:iter_get_md_str_s(IterTag:iter, const offsets[], offsets_size=sizeof(offsets));
native bool:iter_get_md_safe(IterTag:iter, const offsets[], &AnyTag:value, offsets_size=sizeof(offsets), TagTag:tag_id=tagof(value));
native iter_get_md_arr_safe(IterTag:iter, const offsets[], AnyTag:value[], size=sizeof(value), offsets_size=sizeof(offsets), TagTag:tag_id=tagof(value));
native iter_get_md_str_safe(IterTag:iter, const offsets[], value[], size=sizeof(value), offsets_size=sizeof(offsets));
native String:iter_get_md_str_safe_s(IterTag:iter, const offsets[], offsets_size=sizeof(offsets));

Returns the value of the element this iterator points to. This function works both for lists and maps (where it accesses the value). iter_get_value_* should be used for maps, but it uses the same function.

iter_set

native iter_set(IterTag:iter, AnyTag:value, TagTag:tag_id=tagof(value));
native iter_set_arr(IterTag:iter, const AnyTag:value[], size=sizeof(value), TagTag:tag_id=tagof(value));
native iter_set_arr_2d(IterTag:iter, const AnyTag:value[][], size=sizeof(value), size2=sizeof(value[]), TagTag:tag_id=tagof(value));
native iter_set_arr_3d(IterTag:iter, const AnyTag:value[][][], size=sizeof(value), size2=sizeof(value[]), size3=sizeof(value[][]), TagTag:tag_id=tagof(value));
native iter_set_str(IterTag:iter, const value[]);
native iter_set_str_s(IterTag:iter, ConstStringTag:value);
native iter_set_var(IterTag:iter, ConstVariantTag:value);

Sets the value of the element this iterator points to. This function works both for lists and maps (where it accesses the value). iter_set_value_* should be used for maps, but it uses the same function.

iter_set_cell

native iter_set_cell(IterTag:iter, offset, AnyTag:value);
native bool:iter_set_cell_safe(IterTag:iter, offset, AnyTag:value, TagTag:tag_id=tagof(value));
native iter_set_cells(IterTag:iter, offset, AnyTag:values[], size=sizeof(values));
native iter_set_cells_safe(IterTag:iter, offset, AnyTag:values[], size=sizeof(values), TagTag:tag_id=tagof(values));
native iter_set_cell_md(IterTag:iter, const offsets[], AnyTag:value, offsets_size=sizeof(offsets));
native bool:iter_set_cell_md_safe(IterTag:iter, const offsets[], AnyTag:value, offsets_size=sizeof(offsets), TagTag:tag_id=tagof(value));
native iter_set_cells_md(IterTag:iter, const offsets[], AnyTag:values[], offsets_size=sizeof(offsets), size=sizeof(values));
native iter_set_cells_md_safe(IterTag:iter, const offsets[], AnyTag:values[], offsets_size=sizeof(offsets), size=sizeof(values), TagTag:tag_id=tagof(values));

Sets a cell or a range of cells in an array element referenced by the iterator.

iter_insert

native Iter:iter_insert(IterTag:iter, AnyTag:value, TagTag:tag_id=tagof(value));
native Iter:iter_insert_arr(IterTag:iter, const AnyTag:value[], size=sizeof(value), TagTag:tag_id=tagof(value));
native Iter:iter_insert_arr_2d(IterTag:iter, const AnyTag:value[][], size=sizeof(value), size2=sizeof(value[]), TagTag:tag_id=tagof(value));
native Iter:iter_insert_arr_3d(IterTag:iter, const AnyTag:value[][][], size=sizeof(value), size2=sizeof(value[]), size3=sizeof(value[][]), TagTag:tag_id=tagof(value));
native Iter:iter_insert_str(IterTag:iter, const value[]);
native Iter:iter_insert_str_s(IterTag:iter, ConstStringTag:value);
native Iter:iter_insert_var(IterTag:iter, ConstVariantTag:value);

Inserts a new element into the collection in the place of the one the iterator points to. The old element is moved to the next position. Raises an error on failure.

iter_tagof

native iter_tagof(IterTag:iter);

Returns the tag of the element.

iter_tag_uid

native tag_uid:iter_tag_uid(IterTag:iter);

Returns the tag uid of the element.

iter_sizeof

native iter_sizeof(IterTag:iter);
native iter_sizeof_md(IterTag:iter, const offsets[], offsets_size=sizeof(offsets));

Returns the size of the element.

iter_rank

native iter_rank(IterTag:iter);

Returns the rank of the element.

iter_get_key

native iter_get_key(IterTag:iter, offset=0);
native iter_get_key_arr(IterTag:iter, AnyTag:value[], size=sizeof(value));
native iter_get_key_str(IterTag:iter, value[], size=sizeof(value)) = iter_get_key_arr;
native String:iter_get_key_str_s(IterTag:iter);
native Variant:iter_get_key_var(IterTag:iter);
native bool:iter_get_key_safe(IterTag:iter, &AnyTag:value, offset=0, TagTag:tag_id=tagof(value));
native iter_get_key_arr_safe(IterTag:iter, AnyTag:value[], size=sizeof(value), TagTag:tag_id=tagof(value));
native iter_get_key_str_safe(IterTag:iter, value[], size=sizeof(value));
native String:iter_get_key_str_safe_s(IterTag:iter);
native iter_get_key_md(IterTag:iter, const offsets[], offsets_size=sizeof(offsets));
native iter_get_key_md_arr(IterTag:iter, const offsets[], AnyTag:value[], size=sizeof(value), offsets_size=sizeof(offsets));
native iter_get_key_md_str(IterTag:iter, const offsets[], value[], size=sizeof(value), offsets_size=sizeof(offsets)) = iter_get_key_md_arr;
native String:iter_get_key_md_str_s(IterTag:iter, const offsets[], offsets_size=sizeof(offsets));
native bool:iter_get_key_md_safe(IterTag:iter, const offsets[], &AnyTag:value, offsets_size=sizeof(offsets), TagTag:tag_id=tagof(value));
native iter_get_key_md_arr_safe(IterTag:iter, const offsets[], AnyTag:value[], size=sizeof(value), offsets_size=sizeof(offsets), TagTag:tag_id=tagof(value));
native iter_get_key_md_str_safe(IterTag:iter, const offsets[], value[], size=sizeof(value), offsets_size=sizeof(offsets));
native String:iter_get_key_md_str_safe_s(IterTag:iter, const offsets[], offsets_size=sizeof(offsets));

If the iterator points to a map-like collection, returns the key of the record it points to. Otherwise returns the index of the record as a single cell.

iter_tagof_key

native iter_tagof_key(IterTag:iter);

Returns the tag of the key.

iter_key_tag_uid

native tag_uid:iter_key_tag_uid(IterTag:iter);

Returns the tag uid of the key.

iter_sizeof_key

native iter_sizeof_key(IterTag:iter);
native iter_sizeof_key_md(IterTag:iter, const offsets[], offsets_size=sizeof(offsets));

Returns the size of the key.

iter_key_rank

native iter_key_rank(IterTag:iter);

Returns the rank of the key.