1# lws_map generic map abstraction 2 3||| 4|---|---|---| 5|cmake|core feature| 6|Header| ./include/libwebsockets/lws-map.h| 7|api-test| ./minimal-examples/api-tests/api-test-lws_map/| 8 9lws_map provides a robust abstraction for containing a collection of items that 10map key objects to value objects, where both the key and value objects may 11differ in size each time and have any type. 12 13Its one-level linked-list hashtables are useful up to hundreds or low thousands 14of items in the map on may platforms. 15 16The map itself and the items inside it are opaque. 17 18## Creating and destroying the map 19 20The user should prepare a `lws_map_info_t` object, it's legal for it to be 21all zeros to select defaults, an 8-way hashtable with item allocation from heap, 22simple bytewise key comparison, and xor / shift key hashing. These are often 23what you want simplifying construction. 24 25The info object allows user override of item allocator, freeing, key comparison 26and object hashing, allowing custom objects to be keys if desired. 27 28Custom allocator / free implementations for using lwsac for item allocation are 29provided to simplify that case. 30 31Just call `lws_map_create()` with the info struct to create the map, later it 32and all its contents can be destroyed with `lws_map_destroy()`. The info struct 33can go out of scope immediately after the create call. 34 35``` 36lws_map_t * 37lws_map_create(const lws_map_info_t *info); 38void 39lws_map_destroy(lws_map_t **pmap); 40``` 41 42## Keys in lws_map 43 44Items are managed in the map by a key, this may be, eg, a string, but it also 45can be an arbitrary object itself. If comparing keys takes more than a simple 46bytewise comparison, the map creation info struct ._compare() operation should 47be overridden with a user-supplied one that knows how to use the user's 48custom key objects. 49 50Keys are not required to be the same length, so objects with variable size 51overallocation can be used as keys. 52 53Keys and values are copied into allocations inside the map, the original objects 54they are copied from may go out of scope after item creation assuming there are 55no pointers to them copied in the objects themselves. 56 57## Adding items to a map 58 59The map's info._alloc allocator is used for creating items. By default that 60just creates into the heap. 61 62If you create a new item with the same key as an existing one, the existing one 63is destroyed before the new one is created. So there is only one item allowed 64at a given key at a time. 65 66To allocate and create a new item containing the key and value, use 67`lws_map_item_create()` 68 69``` 70lws_map_item_t * 71lws_map_item_create(lws_map_t *map, 72 const lws_map_key_t key, size_t keylen, 73 const lws_map_value_t value, size_t valuelen); 74``` 75 76Eg, 77 78``` 79 if (!lws_map_item_create(map, (lws_map_key_t)&my_key, 80 sizeof(my_key), 81 (lws_map_value_t)"4567", 4)) 82 /* fail */ 83``` 84 85 86In the case the key is a string, there is a ..._ks wrapper to simplify usage 87 88``` 89 if (!lws_map_item_create_ks(map, "123", (lws_map_value_t)"4567", 4)) 90 /* fail */ 91``` 92 93## Lookups in the map 94 95You can retreive a pointer to an item in the map with a give key using 96 97``` 98lws_map_item_t * 99lws_map_item_lookup(lws_map_t *map, const lws_map_key_t key, size_t keylen); 100``` 101 102The item is opaque, but there are accessors 103 104|Accessor|Function| 105|---|---| 106|`lws_map_item_key(lws_map_item_t *_item)`|get a pointer to the item key| 107|`lws_map_item_value(lws_map_item_t *_item)`|get a pointer to the item value| 108|`lws_map_item_key_len(lws_map_item_t *_item)`|get the key length| 109|`lws_map_item_value_len(lws_map_item_t *_item)`|get the value length| 110 111Again there is a ..._ks() helper to simplify C strings as keys 112 113``` 114 item = lws_map_item_lookup_ks(map, "abc"); 115 if (!item) 116 /* fail */ 117``` 118