# Iterator

struct WpIterator

  A generic iterator API

struct _WpIteratorMethods

  Public Members

  guint32 version
  void (*reset)(WpIterator *self)
  gboolean (*next)(WpIterator *self, GValue *item)
  gboolean (*fold)(WpIterator *self, WpIteratorFoldFunc func, GValue *ret, gpointer data)
  gboolean (*foreach)(WpIterator *self, WpIteratorForeachFunc func, gpointer data)
  void (*finalize)(WpIterator *self)

typedef gboolean (*WpIteratorFoldFunc)(const GValue *item, GValue *ret, gpointer data)

  A function to be passed to wp_iterator_fold().

  Param item:

    the item to fold

  Param ret:

    the value collecting the result

  Param data:

    data passed to wp_iterator_fold()

  Return:

    TRUE if the fold should continue, FALSE if it should stop.

typedef void (*WpIteratorForeachFunc)(const GValue *item, gpointer data)

  A function that is called by wp_iterator_foreach().

  Param item:

    the item

  Param data:

    the data passed to wp_iterator_foreach()

WpIterator *wp_iterator_new(const WpIteratorMethods *methods, size_t user_size)

  Constructs an iterator that uses the provided methods to implement its API.

  The WpIterator structure is internally allocated with user_size additional space at the end. A pointer to this space can be retrieved with wp_iterator_get_user_data() and is available for implementation-specific storage.

  Parameters:

    - methods -- method implementations for the new iterator

    - user_size -- size of the user_data structure to be allocated

  Returns:

    (transfer full): a new custom iterator

gpointer wp_iterator_get_user_data(WpIterator *self)

  Gets the implementation-specific storage of an iterator.

  Note

  this only for use by implementations of WpIterator

  Parameters:

    - self -- an iterator object

  Returns:

    a pointer to the implementation-specific storage area

WpIterator *wp_iterator_ref(WpIterator *self)

  Increases the reference count of an iterator.

  Parameters:

    - self -- an iterator object

  Returns:

    (transfer full): self with an additional reference count on it

void wp_iterator_unref(WpIterator *self)

  Decreases the reference count on self and frees it when the ref count reaches zero.

  Parameters:

    - self -- (transfer full): an iterator object

void wp_iterator_reset(WpIterator *self)

  Resets the iterator so we can iterate again from the beginning.

  Parameters:

    - self -- the iterator

gboolean wp_iterator_next(WpIterator *self, GValue *item)

  Gets the next item of the iterator.

  Parameters:

    - self -- the iterator

    - item -- (out): the next item of the iterator

  Returns:

    TRUE if next iterator was obtained, FALSE when the iterator has no more items to iterate through.

gboolean wp_iterator_fold(WpIterator *self, WpIteratorFoldFunc func, GValue *ret, gpointer data)

  Fold a function over the items of the iterator.

  Parameters:

    - self -- the iterator

    - func -- (scope call)(closure data): the fold function

    - ret -- (inout): the accumulator data

    - data -- the user data

  Returns:

    TRUE if all the items were processed, FALSE otherwise.

gboolean wp_iterator_foreach(WpIterator *self, WpIteratorForeachFunc func, gpointer data)

  Iterates over all items of the iterator calling a function.

  Parameters:

    - self -- the iterator

    - func -- (scope call)(closure data): the foreach function

    - data -- the user data

  Returns:

    TRUE if all the items were processed, FALSE otherwise.

WpIterator *wp_iterator_new_ptr_array(GPtrArray *items, GType item_type)

  Creates an iterator from a pointer array.

  Parameters:

    - items -- (element-type gpointer) (transfer full): the items to iterate over

    - item_type -- the type of each item

  Returns:

    (transfer full): a new iterator that iterates over items

WP_TYPE_ITERATOR (wp_iterator_get_type ())

  The WpIterator GType.

WP_ITERATOR_METHODS_VERSION 0U

  The version to set to _WpIteratorMethods::version. This allows future expansion of the struct.