1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/cx/map.h Wed May 18 16:26:32 2022 +0200
1.3 @@ -0,0 +1,268 @@
1.4 +/*
1.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
1.6 + *
1.7 + * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
1.8 + *
1.9 + * Redistribution and use in source and binary forms, with or without
1.10 + * modification, are permitted provided that the following conditions are met:
1.11 + *
1.12 + * 1. Redistributions of source code must retain the above copyright
1.13 + * notice, this list of conditions and the following disclaimer.
1.14 + *
1.15 + * 2. Redistributions in binary form must reproduce the above copyright
1.16 + * notice, this list of conditions and the following disclaimer in the
1.17 + * documentation and/or other materials provided with the distribution.
1.18 + *
1.19 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
1.20 + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1.21 + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
1.22 + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
1.23 + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
1.24 + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
1.25 + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
1.26 + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
1.27 + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
1.28 + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
1.29 + * POSSIBILITY OF SUCH DAMAGE.
1.30 + */
1.31 +/**
1.32 + * \file map.h
1.33 + * \brief Interface for map implementations.
1.34 + * \author Mike Becker
1.35 + * \author Olaf Wintermann
1.36 + * \version 3.0
1.37 + * \copyright 2-Clause BSD License
1.38 + */
1.39 +
1.40 +#ifndef UCX_MAP_H
1.41 +#define UCX_MAP_H
1.42 +
1.43 +#include "common.h"
1.44 +#include "allocator.h"
1.45 +#include "iterator.h"
1.46 +
1.47 +#ifdef __cplusplus
1.48 +extern "C" {
1.49 +#endif
1.50 +
1.51 +/** Type for the UCX map. */
1.52 +typedef struct cx_map_s CxMap;
1.53 +
1.54 +/** Type for a map entry. */
1.55 +typedef struct cx_map_entry_s CxMapEntry;
1.56 +
1.57 +/** Type for map class definitions. */
1.58 +typedef struct cx_map_class_s cx_map_class;
1.59 +
1.60 +/** Structure for the UCX map. */
1.61 +struct cx_map_s {
1.62 + /** The map class definition. */
1.63 + cx_map_class *cl;
1.64 + /** An allocator that is used for the map elements. */
1.65 + CxAllocator *allocator;
1.66 + /** The number of elements currently stored. */
1.67 + size_t size;
1.68 + // TODO: elemsize + a flag if values shall be copied to the map
1.69 +};
1.70 +
1.71 +/**
1.72 + * The class definition for arbitrary maps.
1.73 + */
1.74 +struct cx_map_class_s {
1.75 + /**
1.76 + * Deallocates the entire memory.
1.77 + */
1.78 + __attribute__((__nonnull__))
1.79 + void (*destructor)(struct cx_map_s *map);
1.80 +
1.81 + /**
1.82 + * Removes all elements.
1.83 + */
1.84 + __attribute__((__nonnull__))
1.85 + void (*clear)(struct cx_map_s *map);
1.86 +
1.87 + /**
1.88 + * Add or overwrite an element.
1.89 + */
1.90 + __attribute__((__nonnull__))
1.91 + int (*put)(
1.92 + CxMap *map,
1.93 + CxDataPtr key,
1.94 + void const *value
1.95 + );
1.96 +
1.97 + /**
1.98 + * Returns an element.
1.99 + */
1.100 + __attribute__((__nonnull__, __warn_unused_result__))
1.101 + void *(*get)(
1.102 + CxMap const *map,
1.103 + CxDataPtr key
1.104 + );
1.105 +
1.106 + /**
1.107 + * Removes an element.
1.108 + */
1.109 + __attribute__((__nonnull__, __warn_unused_result__))
1.110 + void *(*remove)(
1.111 + CxMap const *map,
1.112 + CxDataPtr key
1.113 + );
1.114 +
1.115 + /**
1.116 + * Iterator over the key/value pairs.
1.117 + */
1.118 + __attribute__((__nonnull__, __warn_unused_result__))
1.119 + CxIterator (*iterator)(CxMap const *map);
1.120 +
1.121 + /**
1.122 + * Iterator over the keys.
1.123 + */
1.124 + __attribute__((__nonnull__, __warn_unused_result__))
1.125 + CxIterator (*iterator_keys)(CxMap const *map);
1.126 +
1.127 + /**
1.128 + * Iterator over the values.
1.129 + */
1.130 + __attribute__((__nonnull__, __warn_unused_result__))
1.131 + CxIterator (*iterator_values)(CxMap const *map);
1.132 +};
1.133 +
1.134 +/**
1.135 + * A map entry.
1.136 + */
1.137 +struct cx_map_entry_s {
1.138 + /**
1.139 + * The key.
1.140 + */
1.141 + CxDataPtr key;
1.142 + /**
1.143 + * The value.
1.144 + */
1.145 + void const *value;
1.146 +};
1.147 +
1.148 +
1.149 +/**
1.150 + * Deallocates the memory of the specified map.
1.151 + *
1.152 + * @param map the map to be destroyed
1.153 + */
1.154 +__attribute__((__nonnull__))
1.155 +static inline void cxMapDestroy(CxMap *map) {
1.156 + // TODO: likely to add auto-free feature for contents in the future
1.157 + map->cl->destructor(map);
1.158 +}
1.159 +
1.160 +
1.161 +/**
1.162 + * Clears a map by removing all elements.
1.163 + *
1.164 + * @param map the map to be cleared
1.165 + */
1.166 +__attribute__((__nonnull__))
1.167 +static inline void cxMapClear(CxMap *map) {
1.168 + map->cl->clear(map);
1.169 +}
1.170 +
1.171 +/**
1.172 + * Puts a key/value-pair into the map.
1.173 + *
1.174 + * @param map the map
1.175 + * @param key the key
1.176 + * @param value the value
1.177 + * @return 0 on success, non-zero value on failure
1.178 + */
1.179 +__attribute__((__nonnull__))
1.180 +static inline int cxMapPut(
1.181 + CxMap *map,
1.182 + CxDataPtr key,
1.183 + void const *value
1.184 +) {
1.185 + return map->cl->put(map, key, value);
1.186 +}
1.187 +
1.188 +/**
1.189 + * Retrieves a value by using a key.
1.190 + *
1.191 + * @param map the map
1.192 + * @param key the key
1.193 + * @return the value
1.194 + */
1.195 +__attribute__((__nonnull__, __warn_unused_result__))
1.196 +void *cxMapGet(
1.197 + CxMap const *map,
1.198 + CxDataPtr key
1.199 +) {
1.200 + return map->cl->get(map, key);
1.201 +}
1.202 +
1.203 +/**
1.204 + * Removes a key/value-pair from the map by using the key.
1.205 + *
1.206 + * @param map the map
1.207 + * @param key the key
1.208 + * @return the removed value
1.209 + */
1.210 +__attribute__((__nonnull__, __warn_unused_result__))
1.211 +void *cxMapRemove(
1.212 + CxMap *map,
1.213 + CxDataPtr key
1.214 +) {
1.215 + return map->cl->remove(map, key);
1.216 +}
1.217 +
1.218 +// TODO: set-like map operations (union, intersect, difference)
1.219 +
1.220 +/**
1.221 + * Creates a value iterator for a map.
1.222 + *
1.223 + * \note An iterator iterates over all elements successively. Therefore the order
1.224 + * highly depends on the map implementation and may change arbitrarily when the contents change.
1.225 + *
1.226 + * @param map the map to create the iterator for
1.227 + * @return an iterator for the currently stored values
1.228 + */
1.229 +__attribute__((__nonnull__, __warn_unused_result__))
1.230 +static inline CxIterator cxMapIteratorValues(CxMap const *map) {
1.231 + return map->cl->iterator_values(map);
1.232 +}
1.233 +
1.234 +/**
1.235 + * Creates a key iterator for a map.
1.236 + *
1.237 + * \note An iterator iterates over all elements successively. Therefore the order
1.238 + * highly depends on the map implementation and may change arbitrarily when the contents change.
1.239 + *
1.240 + * @param map the map to create the iterator for
1.241 + * @return an iterator for the currently stored keys
1.242 + */
1.243 +__attribute__((__nonnull__, __warn_unused_result__))
1.244 +static inline CxIterator cxMapIteratorKeys(CxMap const *map) {
1.245 + return map->cl->iterator_keys(map);
1.246 +}
1.247 +
1.248 +/**
1.249 + * Creates an iterator for a map.
1.250 + *
1.251 + * The values of the iterator are dynamically created key/value pairs of type CxMapEntry.
1.252 + *
1.253 + * \note An iterator iterates over all elements successively. Therefore the order
1.254 + * highly depends on the map implementation and may change arbitrarily when the contents change.
1.255 + *
1.256 + * @param map the map to create the iterator for
1.257 + * @return an iterator for the currently stored keys
1.258 + * @see cxMapIteratorKeys()
1.259 + * @see cxMapIteratorValues()
1.260 + */
1.261 +__attribute__((__nonnull__, __warn_unused_result__))
1.262 +static inline CxIterator cxMapIterator(CxMap const *map) {
1.263 + return map->cl->iterator(map);
1.264 +}
1.265 +
1.266 +
1.267 +#ifdef __cplusplus
1.268 +}
1.269 +#endif
1.270 +
1.271 +#endif // UCX_MAP_H
1.272 \ No newline at end of file
