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[borrow] 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[borrow] 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[borrow] An array 37 * @param index The index 38 * @return **incref** The item, or `NULL` in case of boundary violation 39 */ 40 _CBOR_NODISCARD 41 CBOR_EXPORT cbor_item_t* cbor_array_get(const cbor_item_t* item, size_t index); 42 43 /** Set item by index 44 * 45 * If the index is out of bounds, the array is not modified and false is 46 * returned. Creating arrays with holes is not possible. 47 * 48 * @param item[borrow] An array 49 * @param value[incref] The item to assign 50 * @param index The index, first item is 0. 51 * @return true on success, false on allocation failure. 52 */ 53 _CBOR_NODISCARD 54 CBOR_EXPORT bool cbor_array_set(cbor_item_t* item, size_t index, 55 cbor_item_t* value); 56 57 /** Replace item at an index 58 * 59 * The item being replace will be #cbor_decref 'ed. 60 * 61 * @param item[borrow] An array 62 * @param value[incref] The item to assign 63 * @param index The index, first item is 0. 64 * @return true on success, false on allocation failure. 65 */ 66 _CBOR_NODISCARD 67 CBOR_EXPORT bool cbor_array_replace(cbor_item_t* item, size_t index, 68 cbor_item_t* value); 69 70 /** Is the array definite? 71 * 72 * @param item[borrow] An array 73 * @return Is the array definite? 74 */ 75 _CBOR_NODISCARD 76 CBOR_EXPORT bool cbor_array_is_definite(const cbor_item_t* item); 77 78 /** Is the array indefinite? 79 * 80 * @param item[borrow] An array 81 * @return Is the array indefinite? 82 */ 83 _CBOR_NODISCARD 84 CBOR_EXPORT bool cbor_array_is_indefinite(const cbor_item_t* item); 85 86 /** Get the array contents 87 * 88 * The items may be reordered and modified as long as references remain 89 * consistent. 90 * 91 * @param item[borrow] An array 92 * @return #cbor_array_size items 93 */ 94 _CBOR_NODISCARD 95 CBOR_EXPORT cbor_item_t** cbor_array_handle(const cbor_item_t* item); 96 97 /** Create new definite array 98 * 99 * @param size Number of slots to preallocate 100 * @return **new** array or `NULL` upon malloc failure 101 */ 102 _CBOR_NODISCARD 103 CBOR_EXPORT cbor_item_t* cbor_new_definite_array(size_t size); 104 105 /** Create new indefinite array 106 * 107 * @return **new** array or `NULL` upon malloc failure 108 */ 109 _CBOR_NODISCARD 110 CBOR_EXPORT cbor_item_t* cbor_new_indefinite_array(void); 111 112 /** Append to the end 113 * 114 * For indefinite items, storage may be reallocated. For definite items, only 115 * the preallocated capacity is available. 116 * 117 * @param array[borrow] An array 118 * @param pushee[incref] The item to push 119 * @return true on success, false on failure 120 */ 121 _CBOR_NODISCARD 122 CBOR_EXPORT bool cbor_array_push(cbor_item_t* array, cbor_item_t* pushee); 123 124 #ifdef __cplusplus 125 } 126 #endif 127 128 #endif // LIBCBOR_ARRAYS_H 129