dali/public-api/object/property-map.h

   1 #ifndef DALI_PROPERTY_MAP_H
   2 #define DALI_PROPERTY_MAP_H
   3
   4 /*
   5  * Copyright (c) 2022 Samsung Electronics Co., Ltd.
   6  *
   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
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  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.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <initializer_list>
  23 #include <sstream>
  24 #include <string>
  25 #include <string_view>
  26
  27 // INTERNAL INCLUDES
  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>
  32
  33 namespace Dali
  34 {
  35 /**
  36  * @addtogroup dali_core_object
  37  * @{
  38  */
  39
  40 using KeyValuePair    = std::pair<Property::Key, Property::Value>;
  41 using StringValuePair = std::pair<std::string, Property::Value>;
  42
  43 /**
  44  * @brief A Map of property values, the key type could be String or Property::Index.
  45  * @SINCE_1_0.0
  46  */
  47 class DALI_CORE_API Property::Map
  48 {
  49 public:
  50   using SizeType = std::size_t;
  51
  52   /**
  53    * @brief Default constructor.
  54    * @SINCE_1_0.0
  55    */
  56   Map();
  57
  58   /**
  59    * @brief Constructor from initializer_list.
  60    *
  61    * @SINCE_1_4.17
  62    * @param[in] values An initializer_list of pairs of index and value.
  63    */
  64   Map(const std::initializer_list<KeyValuePair>& values);
  65
  66   /**
  67    * @brief Copy constructor.
  68    *
  69    * @SINCE_1_0.0
  70    * @param[in] other The Map to copy from
  71    */
  72   Map(const Map& other);
  73
  74   /**
  75    * @brief Move constructor.
  76    *
  77    * @SINCE_1_4.17
  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.
  80    */
  81   Map(Map&& other);
  82
  83   /**
  84    * @brief Non-virtual destructor.
  85    * @SINCE_1_0.0
  86    */
  87   ~Map();
  88
  89   /**
  90    * @brief Retrieves the number of elements in the map.
  91    *
  92    * @SINCE_1_0.0
  93    * @return The number of elements in the map
  94    */
  95   SizeType Count() const;
  96
  97   /**
  98    * @brief Returns whether the map is empty.
  99    *
 100    * @SINCE_1_0.0
 101    * @return @c true if empty, @c false otherwise
 102    */
 103   bool Empty() const;
 104
 105   /**
 106    * @brief Inserts the key-value pair in the Map, with the key type as string.
 107    *
 108    * Does not check for duplicates.
 109    * @SINCE_1_0.0
 110    * @param[in] key The key to insert
 111    * @param[in] value The value to insert
 112    */
 113   void Insert(std::string key, Value value);
 114
 115   /**
 116    * @brief Inserts the key-value pair in the Map, with the key type as index.
 117    *
 118    * Does not check for duplicates.
 119    * @SINCE_1_1.39
 120    * @param[in] key The key to insert
 121    * @param[in] value The value to insert
 122    */
 123   void Insert(Property::Index key, Value value);
 124
 125   /**
 126    * @brief Inserts the key-value pair in the Map, with the key type as string.
 127    *
 128    * Does not check for duplicates
 129    * @SINCE_1_2.5
 130    * @param key to insert
 131    * @param value to insert
 132    * @return a reference to this object
 133    */
 134   Property::Map& Add(std::string key, Value value)
 135   {
 136     Insert(std::move(key), std::move(value));
 137     return *this;
 138   }
 139
 140   /**
 141    * @brief Inserts the key-value pair in the Map, with the key type as index.
 142    *
 143    * Does not check for duplicates
 144    * @SINCE_1_2.5
 145    * @param key to insert
 146    * @param value to insert
 147    * @return a reference to this object
 148    */
 149   Property::Map& Add(Property::Index key, Value value)
 150   {
 151     Insert(key, std::move(value));
 152     return *this;
 153   }
 154
 155   /**
 156    * @brief Retrieves the value at the specified position.
 157    *
 158    * @SINCE_1_0.0
 159    * @param[in] position The specified position
 160    * @return A reference to the value at the specified position
 161    *
 162    * @note Will assert if position >= Count()
 163    */
 164   Value& GetValue(SizeType position) const;
 165
 166   /**
 167    * DEPRECATED_1_1.39 Position based retrieval is no longer supported after extending the key type to both Index and String.
 168    *
 169    * @brief Retrieves the key at the specified position.
 170    *
 171    * @SINCE_1_0.0
 172    * @param[in] position The specified position
 173    * @return A const reference to the key at the specified position
 174    *
 175    * @note Will assert if position >= Count()
 176    */
 177   const std::string& GetKey(SizeType position) const DALI_DEPRECATED_API;
 178
 179   /**
 180    * @brief Retrieve the key at the specified position.
 181    *
 182    * @SINCE_1_2.7
 183    * @param[in] position The specified position
 184    * @return A copy of the key at the specified position.
 185    *
 186    * @note Will assert if position >= Count()
 187    */
 188   Key GetKeyAt(SizeType position) const;
 189
 190   /**
 191    * DEPRECATED_1_1.39 Position based retrieval is no longer supported after extending the key type to both Index and String.
 192    *
 193    * @brief Retrieves the key & the value at the specified position.
 194    *
 195    * @SINCE_1_0.0
 196    * @param[in] position The specified position
 197    * @return A reference to the pair of key and value at the specified position
 198    *
 199    * @note Will assert if position >= Count() or key at position is an index key.
 200    */
 201   StringValuePair& GetPair(SizeType position) const DALI_DEPRECATED_API;
 202
 203   /**
 204    * @brief Retrieve the key & the value at the specified position.
 205    *
 206    * @SINCE_1_2.7
 207    * @param[in] position The specified position
 208    * @return A copy of the pair of key and value at the specified position.
 209    *
 210    * @note Will assert if position >= Count()
 211    */
 212   KeyValuePair GetKeyValue(SizeType position) const;
 213
 214   /**
 215    * @brief Finds the value for the specified key if it exists.
 216    *
 217    * @SINCE_1_0.0
 218    * @param[in] key The key to find
 219    *
 220    * @return A const pointer to the value if it exists, NULL otherwise
 221    */
 222   Value* Find(std::string_view key) const;
 223
 224   /**
 225    * @brief Finds the value for the specified key if it exists.
 226    *
 227    * @SINCE_1_1.39
 228    * @param[in] key The key to find
 229    *
 230    * @return A const pointer to the value if it exists, NULL otherwise
 231    */
 232   Value* Find(Property::Index key) const;
 233
 234   /**
 235    * @brief Finds the value for the specified keys if either exist.
 236    *
 237    * Will search for the index key first.
 238    *
 239    * @SINCE_1_1.45
 240    * @param[in] indexKey  The index key to find
 241    * @param[in] stringKey The string key to find
 242    *
 243    * @return A const pointer to the value if it exists, NULL otherwise
 244    */
 245   Value* Find(Property::Index indexKey, std::string_view stringKey) const;
 246
 247   /**
 248    * @brief Finds the value for the specified key if it exists and its type is type.
 249    *
 250    * @SINCE_1_0.0
 251    * @param[in] key  The key to find
 252    * @param[in] type The type to check
 253    *
 254    * @return A const pointer to the value if it exists, NULL otherwise
 255    */
 256   Value* Find(std::string_view key, Property::Type type) const;
 257
 258   /**
 259    * @brief Finds the value for the specified key if it exists and its type is type.
 260    *
 261    * @SINCE_1_1.39
 262    * @param[in] key  The key to find
 263    * @param[in] type The type to check
 264    *
 265    * @return A const pointer to the value if it exists, NULL otherwise
 266    */
 267   Value* Find(Property::Index key, Property::Type type) const;
 268
 269   /**
 270    * @brief Clears the map.
 271    * @SINCE_1_0.0
 272    */
 273   void Clear();
 274
 275   /**
 276    * @brief Removes the item by the specified key.
 277    *
 278    * @SINCE_2_1.15
 279    * @param[in] key  The key to remove
 280    * @return @c true if succeeded, @c false otherwise
 281    */
 282   bool Remove(Property::Index key);
 283
 284   /**
 285    * @brief Removes the item by the specified key.
 286    *
 287    * @SINCE_2_1.15
 288    * @param[in] key  The key to remove
 289    * @return @c true if succeeded, @c false otherwise
 290    */
 291   bool Remove(std::string_view key);
 292
 293   /**
 294    * @brief Merges values from the map 'from' to the current.
 295    *
 296    * Any values in 'from' will overwrite the values in the current map.
 297    *
 298    * @SINCE_1_0.0
 299    * @param[in] from The map to merge from
 300    */
 301   void Merge(const Map& from);
 302
 303   /**
 304    * @brief Const operator to access element with the specified string key.
 305    *
 306    * @SINCE_1_0.0
 307    * @param[in] key The key whose value to access
 308    *
 309    * @return The value for the element with the specified key, if key doesn't exist, then Property::NONE is returned
 310    *
 311    * @note Will assert if invalid-key is given.
 312    */
 313   const Value& operator[](std::string_view key) const;
 314
 315   /**
 316    * @brief Operator to access the element with the specified string key.
 317    *
 318    * @SINCE_1_0.0
 319    * @param[in] key The key whose value to access
 320    *
 321    * @return A reference to the value for the element with the specified key
 322    *
 323    * @note If an element with the key does not exist, then it is created.
 324    */
 325   Value& operator[](std::string_view key);
 326
 327   /**
 328    * @brief Const operator to access element with the specified index key.
 329    *
 330    * @SINCE_1_1.39
 331    * @param[in] key The key whose value to access
 332    *
 333    * @return The value for the element with the specified key, if key doesn't exist, then Property::NONE is returned
 334    *
 335    * @note Will assert if invalid-key is given.
 336    */
 337   const Value& operator[](Property::Index key) const;
 338
 339   /**
 340    * @brief Operator to access the element with the specified index key.
 341    *
 342    * @SINCE_1_1.39
 343    * @param[in] key The key whose value to access
 344    *
 345    * @return A reference to the value for the element with the specified key
 346    *
 347    * @note If an element with the key does not exist, then it is created.
 348    */
 349   Value& operator[](Property::Index key);
 350
 351   /**
 352    * @brief Assignment operator.
 353    *
 354    * @SINCE_1_0.0
 355    * @param[in] other The map to copy from
 356    *
 357    * @return The copied map
 358    */
 359   Map& operator=(const Map& other);
 360
 361   /**
 362    * @brief Move assignment operator.
 363    *
 364    * @SINCE_1_4.17
 365    * @param[in] other The map to move from
 366    *
 367    * @return The moved map
 368    *
 369    * @note The other array is an r-value so becomes invalid and is no longer usable.
 370    */
 371   Map& operator=(Map&& other);
 372
 373   /**
 374    * @brief Output to stream.
 375    * @SINCE_1_1.28
 376    */
 377   friend DALI_CORE_API std::ostream& operator<<(std::ostream& stream, const Property::Map& map);
 378
 379 private:
 380   struct DALI_INTERNAL Impl;  ///< Private data
 381   Impl*                mImpl; ///< Pointer to private data
 382 };
 383
 384 /**
 385  * @brief Converts the key/value pairs of the property map into a string and append to an output stream.
 386  *
 387  * @SINCE_1_1.28
 388  * @param[in] stream The output stream operator
 389  * @param[in] map The map to insert
 390  * @return The output stream operator
 391  */
 392 DALI_CORE_API std::ostream& operator<<(std::ostream& stream, const Property::Map& map);
 393
 394 /**
 395  * @}
 396  */
 397 } // namespace Dali
 398
 399 #endif // DALI_PROPERTY_MAP_H