ucx: comparison src/cx/map.h

-:ad5eeb256242
+:6db21dee4929
 typedef struct cx_map_s CxMap;
 /** Type for a map entry. */
 typedef struct cx_map_entry_s CxMapEntry;
+/** Type for a map iterator. */
+typedef struct cx_map_iterator_s CxMapIterator;
 /** Type for map class definitions. */
 typedef struct cx_map_class_s cx_map_class;
 /** Structure for the UCX map. */
 struct cx_map_s {
 /** The map class definition. */
 cx_map_class *cl;
 };
 /**
+* A map entry.
+*/
+struct cx_map_entry_s {
+/**
+* A pointer to the key.
+*/
+const CxHashKey *key;
+/**
+* A pointer to the value.
+*/
+void *value;
+};
+/**
 * The type of iterator for a map.
 */
 enum cx_map_iterator_type {
 /**
 * Iterates over key/value pairs.
 CX_MAP_ITERATOR_KEYS,
 /**
 * Iterates over values only.
 */
 CX_MAP_ITERATOR_VALUES
+};
+/**
+* Internal iterator struct - use CxMapIterator.
+*/
+struct cx_map_iterator_s {
+/**
+* Inherited common data for all iterators.
+*/
+CX_ITERATOR_BASE;
+/**
+* Handle for the source map.
+*/
+union {
+/**
+* Access for mutating iterators.
+*/
+CxMap *m;
+/**
+* Access for normal iterators.
+*/
+const CxMap *c;
+} map;
+/**
+* Handle for the current element.
+*
+* @attention Depends on the map implementation, do not assume a type (better: do not use!).
+*/
+void *elem;
+/**
+* Reserved memory for a map entry.
+*
+* If a map implementation uses an incompatible layout, the iterator needs something
+* to point to during iteration which @em is compatible.
+*/
+CxMapEntry entry;
+/**
+* Field for storing the current slot number.
+*
+* (Used internally)
+*/
+size_t slot;
+/**
+* Counts the elements successfully.
+* It usually does not denote a stable index within the map as it would be for arrays.
+*/
+size_t index;
+/**
+* The size of a value stored in this map.
+*/
+size_t elem_size;
+/**
+* May contain the total number of elements, if known.
+* Set to @c SIZE_MAX when the total number is unknown during iteration.
+*
+* @remark The UCX implementations of #CxMap always know the number of elements they store.
+*/
+size_t elem_count;
+/**
+* The type of this iterator.
+*/
+enum cx_map_iterator_type type;
 };
 /**
 * The class definition for arbitrary maps.
 */
 );
 /**
 * Creates an iterator for this map.
 */
-CxIterator (*iterator)(const CxMap *map, enum cx_map_iterator_type type);
+CxMapIterator (*iterator)(const CxMap *map, enum cx_map_iterator_type type);
-};
-/**
-* A map entry.
-*/
-struct cx_map_entry_s {
-/**
-* A pointer to the key.
-*/
-const CxHashKey *key;
-/**
-* A pointer to the value.
-*/
-void *value;
 };
 /**
 * A shared instance of an empty map.
 *
 }
 /**
 * Creates a value iterator for a map.
 *
+* When the map is storing pointers, those pointers are returned.
+* Otherwise, the iterator iterates over pointers to the memory within the map where the
+* respective elements are stored.
+*
 * @note An iterator iterates over all elements successively. Therefore, the order
 * highly depends on the map implementation and may change arbitrarily when the contents change.
 *
 * @param map the map to create the iterator for
 * @return an iterator for the currently stored values
 */
 cx_attr_nonnull
 cx_attr_nodiscard
