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