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