deimos.cbor.arrays source code

1 module deimos.cbor.arrays;
2 
3 import deimos.cbor.data;
4 
5 /*
6  * Copyright (c) 2014-2019 Pavel Kalvoda <me@pavelkalvoda.com>
7  *
8  * libcbor is free software; you can redistribute it and/or modify
9  * it under the terms of the MIT license. See LICENSE for details.
10  */
11 
12 extern (C):
13 
14 /** Get the number of members
15  *
16  * @param item[borrow] An array
17  * @return The number of members
18  */
19 size_t cbor_array_size(const cbor_item_t* item);
20 
21 /** Get the size of the allocated storage
22  *
23  * @param item[borrow] An array
24  * @return The size of the allocated storage (number of items)
25  */
26 size_t cbor_array_allocated(const cbor_item_t* item);
27 
28 /** Get item by index
29  *
30  * @param item[borrow] An array
31  * @param index The index
32  * @return **incref** The item, or `NULL` in case of boundary violation
33  */
34 cbor_item_t* cbor_array_get(const cbor_item_t* item, size_t index);
35 
36 /** Set item by index
37  *
38  * Creating arrays with holes is not possible
39  *
40  * @param item[borrow] An array
41  * @param value[incref] The item to assign
42  * @param index The index, first item is 0.
43  * @return true on success, false on allocation failure.
44  */
45 bool cbor_array_set(cbor_item_t* item, size_t index, cbor_item_t* value);
46 
47 /** Replace item at an index
48  *
49  * The item being replace will be #cbor_decref 'ed.
50  *
51  * @param item[borrow] An array
52  * @param value[incref] The item to assign
53  * @param index The index, first item is 0.
54  * @return true on success, false on allocation failure.
55  */
56 bool cbor_array_replace(cbor_item_t* item, size_t index, cbor_item_t* value);
57 
58 /** Is the array definite?
59  *
60  * @param item[borrow] An array
61  * @return Is the array definite?
62  */
63 bool cbor_array_is_definite(const cbor_item_t* item);
64 
65 /** Is the array indefinite?
66  *
67  * @param item[borrow] An array
68  * @return Is the array indefinite?
69  */
70 bool cbor_array_is_indefinite(const cbor_item_t* item);
71 
72 /** Get the array contents
73  *
74  * The items may be reordered and modified as long as references remain
75  * consistent.
76  *
77  * @param item[borrow] An array
78  * @return #cbor_array_size items
79  */
80 cbor_item_t** cbor_array_handle(const cbor_item_t* item);
81 
82 /** Create new definite array
83  *
84  * @param size Number of slots to preallocate
85  * @return **new** array or `NULL` upon malloc failure
86  */
87 cbor_item_t* cbor_new_definite_array(size_t size);
88 
89 /** Create new indefinite array
90  *
91  * @return **new** array or `NULL` upon malloc failure
92  */
93 cbor_item_t* cbor_new_indefinite_array();
94 
95 /** Append to the end
96  *
97  * For indefinite items, storage may be realloacted. For definite items, only
98  * the preallocated capacity is available.
99  *
100  * @param array[borrow] An array
101  * @param pushee[incref] The item to push
102  * @return true on success, false on failure
103  */
104 bool cbor_array_push(cbor_item_t* array, cbor_item_t* pushee);