dali/internal/common/indexed-map-base.h

   1 #ifndef DALI_INDEXED_MAP_BASE_H
   2 #define DALI_INDEXED_MAP_BASE_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 // EXTERNAL INCLUDES
  21 #include <algorithm>
  22 #include <string>
  23 #include <vector>
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/public-api/common/dali-common.h>
  27
  28 namespace Dali
  29 {
  30 namespace Internal
  31 {
  32 /**
  33  * @brief Specific key-element container which can access by index.
  34  * Register element by key. and Get element by key or index.
  35  *
  36  * This basical member API that indexed map container needs.
  37  * Indexed map container can only Register and not allow Unregister in current implement spec.
  38  *
  39  * This container hold std::pair<KeyType, ElementType>.
  40  * Iterator will iterate this pair container.
  41  *
  42  * For example,
  43  * @code
  44  * TrieContainerBase<KeyType, SearchKeyType, KeyIndexConverterType, ElementType> container;
  45  * for(auto && elements : container)
  46  * {
  47  *   elements.first == KeyType();
  48  *   elements.second == ElementType();
  49  * }
  50  * @endcode
  51  *
  52  * Contain elements in registered order.
  53  * You can access that data by this order as 'index'
  54  *
  55  * For example,
  56  * @code
  57  * container.Register(10001, 111);
  58  * container.Register(20002, 222);
  59  * container[10001] == 111;
  60  * container[20002] == 222;
  61  * container.GetElementByIndex(0) == 111;
  62  * container.GetKeyByIndex(0) == 10001;
  63  * container.GetKeyElementPairByIndex(1) == KeyElementPairType(20002, 222);
  64  * @endcode
  65  *
  66  * Get API return iterator of container.
  67  *
  68  * For example,
  69  * @code
  70  * container.Register(10001, 111);
  71  * const auto& iter = container.Get(10001);
  72  * iter->first == 10001;
  73  * iter->second == 111;
  74  * container.Get(30003) == container.End();
  75  * @endcode
  76  *
  77  * @tparam KeyType The type of the key that the container holds.
  78  * @tparam SearchKeyType The type of the key when the container register or get.
  79  * @tparam ElementType The type of the data that the container holds.
  80  */
  81 template<typename KeyType, typename SearchKeyType, typename ElementType>
  82 class IndexedMapBase
  83 {
  84 public:
  85   /**
  86    * @brief Type definitions.
  87    */
  88   using KeyElementPairType = std::pair<KeyType, ElementType>;
  89   using iterator           = typename std::vector<KeyElementPairType>::iterator;
  90   using const_iterator     = typename std::vector<KeyElementPairType>::const_iterator;
  91
  92 public: // Virtual API
  93   /**
  94    * @brief Register element by the key.
  95    *
  96    * @param[in] key The key that this container will hold. Duplicated key doesn't allow.
  97    * @param[in] element The element pairwise with key.
  98    * @return True if Register success. Otherwise, return false.
  99    */
 100   virtual bool Register(const SearchKeyType& key, const ElementType& element) = 0;
 101
 102   /**
 103    * @brief Register moved element by the key.
 104    *
 105    * @param[in] key The key that this container will hold. Duplicated key doesn't allow.
 106    * @param[in] element The element pairwise with key.
 107    * @return True if Register success. Otherwise, return false.
 108    */
 109   virtual bool Register(const SearchKeyType& key, ElementType&& element) = 0;
 110
 111   /**
 112    * @brief Get element by the key.
 113    *
 114    * @param[in] key The key that this container will hold.
 115    * @return If exist, iterator of container. Otherwise, return End().
 116    */
 117   virtual iterator Get(const SearchKeyType& key) = 0;
 118
 119   /**
 120    * @brief Get element by the key.
 121    *
 122    * @param[in] key The key that this container will hold.
 123    * @return If exist, iterator of container. Otherwise, return End().
 124    */
 125   virtual const_iterator Get(const SearchKeyType& key) const = 0;
 126
 127 public:
 128   /**
 129    * @brief Constructor.
 130    */
 131   IndexedMapBase()
 132   {
 133   }
 134
 135   /**
 136    * @brief Destructor.
 137    */
 138   virtual ~IndexedMapBase()
 139   {
 140   }
 141
 142   /**
 143    * @brief Clear this container.
 144    */
 145   virtual void Clear()
 146   {
 147     mKeyElementPool.clear();
 148   }
 149
 150   /**
 151    * @brief Get the number of elements that this container hold.
 152    *
 153    * @return The number of elements that this container hold.
 154    */
 155   std::size_t Count() const
 156   {
 157     return mKeyElementPool.size();
 158   }
 159
 160   /**
 161    * @brief Check whether container is empty or not.
 162    *
 163    * @return Whether elemnt is empty or not.
 164    */
 165   bool Empty() const
 166   {
 167     return mKeyElementPool.empty();
 168   }
 169
 170   /**
 171    * @brief Reserve KeyElementPool container size.
 172    * Reserve only if current container size is smaller than input size.
 173    *
 174    * @param[in] size Reserve size.
 175    */
 176   void Reserve(const std::size_t& size)
 177   {
 178     if(mKeyElementPool.size() < size)
 179     {
 180       mKeyElementPool.reserve(size);
 181     }
 182   }
 183
 184   /**
 185    * @brief Get Element by the key.
 186    * @note Assert throw when try to use unregistered key.
 187    *
 188    * @param[in] key The key what we want to get.
 189    * @return registered element.
 190    */
 191   const ElementType& operator[](const SearchKeyType& key) const
 192   {
 193     const_iterator iter = Get(key);
 194     DALI_ASSERT_ALWAYS(iter != End() && "const operator[] doesn't allow non-exist key access");
 195     return iter->second;
 196   }
 197
 198   /**
 199    * @brief Get Element by the key.
 200    * @note Assert throw when try to use unregistered key.
 201    *
 202    * @param[in] key The key what we want to get.
 203    * @return registered element.
 204    */
 205   ElementType& operator[](const SearchKeyType& key)
 206   {
 207     iterator iter = Get(key);
 208     DALI_ASSERT_ALWAYS(iter != End() && "operator[] doesn't allow non-exist key access");
 209     return iter->second;
 210   }
 211
 212   /**
 213    * @brief Get Element by the index.
 214    *
 215    * @param[in] index The index what we want to get.
 216    * @return index'th registered element.
 217    * @note mTrieKeyElementPool emplace_back the elements ordered by Register function called.
 218    */
 219   const ElementType& GetElementByIndex(const std::uint32_t& index) const
 220   {
 221     DALI_ASSERT_ALWAYS((index < mKeyElementPool.size()) && "operator[] index >= Count()");
 222     return mKeyElementPool[index].second;
 223   }
 224
 225   /**
 226    * @brief Get Key by the index.
 227    *
 228    * @param[in] index The index what we want to get.
 229    * @return index'th registered key.
 230    * @note mTrieKeyElementPool emplace_back the elements ordered by Register function called.
 231    */
 232   const KeyType& GetKeyByIndex(const std::uint32_t& index) const
 233   {
 234     DALI_ASSERT_ALWAYS((index < mKeyElementPool.size()) && "operator[] index >= Count()");
 235     return mKeyElementPool[index].first;
 236   }
 237
 238   /**
 239    * @brief Get Key and Element by the index.
 240    *
 241    * @param[in] index The index what we want to get.
 242    * @return index'th registered key element pair.
 243    * @note mTrieKeyElementPool emplace_back the elements ordered by Register function called.
 244    */
 245   const KeyElementPairType& GetKeyElementPairByIndex(const std::uint32_t& index) const
 246   {
 247     DALI_ASSERT_ALWAYS((index < mKeyElementPool.size()) && "operator[] index >= Count()");
 248     return mKeyElementPool[index];
 249   }
 250
 251   /**
 252    * @brief Iterator to the beginning of the data.
 253    * @return Iterator to the beginning of the data
 254    */
 255   iterator Begin()
 256   {
 257     return mKeyElementPool.begin();
 258   }
 259   /**
 260    * @brief Const Iterator to the beginning of the data.
 261    * @return Const Iterator to the beginning of the data
 262    */
 263   const_iterator CBegin() const
 264   {
 265     return mKeyElementPool.cbegin();
 266   }
 267   /**
 268    * @brief Const Iterator to the beginning of the data.
 269    * @return Const Iterator to the beginning of the data
 270    */
 271   const_iterator Begin() const
 272   {
 273     return mKeyElementPool.begin();
 274   }
 275
 276   /**
 277    * @brief Iterator to the end of the data (one past last element).
 278    * @return Iterator to the end of the data (one past last element)
 279    */
 280   iterator End()
 281   {
 282     return mKeyElementPool.end();
 283   }
 284   /**
 285    * @brief Const iterator to the end of the data (one past last element).
 286    * @return Const iterator to the end of the data (one past last element)
 287    */
 288   const_iterator CEnd() const
 289   {
 290     return mKeyElementPool.cend();
 291   }
 292   /**
 293    * @brief Const iterator to the end of the data (one past last element).
 294    * @return Const iterator to the end of the data (one past last element)
 295    */
 296   const_iterator End() const
 297   {
 298     return mKeyElementPool.end();
 299   }
 300
 301 public: // API for C++11 std style functions.
 302   /**
 303    * Support for C++11 std style function call.
 304    * @see Clear()
 305    */
 306   void clear()
 307   {
 308     Clear();
 309   }
 310
 311   /**
 312    * Support for C++11 std style function call.
 313    *
 314    * @return The number of elements that this container hold.
 315    * @see Count()
 316    */
 317   std::size_t size() const
 318   {
 319     return Count();
 320   }
 321
 322   /**
 323    * Support for C++11 std style function call.
 324    *
 325    * @return Whether elemnt is empty or not.
 326    * @see Empty()
 327    */
 328   bool empty() const
 329   {
 330     return Empty();
 331   }
 332
 333   /**
 334    * Support for C++11 std style function call.
 335    *
 336    * @param[in] size Reserve size.
 337    * @see Reserve()
 338    */
 339   void reserve(const std::size_t size)
 340   {
 341     Reserve(size);
 342   }
 343
 344   /**
 345    * Support for C++11 Range-based for loop: for( item : container ).
 346    * @return The start iterator
 347    */
 348   iterator begin()
 349   {
 350     return Begin();
 351   }
 352   /**
 353    * Support for C++11 Range-based for loop: for( item : container ).
 354    * @return The start const iterator
 355    */
 356   const_iterator cbegin() const
 357   {
 358     return CBegin();
 359   }
 360
 361   /**
 362    * Support for C++11 Range-based for loop: for( item : container ).
 363    * @return The start const iterator
 364    */
 365   const_iterator begin() const
 366   {
 367     return Begin();
 368   }
 369
 370   /**
 371    * Support for C++11 Range-based for loop: for( item : container ).
 372    * @return The end iterator
 373    */
 374   iterator end()
 375   {
 376     return End();
 377   }
 378
 379   /**
 380    * Support for C++11 Range-based for loop: for( item : container ).
 381    * @return The end const iterator
 382    */
 383   const_iterator cend() const
 384   {
 385     return CEnd();
 386   }
 387
 388   /**
 389    * Support for C++11 Range-based for loop: for( item : container ).
 390    * @return The end const iterator
 391    */
 392   const_iterator end() const
 393   {
 394     return End();
 395   }
 396
 397 protected:
 398   std::vector<KeyElementPairType> mKeyElementPool{};
 399 };
 400
 401 } // namespace Internal
 402
 403 } // namespace Dali
 404
 405 #endif //  DALI_INDEXED_MAP_BASE_H