110ff414cSEd Maste /* 210ff414cSEd Maste * Copyright (c) 2014-2020 Pavel Kalvoda <me@pavelkalvoda.com> 310ff414cSEd Maste * 410ff414cSEd Maste * libcbor is free software; you can redistribute it and/or modify 510ff414cSEd Maste * it under the terms of the MIT license. See LICENSE for details. 610ff414cSEd Maste */ 710ff414cSEd Maste 810ff414cSEd Maste #ifndef LIBCBOR_ARRAYS_H 910ff414cSEd Maste #define LIBCBOR_ARRAYS_H 1010ff414cSEd Maste 1110ff414cSEd Maste #include "cbor/cbor_export.h" 1210ff414cSEd Maste #include "cbor/common.h" 1310ff414cSEd Maste 1410ff414cSEd Maste #ifdef __cplusplus 1510ff414cSEd Maste extern "C" { 1610ff414cSEd Maste #endif 1710ff414cSEd Maste 1810ff414cSEd Maste /** Get the number of members 1910ff414cSEd Maste * 20*5d3e7166SEd Maste * @param item An array 2110ff414cSEd Maste * @return The number of members 2210ff414cSEd Maste */ 23*5d3e7166SEd Maste _CBOR_NODISCARD 2410ff414cSEd Maste CBOR_EXPORT size_t cbor_array_size(const cbor_item_t* item); 2510ff414cSEd Maste 2610ff414cSEd Maste /** Get the size of the allocated storage 2710ff414cSEd Maste * 28*5d3e7166SEd Maste * @param item An array 2910ff414cSEd Maste * @return The size of the allocated storage (number of items) 3010ff414cSEd Maste */ 31*5d3e7166SEd Maste _CBOR_NODISCARD 3210ff414cSEd Maste CBOR_EXPORT size_t cbor_array_allocated(const cbor_item_t* item); 3310ff414cSEd Maste 3410ff414cSEd Maste /** Get item by index 3510ff414cSEd Maste * 36*5d3e7166SEd Maste * @param item An array 37*5d3e7166SEd Maste * @param index The index (zero-based) 38*5d3e7166SEd Maste * @return Reference to the item, or `NULL` in case of boundary violation. 39*5d3e7166SEd Maste * 40*5d3e7166SEd Maste * Increases the reference count of the underlying item. The returned reference 41*5d3e7166SEd Maste * must be released using #cbor_decref. 4210ff414cSEd Maste */ 43*5d3e7166SEd Maste _CBOR_NODISCARD 4410ff414cSEd Maste CBOR_EXPORT cbor_item_t* cbor_array_get(const cbor_item_t* item, size_t index); 4510ff414cSEd Maste 4610ff414cSEd Maste /** Set item by index 4710ff414cSEd Maste * 48*5d3e7166SEd Maste * If the index is out of bounds, the array is not modified and false is 49*5d3e7166SEd Maste * returned. Creating arrays with holes is not possible. 5010ff414cSEd Maste * 51*5d3e7166SEd Maste * @param item An array 52*5d3e7166SEd Maste * @param value The item to assign 53*5d3e7166SEd Maste * @param index The index (zero-based) 54*5d3e7166SEd Maste * @return `true` on success, `false` on allocation failure. 5510ff414cSEd Maste */ 56*5d3e7166SEd Maste _CBOR_NODISCARD 5710ff414cSEd Maste CBOR_EXPORT bool cbor_array_set(cbor_item_t* item, size_t index, 5810ff414cSEd Maste cbor_item_t* value); 5910ff414cSEd Maste 6010ff414cSEd Maste /** Replace item at an index 6110ff414cSEd Maste * 62*5d3e7166SEd Maste * The reference to the item being replaced will be released using #cbor_decref. 6310ff414cSEd Maste * 64*5d3e7166SEd Maste * @param item An array 65*5d3e7166SEd Maste * @param value The item to assign. Its reference count will be increased by 66*5d3e7166SEd Maste * one. 67*5d3e7166SEd Maste * @param index The index (zero-based) 6810ff414cSEd Maste * @return true on success, false on allocation failure. 6910ff414cSEd Maste */ 70*5d3e7166SEd Maste _CBOR_NODISCARD 7110ff414cSEd Maste CBOR_EXPORT bool cbor_array_replace(cbor_item_t* item, size_t index, 7210ff414cSEd Maste cbor_item_t* value); 7310ff414cSEd Maste 7410ff414cSEd Maste /** Is the array definite? 7510ff414cSEd Maste * 76*5d3e7166SEd Maste * @param item An array 7710ff414cSEd Maste * @return Is the array definite? 7810ff414cSEd Maste */ 79*5d3e7166SEd Maste _CBOR_NODISCARD 8010ff414cSEd Maste CBOR_EXPORT bool cbor_array_is_definite(const cbor_item_t* item); 8110ff414cSEd Maste 8210ff414cSEd Maste /** Is the array indefinite? 8310ff414cSEd Maste * 84*5d3e7166SEd Maste * @param item An array 8510ff414cSEd Maste * @return Is the array indefinite? 8610ff414cSEd Maste */ 87*5d3e7166SEd Maste _CBOR_NODISCARD 8810ff414cSEd Maste CBOR_EXPORT bool cbor_array_is_indefinite(const cbor_item_t* item); 8910ff414cSEd Maste 9010ff414cSEd Maste /** Get the array contents 9110ff414cSEd Maste * 9210ff414cSEd Maste * The items may be reordered and modified as long as references remain 9310ff414cSEd Maste * consistent. 9410ff414cSEd Maste * 95*5d3e7166SEd Maste * @param item An array item 96*5d3e7166SEd Maste * @return An array of #cbor_item_t pointers of size #cbor_array_size. 9710ff414cSEd Maste */ 98*5d3e7166SEd Maste _CBOR_NODISCARD 9910ff414cSEd Maste CBOR_EXPORT cbor_item_t** cbor_array_handle(const cbor_item_t* item); 10010ff414cSEd Maste 10110ff414cSEd Maste /** Create new definite array 10210ff414cSEd Maste * 10310ff414cSEd Maste * @param size Number of slots to preallocate 104*5d3e7166SEd Maste * @return Reference to the new array item. The item's reference count is 105*5d3e7166SEd Maste * initialized to one. 106*5d3e7166SEd Maste * @return `NULL` if memory allocation fails 10710ff414cSEd Maste */ 108*5d3e7166SEd Maste _CBOR_NODISCARD 10910ff414cSEd Maste CBOR_EXPORT cbor_item_t* cbor_new_definite_array(size_t size); 11010ff414cSEd Maste 11110ff414cSEd Maste /** Create new indefinite array 11210ff414cSEd Maste * 113*5d3e7166SEd Maste * @return Reference to the new array item. The item's reference count is 114*5d3e7166SEd Maste * initialized to one. 115*5d3e7166SEd Maste * @return `NULL` if memory allocation fails 11610ff414cSEd Maste */ 117*5d3e7166SEd Maste _CBOR_NODISCARD 118*5d3e7166SEd Maste CBOR_EXPORT cbor_item_t* cbor_new_indefinite_array(void); 11910ff414cSEd Maste 12010ff414cSEd Maste /** Append to the end 12110ff414cSEd Maste * 122*5d3e7166SEd Maste * For indefinite items, storage may be reallocated. For definite items, only 12310ff414cSEd Maste * the preallocated capacity is available. 12410ff414cSEd Maste * 125*5d3e7166SEd Maste * @param array An array 126*5d3e7166SEd Maste * @param pushee The item to push. Its reference count will be increased by 127*5d3e7166SEd Maste * one. 128*5d3e7166SEd Maste * @return `true` on success, `false` on failure 12910ff414cSEd Maste */ 130*5d3e7166SEd Maste _CBOR_NODISCARD 13110ff414cSEd Maste CBOR_EXPORT bool cbor_array_push(cbor_item_t* array, cbor_item_t* pushee); 13210ff414cSEd Maste 13310ff414cSEd Maste #ifdef __cplusplus 13410ff414cSEd Maste } 13510ff414cSEd Maste #endif 13610ff414cSEd Maste 13710ff414cSEd Maste #endif // LIBCBOR_ARRAYS_H 138