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[borrow] 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[borrow] 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 **new** definite map. `NULL` on malloc failure. 42 */ 43 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_new_definite_map(size_t size); 44 45 /** Create a new indefinite map 46 * 47 * @return **new** indefinite map. `NULL` on malloc failure. 48 */ 49 _CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_new_indefinite_map(void); 50 51 /** Add a pair to the map 52 * 53 * For definite maps, items can only be added to the preallocated space. For 54 * indefinite maps, the storage will be expanded as needed 55 * 56 * @param item[borrow] A map 57 * @param pair[incref] The key-value pair to add (incref is member-wise) 58 * @return `true` on success, `false` if either reallocation failed or the 59 * preallocated storage is full 60 */ 61 _CBOR_NODISCARD CBOR_EXPORT bool cbor_map_add(cbor_item_t *item, 62 struct cbor_pair pair); 63 64 /** Add a key to the map 65 * 66 * Sets the value to `NULL`. Internal API. 67 * 68 * @param item[borrow] A map 69 * @param key[incref] The key 70 * @return `true` on success, `false` if either reallocation failed or the 71 * preallocated storage is full 72 */ 73 _CBOR_NODISCARD CBOR_EXPORT bool _cbor_map_add_key(cbor_item_t *item, 74 cbor_item_t *key); 75 76 /** Add a value to the map 77 * 78 * Assumes that #_cbor_map_add_key has been called. Internal API. 79 * 80 * @param item[borrow] A map 81 * @param key[incref] The value 82 * @return `true` on success, `false` if either reallocation failed or the 83 * preallocated storage is full 84 */ 85 _CBOR_NODISCARD CBOR_EXPORT bool _cbor_map_add_value(cbor_item_t *item, 86 cbor_item_t *value); 87 88 /** Is this map definite? 89 * 90 * @param item[borrow] A map 91 * @return Is this map definite? 92 */ 93 _CBOR_NODISCARD CBOR_EXPORT bool cbor_map_is_definite(const cbor_item_t *item); 94 95 /** Is this map indefinite? 96 * 97 * @param item[borrow] A map 98 * @return Is this map indefinite? 99 */ 100 _CBOR_NODISCARD CBOR_EXPORT bool cbor_map_is_indefinite( 101 const cbor_item_t *item); 102 103 /** Get the pairs storage 104 * 105 * @param item[borrow] A map 106 * @return Array of #cbor_map_size pairs. Manipulation is possible as long as 107 * references remain valid. 108 */ 109 _CBOR_NODISCARD CBOR_EXPORT struct cbor_pair *cbor_map_handle( 110 const cbor_item_t *item); 111 112 #ifdef __cplusplus 113 } 114 #endif 115 116 #endif // LIBCBOR_MAPS_H 117