ucx: src/cx/map.h@64919f63f059 (annotated)

src/cx/map.h@64919f63f059 (annotated)

src/cx/map.h

Tue, 18 Apr 2023 19:10:45 +0200

author: Mike Becker <universe@uap-core.de>
date: Tue, 18 Apr 2023 19:10:45 +0200
changeset 686: 64919f63f059
parent 685: 2dd841e364af
child 689: 5d0244c6fa3e
permissions: -rw-r--r--

add destructor functions for maps - fixes #253

 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
  * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:
  *
  *   1. Redistributions of source code must retain the above copyright
  *      notice, this list of conditions and the following disclaimer.
  *
  *   2. Redistributions in binary form must reproduce the above copyright
  *      notice, this list of conditions and the following disclaimer in the
  *      documentation and/or other materials provided with the distribution.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
 /**
  * \file map.h
  * \brief Interface for map implementations.
  * \author Mike Becker
  * \author Olaf Wintermann
  * \version 3.0
  * \copyright 2-Clause BSD License
  */
 #ifndef UCX_MAP_H
 #define UCX_MAP_H
 #include "common.h"
 #include "collection.h"
 #include "hash_key.h"
 #ifdef    __cplusplus
 extern "C" {
 #endif
 /** Type for the UCX map. */
 typedef struct cx_map_s CxMap;
 /** Type for a map entry. */
 typedef struct cx_map_entry_s CxMapEntry;
 /** Type for map class definitions. */
 typedef struct cx_map_class_s cx_map_class;
 /** Structure for the UCX map. */
 struct cx_map_s {
     CX_COLLECTION_MEMBERS
     /** The map class definition. */
     cx_map_class *cl;
 };
 /**
  * The class definition for arbitrary maps.
  */
 struct cx_map_class_s {
     /**
      * Deallocates the entire memory.
      */
     __attribute__((__nonnull__))
     void (*destructor)(struct cx_map_s *map);
     /**
      * Removes all elements.
      */
     __attribute__((__nonnull__))
     void (*clear)(struct cx_map_s *map);
     /**
      * Add or overwrite an element.
      */
     __attribute__((__nonnull__))
     int (*put)(
             CxMap *map,
             CxHashKey key,
             void *value
     );
     /**
      * Returns an element.
      */
     __attribute__((__nonnull__, __warn_unused_result__))
     void *(*get)(
             CxMap const *map,
             CxHashKey key
     );
     /**
      * Removes an element.
      */
     __attribute__((__nonnull__))
     void *(*remove)(
             CxMap *map,
             CxHashKey key,
             bool destroy
     );
     /**
      * Iterator over the key/value pairs.
      */
     __attribute__((__nonnull__, __warn_unused_result__))
     CxIterator (*iterator)(CxMap const *map);
     /**
      * Iterator over the keys.
      */
     __attribute__((__nonnull__, __warn_unused_result__))
     CxIterator (*iterator_keys)(CxMap const *map);
     /**
      * Iterator over the values.
      */
     __attribute__((__nonnull__, __warn_unused_result__))
     CxIterator (*iterator_values)(CxMap const *map);
     /**
      * Mutating iterator over the key/value pairs.
      */
     __attribute__((__nonnull__, __warn_unused_result__))
     CxMutIterator (*mut_iterator)(CxMap *map);
     /**
      * Mutating iterator over the keys.
      */
     __attribute__((__nonnull__, __warn_unused_result__))
     CxMutIterator (*mut_iterator_keys)(CxMap *map);
     /**
      * Mutating iterator over the values.
      */
     __attribute__((__nonnull__, __warn_unused_result__))
     CxMutIterator (*mut_iterator_values)(CxMap *map);
 };
 /**
  * A map entry.
  */
 struct cx_map_entry_s {
     /**
      * A pointer to the key.
      */
     CxHashKey const *key;
     /**
      * A pointer to the value.
      */
     void *value;
 };
 /**
  * Advises the map to store copies of the objects (default mode of operation).
  *
  * Retrieving objects from this map will yield pointers to the copies stored
  * within this list.
  *
  * @param map the map
  * @see cxMapStorePointers()
  */
 __attribute__((__nonnull__))
 static inline void cxMapStoreObjects(CxMap *map) {
     map->store_pointer = false;
 }
 /**
  * Advises the map to only store pointers to the objects.
  *
  * Retrieving objects from this list will yield the original pointers stored.
  *
  * @note This function forcibly sets the element size to the size of a pointer.
  * Invoking this function on a non-empty map that already stores copies of
  * objects is undefined.
  *
  * @param map the map
  * @see cxMapStoreObjects()
  */
 __attribute__((__nonnull__))
 static inline void cxMapStorePointers(CxMap *map) {
     map->store_pointer = true;
     map->item_size = sizeof(void *);
 }
 /**
  * Deallocates the memory of the specified map.
  *
  * @param map the map to be destroyed
  */
 __attribute__((__nonnull__))
 static inline void cxMapDestroy(CxMap *map) {
     map->cl->destructor(map);
 }
 /**
  * Clears a map by removing all elements.
  *
  * @param map the map to be cleared
  */
 __attribute__((__nonnull__))
 static inline void cxMapClear(CxMap *map) {
     map->cl->clear(map);
 }
 /**
  * Puts a key/value-pair into the map.
  *
  * @param map the map
  * @param key the key
  * @param value the value
  * @return 0 on success, non-zero value on failure
  */
 __attribute__((__nonnull__))
 static inline int cxMapPut(
         CxMap *map,
         CxHashKey key,
         void *value
 ) {
     return map->cl->put(map, key, value);
 }
 /**
  * Retrieves a value by using a key.
  *
  * @param map the map
  * @param key the key
  * @return the value
  */
 __attribute__((__nonnull__, __warn_unused_result__))
 static inline void *cxMapGet(
         CxMap const *map,
         CxHashKey key
 ) {
     return map->cl->get(map, key);
 }
 /**
  * Removes a key/value-pair from the map by using the key.
  *
  * Always invokes the destructor function, if any, on the removed element.
  * If this map is storing pointers and you just want to retrieve the pointer
  * without invoking the destructor, use cxMapRemoveAndGet().
  * If you just want to detach the element from the map without invoking the
  * destructor or returning the element, use cxMapDetach().
  *
  * @param map the map
  * @param key the key
  * @see cxMapRemoveAndGet()
  * @see cxMapDetach()
  */
 __attribute__((__nonnull__))
 static inline void cxMapRemove(
         CxMap *map,
         CxHashKey key
 ) {
     (void) map->cl->remove(map, key, true);
 }
 /**
  * Detaches a key/value-pair from the map by using the key
  * without invoking the destructor.
  *
  * In general, you should only use this function if the map does not own
  * the data and there is a valid reference to the data somewhere else
  * in the program. In all other cases it is prefarable to use
  * cxMapRemove() or cxMapRemoveAndGet().
  *
  * @param map the map
  * @param key the key
  * @see cxMapRemove()
  * @see cxMapRemoveAndGet()
  */
 __attribute__((__nonnull__))
 static inline void cxMapDetach(
         CxMap *map,
         CxHashKey key
 ) {
     (void) map->cl->remove(map, key, false);
 }
 /**
  * Removes a key/value-pair from the map by using the key.
  *
  * This function can be used when the map is storing pointers,
  * in order to retrieve the pointer from the map without invoking
  * any destructor function. Sometimes you do not want the pointer
  * to be returned - in that case (instead of suppressing the "unused
  * result" warning) you can use cxMapDetach().
  *
  * If this map is not storing pointers, this function behaves like
  * cxMapRemove() and returns \c NULL.
  *
  * @param map the map
  * @param key the key
  * @return the stored pointer or \c NULL if either the key is not present
  * in the map or the map is not storing pointers
  * @see cxMapStorePointers()
  * @see cxMapDetach()
  */
 __attribute__((__nonnull__, __warn_unused_result__))
 static inline void *cxMapRemoveAndGet(
         CxMap *map,
         CxHashKey key
 ) {
     return map->cl->remove(map, key, !map->store_pointer);
 }
 // TODO: set-like map operations (union, intersect, difference)
 /**
  * Creates a value iterator for a map.
  *
  * \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
  */
 __attribute__((__nonnull__, __warn_unused_result__))
 static inline CxIterator cxMapIteratorValues(CxMap *map) {
     return map->cl->iterator_values(map);
 }
 /**
  * Creates a key iterator for a map.
  *
  * The elements of the iterator are keys of type 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
  */
 __attribute__((__nonnull__, __warn_unused_result__))
 static inline CxIterator cxMapIteratorKeys(CxMap *map) {
     return map->cl->iterator_keys(map);
 }
 /**
  * Creates an iterator for a map.
  *
  * The elements of the iterator are key/value pairs of type 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
  * @return an iterator for the currently stored entries
  * @see cxMapIteratorKeys()
  * @see cxMapIteratorValues()
  */
 __attribute__((__nonnull__, __warn_unused_result__))
 static inline CxIterator cxMapIterator(CxMap *map) {
     return map->cl->iterator(map);
 }
 /**
  * Creates a mutating iterator over the values of a map.
  *
  * \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
  */
 __attribute__((__nonnull__, __warn_unused_result__))
 static inline CxMutIterator cxMapMutIteratorValues(CxMap *map) {
     return map->cl->mut_iterator_values(map);
 }
 /**
  * Creates a mutating iterator over the keys of a map.
  *
  * The elements of the iterator are keys of type 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
  */
 __attribute__((__nonnull__, __warn_unused_result__))
 static inline CxMutIterator cxMapMutIteratorKeys(CxMap *map) {
     return map->cl->mut_iterator_keys(map);
 }
 /**
  * Creates a mutating iterator for a map.
  *
  * The elements of the iterator are key/value pairs of type 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
  * @return an iterator for the currently stored entries
  * @see cxMapMutIteratorKeys()
  * @see cxMapMutIteratorValues()
  */
 __attribute__((__nonnull__, __warn_unused_result__))
 static inline CxMutIterator cxMapMutIterator(CxMap *map) {
     return map->cl->mut_iterator(map);
 }
 #ifdef    __cplusplus
 }
 #endif
 #endif // UCX_MAP_H

Mercurial > hg > ucx / annotate

src/cx/map.h@64919f63f059 (annotated)

src/cx/map.h