1 /* ========================================================================= 2 zhashx - extended generic type-free hash container 3 4 Copyright (c) the Contributors as noted in the AUTHORS file. 5 This file is part of CZMQ, the high-level C binding for 0MQ: 6 http://czmq.zeromq.org. 7 8 This Source Code Form is subject to the terms of the Mozilla Public 9 License, v. 2.0. If a copy of the MPL was not distributed with this 10 file, You can obtain one at http://mozilla.org/MPL/2.0/. 11 ========================================================================= 12 */ 13 14 #ifndef __ZHASHX_H_INCLUDED__ 15 #define __ZHASHX_H_INCLUDED__ 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 22 // @warning THE FOLLOWING @INTERFACE BLOCK IS AUTO-GENERATED BY ZPROJECT 23 // @warning Please edit the model at "api/zhashx.api" to make changes. 24 // @interface 25 // This is a stable class, and may not change except for emergencies. It 26 // is provided in stable builds. 27 // This class has draft methods, which may change over time. They are not 28 // in stable releases, by default. Use --enable-drafts to enable. 29 // Destroy an item 30 typedef void (zhashx_destructor_fn) ( 31 void **item); 32 33 // Duplicate an item 34 typedef void * (zhashx_duplicator_fn) ( 35 const void *item); 36 37 // Compare two items, for sorting 38 typedef int (zhashx_comparator_fn) ( 39 const void *item1, const void *item2); 40 41 // Destroy an item. 42 typedef void (zhashx_free_fn) ( 43 void *data); 44 45 // Hash function for keys. 46 typedef size_t (zhashx_hash_fn) ( 47 const void *key); 48 49 // Serializes an item to a longstr. 50 // The caller takes ownership of the newly created object. 51 typedef char * (zhashx_serializer_fn) ( 52 const void *item); 53 54 // Deserializes a longstr into an item. 55 // The caller takes ownership of the newly created object. 56 typedef void * (zhashx_deserializer_fn) ( 57 const char *item_str); 58 59 // Create a new, empty hash container 60 CZMQ_EXPORT zhashx_t * 61 zhashx_new (void); 62 63 // Unpack binary frame into a new hash table. Packed data must follow format 64 // defined by zhashx_pack. Hash table is set to autofree. An empty frame 65 // unpacks to an empty hash table. 66 CZMQ_EXPORT zhashx_t * 67 zhashx_unpack (zframe_t *frame); 68 69 // Destroy a hash container and all items in it 70 CZMQ_EXPORT void 71 zhashx_destroy (zhashx_t **self_p); 72 73 // Insert item into hash table with specified key and item. 74 // If key is already present returns -1 and leaves existing item unchanged 75 // Returns 0 on success. 76 CZMQ_EXPORT int 77 zhashx_insert (zhashx_t *self, const void *key, void *item); 78 79 // Update or insert item into hash table with specified key and item. If the 80 // key is already present, destroys old item and inserts new one. If you set 81 // a container item destructor, this is called on the old value. If the key 82 // was not already present, inserts a new item. Sets the hash cursor to the 83 // new item. 84 CZMQ_EXPORT void 85 zhashx_update (zhashx_t *self, const void *key, void *item); 86 87 // Remove an item specified by key from the hash table. If there was no such 88 // item, this function does nothing. 89 CZMQ_EXPORT void 90 zhashx_delete (zhashx_t *self, const void *key); 91 92 // Delete all items from the hash table. If the key destructor is 93 // set, calls it on every key. If the item destructor is set, calls 94 // it on every item. 95 CZMQ_EXPORT void 96 zhashx_purge (zhashx_t *self); 97 98 // Return the item at the specified key, or null 99 CZMQ_EXPORT void * 100 zhashx_lookup (zhashx_t *self, const void *key); 101 102 // Reindexes an item from an old key to a new key. If there was no such 103 // item, does nothing. Returns 0 if successful, else -1. 104 CZMQ_EXPORT int 105 zhashx_rename (zhashx_t *self, const void *old_key, const void *new_key); 106 107 // Set a free function for the specified hash table item. When the item is 108 // destroyed, the free function, if any, is called on that item. 109 // Use this when hash items are dynamically allocated, to ensure that 110 // you don't have memory leaks. You can pass 'free' or NULL as a free_fn. 111 // Returns the item, or NULL if there is no such item. 112 CZMQ_EXPORT void * 113 zhashx_freefn (zhashx_t *self, const void *key, zhashx_free_fn free_fn); 114 115 // Return the number of keys/items in the hash table 116 CZMQ_EXPORT size_t 117 zhashx_size (zhashx_t *self); 118 119 // Return a zlistx_t containing the keys for the items in the 120 // table. Uses the key_duplicator to duplicate all keys and sets the 121 // key_destructor as destructor for the list. 122 // Caller owns return value and must destroy it when done. 123 CZMQ_EXPORT zlistx_t * 124 zhashx_keys (zhashx_t *self); 125 126 // Return a zlistx_t containing the values for the items in the 127 // table. Uses the duplicator to duplicate all items and sets the 128 // destructor as destructor for the list. 129 // Caller owns return value and must destroy it when done. 130 CZMQ_EXPORT zlistx_t * 131 zhashx_values (zhashx_t *self); 132 133 // Simple iterator; returns first item in hash table, in no given order, 134 // or NULL if the table is empty. This method is simpler to use than the 135 // foreach() method, which is deprecated. To access the key for this item 136 // use zhashx_cursor(). NOTE: do NOT modify the table while iterating. 137 CZMQ_EXPORT void * 138 zhashx_first (zhashx_t *self); 139 140 // Simple iterator; returns next item in hash table, in no given order, 141 // or NULL if the last item was already returned. Use this together with 142 // zhashx_first() to process all items in a hash table. If you need the 143 // items in sorted order, use zhashx_keys() and then zlistx_sort(). To 144 // access the key for this item use zhashx_cursor(). NOTE: do NOT modify 145 // the table while iterating. 146 CZMQ_EXPORT void * 147 zhashx_next (zhashx_t *self); 148 149 // After a successful first/next method, returns the key for the item that 150 // was returned. This is a constant string that you may not modify or 151 // deallocate, and which lasts as long as the item in the hash. After an 152 // unsuccessful first/next, returns NULL. 153 CZMQ_EXPORT const void * 154 zhashx_cursor (zhashx_t *self); 155 156 // Add a comment to hash table before saving to disk. You can add as many 157 // comment lines as you like. These comment lines are discarded when loading 158 // the file. If you use a null format, all comments are deleted. 159 CZMQ_EXPORT void 160 zhashx_comment (zhashx_t *self, const char *format, ...) CHECK_PRINTF (2); 161 162 // Save hash table to a text file in name=value format. Hash values must be 163 // printable strings; keys may not contain '=' character. Returns 0 if OK, 164 // else -1 if a file error occurred. 165 CZMQ_EXPORT int 166 zhashx_save (zhashx_t *self, const char *filename); 167 168 // Load hash table from a text file in name=value format; hash table must 169 // already exist. Hash values must printable strings; keys may not contain 170 // '=' character. Returns 0 if OK, else -1 if a file was not readable. 171 CZMQ_EXPORT int 172 zhashx_load (zhashx_t *self, const char *filename); 173 174 // When a hash table was loaded from a file by zhashx_load, this method will 175 // reload the file if it has been modified since, and is "stable", i.e. not 176 // still changing. Returns 0 if OK, -1 if there was an error reloading the 177 // file. 178 CZMQ_EXPORT int 179 zhashx_refresh (zhashx_t *self); 180 181 // Serialize hash table to a binary frame that can be sent in a message. 182 // The packed format is compatible with the 'dictionary' type defined in 183 // http://rfc.zeromq.org/spec:35/FILEMQ, and implemented by zproto: 184 // 185 // ; A list of name/value pairs 186 // dictionary = dict-count *( dict-name dict-value ) 187 // dict-count = number-4 188 // dict-value = longstr 189 // dict-name = string 190 // 191 // ; Strings are always length + text contents 192 // longstr = number-4 *VCHAR 193 // string = number-1 *VCHAR 194 // 195 // ; Numbers are unsigned integers in network byte order 196 // number-1 = 1OCTET 197 // number-4 = 4OCTET 198 // 199 // Comments are not included in the packed data. Item values MUST be 200 // strings. 201 // Caller owns return value and must destroy it when done. 202 CZMQ_EXPORT zframe_t * 203 zhashx_pack (zhashx_t *self); 204 205 // Make a copy of the list; items are duplicated if you set a duplicator 206 // for the list, otherwise not. Copying a null reference returns a null 207 // reference. Note that this method's behavior changed slightly for CZMQ 208 // v3.x, as it does not set nor respect autofree. It does however let you 209 // duplicate any hash table safely. The old behavior is in zhashx_dup_v2. 210 // Caller owns return value and must destroy it when done. 211 CZMQ_EXPORT zhashx_t * 212 zhashx_dup (zhashx_t *self); 213 214 // Set a user-defined deallocator for hash items; by default items are not 215 // freed when the hash is destroyed. 216 CZMQ_EXPORT void 217 zhashx_set_destructor (zhashx_t *self, zhashx_destructor_fn destructor); 218 219 // Set a user-defined duplicator for hash items; by default items are not 220 // copied when the hash is duplicated. 221 CZMQ_EXPORT void 222 zhashx_set_duplicator (zhashx_t *self, zhashx_duplicator_fn duplicator); 223 224 // Set a user-defined deallocator for keys; by default keys are freed 225 // when the hash is destroyed using free(). 226 CZMQ_EXPORT void 227 zhashx_set_key_destructor (zhashx_t *self, zhashx_destructor_fn destructor); 228 229 // Set a user-defined duplicator for keys; by default keys are duplicated 230 // using strdup. 231 CZMQ_EXPORT void 232 zhashx_set_key_duplicator (zhashx_t *self, zhashx_duplicator_fn duplicator); 233 234 // Set a user-defined comparator for keys; by default keys are 235 // compared using strcmp. 236 // The callback function should return zero (0) on matching 237 // items. 238 CZMQ_EXPORT void 239 zhashx_set_key_comparator (zhashx_t *self, zhashx_comparator_fn comparator); 240 241 // Set a user-defined hash function for keys; by default keys are 242 // hashed by a modified Bernstein hashing function. 243 CZMQ_EXPORT void 244 zhashx_set_key_hasher (zhashx_t *self, zhashx_hash_fn hasher); 245 246 // Make copy of hash table; if supplied table is null, returns null. 247 // Does not copy items themselves. Rebuilds new table so may be slow on 248 // very large tables. NOTE: only works with item values that are strings 249 // since there's no other way to know how to duplicate the item value. 250 CZMQ_EXPORT zhashx_t * 251 zhashx_dup_v2 (zhashx_t *self); 252 253 // Self test of this class. 254 CZMQ_EXPORT void 255 zhashx_test (bool verbose); 256 257 #ifdef CZMQ_BUILD_DRAFT_API 258 // *** Draft method, for development use, may change without warning *** 259 // Same as unpack but uses a user-defined deserializer function to convert 260 // a longstr back into item format. 261 CZMQ_EXPORT zhashx_t * 262 zhashx_unpack_own (zframe_t *frame, zhashx_deserializer_fn deserializer); 263 264 // *** Draft method, for development use, may change without warning *** 265 // Same as pack but uses a user-defined serializer function to convert items 266 // into longstr. 267 // Caller owns return value and must destroy it when done. 268 CZMQ_EXPORT zframe_t * 269 zhashx_pack_own (zhashx_t *self, zhashx_serializer_fn serializer); 270 271 #endif // CZMQ_BUILD_DRAFT_API 272 // @end 273 274 275 #ifdef __cplusplus 276 } 277 #endif 278 279 #endif 280