1 #ifndef DALI_PROPERTY_MAP_H
2 #define DALI_PROPERTY_MAP_H
5 * Copyright (c) 2022 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
22 #include <initializer_list>
25 #include <string_view>
28 #include <dali/public-api/common/dali-common.h>
29 #include <dali/public-api/object/property-key.h>
30 #include <dali/public-api/object/property-value.h>
31 #include <dali/public-api/object/property.h>
36 * @addtogroup dali_core_object
40 using KeyValuePair = std::pair<Property::Key, Property::Value>;
41 using StringValuePair = std::pair<std::string, Property::Value>;
44 * @brief A Map of property values, the key type could be String or Property::Index.
47 class DALI_CORE_API Property::Map
50 using SizeType = std::size_t;
53 * @brief Default constructor.
59 * @brief Constructor from initializer_list.
62 * @param[in] values An initializer_list of pairs of index and value.
64 Map(const std::initializer_list<KeyValuePair>& values);
67 * @brief Copy constructor.
70 * @param[in] other The Map to copy from
72 Map(const Map& other);
75 * @brief Move constructor.
78 * @param[in] other The Map to move from
79 * @note After the @a other array is used, it becomes invalid and is no longer usable.
81 Map(Map&& other) noexcept;
84 * @brief Non-virtual destructor.
90 * @brief Retrieves the number of elements in the map.
93 * @return The number of elements in the map
95 SizeType Count() const;
98 * @brief Returns whether the map is empty.
101 * @return @c true if empty, @c false otherwise
106 * @brief Inserts the key-value pair in the Map, with the key type as string.
108 * Does not check for duplicates.
110 * @param[in] key The key to insert
111 * @param[in] value The value to insert
113 void Insert(std::string key, Value value);
116 * @brief Inserts the key-value pair in the Map, with the key type as index.
118 * Does not check for duplicates.
120 * @param[in] key The key to insert
121 * @param[in] value The value to insert
123 void Insert(Property::Index key, Value value);
126 * @brief Inserts the key-value pair in the Map, with the key type as string.
128 * Does not check for duplicates
130 * @param key to insert
131 * @param value to insert
132 * @return a reference to this object
134 Property::Map& Add(std::string key, Value value)
136 Insert(std::move(key), std::move(value));
141 * @brief Inserts the key-value pair in the Map, with the key type as index.
143 * Does not check for duplicates
145 * @param key to insert
146 * @param value to insert
147 * @return a reference to this object
149 Property::Map& Add(Property::Index key, Value value)
151 Insert(key, std::move(value));
156 * @brief Retrieves the value at the specified position.
159 * @param[in] position The specified position
160 * @return A reference to the value at the specified position
162 * @note Will assert if position >= Count()
164 Value& GetValue(SizeType position) const;
167 * DEPRECATED_1_1.39 Position based retrieval is no longer supported after extending the key type to both Index and String.
169 * @brief Retrieves the key at the specified position.
172 * @param[in] position The specified position
173 * @return A const reference to the key at the specified position
175 * @note Will assert if position >= Count()
177 const std::string& GetKey(SizeType position) const DALI_DEPRECATED_API;
180 * @brief Retrieve the key at the specified position.
183 * @param[in] position The specified position
184 * @return A copy of the key at the specified position.
186 * @note Will assert if position >= Count()
188 Key GetKeyAt(SizeType position) const;
191 * DEPRECATED_1_1.39 Position based retrieval is no longer supported after extending the key type to both Index and String.
193 * @brief Retrieves the key & the value at the specified position.
196 * @param[in] position The specified position
197 * @return A reference to the pair of key and value at the specified position
199 * @note Will assert if position >= Count() or key at position is an index key.
201 StringValuePair& GetPair(SizeType position) const DALI_DEPRECATED_API;
204 * @brief Retrieve the key & the value at the specified position.
207 * @param[in] position The specified position
208 * @return A copy of the pair of key and value at the specified position.
210 * @note Will assert if position >= Count()
212 KeyValuePair GetKeyValue(SizeType position) const;
215 * @brief Finds the value for the specified key if it exists.
218 * @param[in] key The key to find
220 * @return A const pointer to the value if it exists, NULL otherwise
222 Value* Find(std::string_view key) const;
225 * @brief Finds the value for the specified key if it exists.
228 * @param[in] key The key to find
230 * @return A const pointer to the value if it exists, NULL otherwise
232 Value* Find(Property::Index key) const;
235 * @brief Finds the value for the specified keys if either exist.
237 * Will search for the index key first.
240 * @param[in] indexKey The index key to find
241 * @param[in] stringKey The string key to find
243 * @return A const pointer to the value if it exists, NULL otherwise
245 Value* Find(Property::Index indexKey, std::string_view stringKey) const;
248 * @brief Finds the value for the specified key if it exists and its type is type.
251 * @param[in] key The key to find
252 * @param[in] type The type to check
254 * @return A const pointer to the value if it exists, NULL otherwise
256 Value* Find(std::string_view key, Property::Type type) const;
259 * @brief Finds the value for the specified key if it exists and its type is type.
262 * @param[in] key The key to find
263 * @param[in] type The type to check
265 * @return A const pointer to the value if it exists, NULL otherwise
267 Value* Find(Property::Index key, Property::Type type) const;
270 * @brief Clears the map.
276 * @brief Removes the item by the specified key.
279 * @param[in] key The key to remove
280 * @return @c true if succeeded, @c false otherwise
282 bool Remove(Property::Index key);
285 * @brief Removes the item by the specified key.
288 * @param[in] key The key to remove
289 * @return @c true if succeeded, @c false otherwise
291 bool Remove(std::string_view key);
294 * @brief Merges values from the map 'from' to the current.
296 * Any values in 'from' will overwrite the values in the current map.
299 * @param[in] from The map to merge from
301 void Merge(const Map& from);
304 * @brief Const operator to access element with the specified string key.
307 * @param[in] key The key whose value to access
309 * @return The value for the element with the specified key, if key doesn't exist, then Property::NONE is returned
311 * @note Will assert if invalid-key is given.
313 const Value& operator[](std::string_view key) const;
316 * @brief Operator to access the element with the specified string key.
319 * @param[in] key The key whose value to access
321 * @return A reference to the value for the element with the specified key
323 * @note If an element with the key does not exist, then it is created.
325 Value& operator[](std::string_view key);
328 * @brief Const operator to access element with the specified index key.
331 * @param[in] key The key whose value to access
333 * @return The value for the element with the specified key, if key doesn't exist, then Property::NONE is returned
335 * @note Will assert if invalid-key is given.
337 const Value& operator[](Property::Index key) const;
340 * @brief Operator to access the element with the specified index key.
343 * @param[in] key The key whose value to access
345 * @return A reference to the value for the element with the specified key
347 * @note If an element with the key does not exist, then it is created.
349 Value& operator[](Property::Index key);
352 * @brief Assignment operator.
355 * @param[in] other The map to copy from
357 * @return The copied map
359 Map& operator=(const Map& other);
362 * @brief Move assignment operator.
365 * @param[in] other The map to move from
367 * @return The moved map
369 * @note The other array is an r-value so becomes invalid and is no longer usable.
371 Map& operator=(Map&& other) noexcept;
374 * @brief Output to stream.
377 friend DALI_CORE_API std::ostream& operator<<(std::ostream& stream, const Property::Map& map);
380 struct DALI_INTERNAL Impl; ///< Private data
381 Impl* mImpl; ///< Pointer to private data
385 * @brief Converts the key/value pairs of the property map into a string and append to an output stream.
388 * @param[in] stream The output stream operator
389 * @param[in] map The map to insert
390 * @return The output stream operator
392 DALI_CORE_API std::ostream& operator<<(std::ostream& stream, const Property::Map& map);
399 #endif // DALI_PROPERTY_MAP_H