aboutsummaryrefslogtreecommitdiffstats
path: root/contrib/libs/c-ares/src/lib/ares__htable_stvp.h
blob: 11d9d5ed4cfc1f0207d7a96702b3dc02e8c6e8f6 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
/* MIT License
 *
 * Copyright (c) 2023 Brad House
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice (including the next
 * paragraph) shall be included in all copies or substantial portions of the
 * Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef __ARES__HTABLE_STVP_H
#define __ARES__HTABLE_STVP_H

/*! \addtogroup ares__htable_stvp HashTable with size_t Key and void pointer Value
 *
 * This data structure wraps the base ares__htable data structure in order to
 * split the key and value data types as size_t and void pointer, respectively.
 *
 * Average time complexity:
 *  - Insert: O(1)
 *  - Search: O(1)
 *  - Delete: O(1)
 *
 * @{
 */

struct ares__htable_stvp;

/*! Opaque data type for size_t key, void pointer hash table implementation */
typedef struct ares__htable_stvp ares__htable_stvp_t;

/*! Callback to free value stored in hashtable
 * 
 *  \param[in] val  user-supplied value
 */
typedef void (*ares__htable_stvp_val_free_t)(void *val);

/*! Destroy hashtable
 * 
 *  \param[in] htable  Initialized hashtable
 */
void ares__htable_stvp_destroy(ares__htable_stvp_t *htable);

/*! Create size_t key, void pointer value hash table
 * 
 *  \param[in] val_free  Optional. Call back to free user-supplied value.  If
 *                       NULL it is expected the caller will clean up any user
 *                       supplied values.
 */
ares__htable_stvp_t *ares__htable_stvp_create(
    ares__htable_stvp_val_free_t val_free);

/*! Insert key/value into hash table
 * 
 *  \param[in] htable Initialized hash table
 *  \param[in] key    key to associate with value
 *  \param[in] val    value to store (takes ownership). May be NULL.
 *  \return 1 on success, 0 on out of memory or misuse
 */
unsigned int ares__htable_stvp_insert(ares__htable_stvp_t *htable, size_t key,
                                      void *val);

/*! Retrieve value from hashtable based on key
 * 
 *  \param[in]  htable  Initialized hash table
 *  \param[in]  key     key to use to search
 *  \param[out] val     Optional.  Pointer to store value.
 *  \return 1 on success, 0 on failure
 */
unsigned int ares__htable_stvp_get(ares__htable_stvp_t *htable, size_t key,
                                   void **val);

/*! Retrieve value from hashtable directly as return value.  Caveat to this
 *  function over ares__htable_stvp_get() is that if a NULL value is stored
 *  you cannot determine if the key is not found or the value is NULL.
 * 
 *  \param[in] htable  Initialized hash table
 *  \param[in] key     key to use to search
 *  \return value associated with key in hashtable or NULL
 */
void *ares__htable_stvp_get_direct(ares__htable_stvp_t *htable, size_t key);

/*! Remove a value from the hashtable by key
 * 
 *  \param[in] htable  Initialized hash table
 *  \param[in] key     key to use to search
 *  \return 1 if found, 0 if not
 */
unsigned int ares__htable_stvp_remove(ares__htable_stvp_t *htable, size_t key);

/*! Retrieve the number of keys stored in the hash table
 * 
 *  \param[in] htable  Initialized hash table
 *  \return count
 */
size_t ares__htable_stvp_num_keys(ares__htable_stvp_t *htable);

/*! @} */

#endif /* __ARES__HTABLE_STVP_H */