dbutils: comparison ucx/cx/iterator.h

-:80f9d007cb52
+:0aa8cbd7912e
 #ifndef UCX_ITERATOR_H
 #define UCX_ITERATOR_H
 #include "common.h"
+#ifdef __cplusplus
+extern "C" {
+#endif
+/**
+* Common data for all iterators.
+*/
 struct cx_iterator_base_s {
 /**
 * True iff the iterator points to valid data.
 */
-__attribute__ ((__nonnull__))
+cx_attr_nonnull
-bool (*valid)(void const *);
+bool (*valid)(const void *);
 /**
 * Returns a pointer to the current element.
 *
 * When valid returns false, the behavior of this function is undefined.
 */
-__attribute__ ((__nonnull__))
+cx_attr_nonnull
-void *(*current)(void const *);
+cx_attr_nodiscard
+void *(*current)(const void *);
 /**
 * Original implementation in case the function needs to be wrapped.
 */
-__attribute__ ((__nonnull__))
+cx_attr_nonnull
-void *(*current_impl)(void const *);
+cx_attr_nodiscard
+void *(*current_impl)(const void *);
 /**
 * Advances the iterator.
 *
 * When valid returns false, the behavior of this function is undefined.
 */
-__attribute__ ((__nonnull__))
+cx_attr_nonnull
 void (*next)(void *);
 /**
 * Indicates whether this iterator may remove elements.
 */
 bool mutating;
 bool remove;
 };
 /**
 * Declares base attributes for an iterator.
+* Must be the first member of an iterator structure.
 */
 #define CX_ITERATOR_BASE struct cx_iterator_base_s base
 /**
 * Internal iterator struct - use CxIterator.
 */
 struct cx_iterator_s {
+/**
+* Inherited common data for all iterators.
+*/
 CX_ITERATOR_BASE;
 /**
 * Handle for the current element.
 */
 */
 void *m;
 /**
 * Access for normal iterators.
 */
-void const *c;
+const void *c;
 } src_handle;
 /**
 * Field for storing a key-value pair.
 * May be used by iterators that iterate over k/v-collections.
 */
 struct {
 /**
 * A pointer to the key.
 */
-void const *key;
+const void *key;
 /**
 * A pointer to the value.
 */
 void *value;
 } kv_data;
 * @param iter the iterator
 */
 #define cxIteratorFlagRemoval(iter) (iter).base.remove |= (iter).base.mutating
 /**
+* Obtains a reference to an arbitrary iterator.
+*
+* This is useful for APIs that expect some iterator as an argument.
+*
+* @param iter the iterator
+*/
+#define cxIteratorRef(iter) &((iter).base)
+/**
 * Loops over an iterator.
 * @param type the type of the elements
 * @param elem the name of the iteration variable
 * @param iter the iterator
 */
 * Creates an iterator for the specified plain array.
 *
 * The \p array can be \c NULL in which case the iterator will be immediately
 * initialized such that #cxIteratorValid() returns \c false.
 *
+* This iterator yields the addresses of the array elements.
+* If you want to iterator over an array of pointers, you can
+* use cxIteratorPtr() to create an iterator which directly
+* yields the stored pointers.
 *
 * @param array a pointer to the array (can be \c NULL)
 * @param elem_size the size of one array element
 * @param elem_count the number of elements in the array
 * @return an iterator for the specified array
-*/
+* @see cxIteratorPtr()
-__attribute__((__warn_unused_result__))
+*/
+cx_attr_nodiscard
 CxIterator cxIterator(
-void const *array,
+const void *array,
 size_t elem_size,
 size_t elem_count
 );
 /**
 * @param elem_count the number of elements in the array
 * @param remove_keeps_order \c true if the order of elements must be preserved
 * when removing an element
 * @return an iterator for the specified array
 */
-__attribute__((__warn_unused_result__))
+cx_attr_nodiscard
 CxIterator cxMutIterator(
 void *array,
 size_t elem_size,
 size_t elem_count,
 bool remove_keeps_order
 );
+/**
+* Creates an iterator for the specified plain pointer array.
+*
+* This iterator assumes that every element in the array is a pointer
+* and yields exactly those pointers during iteration (while in contrast
+* an iterator created with cxIterator() would return the addresses
+* of those pointers within the array).
+*
+* @param array a pointer to the array (can be \c NULL)
+* @param elem_count the number of elements in the array
+* @return an iterator for the specified array
+* @see cxIterator()
+*/
+cx_attr_nodiscard
+CxIterator cxIteratorPtr(
+const void *array,
+size_t elem_count
+);
+/**
+* Creates a mutating iterator for the specified plain pointer array.
+*
+* This is the mutating variant of cxIteratorPtr(). See also
+* cxMutIterator().
+*
+* @param array a pointer to the array (can be \c NULL)
+* @param elem_count the number of elements in the array
+* @param remove_keeps_order \c true if the order of elements must be preserved
+* when removing an element
+* @return an iterator for the specified array
+* @see cxMutIterator()
+* @see cxIteratorPtr()
+*/
+cx_attr_nodiscard
+CxIterator cxMutIteratorPtr(
+void *array,
+size_t elem_count,
+bool remove_keeps_order
+);
+#ifdef __cplusplus
+} // extern "C"
+#endif
 #endif // UCX_ITERATOR_H

Mercurial > hg > dbutils / file comparison

comparison: ucx/cx/iterator.h

ucx/cx/iterator.h