inc/FBaseColIMultiMap.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the License);
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 // http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16
  17 /**
  18  * @file                FBaseColIMultiMap.h
  19  * @brief               This is the header file for the %IMultiMap interface.
  20  *
  21  * This header file contains the declarations of the %IMultiMap interface.
  22  */
  23 #ifndef _FBASE_COL_IMULTI_MAP_H_
  24 #define _FBASE_COL_IMULTI_MAP_H_
  25
  26 #include <FBaseColICollection.h>
  27 #include <FBaseColTypes.h>
  28 #include <FBaseColIMapEnumerator.h>
  29 #include <FBaseObject.h>
  30
  31 namespace Tizen { namespace Base { namespace Collection
  32 {
  33
  34 class IList;
  35 class MapEntry;
  36
  37 /**
  38  * @interface IMultiMap
  39  * @brief       This interface represents a collection of key-value pairs.
  40  *
  41  * @since 2.0
  42  *
  43  * The %IMultiMap interface represents a collection of key-value pairs.
  44  * There is no limit on the number of elements having the same key, but duplicate elements with the same key are not allowed.
  45  * The key and value cannot be a @c null reference.
  46  * @n
  47  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/hashmap_multihashmap.htm">HashMap and MultiHashMap</a>.
  48  *
  49  */
  50 class _OSP_EXPORT_ IMultiMap
  51         : public virtual ICollection
  52 {
  53 public:
  54         /**
  55          * This polymorphic destructor should be overridden if required. @n
  56          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
  57          *
  58          * @since 2.0
  59          */
  60         virtual ~IMultiMap(void) {}
  61
  62         /**
  63          * @if OSPDEPREC
  64          * Adds the specified key-value pair to the map.
  65          *
  66          * @brief               <i> [Deprecated] </i>
  67          * @deprecated  This method is deprecated because it has a problem of constant reference argument.
  68          *                              Instead of using this method, use Add(Object* pKey, Object* pValue).
  69          * @since 2.0
  70          *
  71          * @return              An error code
  72          * @param[in]   key                             The key to add
  73          * @param[in]   value                           The corresponding value to add
  74          * @exception   E_SUCCESS                       The method is successful.
  75          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
  76          *                                                                      - A specified input parameter is invalid.
  77          *                                                                      - The comparer has failed to compare the keys.
  78          * @exception   E_OBJ_ALREADY_EXIST     The specified @c key and @c value already exist.
  79          * @remarks     This method performs a shallow copy. It adds just the pointer and not the element itself.
  80          * @see Remove()
  81          * @endif
  82          */
  83         result Add(const Object& key, const Object& value)
  84         {
  85                 return Add(const_cast< Object* >(&key), const_cast< Object* >(&value));
  86         }
  87
  88         /**
  89          * Adds the specified key-value pair to the map.
  90          *
  91          * @since 2.0
  92          *
  93          * @return              An error code
  94          * @param[in]   pKey                            A pointer to the key to add
  95          * @param[in]   pValue                          A pointer to the corresponding value to add
  96          * @exception   E_SUCCESS                       The method is successful.
  97          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
  98          *                                                                      - A specified input parameter is invalid.
  99          *                                                                      - The comparer has failed to compare the keys.
 100          * @exception   E_OBJ_ALREADY_EXIST     The specified @c pKey and @c pValue already exist.
 101          * @remarks     This method performs a shallow copy. It adds just the pointer and not the element itself.
 102          * @see Remove()
 103          */
 104         virtual result Add(Object* pKey, Object* pValue) = 0;
 105
 106         /**
 107          * Gets the number of values stored in the map.
 108          *
 109          * @since 2.0
 110          *
 111          * @return              The number of values currently stored in the map
 112          */
 113         virtual int GetCount(void) const = 0;
 114
 115         /**
 116          * Gets the number of values with keys matching the specified @c key.
 117          *
 118          * @since 2.0
 119          *
 120          * @return              The number of values with keys matching the specified key
 121          * @param[in]   key                             The key to locate in the map
 122          * @param[out]  count                           The number of values with keys matching the specified key
 123          * @exception   E_SUCCESS                       The method is successful.
 124          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 125          *                                                                      - A specified input parameter is invalid.
 126          *                                                                      - The comparer has failed to compare the keys.
 127          * @exception   E_OBJ_NOT_FOUND         The specified @c key has not been found in the map.
 128          */
 129         virtual result GetCount(const Object& key, int& count) const = 0;
 130
 131         /**
 132          * Gets the enumerator of the values associated with the specified @c key.
 133          *
 134          * @since 2.0
 135          *
 136          * @return              An instance of the IEnumerator derived class that contains the values associated with the specified key, @n
 137          *                              else @c null if an exception occurs
 138          * @param[in]   key                     The key to locate in the map
 139          * @exception   E_SUCCESS               The method is successful.
 140          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 141          *                                                              - A specified input parameter is invalid.
 142          *                                                              - The comparer has failed to compare the keys.
 143          * @exception   E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
 144          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 145          */
 146         virtual IEnumerator* GetValuesN(const Object& key) const = 0;
 147
 148         /**
 149          * Gets the list of all the unique keys in the map.
 150          *
 151          * @since 2.0
 152          *
 153          * @return              A pointer to the list of all the unique keys in the map, @n
 154          *                              else @c null if an exception occurs
 155          * @remarks
 156          *                              - The IList stores just the pointers to the elements in the map and not the elements themselves.
 157          *                              - The specific error code can be accessed using the GetLastResult() method.
 158          * @see                 GetValuesN()
 159          */
 160         virtual IList* GetKeysN(void) const = 0;
 161
 162         /**
 163          * Gets the list of all the values in the map.
 164          *
 165          * @since 2.0
 166          *
 167          * @return              A pointer to the list of all the values in the map, @n
 168          *                              else @c null if an exception occurs
 169          * @remarks
 170          *                              - The IList stores just the pointers to the elements in the map and not the elements themselves.
 171          *                              - The specific error code can be accessed using the GetLastResult() method.
 172          * @see                 SetValue()
 173          */
 174         virtual IList* GetValuesN(void) const = 0;
 175
 176         /**
 177          * Removes all the values associated with the specified @c key.
 178          *
 179          * @since 2.0
 180          *
 181          * @return              An error code
 182          * @param[in]   key                             The key for which the associated values are removed
 183          * @param[in]   forceDeletion           Set to @c true to deallocate the object, @n
 184          *                                                                      else @c false
 185          * @exception   E_SUCCESS                       The method is successful.
 186          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 187          *                                                                      - A specified input parameter is invalid.
 188          *                                                                      - The comparer has failed to compare the keys.
 189          * @exception   E_OBJ_NOT_FOUND         The specified @c key has not been found in the map.
 190          * @remarks
 191          *                              - Based on the specified element deleter, the remove operation not only gets rid of an element from the list, but also deletes its object instance. @n
 192          *                              The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
 193          *                              If both the element deleter and the @c forceDeleteion are set, the remove operation follows the @c forceDeletion setting.
 194          *                              - Remove(key, @b true) internally works as the below code:
 195          * @code
 196          * DeleterFunctionType deleter = GetDeleter();
 197          * SetDeleter(SingleObjectDeleter);
 198          * Remove(key);
 199          * SetDeleter(deleter);
 200          * @endcode
 201          *                              - Remove(key, @b false) internally works as the below code:
 202          * @code
 203          * DeleterFunctionType deleter = GetDeleter();
 204          * SetDeleter(NoOpDeleter);
 205          * Remove(key);
 206          * SetDeleter(deleter);
 207          * @endcode
 208          * @see                 Add(Object*, Object*)
 209          */
 210         result Remove(const Object& key, bool forceDeletion)
 211         {
 212                 DeleterFunctionType deleter = GetDeleter();
 213
 214                 if (forceDeletion)
 215                 {
 216                         SetDeleter(SingleObjectDeleter);
 217                 }
 218                 else
 219                 {
 220                         SetDeleter(NoOpDeleter);
 221                 }
 222
 223                 result r = Remove(key);
 224                 SetDeleter(deleter);
 225                 return r;
 226         }
 227
 228         /**
 229          * Removes all the values associated with the specified @c key.
 230          *
 231          * @since 2.0
 232          *
 233          * @return              An error code
 234          * @param[in]   key                             The key for which the associated values are removed
 235          * @exception   E_SUCCESS               The method is successful.
 236          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 237          *                                                              - A specified input parameter is invalid.
 238          *                                                              - The comparer has failed to compare the keys.
 239          * @exception   E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
 240          * @see                 Add(Object*, Object*)
 241          */
 242         virtual result Remove(const Object& key) = 0;
 243
 244         /**
 245          * Removes the specified @c value associated with the specified @c key. @n
 246          * The @c key is also removed if there are no more values associated with it.
 247          *
 248          * @since 2.0
 249          *
 250          * @return              An error code
 251          * @param[in]   key                             The key for which the mapping is removed from the map
 252          * @param[in]   value                           The value to remove
 253          * @param[in]   forceDeletion           Set to @c true to deallocate the object, @n
 254          *                                                                      else @c false
 255          * @exception   E_SUCCESS                       The method is successful.
 256          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 257          *                                                                      - A specified input parameter is invalid.
 258          *                                                                      - The comparer has failed to compare the keys.
 259          * @exception   E_OBJ_NOT_FOUND         The specified @c key and the specified @c value pair has not been found in the map.
 260          * @remarks
 261          *                              - Based on the specified element deleter, the remove operation not only gets rid of an element from the list, but also deletes its object instance. @n
 262          *                              - The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
 263          *                              - If both the element deleter and the @c forceDeleteion are set, the remove operation follows the @c forceDeletion setting.
 264          *                              - Remove(key, value, @b true) internally works as the below code:
 265          * @code
 266          * DeleterFunctionType deleter = GetDeleter();
 267          * SetDeleter(SingleObjectDeleter);
 268          * Remove(key, value);
 269          * SetDeleter(deleter);
 270          * @endcode
 271          *                              - Remove(key, value, @b false) internally works as the below code:
 272          * @code
 273          * DeleterFunctionType deleter = GetDeleter();
 274          * SetDeleter(NoOpDeleter);
 275          * Remove(key, value);
 276          * SetDeleter(deleter);
 277          * @endcode
 278          * @see                 Add(Object*, Object*)
 279          */
 280         result Remove(const Object& key, const Object& value, bool forceDeletion)
 281         {
 282                 DeleterFunctionType deleter = GetDeleter();
 283
 284                 if (forceDeletion)
 285                 {
 286                         SetDeleter(SingleObjectDeleter);
 287                 }
 288                 else
 289                 {
 290                         SetDeleter(NoOpDeleter);
 291                 }
 292
 293                 result r = Remove(key, value);
 294                 SetDeleter(deleter);
 295                 return r;
 296         }
 297
 298         /**
 299          * Removes the specified @c value associated with the specified @c key. @n
 300          * The @c key is also removed if there are no more values associated with it.
 301          *
 302          * @since 2.0
 303          *
 304          * @return              An error code
 305          * @param[in]   key                     The key for which the mapping is removed from the map
 306          * @param[in]   value                   The value to remove
 307          * @exception   E_SUCCESS               The method is successful.
 308          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 309          *                                                              - A specified input parameter is invalid.
 310          *                                                              - The comparer has failed to compare the keys.
 311          * @exception   E_OBJ_NOT_FOUND The specified @c key and the specified @c value pair has not been found in the map.
 312          * @see                 Add(Object*, Object*)
 313          */
 314         virtual result Remove(const Object& key, const Object& value) = 0;
 315
 316         /**
 317          * Removes all the object pointers in the collection. @n
 318          * If @c forceDeletion is set to @c true, the method also removes all the objects. This method can be called before deleting the collection.
 319          *
 320          * @since 2.0
 321          *
 322          * @param[in]   forceDeletion           Set to @c true to deallocate all objects, @n
 323          *                                                                      else @c false
 324          * @remarks
 325          *                              - Based on the specified element deleter, the remove operation not only gets rid of an element from the list, but also deletes its object instance. @n
 326          *                              - The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
 327          *                              - If both the element deleter and the @c forceDeletion are set, the remove operation follows the @c forceDeletion setting.
 328          *                              - RemoveAll(@b true) internally works as the below code:
 329          * @code
 330          * DeleterFunctionType deleter = GetDeleter();
 331          * SetDeleter(SingleObjectDeleter);
 332          * RemoveAll();
 333          * SetDeleter(deleter);
 334          * @endcode
 335          *                              - RemoveAll(@b false) internally works as the below code:
 336          * @code
 337          * DeleterFunctionType deleter = GetDeleter();
 338          * SetDeleter(NoOpDeleter);
 339          * RemoveAll();
 340          * SetDeleter(deleter);
 341          * @endcode
 342          */
 343         void RemoveAll(bool forceDeletion)
 344         {
 345                 DeleterFunctionType deleter = GetDeleter();
 346
 347                 if (forceDeletion)
 348                 {
 349                         SetDeleter(SingleObjectDeleter);
 350                 }
 351                 else
 352                 {
 353                         SetDeleter(NoOpDeleter);
 354                 }
 355
 356                 RemoveAll();
 357                 SetDeleter(deleter);
 358         }
 359
 360         /**
 361          * Removes all the object pointers in the collection. @n
 362          * The %RemoveAll() method can be called before deleting the collection.
 363          *
 364          * @since 2.0
 365          */
 366         virtual void RemoveAll(void) = 0;
 367
 368         /**
 369          * Replaces the specified @c value associated with the specified @c key with a @c newValue.
 370          *
 371          * @since 2.0
 372          *
 373          * @return              An error code
 374          * @param[in]   key                     The key for which the associated value is replaced
 375          * @param[in]   value                   The value associated with the key
 376          * @param[in]   newValue                The new value
 377          * @param[in]   forceDeletion   Set to @c true to deallocate the object, @n
 378          *                                                              else @c false
 379          * @exception   E_SUCCESS               The method is successful.
 380          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 381          *                                                              - A specified input parameter is invalid.
 382          *                                                              - The comparer has failed to compare the keys.
 383          * @exception   E_OBJ_NOT_FOUND The key-value pair has not been found in the map.
 384          * @remarks
 385          *                              - Use the Add(Object*, Object*) method to add a new key-value pair.
 386          *                              - Based on the specified element deleter, the set operation not only gets rid of an element from the list, but also deletes its object instance. @n
 387          *                              The element deleter style is recommended rather than using @c forceDeletetion in the set method. @n
 388          *                              If both the element deleter and the @c forceDeleteion are set, the set operation follows the @c forceDeletion setting.
 389          *                              - SetValue(key, value, newValue, @b true) internally works as the below code:
 390          * @code
 391          * DeleterFunctionType deleter = GetDeleter();
 392          * SetDeleter(SingleObjectDeleter);
 393          * SetValue(key, value, const_cast< Object* >(&newValue));
 394          * SetDeleter(deleter);
 395          * @endcode
 396          *                              - SetValue(key, value, newValue, @b false) internally works as the below code:
 397          * @code
 398          * DeleterFunctionType deleter = GetDeleter();
 399          * SetDeleter(NoOpDeleter);
 400          * SetValue(key, value, const_cast< Object* >(&newValue));
 401          * SetDeleter(deleter);
 402          * @endcode
 403          * @see                 GetValuesN()
 404          */
 405         result SetValue(const Object& key, const Object& value, const Object& newValue, bool forceDeletion = false)
 406         {
 407                 DeleterFunctionType deleter = GetDeleter();
 408
 409                 if (forceDeletion)
 410                 {
 411                         SetDeleter(SingleObjectDeleter);
 412                 }
 413                 else
 414                 {
 415                         SetDeleter(NoOpDeleter);
 416                 }
 417
 418                 result r = SetValue(key, value, const_cast< Object* >(&newValue));
 419                 SetDeleter(deleter);
 420                 return r;
 421         }
 422
 423         /**
 424          * Replaces the specified @c value associated with the specified @c key with a @c pNewValue.
 425          *
 426          * @since 2.0
 427          *
 428          * @return              An error code
 429          * @param[in]   key                             The key for which the associated value is replaced
 430          * @param[in]   value                   The value associated with the key
 431          * @param[in]   pNewValue               A pointer to the new value
 432          * @exception   E_SUCCESS               The method is successful.
 433          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 434          *                                                              - A specified input parameter is invalid.
 435          *                                                              - The comparer has failed to compare the keys.
 436          * @exception   E_OBJ_NOT_FOUND The key-value pair has not been found in the map.
 437          * @remarks             Use the Add(Object*, Object*) method to add a new key-value pair.
 438          * @see                 GetValuesN()
 439          */
 440         virtual result SetValue(const Object& key, const Object& value, Object* pNewValue) = 0;
 441
 442         /**
 443          * @if OSPDEPREC
 444          * Checks whether the map contains the specified key-value pair.
 445          *
 446          * @brief               <i> [Deprecated] </i>
 447          * @deprecated  This method is deprecated because it transfers the result of the comparison in an out-parameter form.
 448          *                              The return type is changed into boolean and this method returns the result.
 449          *                              Instead of using this method, use bool Contains(const Object& key, const Object& value).
 450          * @since 2.0
 451          *
 452          * @return              An error code
 453          * @param[in]   key                     The key to locate
 454          * @param[in]   value                   The value to locate
 455          * @param[out]  out                             Set to @c true if the map contains the specified key-value pair, @n
 456          *                                                              else @c false
 457          * @exception   E_SUCCESS               The method is successful.
 458          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 459          *                                                              - A specified input parameter is invalid.
 460          *                                                              - The comparer has failed to compare the keys.
 461          * @see                 ContainsKey()
 462          * @see                 ContainsValue()
 463          * @endif
 464          */
 465         result Contains(const Object& key, const Object& value, bool& out) const
 466         {
 467                 out = Contains(key, value);
 468                 result r = GetLastResult();
 469                 return r;
 470         }
 471
 472         /**
 473          * Checks whether the map contains the specified key-value pair.
 474          *
 475          * @since 2.0
 476          *
 477          * @return              @c true if the map contains the specified key-value pair, @n
 478          *                              else @c false
 479          * @param[in]   key                     The key to locate
 480          * @param[in]   value                   The value to locate
 481          * @exception   E_SUCCESS               The method is successful.
 482          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 483          *                                                              - A specified input parameter is invalid.
 484          *                                                              - The comparer has failed to compare the keys.
 485          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 486          * @see                 ContainsKey(const Object&) const
 487          * @see                 ContainsValue()
 488          */
 489         virtual bool Contains(const Object& key, const Object& value) const = 0;
 490
 491         /**
 492          * @if OSPDEPREC
 493          * Checks whether the map contains the specified @c key.
 494          *
 495          * @brief               <i> [Deprecated] </i>
 496          * @deprecated  This method is deprecated because it transfers the result of the comparison in an out-parameter form.
 497          *                              The return type is changed into boolean and this method returns the result.
 498          *                              Instead of using this method, use bool ContainsKey(const Object& key).
 499          * @since 2.0
 500          *
 501          * @return              An error code
 502          * @param[in]   key                     The key to locate
 503          * @param[out]  out                             Set to @c true if the map contains the specified key, @n
 504          *                                                              else @c false
 505          * @exception   E_SUCCESS               The method is successful.
 506          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 507          *                                                              - A specified input parameter is invalid.
 508          *                                                              - The comparer has failed to compare the keys.
 509          * @see                 ContainsValue()
 510          * @see                 Contains(const Object&, const Object&)
 511          * @endif
 512          */
 513         result ContainsKey(const Object& key, bool& out) const
 514         {
 515                 out = ContainsKey(key);
 516                 result r = GetLastResult();
 517                 return r;
 518         }
 519
 520         /**
 521          * Checks whether the map contains the specified @c key.
 522          *
 523          * @since 2.0
 524          *
 525          * @return              @c true if the map contains the specified key, @n
 526          *                              else @c false
 527          * @param[in]   key                             The key to locate
 528          * @exception   E_SUCCESS               The method is successful.
 529          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 530          *                                                              - A specified input parameter is invalid.
 531          *                                                              - The comparer has failed to compare the keys.
 532          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 533          * @see                 ContainsValue()
 534          * @see                 Contains(const Object&, const Object&) const
 535          */
 536         virtual bool ContainsKey(const Object& key) const = 0;
 537
 538         /**
 539          * Checks whether the map contains the specified @c value.
 540          *
 541          * @since 2.0
 542          *
 543          * @return              @c true if the map contains the specified value, @n
 544          *                              else @c false
 545          * @param[in]   value   The value to locate
 546          *
 547          * @see                 ContainsKey(const Object&) const
 548          * @see                 Contains(const Object&, const Object&) const
 549          */
 550         virtual bool ContainsValue(const Object& value) const = 0;
 551
 552         /**
 553          * Gets the enumerator of the map.
 554          *
 555          * @since 2.0
 556          *
 557          * @return              An instance of IMapEnumerator for the map, @n
 558          *                              else @c null if an exception occurs
 559          * @exception   E_SUCCESS               The method is successful.
 560          * @remarks
 561          *                              - If a key has multiple values, the enumeration proceeds as follows: @n
 562          *                              {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ...
 563          *                              - The specific error code can be accessed using the GetLastResult() method.
 564          * @see                 IEnumerator
 565          */
 566         virtual IMapEnumerator* GetMapEnumeratorN(void) const = 0;
 567
 568         /**
 569          * Gets the element deleter of the collection.
 570          *
 571          * @since 2.0
 572          *
 573          * @return              A function pointer to the existing element deleter
 574          */
 575         virtual DeleterFunctionType GetDeleter(void) const = 0;
 576
 577 protected:
 578         //
 579         // This method is for internal use only. Using this method can cause behavioral, security-related,
 580         // and consistency-related issues in the application.
 581         // This method is reserved and may change its name at any time without prior notice.
 582         //
 583         // @since 2.0
 584         //
 585         virtual void IMultiMap_Reserved1(void) { }
 586
 587         //
 588         // This method is for internal use only. Using this method can cause behavioral, security-related,
 589         // and consistency-related issues in the application.
 590         // This method is reserved and may change its name at any time without prior notice.
 591         //
 592         // @since 2.0
 593         //
 594         virtual void IMultiMap_Reserved2(void) { }
 595
 596 private:
 597         /**
 598          * Sets the element deleter of the collection.
 599          *
 600          * @since 2.0
 601          *
 602          * @param[in]   deleter A function pointer to the element deleter to set
 603          */
 604         virtual void SetDeleter(DeleterFunctionType deleter) = 0;
 605
 606 }; // IMultiMap
 607
 608 }}} // Tizen::Base::Collection
 609
 610 #endif // _FBASE_COL_IMULTI_MAP_H_