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
15extern "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
24CBOR_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
32CBOR_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
41CBOR_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
54CBOR_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
67CBOR_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
76CBOR_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
84CBOR_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
95CBOR_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
103CBOR_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
110CBOR_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
122CBOR_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