1 #ifndef DALI_PROPERTY_MAP_H
2 #define DALI_PROPERTY_MAP_H
5 * Copyright (c) 2020 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>
27 #include <dali/public-api/common/dali-common.h>
28 #include <dali/public-api/object/property-key.h>
29 #include <dali/public-api/object/property-value.h>
30 #include <dali/public-api/object/property.h>
35 * @addtogroup dali_core_object
39 using KeyValuePair = std::pair<Property::Key, Property::Value>;
40 using StringValuePair = std::pair<std::string, Property::Value>;
43 * @brief A Map of property values, the key type could be String or Property::Index.
46 class DALI_CORE_API Property::Map
49 using SizeType = std::size_t;
52 * @brief Default constructor.
58 * @brief Constructor from initializer_list.
61 * @param[in] values An initializer_list of pairs of index and value.
63 Map(const std::initializer_list<KeyValuePair>& values);
66 * @brief Copy constructor.
69 * @param[in] other The Map to copy from
71 Map(const Map& other);
74 * @brief Move constructor.
77 * @param[in] other The Map to move from
78 * @note After the @a other array is used, it becomes invalid and is no longer usable.
83 * @brief Non-virtual destructor.
89 * @brief Retrieves the number of elements in the map.
92 * @return The number of elements in the map
94 SizeType Count() const;
97 * @brief Returns whether the map is empty.
100 * @return @c true if empty, @c false otherwise
105 * @brief Inserts the key-value pair in the Map, with the key type as string.
107 * Does not check for duplicates.
109 * @param[in] key The key to insert
110 * @param[in] value The value to insert
112 void Insert(const char* key, const Value& value);
115 * @brief Inserts the key-value pair in the Map, with the key type as string.
117 * Does not check for duplicates.
119 * @param[in] key The key to insert
120 * @param[in] value The value to insert
122 void Insert(const std::string& key, const Value& value);
125 * @brief Inserts the key-value pair in the Map, with the key type as index.
127 * Does not check for duplicates.
129 * @param[in] key The key to insert
130 * @param[in] value The value to insert
132 void Insert(Property::Index key, const Value& value);
135 * @brief Inserts the key-value pair in the Map, with the key type as string.
137 * Does not check for duplicates
139 * @param key to insert
140 * @param value to insert
141 * @return a reference to this object
143 inline Property::Map& Add(const char* key, const Value& value)
150 * @brief Inserts the key-value pair in the Map, with the key type as string.
152 * Does not check for duplicates
154 * @param key to insert
155 * @param value to insert
156 * @return a reference to this object
158 inline Property::Map& Add(const std::string& key, const Value& value)
165 * @brief Inserts the key-value pair in the Map, with the key type as index.
167 * Does not check for duplicates
169 * @param key to insert
170 * @param value to insert
171 * @return a reference to this object
173 inline Property::Map& Add(Property::Index key, const Value& value)
180 * @brief Retrieves the value at the specified position.
183 * @param[in] position The specified position
184 * @return A reference to the value at the specified position
186 * @note Will assert if position >= Count()
188 Value& GetValue(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 at the specified position.
196 * @param[in] position The specified position
197 * @return A const reference to the key at the specified position
199 * @note Will assert if position >= Count()
201 const std::string& GetKey(SizeType position) const DALI_DEPRECATED_API;
204 * @brief Retrieve the key at the specified position.
207 * @param[in] position The specified position
208 * @return A copy of the key at the specified position.
210 * @note Will assert if position >= Count()
212 Key GetKeyAt(SizeType position) const;
215 * DEPRECATED_1_1.39 Position based retrieval is no longer supported after extending the key type to both Index and String.
217 * @brief Retrieves the key & the value at the specified position.
220 * @param[in] position The specified position
221 * @return A reference to the pair of key and value at the specified position
223 * @note Will assert if position >= Count() or key at position is an index key.
225 StringValuePair& GetPair(SizeType position) const DALI_DEPRECATED_API;
228 * @brief Retrieve the key & the value at the specified position.
231 * @param[in] position The specified position
232 * @return A copy of the pair of key and value at the specified position.
234 * @note Will assert if position >= Count()
236 KeyValuePair GetKeyValue(SizeType position) const;
239 * @brief Finds the value for the specified key if it exists.
242 * @param[in] key The key to find
244 * @return A const pointer to the value if it exists, NULL otherwise
246 Value* Find(const char* key) const;
249 * @brief Finds the value for the specified key if it exists.
252 * @param[in] key The key to find
254 * @return A const pointer to the value if it exists, NULL otherwise
256 Value* Find(const std::string& key) const;
259 * @brief Finds the value for the specified key if it exists.
262 * @param[in] key The key to find
264 * @return A const pointer to the value if it exists, NULL otherwise
266 Value* Find(Property::Index key) const;
269 * @brief Finds the value for the specified keys if either exist.
271 * Will search for the index key first.
274 * @param[in] indexKey The index key to find
275 * @param[in] stringKey The string key to find
277 * @return A const pointer to the value if it exists, NULL otherwise
279 Value* Find(Property::Index indexKey, const std::string& stringKey) const;
282 * @brief Finds the value for the specified key if it exists and its type is type.
285 * @param[in] key The key to find
286 * @param[in] type The type to check
288 * @return A const pointer to the value if it exists, NULL otherwise
290 Value* Find(const std::string& key, Property::Type type) const;
293 * @brief Finds the value for the specified key if it exists and its type is type.
296 * @param[in] key The key to find
297 * @param[in] type The type to check
299 * @return A const pointer to the value if it exists, NULL otherwise
301 Value* Find(Property::Index key, Property::Type type) const;
304 * @brief Clears the map.
310 * @brief Merges values from the map 'from' to the current.
312 * Any values in 'from' will overwrite the values in the current map.
315 * @param[in] from The map to merge from
317 void Merge(const Map& from);
320 * @brief Const operator to access element with the specified string key.
323 * @param[in] key The key whose value to access
325 * @return The value for the element with the specified key, if key doesn't exist, then Property::NONE is returned
327 * @note Will assert if invalid-key is given.
329 const Value& operator[](const std::string& key) const;
332 * @brief Operator to access the element with the specified string key.
335 * @param[in] key The key whose value to access
337 * @return A reference to the value for the element with the specified key
339 * @note If an element with the key does not exist, then it is created.
341 Value& operator[](const std::string& key);
344 * @brief Const operator to access element with the specified index key.
347 * @param[in] key The key whose value to access
349 * @return The value for the element with the specified key, if key doesn't exist, then Property::NONE is returned
351 * @note Will assert if invalid-key is given.
353 const Value& operator[](Property::Index key) const;
356 * @brief Operator to access the element with the specified index key.
359 * @param[in] key The key whose value to access
361 * @return A reference to the value for the element with the specified key
363 * @note If an element with the key does not exist, then it is created.
365 Value& operator[](Property::Index key);
368 * @brief Assignment operator.
371 * @param[in] other The map to copy from
373 * @return The copied map
375 Map& operator=(const Map& other);
378 * @brief Move assignment operator.
381 * @param[in] other The map to move from
383 * @return The moved map
385 * @note The other array is an r-value so becomes invalid and is no longer usable.
387 Map& operator=(Map&& other);
390 * @brief Output to stream.
393 friend DALI_CORE_API std::ostream& operator<<(std::ostream& stream, const Property::Map& map);
396 struct DALI_INTERNAL Impl; ///< Private data
397 Impl* mImpl; ///< Pointer to private data
401 * @brief Converts the key/value pairs of the property map into a string and append to an output stream.
404 * @param[in] stream The output stream operator
405 * @param[in] map The map to insert
406 * @return The output stream operator
408 DALI_CORE_API std::ostream& operator<<(std::ostream& stream, const Property::Map& map);
415 #endif // DALI_PROPERTY_MAP_H