/*
* 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
* \copyright 2-Clause BSD License
*/
#ifndef UCX_MAP_H
#define UCX_MAP_H
#include "common.h"
#include "collection.h"
#include "string.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 {
/**
* Base attributes.
*/
CX_COLLECTION_BASE;
/** The map class definition. */
cx_map_class *cl;
};
/**
* The type of iterator for a map.
*/
enum cx_map_iterator_type {
/**
* Iterates over key/value pairs.
*/
CX_MAP_ITERATOR_PAIRS,
/**
* Iterates over keys only.
*/
CX_MAP_ITERATOR_KEYS,
/**
* Iterates over values only.
*/
CX_MAP_ITERATOR_VALUES
};
/**
* 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
);
/**
* Creates an iterator for this map.
*/
__attribute__((__nonnull__, __warn_unused_result__))
CxIterator (*iterator)(CxMap const *map, enum cx_map_iterator_type type);
};
/**
* A map entry.
*/
struct cx_map_entry_s {
/**
* A pointer to the key.
*/
CxHashKey const *key;
/**
* A pointer to the value.
*/
void *value;
};
/**
* A shared instance of an empty map.
*
* Writing to that map is undefined.
*/
extern CxMap *const cxEmptyMap;
/**
* 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->collection.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->collection.store_pointer = true;
map->collection.elem_size = sizeof(void *);
}
/**
* Returns true, if this map is storing pointers instead of the actual data.
*
* @param map
* @return true, if this map is storing pointers
* @see cxMapStorePointers()
*/
__attribute__((__nonnull__))
static inline bool cxMapIsStoringPointers(CxMap const *map) {
return map->collection.store_pointer;
}
/**
* 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);
}
/**
* Returns the number of elements in this map.
*
* @param map the map
* @return the number of stored elements
*/
__attribute__((__nonnull__))
static inline size_t cxMapSize(CxMap const *map) {
return map->collection.size;
}
// 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 const *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.
*
* \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 const *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.
*
* \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 const *map) {
return map->cl->iterator(map, CX_MAP_ITERATOR_PAIRS);
}
/**
* 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__))
CxIterator cxMapMutIteratorValues(CxMap *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__))
CxIterator cxMapMutIteratorKeys(CxMap *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__))
CxIterator cxMapMutIterator(CxMap *map);
#ifdef __cplusplus
} // end the extern "C" block here, because we want to start overloading
/**
* 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 const &key,
void *value
) {
return map->cl->put(map, key, value);
}
/**
* 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,
cxstring const &key,
void *value
) {
return map->cl->put(map, cx_hash_key_cxstr(key), value);
}
/**
* 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,
cxmutstr const &key,
void *value
) {
return map->cl->put(map, cx_hash_key_cxstr(key), value);
}
/**
* 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,
char const *key,
void *value
) {
return map->cl->put(map, cx_hash_key_str(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 const &key
) {
return map->cl->get(map, key);
}
/**
* 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,
cxstring const &key
) {
return map->cl->get(map, cx_hash_key_cxstr(key));
}
/**
* 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,
cxmutstr const &key
) {
return map->cl->get(map, cx_hash_key_cxstr(key));
}
/**
* 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,
char const *key
) {
return map->cl->get(map, cx_hash_key_str(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 const &key
) {
(void) map->cl->remove(map, key, true);
}
/**
* 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,
cxstring const &key
) {
(void) map->cl->remove(map, cx_hash_key_cxstr(key), true);
}
/**
* 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,
cxmutstr const &key
) {
(void) map->cl->remove(map, cx_hash_key_cxstr(key), true);
}
/**
* 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,
char const *key
) {
(void) map->cl->remove(map, cx_hash_key_str(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 preferable 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 const &key
) {
(void) map->cl->remove(map, key, false);
}
/**
* 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 preferable 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,
cxstring const &key
) {
(void) map->cl->remove(map, cx_hash_key_cxstr(key), false);
}
/**
* 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 preferable 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,
cxmutstr const &key
) {
(void) map->cl->remove(map, cx_hash_key_cxstr(key), false);
}
/**
* 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 preferable 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,
char const *key
) {
(void) map->cl->remove(map, cx_hash_key_str(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);
}
/**
* 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,
cxstring key
) {
return map->cl->remove(map, cx_hash_key_cxstr(key), !map->store_pointer);
}
/**
* 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,
cxmutstr key
) {
return map->cl->remove(map, cx_hash_key_cxstr(key), !map->store_pointer);
}
/**
* 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,
char const *key
) {
return map->cl->remove(map, cx_hash_key_str(key), !map->store_pointer);
}
#else // __cplusplus
/**
* 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 cx_map_put(
CxMap *map,
CxHashKey key,
void *value
) {
return map->cl->put(map, key, value);
}
/**
* 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 cx_map_put_cxstr(
CxMap *map,
cxstring key,
void *value
) {
return map->cl->put(map, cx_hash_key_cxstr(key), value);
}
/**
* 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 cx_map_put_mustr(
CxMap *map,
cxmutstr key,
void *value
) {
return map->cl->put(map, cx_hash_key_cxstr(key), value);
}
/**
* 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 cx_map_put_str(
CxMap *map,
char const *key,
void *value
) {
return map->cl->put(map, cx_hash_key_str(key), value);
}
/**
* 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
*/
#define cxMapPut(map, key, value) _Generic((key), \
CxHashKey: cx_map_put, \
cxstring: cx_map_put_cxstr, \
cxmutstr: cx_map_put_mustr, \
char*: cx_map_put_str, \
char const*: cx_map_put_str) \
(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 *cx_map_get(
CxMap const *map,
CxHashKey key
) {
return map->cl->get(map, key);
}
/**
* 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 *cx_map_get_cxstr(
CxMap const *map,
cxstring key
) {
return map->cl->get(map, cx_hash_key_cxstr(key));
}
/**
* 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 *cx_map_get_mustr(
CxMap const *map,
cxmutstr key
) {
return map->cl->get(map, cx_hash_key_cxstr(key));
}
/**
* 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 *cx_map_get_str(
CxMap const *map,
char const *key
) {
return map->cl->get(map, cx_hash_key_str(key));
}
/**
* Retrieves a value by using a key.
*
* @param map the map
* @param key the key
* @return the value
*/
#define cxMapGet(map, key) _Generic((key), \
CxHashKey: cx_map_get, \
cxstring: cx_map_get_cxstr, \
cxmutstr: cx_map_get_mustr, \
char*: cx_map_get_str, \
char const*: cx_map_get_str) \
(map, key)
/**
* Removes a key/value-pair from the map by using the key.
*
* @param map the map
* @param key the key
*/
__attribute__((__nonnull__))
static inline void cx_map_remove(
CxMap *map,
CxHashKey key
) {
(void) map->cl->remove(map, key, true);
}
/**
* Removes a key/value-pair from the map by using the key.
*
* @param map the map
* @param key the key
*/
__attribute__((__nonnull__))
static inline void cx_map_remove_cxstr(
CxMap *map,
cxstring key
) {
(void) map->cl->remove(map, cx_hash_key_cxstr(key), true);
}
/**
* Removes a key/value-pair from the map by using the key.
*
* @param map the map
* @param key the key
*/
__attribute__((__nonnull__))
static inline void cx_map_remove_mustr(
CxMap *map,
cxmutstr key
) {
(void) map->cl->remove(map, cx_hash_key_cxstr(key), true);
}
/**
* Removes a key/value-pair from the map by using the key.
*
* @param map the map
* @param key the key
*/
__attribute__((__nonnull__))
static inline void cx_map_remove_str(
CxMap *map,
char const *key
) {
(void) map->cl->remove(map, cx_hash_key_str(key), true);
}
/**
* 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()
*/
#define cxMapRemove(map, key) _Generic((key), \
CxHashKey: cx_map_remove, \
cxstring: cx_map_remove_cxstr, \
cxmutstr: cx_map_remove_mustr, \
char*: cx_map_remove_str, \
char const*: cx_map_remove_str) \
(map, key)
/**
* Detaches a key/value-pair from the map by using the key
* without invoking the destructor.
*
* @param map the map
* @param key the key
*/
__attribute__((__nonnull__))
static inline void cx_map_detach(
CxMap *map,
CxHashKey key
) {
(void) map->cl->remove(map, key, false);
}
/**
* Detaches a key/value-pair from the map by using the key
* without invoking the destructor.
*
* @param map the map
* @param key the key
*/
__attribute__((__nonnull__))
static inline void cx_map_detach_cxstr(
CxMap *map,
cxstring key
) {
(void) map->cl->remove(map, cx_hash_key_cxstr(key), false);
}
/**
* Detaches a key/value-pair from the map by using the key
* without invoking the destructor.
*
* @param map the map
* @param key the key
*/
__attribute__((__nonnull__))
static inline void cx_map_detach_mustr(
CxMap *map,
cxmutstr key
) {
(void) map->cl->remove(map, cx_hash_key_cxstr(key), false);
}
/**
* Detaches a key/value-pair from the map by using the key
* without invoking the destructor.
*
* @param map the map
* @param key the key
*/
__attribute__((__nonnull__))
static inline void cx_map_detach_str(
CxMap *map,
char const *key
) {
(void) map->cl->remove(map, cx_hash_key_str(key), false);
}
/**
* 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 preferable to use
* cxMapRemove() or cxMapRemoveAndGet().
*
* @param map the map
* @param key the key
* @see cxMapRemove()
* @see cxMapRemoveAndGet()
*/
#define cxMapDetach(map, key) _Generic((key), \
CxHashKey: cx_map_detach, \
cxstring: cx_map_detach_cxstr, \
cxmutstr: cx_map_detach_mustr, \
char*: cx_map_detach_str, \
char const*: cx_map_detach_str) \
(map, key)
/**
* Removes a key/value-pair from the map by using the key.
*
* @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
*/
__attribute__((__nonnull__, __warn_unused_result__))
static inline void *cx_map_remove_and_get(
CxMap *map,
CxHashKey key
) {
return map->cl->remove(map, key, !map->collection.store_pointer);
}
/**
* Removes a key/value-pair from the map by using the key.
*
* @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
*/
__attribute__((__nonnull__, __warn_unused_result__))
static inline void *cx_map_remove_and_get_cxstr(
CxMap *map,
cxstring key
) {
return map->cl->remove(map, cx_hash_key_cxstr(key), !map->collection.store_pointer);
}
/**
* Removes a key/value-pair from the map by using the key.
*
* @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
*/
__attribute__((__nonnull__, __warn_unused_result__))
static inline void *cx_map_remove_and_get_mustr(
CxMap *map,
cxmutstr key
) {
return map->cl->remove(map, cx_hash_key_cxstr(key), !map->collection.store_pointer);
}
/**
* Removes a key/value-pair from the map by using the key.
*
* @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
*/
__attribute__((__nonnull__, __warn_unused_result__))
static inline void *cx_map_remove_and_get_str(
CxMap *map,
char const *key
) {
return map->cl->remove(map, cx_hash_key_str(key), !map->collection.store_pointer);
}
/**
* 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()
*/
#define cxMapRemoveAndGet(map, key) _Generic((key), \
CxHashKey: cx_map_remove_and_get, \
cxstring: cx_map_remove_and_get_cxstr, \
cxmutstr: cx_map_remove_and_get_mustr, \
char*: cx_map_remove_and_get_str, \
char const*: cx_map_remove_and_get_str) \
(map, key)
#endif // __cplusplus
#endif // UCX_MAP_H