ucx: src/cx/map.h@89b2a83728b1

     1 /*

     2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

     3  *

     4  * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.

     5  *

     6  * Redistribution and use in source and binary forms, with or without

     7  * modification, are permitted provided that the following conditions are met:

     8  *

     9  *   1. Redistributions of source code must retain the above copyright

    10  *      notice, this list of conditions and the following disclaimer.

    11  *

    12  *   2. Redistributions in binary form must reproduce the above copyright

    13  *      notice, this list of conditions and the following disclaimer in the

    14  *      documentation and/or other materials provided with the distribution.

    15  *

    16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

    17  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

    18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

    19  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE

    20  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

    21  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

    22  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

    23  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN

    24  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

    25  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE

    26  * POSSIBILITY OF SUCH DAMAGE.

    27  */

    28 /**

    29  * \file map.h

    30  * \brief Interface for map implementations.

    31  * \author Mike Becker

    32  * \author Olaf Wintermann

    33  * \version 3.0

    34  * \copyright 2-Clause BSD License

    35  */

    37 #ifndef UCX_MAP_H

    38 #define UCX_MAP_H

    40 #include "common.h"

    41 #include "allocator.h"

    42 #include "iterator.h"

    44 #ifdef    __cplusplus

    45 extern "C" {

    46 #endif

    48 /** Type for the UCX map. */

    49 typedef struct cx_map_s CxMap;

    51 /** Type for a map entry. */

    52 typedef struct cx_map_entry_s CxMapEntry;

    54 /** Type for map class definitions. */

    55 typedef struct cx_map_class_s cx_map_class;

    57 /** Structure for the UCX map. */

    58 struct cx_map_s {

    59     /** The map class definition. */

    60     cx_map_class *cl;

    61     /** An allocator that is used for the map elements. */

    62     CxAllocator *allocator;

    63     /** The number of elements currently stored. */

    64     size_t size;

    65     // TODO: elemsize + a flag if values shall be copied to the map

    66 };

    68 /**

    69  * The class definition for arbitrary maps.

    70  */

    71 struct cx_map_class_s {

    72     /**

    73      * Deallocates the entire memory.

    74      */

    75     __attribute__((__nonnull__))

    76     void (*destructor)(struct cx_map_s *map);

    78     /**

    79      * Removes all elements.

    80      */

    81     __attribute__((__nonnull__))

    82     void (*clear)(struct cx_map_s *map);

    84     /**

    85      * Add or overwrite an element.

    86      */

    87     __attribute__((__nonnull__))

    88     int (*put)(

    89             CxMap *map,

    90             CxDataPtr key,

    91             void *value

    92     );

    94     /**

    95      * Returns an element.

    96      */

    97     __attribute__((__nonnull__, __warn_unused_result__))

    98     void *(*get)(

    99             CxMap const *map,

   100             CxDataPtr key

   101     );

   103     /**

   104      * Removes an element.

   105      */

   106     __attribute__((__nonnull__, __warn_unused_result__))

   107     void *(*remove)(

   108             CxMap *map,

   109             CxDataPtr key

   110     );

   112     /**

   113      * Iterator over the key/value pairs.

   114      */

   115     __attribute__((__nonnull__, __warn_unused_result__))

   116     CxIterator (*iterator)(CxMap const *map);

   118     /**

   119      * Iterator over the keys.

   120      */

   121     __attribute__((__nonnull__, __warn_unused_result__))

   122     CxIterator (*iterator_keys)(CxMap const *map);

   124     /**

   125      * Iterator over the values.

   126      */

   127     __attribute__((__nonnull__, __warn_unused_result__))

   128     CxIterator (*iterator_values)(CxMap const *map);

   129 };

   131 /**

   132  * A map entry.

   133  */

   134 struct cx_map_entry_s {

   135     /**

   136      * The key.

   137      */

   138     CxDataPtr key;

   139     /**

   140      * The value.

   141      */

   142     void const *value;

   143 };

   146 /**

   147  * Deallocates the memory of the specified map.

   148  *

   149  * @param map the map to be destroyed

   150  */

   151 __attribute__((__nonnull__))

   152 static inline void cxMapDestroy(CxMap *map) {

   153     // TODO: likely to add auto-free feature for contents in the future

   154     map->cl->destructor(map);

   155 }

   158 /**

   159  * Clears a map by removing all elements.

   160  *

   161  * @param map the map to be cleared

   162  */

   163 __attribute__((__nonnull__))

   164 static inline void cxMapClear(CxMap *map) {

   165     map->cl->clear(map);

   166 }

   168 /**

   169  * Puts a key/value-pair into the map.

   170  *

   171  * @param map the map

   172  * @param key the key

   173  * @param value the value

   174  * @return 0 on success, non-zero value on failure

   175  */

   176 __attribute__((__nonnull__))

   177 static inline int cxMapPut(

   178         CxMap *map,

   179         CxDataPtr key,

   180         void *value

   181 ) {

   182     return map->cl->put(map, key, value);

   183 }

   185 /**

   186  * Retrieves a value by using a key.

   187  *

   188  * @param map the map

   189  * @param key the key

   190  * @return the value

   191  */

   192 __attribute__((__nonnull__, __warn_unused_result__))

   193 void *cxMapGet(

   194         CxMap const *map,

   195         CxDataPtr key

   196 ) {

   197     return map->cl->get(map, key);

   198 }

   200 /**

   201  * Removes a key/value-pair from the map by using the key.

   202  *

   203  * @param map the map

   204  * @param key the key

   205  * @return the removed value

   206  */

   207 __attribute__((__nonnull__, __warn_unused_result__))

   208 void *cxMapRemove(

   209         CxMap *map,

   210         CxDataPtr key

   211 ) {

   212     return map->cl->remove(map, key);

   213 }

   215 // TODO: set-like map operations (union, intersect, difference)

   217 /**

   218  * Creates a value iterator for a map.

   219  *

   220  * \note An iterator iterates over all elements successively. Therefore the order

   221  * highly depends on the map implementation and may change arbitrarily when the contents change.

   222  *

   223  * @param map the map to create the iterator for

   224  * @return an iterator for the currently stored values

   225  */

   226 __attribute__((__nonnull__, __warn_unused_result__))

   227 static inline CxIterator cxMapIteratorValues(CxMap const *map) {

   228     return map->cl->iterator_values(map);

   229 }

   231 /**

   232  * Creates a key iterator for a map.

   233  *

   234  * \note An iterator iterates over all elements successively. Therefore the order

   235  * highly depends on the map implementation and may change arbitrarily when the contents change.

   236  *

   237  * @param map the map to create the iterator for

   238  * @return an iterator for the currently stored keys

   239  */

   240 __attribute__((__nonnull__, __warn_unused_result__))

   241 static inline CxIterator cxMapIteratorKeys(CxMap const *map) {

   242     return map->cl->iterator_keys(map);

   243 }

   245 /**

   246  * Creates an iterator for a map.

   247  *

   248  * The values of the iterator are dynamically created key/value pairs of type CxMapEntry.

   249  *

   250  * \note An iterator iterates over all elements successively. Therefore the order

   251  * highly depends on the map implementation and may change arbitrarily when the contents change.

   252  *

   253  * @param map the map to create the iterator for

   254  * @return an iterator for the currently stored keys

   255  * @see cxMapIteratorKeys()

   256  * @see cxMapIteratorValues()

   257  */

   258 __attribute__((__nonnull__, __warn_unused_result__))

   259 static inline CxIterator cxMapIterator(CxMap const *map) {

   260     return map->cl->iterator(map);

   261 }

   264 #ifdef    __cplusplus

   265 }

   266 #endif

   268 #endif // UCX_MAP_H

Mercurial > hg > ucx / file revision

src/cx/map.h@89b2a83728b1

src/cx/map.h