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