1 /*
2 * Copyright (c) 2009-2021, Google LLC
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 * * Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * * Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 * * Neither the name of Google LLC nor the
13 * names of its contributors may be used to endorse or promote products
14 * derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL Google LLC BE LIABLE FOR ANY DIRECT,
20 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27
28 #ifndef UPB_COLLECTIONS_MAP_H_
29 #define UPB_COLLECTIONS_MAP_H_
30
31 #include "upb/base/descriptor_constants.h"
32 #include "upb/collections/message_value.h"
33 #include "upb/mem/arena.h"
34
35 // Must be last.
36 #include "upb/port/def.inc"
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42 // Creates a new map on the given arena with the given key/value size.
43 UPB_API upb_Map* upb_Map_New(upb_Arena* a, upb_CType key_type,
44 upb_CType value_type);
45
46 // Returns the number of entries in the map.
47 UPB_API size_t upb_Map_Size(const upb_Map* map);
48
49 // Stores a value for the given key into |*val| (or the zero value if the key is
50 // not present). Returns whether the key was present. The |val| pointer may be
51 // NULL, in which case the function tests whether the given key is present.
52 UPB_API bool upb_Map_Get(const upb_Map* map, upb_MessageValue key,
53 upb_MessageValue* val);
54
55 // Removes all entries in the map.
56 UPB_API void upb_Map_Clear(upb_Map* map);
57
58 typedef enum {
59 kUpb_MapInsertStatus_Inserted = 0,
60 kUpb_MapInsertStatus_Replaced = 1,
61 kUpb_MapInsertStatus_OutOfMemory = 2,
62 } upb_MapInsertStatus;
63
64 // Sets the given key to the given value, returning whether the key was inserted
65 // or replaced. If the key was inserted, then any existing iterators will be
66 // invalidated.
67 UPB_API upb_MapInsertStatus upb_Map_Insert(upb_Map* map, upb_MessageValue key,
68 upb_MessageValue val,
69 upb_Arena* arena);
70
71 // Sets the given key to the given value. Returns false if memory allocation
72 // failed. If the key is newly inserted, then any existing iterators will be
73 // invalidated.
upb_Map_Set(upb_Map * map,upb_MessageValue key,upb_MessageValue val,upb_Arena * arena)74 UPB_API_INLINE bool upb_Map_Set(upb_Map* map, upb_MessageValue key,
75 upb_MessageValue val, upb_Arena* arena) {
76 return upb_Map_Insert(map, key, val, arena) !=
77 kUpb_MapInsertStatus_OutOfMemory;
78 }
79
80 // Deletes this key from the table. Returns true if the key was present.
81 // If present and |val| is non-NULL, stores the deleted value.
82 UPB_API bool upb_Map_Delete(upb_Map* map, upb_MessageValue key,
83 upb_MessageValue* val);
84
85 // (DEPRECATED and going away soon. Do not use.)
upb_Map_Delete2(upb_Map * map,upb_MessageValue key,upb_MessageValue * val)86 UPB_INLINE bool upb_Map_Delete2(upb_Map* map, upb_MessageValue key,
87 upb_MessageValue* val) {
88 return upb_Map_Delete(map, key, val);
89 }
90
91 // Map iteration:
92 //
93 // size_t iter = kUpb_Map_Begin;
94 // upb_MessageValue key, val;
95 // while (upb_Map_Next(map, &key, &val, &iter)) {
96 // ...
97 // }
98
99 #define kUpb_Map_Begin ((size_t)-1)
100
101 // Advances to the next entry. Returns false if no more entries are present.
102 // Otherwise returns true and populates both *key and *value.
103 UPB_API bool upb_Map_Next(const upb_Map* map, upb_MessageValue* key,
104 upb_MessageValue* val, size_t* iter);
105
106 // DEPRECATED iterator, slated for removal.
107
108 /* Map iteration:
109 *
110 * size_t iter = kUpb_Map_Begin;
111 * while (upb_MapIterator_Next(map, &iter)) {
112 * upb_MessageValue key = upb_MapIterator_Key(map, iter);
113 * upb_MessageValue val = upb_MapIterator_Value(map, iter);
114 * }
115 */
116
117 // Advances to the next entry. Returns false if no more entries are present.
118 bool upb_MapIterator_Next(const upb_Map* map, size_t* iter);
119
120 // Returns true if the iterator still points to a valid entry, or false if the
121 // iterator is past the last element. It is an error to call this function with
122 // kUpb_Map_Begin (you must call next() at least once first).
123 bool upb_MapIterator_Done(const upb_Map* map, size_t iter);
124
125 // Returns the key and value for this entry of the map.
126 upb_MessageValue upb_MapIterator_Key(const upb_Map* map, size_t iter);
127 upb_MessageValue upb_MapIterator_Value(const upb_Map* map, size_t iter);
128
129 #ifdef __cplusplus
130 } /* extern "C" */
131 #endif
132
133 #include "upb/port/undef.inc"
134
135 #endif /* UPB_COLLECTIONS_MAP_H_ */
136