~brenns10/sc-collections

2e521057fd1102ba05ed212ed9703a6b5238cd13 — Stephen Brennan 5 months ago 2858fa6 master
docs: add iterator docs (yuck)
4 files changed, 81 insertions(+), 15 deletions(-)

M doc/index.rst
A doc/iterator.rst
M doc/meson.build
M include/sc-collections.h
M doc/index.rst => doc/index.rst +1 -0
@@ 9,6 9,7 @@ Welcome to sc-collections documentation!
   charbuf
   hashtable
   arr
   iterator

sc-collections
--------------

A doc/iterator.rst => doc/iterator.rst +42 -0
@@ 0,0 1,42 @@
Iterator
========

Overview
--------

The Iterator interface exists mainly to support the hash table implementation.
It allows flexible iteration over keys or values. However, the iterator
interface is more general and could be useful for implementing some styles of
application architecture.

The iterator interface has a single function to return the next value and
advance the iterator. It has a separate function to tell whether there is a next
value. Finally, iterators have cleanup functions which must be called when
you're done with them (even if the iterator is stored on the stack).

The iterator lifetime is interesting. Many iterators are intended to be returned
by value, and not have any cleanup required. However, some iterators
(particularly those which compose others), allocate memory behind the scenes.
There is likely some cleanup required in this API to avoid memory leaks.
Happily, for the common case (using iterators over hash table entries), this is
not an issue. The general solution is left as an exercise for a future Stephen.

API
---

Data Structures
^^^^^^^^^^^^^^^

.. doxygenstruct:: sc_iterator

Functions
^^^^^^^^^

.. doxygenfunction:: sc_iterator_close_noop
.. doxygenfunction:: sc_iterator_empty
.. doxygenfunction:: sc_iterator_single_value
.. doxygenfunction:: sc_iterator_concat
.. doxygenfunction:: sc_iterator_concat2
.. doxygenfunction:: sc_iterator_concat3
.. doxygenfunction:: sc_iterator_array
.. doxygenfunction:: sc_iterator_from_args

M doc/meson.build => doc/meson.build +1 -0
@@ 78,6 78,7 @@ sphinx_files = [
	'charbuf.rst',
	'hashtable.rst',
	'arr.rst',
	'iterator.rst',
]
foreach file : sphinx_files
	configure_file(input: file, output: file, copy: true)

M include/sc-collections.h => include/sc-collections.h +37 -15
@@ 16,6 16,8 @@
 *************/

/**
 * @brief Generic iterator interface.
 *
 * A generic iterator interface which can be implemented by data structures or
 * even as a generator.
 *


@@ 23,64 25,84 @@
 * use the data fields declared.
 */
struct sc_iterator {
	void *ds;      /* the container data structure */
	int index;     /* zero-based index for the iterator */
	int state_int; /* some state variables that may help */
	/** @brief the container data structure */
	void *ds;
	/** @brief zero-based index for the iterator */
	int index;
	/** @brief an integer field to use as state */
	int state_int;
	/** @brief a pointer field to use as state */
	void *state_ptr;

	/**
	 * Return true if next() will return another value
	 * @brief Return true if sc_iterator.next will return another value
	 * @param iter Iterator instance
	 */
	bool (*has_next)(struct sc_iterator *iter);

	/**
	 * Return the next value.
	 * @brief Return the next value.
	 * @param iter iterator instance
	 */
	void *(*next)(struct sc_iterator *iter);

	/**
	 * Free any resources associated with the iterator.
	 * @brief Free any resources associated with the iterator.
	 * @param iter iterator instance
	 */
	void (*close)(struct sc_iterator *iter);
};

/**
 * Function which does nothing, and satisfies the signature of close(), w
 * @brief Function which does nothing, and satisfies the signature of close(), w
 * @param iter iterator instance
 */
void sc_iterator_close_noop(struct sc_iterator *iter);
/**
 * Return an empty iterator.
 * @brief Return an empty iterator.
 * @returns An iterator whose has_next returns false
 */
struct sc_iterator sc_iterator_empty(void);
/**
 * Return an iterator which returns a single value.
 * @brief Return an iterator which returns a single value.
 * @param value The value to be returned by the iterator
 * @returns an iterator which returns only @a value
 */
struct sc_iterator sc_iterator_single_value(void *value);

/**
 * Concatenate n iterators. This function takes ownership of the *its pointer;
 * it will be freed upon calling close() on the returned iterator.
 * @brief Concatenate n iterators.
 * @param its Array of iterators which will be combined
 * @param n Number of iterators contained in its
 * @return An iterator which will draw from each component iterator in `its`
 * until all iterators are consumed.
 *
 * This function takes ownership of the @a its pointer; it will be freed upon
 * calling sc_iterator.close on the returned iterator.
 */
struct sc_iterator sc_iterator_concat(struct sc_iterator *its, size_t n);

/**
 * Concatenate two iterators -- a convenience method for sc_iterator_concat()
 * @brief Concatenate two iterators -- a convenience method for sc_iterator_concat()
 * @param left First iterator
 * @param right Second iterator
 * @return New iterator over both
 */
struct sc_iterator sc_iterator_concat2(struct sc_iterator left,
                                       struct sc_iterator right);
/**
 * Concatenate three iterators -- a convenience method for sc_iterator_concat()
 * @brief Concatenate three iterators -- a convenience method for sc_iterator_concat()
 * @param a First iterator
 * @param b Second iterator
 * @param c Third iterator
 * @return New iterator over all three
 */
struct sc_iterator sc_iterator_concat3(struct sc_iterator a,
                                       struct sc_iterator b,
                                       struct sc_iterator c);

/**
 * Return an iterator which yields items out of an array.
 * @brief Return an iterator which yields items out of an array.
 * @param array An array of items to yield
 * @param len Number of items in the array
 * @param own If true is passed here, then the array will be freed when close()


@@ 91,7 113,7 @@ struct sc_iterator sc_iterator_concat3(struct sc_iterator a,
 */
struct sc_iterator sc_iterator_array(void **array, int len, bool own);
/**
 * Return an iterator which will yield each item passed as an argument
 * @brief Return an iterator which will yield each item passed as an argument
 * @param n Number of items provided in the args
 * @param ... Several void* pointers to return from the iterator
 * @return An iterator which yields the items passed in the function.