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

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