1 /* 2 * Copyright (c) 2014-2020 Pavel Kalvoda <me@pavelkalvoda.com> 3 * 4 * libcbor is free software; you can redistribute it and/or modify 5 * it under the terms of the MIT license. See LICENSE for details. 6 */ 7 8 #ifndef LIBCBOR_MAPS_H 9 #define LIBCBOR_MAPS_H 10 11 #include "cbor/cbor_export.h" 12 #include "cbor/common.h" 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 /* 19 * ============================================================================ 20 * Map manipulation 21 * ============================================================================ 22 */ 23 24 /** Get the number of pairs 25 * 26 * @param item A map 27 * @return The number of pairs 28 */ 29 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_map_size(const cbor_item_t *item); 30 31 /** Get the size of the allocated storage 32 * 33 * @param item A map 34 * @return Allocated storage size (as the number of #cbor_pair items) 35 */ 36 _CBOR_NODISCARD CBOR_EXPORT size_t cbor_map_allocated(const cbor_item_t *item); 37 38 /** Create a new definite map 39 * 40 * @param size The number of slots to preallocate 41 * @return Reference to the new map item. The item's reference count is 42 * initialized to one. 43 * @return `NULL` if memory allocation fails 44 */ 45 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_new_definite_map(size_t size); 46 47 /** Create a new indefinite map 48 * 49 * @return Reference to the new map item. The item's reference count is 50 * initialized to one. 51 * @return `NULL` if memory allocation fails 52 */ 53 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_new_indefinite_map(void); 54 55 /** Add a pair to the map 56 * 57 * For definite maps, items can only be added to the preallocated space. For 58 * indefinite maps, the storage will be expanded as needed 59 * 60 * @param item A map 61 * @param pair The key-value pair to add. Reference count of the #cbor_pair.key 62 * and #cbor_pair.value will be increased by one. 63 * @return `true` on success, `false` if memory allocation failed (indefinite 64 * maps) or the preallocated storage is full (definite maps) 65 */ 66 _CBOR_NODISCARD CBOR_EXPORT bool cbor_map_add(cbor_item_t *item, 67 struct cbor_pair pair); 68 69 /** Add a key to the map 70 * 71 * Sets the value to `NULL`. Internal API. 72 * 73 * @param item A map 74 * @param key The key, Its reference count will be be increased by one. 75 * @return `true` on success, `false` if either reallocation failed or the 76 * preallocated storage is full 77 */ 78 _CBOR_NODISCARD CBOR_EXPORT bool _cbor_map_add_key(cbor_item_t *item, 79 cbor_item_t *key); 80 81 /** Add a value to the map 82 * 83 * Assumes that #_cbor_map_add_key has been called. Internal API. 84 * 85 * @param item A map 86 * @param value The value. Its reference count will be be increased by one. 87 * @return `true` on success, `false` if either reallocation failed or the 88 * preallocated storage is full 89 */ 90 _CBOR_NODISCARD CBOR_EXPORT bool _cbor_map_add_value(cbor_item_t *item, 91 cbor_item_t *value); 92 93 /** Is this map definite? 94 * 95 * @param item A map 96 * @return Is this map definite? 97 */ 98 _CBOR_NODISCARD CBOR_EXPORT bool cbor_map_is_definite(const cbor_item_t *item); 99 100 /** Is this map indefinite? 101 * 102 * @param item A map 103 * @return Is this map indefinite? 104 */ 105 _CBOR_NODISCARD CBOR_EXPORT bool cbor_map_is_indefinite( 106 const cbor_item_t *item); 107 108 /** Get the pairs storage 109 * 110 * @param item A map 111 * @return Array of #cbor_map_size pairs. Manipulation is possible as long as 112 * references remain valid. 113 */ 114 _CBOR_NODISCARD CBOR_EXPORT struct cbor_pair *cbor_map_handle( 115 const cbor_item_t *item); 116 117 #ifdef __cplusplus 118 } 119 #endif 120 121 #endif // LIBCBOR_MAPS_H 122