summaryrefslogtreecommitdiff
path: root/external/mit/libcbor/dist/src/cbor/arrays.h
blob: 1e68689f462f21888fc052948e0c9b82a5044e93 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
/*
 * Copyright (c) 2014-2019 Pavel Kalvoda <me@pavelkalvoda.com>
 *
 * libcbor is free software; you can redistribute it and/or modify
 * it under the terms of the MIT license. See LICENSE for details.
 */

#ifndef LIBCBOR_ARRAYS_H
#define LIBCBOR_ARRAYS_H

#include "cbor/common.h"

#ifdef __cplusplus
extern "C" {
#endif

/** Get the number of members
 *
 * @param item[borrow] An array
 * @return The number of members
 */
size_t cbor_array_size(const cbor_item_t* item);

/** Get the size of the allocated storage
 *
 * @param item[borrow] An array
 * @return The size of the allocated storage (number of items)
 */
size_t cbor_array_allocated(const cbor_item_t* item);

/** Get item by index
 *
 * @param item[borrow] An array
 * @param index The index
 * @return **incref** The item, or `NULL` in case of boundary violation
 */
cbor_item_t* cbor_array_get(const cbor_item_t* item, size_t index);

/** Set item by index
 *
 * Creating arrays with holes is not possible
 *
 * @param item[borrow] An array
 * @param value[incref] The item to assign
 * @param index The index, first item is 0.
 * @return true on success, false on allocation failure.
 */
bool cbor_array_set(cbor_item_t* item, size_t index, cbor_item_t* value);

/** Replace item at an index
 *
 * The item being replace will be #cbor_decref 'ed.
 *
 * @param item[borrow] An array
 * @param value[incref] The item to assign
 * @param index The index, first item is 0.
 * @return true on success, false on allocation failure.
 */
bool cbor_array_replace(cbor_item_t* item, size_t index, cbor_item_t* value);

/** Is the array definite?
 *
 * @param item[borrow] An array
 * @return Is the array definite?
 */
bool cbor_array_is_definite(const cbor_item_t* item);

/** Is the array indefinite?
 *
 * @param item[borrow] An array
 * @return Is the array indefinite?
 */
bool cbor_array_is_indefinite(const cbor_item_t* item);

/** Get the array contents
 *
 * The items may be reordered and modified as long as references remain
 * consistent.
 *
 * @param item[borrow] An array
 * @return #cbor_array_size items
 */
cbor_item_t** cbor_array_handle(const cbor_item_t* item);

/** Create new definite array
 *
 * @param size Number of slots to preallocate
 * @return **new** array or `NULL` upon malloc failure
 */
cbor_item_t* cbor_new_definite_array(size_t size);

/** Create new indefinite array
 *
 * @return **new** array or `NULL` upon malloc failure
 */
cbor_item_t* cbor_new_indefinite_array();

/** Append to the end
 *
 * For indefinite items, storage may be realloacted. For definite items, only
 * the preallocated capacity is available.
 *
 * @param array[borrow] An array
 * @param pushee[incref] The item to push
 * @return true on success, false on failure
 */
bool cbor_array_push(cbor_item_t* array, cbor_item_t* pushee);

#ifdef __cplusplus
}
#endif

#endif  // LIBCBOR_ARRAYS_H