xref: /freebsd/contrib/libcbor/src/cbor/arrays.h (revision 5d3e7166f6a0187fa3f8831b16a06bd9955c21ff)
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