deimos.cbor.maps source code

1 module deimos.cbor.maps;
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 /*
15  * ============================================================================
16  * Map manipulation
17  * ============================================================================
18  */
19 
20 /** Get the number of pairs
21  *
22  * @param item[borrow] A map
23  * @return The number of pairs
24  */
25 size_t cbor_map_size(const cbor_item_t* item);
26 
27 /** Get the size of the allocated storage
28  *
29  * @param item[borrow] A map
30  * @return Allocated storage size (as the number of #cbor_pair items)
31  */
32 size_t cbor_map_allocated(const cbor_item_t* item);
33 
34 /** Create a new definite map
35  *
36  * @param size The number of slots to preallocate
37  * @return **new** definite map. `NULL` on malloc failure.
38  */
39 cbor_item_t* cbor_new_definite_map(size_t size);
40 
41 /** Create a new indefinite map
42  *
43  * @param size The number of slots to preallocate
44  * @return **new** definite map. `NULL` on malloc failure.
45  */
46 cbor_item_t* cbor_new_indefinite_map();
47 
48 /** Add a pair to the map
49  *
50  * For definite maps, items can only be added to the preallocated space. For
51  * indefinite maps, the storage will be expanded as needed
52  *
53  * @param item[borrow] A map
54  * @param pair[incref] The key-value pair to add (incref is member-wise)
55  * @return `true` on success, `false` if either reallocation failed or the
56  * preallcoated storage is full
57  */
58 bool cbor_map_add(cbor_item_t* item, cbor_pair pair);
59 
60 /** Add a key to the map
61  *
62  * Sets the value to `NULL`. Internal API.
63  *
64  * @param item[borrow] A map
65  * @param key[incref] The key
66  * @return `true` on success, `false` if either reallocation failed or the
67  * preallcoated storage is full
68  */
69 bool _cbor_map_add_key(cbor_item_t* item, cbor_item_t* key);
70 
71 /** Add a value to the map
72  *
73  * Assumes that #_cbor_map_add_key has been called. Internal API.
74  *
75  * @param item[borrow] A map
76  * @param key[incref] The value
77  * @return `true` on success, `false` if either reallocation failed or the
78  * preallcoated storage is full
79  */
80 bool _cbor_map_add_value(cbor_item_t* item, cbor_item_t* value);
81 
82 /** Is this map definite?
83  *
84  * @param item[borrow] A map
85  * @return Is this map definite?
86  */
87 bool cbor_map_is_definite(const cbor_item_t* item);
88 
89 /** Is this map indefinite?
90  *
91  * @param item[borrow] A map
92  * @return Is this map indefinite?
93  */
94 bool cbor_map_is_indefinite(const cbor_item_t* item);
95 
96 /** Get the pairs storage
97  *
98  * @param item[borrow] A map
99  * @return Array of #cbor_map_size pairs. Manipulation is possible as long as
100  * references remain valid.
101  */
102 cbor_pair* cbor_map_handle(const cbor_item_t* item);