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_ARRAYS_H 9 #define LIBCBOR_ARRAYS_H 10 11 #include "cbor/cbor_export.h" 12 #include "cbor/common.h" 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 /** Get the number of members 19 * 20 * @param item An array 21 * @return The number of members 22 */ 23 _CBOR_NODISCARD 24 CBOR_EXPORT size_t cbor_array_size(const cbor_item_t* item); 25 26 /** Get the size of the allocated storage 27 * 28 * @param item An array 29 * @return The size of the allocated storage (number of items) 30 */ 31 _CBOR_NODISCARD 32 CBOR_EXPORT size_t cbor_array_allocated(const cbor_item_t* item); 33 34 /** Get item by index 35 * 36 * @param item An array 37 * @param index The index (zero-based) 38 * @return Reference to the item, or `NULL` in case of boundary violation. 39 * 40 * Increases the reference count of the underlying item. The returned reference 41 * must be released using #cbor_decref. 42 */ 43 _CBOR_NODISCARD 44 CBOR_EXPORT cbor_item_t* cbor_array_get(const cbor_item_t* item, size_t index); 45 46 /** Set item by index 47 * 48 * If the index is out of bounds, the array is not modified and false is 49 * returned. Creating arrays with holes is not possible. 50 * 51 * @param item An array 52 * @param value The item to assign 53 * @param index The index (zero-based) 54 * @return `true` on success, `false` on allocation failure. 55 */ 56 _CBOR_NODISCARD 57 CBOR_EXPORT bool cbor_array_set(cbor_item_t* item, size_t index, 58 cbor_item_t* value); 59 60 /** Replace item at an index 61 * 62 * The reference to the item being replaced will be released using #cbor_decref. 63 * 64 * @param item An array 65 * @param value The item to assign. Its reference count will be increased by 66 * one. 67 * @param index The index (zero-based) 68 * @return true on success, false on allocation failure. 69 */ 70 _CBOR_NODISCARD 71 CBOR_EXPORT bool cbor_array_replace(cbor_item_t* item, size_t index, 72 cbor_item_t* value); 73 74 /** Is the array definite? 75 * 76 * @param item An array 77 * @return Is the array definite? 78 */ 79 _CBOR_NODISCARD 80 CBOR_EXPORT bool cbor_array_is_definite(const cbor_item_t* item); 81 82 /** Is the array indefinite? 83 * 84 * @param item An array 85 * @return Is the array indefinite? 86 */ 87 _CBOR_NODISCARD 88 CBOR_EXPORT bool cbor_array_is_indefinite(const cbor_item_t* item); 89 90 /** Get the array contents 91 * 92 * The items may be reordered and modified as long as references remain 93 * consistent. 94 * 95 * @param item An array item 96 * @return An array of #cbor_item_t pointers of size #cbor_array_size. 97 */ 98 _CBOR_NODISCARD 99 CBOR_EXPORT cbor_item_t** cbor_array_handle(const cbor_item_t* item); 100 101 /** Create new definite array 102 * 103 * @param size Number of slots to preallocate 104 * @return Reference to the new array item. The item's reference count is 105 * initialized to one. 106 * @return `NULL` if memory allocation fails 107 */ 108 _CBOR_NODISCARD 109 CBOR_EXPORT cbor_item_t* cbor_new_definite_array(size_t size); 110 111 /** Create new indefinite array 112 * 113 * @return Reference to the new array item. The item's reference count is 114 * initialized to one. 115 * @return `NULL` if memory allocation fails 116 */ 117 _CBOR_NODISCARD 118 CBOR_EXPORT cbor_item_t* cbor_new_indefinite_array(void); 119 120 /** Append to the end 121 * 122 * For indefinite items, storage may be reallocated. For definite items, only 123 * the preallocated capacity is available. 124 * 125 * @param array An array 126 * @param pushee The item to push. Its reference count will be increased by 127 * one. 128 * @return `true` on success, `false` on failure 129 */ 130 _CBOR_NODISCARD 131 CBOR_EXPORT bool cbor_array_push(cbor_item_t* array, cbor_item_t* pushee); 132 133 #ifdef __cplusplus 134 } 135 #endif 136 137 #endif // LIBCBOR_ARRAYS_H 138