Iterators

struct UIter

An iterator.

UIter uiter(void const *data, void *(*next)(UIter *self), void (*free)(UIter *self))

Creates a custom iterator.

Note

The returned object must be destroyed by calling uiter_deinit.

Parameters:

  • data – Pointer to user-defined data, or NULL if no data is needed.

  • next – Function that retrieves the next element from the iterator.

  • free – Function that deinitializes the user-defined data.

Returns:

Iterator.

void *uiter_alloc_data(UIter *iter, size_t size)

Allocates user-defined data for an iterator.

Note

Should only be used with iterators created with uiter and NULL data.

Note

The allocated data is automatically deallocated when the iterator is deinitialized.

Note

As an optimization, this function may choose to store small data directly in the iterator without performing a separate allocation.

Parameters:

  • iter – Iterator.

  • size – Size of the user-defined data.

Returns:

Pointer to the allocated data, or NULL if the allocation failed or the size is zero.

UIter uiter_empty(void)

Creates an empty iterator.

Note

The returned object must be destroyed by calling uiter_deinit.

Returns:

Empty iterator.

UIter uiter_enum(size_t count, void const **elems)

Creates an iterator over multiple elements.

Note

The returned object must be destroyed by calling uiter_deinit.

Parameters:

  • count – Number of elements to iterate over.

  • elems – Array of pointers to the elements to iterate over.

Returns:

Iterator.

UIter uiter_one(void const *elem)

Creates an iterator over a single element.

Note

The returned object must be destroyed by calling uiter_deinit.

Parameters:

  • elem – Pointer to element to iterate over.

Returns:

Iterator.

UIter uiter_over(...)

Creates an iterator over the elements passed as arguments.

Note

The returned object must be destroyed by calling uiter_deinit.

Parameters:

  • ... – Pointers to elements to iterate over.

Returns:

Iterator.

UIter uiter_buf(void const *buf, size_t count, size_t elem_size)

Creates an iterator over a contiguous memory area.

Note

The returned object must be destroyed by calling uiter_deinit.

Parameters:

  • buf – Pointer to the beginning of the memory area.

  • count – Number of elements.

  • elem_size – Size of each element.

Returns:

Iterator.

UIter uiter_array(T const *array, size_t count)

Creates an iterator over an array.

Note

The returned object must be destroyed by calling uiter_deinit.

Parameters:

  • array – Pointer to the beginning of the array.

  • count – Number of elements in the array.

Returns:

Iterator.

ulib_ret uiter_join(UIter *iter, UIter *other)

Joins two iterators.

Note

The second iterator is consumed by this operation and should not be used afterwards.

Parameters:

  • iter – First iterator.

  • other – Second iterator.

Returns:

Return code.

ulib_ret uiter_map(UIter *iter, void *ctx, void *(*map)(UIter *self, void *ctx, void *elem), void (*free)(UIter *self, void *ctx))

Maps an iterator.

Parameters:

  • iter – Iterator.

  • ctx – User-defined context.

  • map – Function that maps each element. Return NULL to skip an element.

  • free – Function that deinitializes the user-defined context.

Returns:

Return code.

void uiter_deinit(UIter *iter)

Deinitializes an iterator.

Note

Iterators are automatically deinitialized when exhausted. Calling this function is only necessary if you stop iterating before reaching the end.

Parameters:

  • iter – Iterator to deinitialize.

void *uiter_next(UIter *iter)

Retrieves the next element from the iterator.

Parameters:

  • iter – Iterator.

Returns:

Next element, or NULL if the iteration is finished or an error occurred.

ulib_ret uiter_state(UIter const *iter)

Retrieves the current state of the iterator.

Parameters:

  • iter – Iterator.

Returns:

Iterator state.

void uiter_set_state(UIter *iter, ulib_ret state)

Sets the state of the iterator.

Note

Should only be used in the functions of custom iterators created with uiter.

Parameters:

  • iter – Iterator.

  • state – New state.

void *uiter_data(UIter const *iter)

Retrieves the user-defined data associated with the iterator.

Note

Should only be used in the functions of custom iterators created with uiter.

Parameters:

  • iter – Iterator.

Returns:

User-defined data.

uiter_foreach(T, iter, var)

Iterates over the iterator, executing the specified code block for each element.

Usage example: 

uiter_foreach (ulib_int, iter, var) {
    ulib_int item = *var;
    ...
}

Parameters:

  • T – symbol Element type.

  • iter – UIter * Iterator.

  • var – symbol Name of the variable holding the current item.

uiter_break(iter)

Breaks out of a uiter_foreach loop, deinitializing the iterator.

Usage example: 

uiter_foreach (ulib_int, iter, var) {
    if (some_condition) {
        uiter_break(iter);
    }
    ...
}

Parameters:

  • iter – UIter * Iterator.

uiter_continue(iter)

Continues to the next iteration of a uiter_foreach loop.

Usage example: 

uiter_foreach (ulib_int, iter, var) {
    if (some_condition) {
        uiter_continue(iter);
    }
    ...
}

Note

Provided for symmetry with uiter_break.

Parameters:

  • iter – UIter * Iterator.