-static inline CxIterator cxMapIteratorValues(const CxMap *map) {
+static inline CxMapIterator cxMapIteratorValues(const CxMap *map) {
 return map->cl->iterator(map, CX_MAP_ITERATOR_VALUES);
 }
 /**
 * Creates a key iterator for a map.
 *
-* The elements of the iterator are keys of type CxHashKey.
+* The elements of the iterator are keys of type CxHashKey and the pointer returned
+* during iterator shall be treated as @c const @c CxHashKey* .
 *
 * @note An iterator iterates over all elements successively. Therefore, the order
 * highly depends on the map implementation and may change arbitrarily when the contents change.
 *
 * @param map the map to create the iterator for
 * @return an iterator for the currently stored keys
 */
 cx_attr_nonnull
 cx_attr_nodiscard
-static inline CxIterator cxMapIteratorKeys(const CxMap *map) {
+static inline CxMapIterator cxMapIteratorKeys(const CxMap *map) {
 return map->cl->iterator(map, CX_MAP_ITERATOR_KEYS);
 }
 /**
 * Creates an iterator for a map.
 *
-* The elements of the iterator are key/value pairs of type CxMapEntry.
+* The elements of the iterator are key/value pairs of type CxMapEntry and the pointer returned
+* during iterator shall be treated as @c const @c CxMapEntry* .
 *
 * @note An iterator iterates over all elements successively. Therefore, the order
 * highly depends on the map implementation and may change arbitrarily when the contents change.
 *
 * @param map the map to create the iterator for
 * @see cxMapIteratorKeys()
 * @see cxMapIteratorValues()
 */
 cx_attr_nonnull
 cx_attr_nodiscard
-static inline CxIterator cxMapIterator(const CxMap *map) {
+static inline CxMapIterator cxMapIterator(const CxMap *map) {
 return map->cl->iterator(map, CX_MAP_ITERATOR_PAIRS);
 }
 /**
 * Creates a mutating iterator over the values of a map.
+*
+* When the map is storing pointers, those pointers are returned.
+* Otherwise, the iterator iterates over pointers to the memory within the map where the
+* respective elements are stored.
 *
 * @note An iterator iterates over all elements successively. Therefore, the order
 * highly depends on the map implementation and may change arbitrarily when the contents change.
 *
 * @param map the map to create the iterator for
 * @return an iterator for the currently stored values
 */
 cx_attr_nonnull
 cx_attr_nodiscard
-CxIterator cxMapMutIteratorValues(CxMap *map);
+CxMapIterator cxMapMutIteratorValues(CxMap *map);
 /**
 * Creates a mutating iterator over the keys of a map.
 *
-* The elements of the iterator are keys of type CxHashKey.
+* The elements of the iterator are keys of type CxHashKey and the pointer returned
+* during iterator shall be treated as @c const @c CxHashKey* .
 *
 * @note An iterator iterates over all elements successively. Therefore, the order
 * highly depends on the map implementation and may change arbitrarily when the contents change.
 *
 * @param map the map to create the iterator for
 * @return an iterator for the currently stored keys
 */
 cx_attr_nonnull
 cx_attr_nodiscard
-CxIterator cxMapMutIteratorKeys(CxMap *map);
+CxMapIterator cxMapMutIteratorKeys(CxMap *map);
 /**
 * Creates a mutating iterator for a map.
 *
-* The elements of the iterator are key/value pairs of type CxMapEntry.
+* The elements of the iterator are key/value pairs of type CxMapEntry and the pointer returned
+* during iterator shall be treated as @c const @c CxMapEntry* .
 *
 * @note An iterator iterates over all elements successively. Therefore, the order
 * highly depends on the map implementation and may change arbitrarily when the contents change.
 *
 * @param map the map to create the iterator for
 * @see cxMapMutIteratorKeys()
 * @see cxMapMutIteratorValues()
 */
 cx_attr_nonnull
 cx_attr_nodiscard
-CxIterator cxMapMutIterator(CxMap *map);
+CxMapIterator cxMapMutIterator(CxMap *map);
 #ifdef __cplusplus
 } // end the extern "C" block here, because we want to start overloading
 cx_attr_nonnull
 static inline int cxMapPut(

Mercurial > hg > ucx / file comparison

comparison: src/cx/map.h

src/cx/map.h