inc/FBaseColIMultiMapT.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                FBaseColIMultiMapT.h
  19  * @brief               This is the header file for the %IMultiMapT interface.
  20  *
  21  * This header file contains the declarations of the %IMultiMapT interface.
  22  */
  23 #ifndef _FBASE_COL_IMULTI_MAP_T_H_
  24 #define _FBASE_COL_IMULTI_MAP_T_H_
  25
  26 #include <FBaseColICollectionT.h>
  27 #include <FBaseColIMapEnumeratorT.h>
  28 #include <FBaseColMapEntryT.h>
  29
  30 namespace Tizen { namespace Base { namespace Collection
  31 {
  32
  33 template< class Type > class IListT;
  34
  35 /**
  36  * @interface   IMultiMapT
  37  * @brief               This interface represents a template-based collection of key-value pairs.
  38  *
  39  * @since 2.0
  40  *
  41  * The %IMultiMapT interface represents a template-based collection of key-value pairs.
  42  * There is no limit on the number of elements having the same key, but duplicate elements with the same key are not allowed.
  43  * The key and value cannot be a @c null reference.
  44  * @n
  45  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/hashmap_multihashmap.htm">HashMap and MultiHashMap</a>.
  46  *
  47  */
  48 template< class KeyType, class ValueType >
  49 class IMultiMapT
  50         : public virtual ICollectionT< MapEntryT< KeyType, ValueType > >
  51 {
  52 public:
  53         /**
  54          * This polymorphic destructor should be overridden if required. @n
  55          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
  56          *
  57          * @since 2.0
  58          */
  59         virtual ~IMultiMapT(void) {}
  60
  61         /**
  62          * Adds the specified key-value pair to the map.
  63          *
  64          * @since 2.0
  65          *
  66          * @return              An error code
  67          * @param[in]   key                                     The key to add
  68          * @param[in]   value                           The corresponding value to add
  69          * @exception   E_SUCCESS                       The method is successful.
  70          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
  71          *                                                                      - A specified input parameter is invalid.
  72          *                                                                      - The comparer has failed to compare the keys.
  73          * @exception   E_OBJ_ALREADY_EXIST     The specified @c key and the specified @c value already exists.
  74          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
  75          * @see Remove()
  76          */
  77         virtual result Add(const KeyType& key, const ValueType& value) = 0;
  78
  79         /**
  80          * Gets the number of values stored in the map.
  81          *
  82          * @since 2.0
  83          *
  84          * @return      The number of values currently stored in the map
  85          */
  86         virtual int GetCount(void) const = 0;
  87
  88         /**
  89          * Gets the number of values whose key matches the specified @c key.
  90          *
  91          * @since 2.0
  92          *
  93          * @return              The number of values whose key matches the specified key
  94          * @param[in]   key                                     The key to locate in the map
  95          * @param[out]  count                           The number of values whose key matches the specified key
  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_NOT_FOUND         The specified @c key has not been found in the map.
 101          */
 102         virtual result GetCount(const KeyType& key, int& count) const = 0;
 103
 104         /**
 105          * Gets the enumerator of the values associated with the specified @c key.
 106          *
 107          * @since 2.0
 108          *
 109          * @return              An instance of the IEnumeratorT derived class that contains the values associated with the specified key, @n
 110          *                              else @c null if an exception occurs
 111          * @param[in]   key                             The key to locate
 112          * @exception   E_SUCCESS               The method is successful.
 113          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 114          *                                                              - A specified input parameter is invalid.
 115          *                                                              - The comparer has failed to compare the keys.
 116          * @exception   E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
 117          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 118          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 119          * @see                 SetValue()
 120          */
 121         virtual IEnumeratorT< ValueType >* GetValuesN(const KeyType& key) const = 0;
 122
 123         /**
 124          * Gets the list of all the unique keys in the map.
 125          *
 126          * @since 2.0
 127          *
 128          * @return              A pointer to the list of all the unique keys in the map, @n
 129          *                              else @c null if an exception occurs
 130          * @exception   E_SUCCESS               The method is successful.
 131          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 132          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 133          * @see                 GetValuesN()
 134          */
 135         virtual IListT< KeyType >* GetKeysN(void) const = 0;
 136
 137         /**
 138          * Gets the list of all the values in the map.
 139          *
 140          * @since 2.0
 141          *
 142          * @return              A pointer to the list of all the values in the map, @n
 143          *                              else @c null if an exception occurs
 144          * @exception   E_SUCCESS               The method is successful.
 145          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 146          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 147          * @see                 GetKeysN()
 148          */
 149         virtual IListT< ValueType >* GetValuesN(void) const = 0;
 150
 151         /**
 152          * Removes all the values associated with the specified @c key.
 153          *
 154          * @since 2.0
 155          *
 156          * @return              An error code
 157          * @param[in]   key                             The key whose associated values are removed
 158          * @exception   E_SUCCESS               The method is successful.
 159          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 160          *                                                              - A specified input parameter is invalid.
 161          *                                                              - The comparer has failed to compare the keys.
 162          * @exception   E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
 163          * @see                 Add()
 164          */
 165         virtual result Remove(const KeyType& key) = 0;
 166
 167         /**
 168          * Removes the specified value associated with the specified key. @n
 169          * The key is also removed if there are no more values associated with it.
 170          *
 171          * @since 2.0
 172          *
 173          * @return              An error code
 174          * @param[in]   key                             The key whose mapping is removed from the map
 175          * @param[in]   value                   The value to remove
 176          * @exception   E_SUCCESS               The method is successful.
 177          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 178          *                                                              - A specified input parameter is invalid.
 179          *                                                              - The comparer has failed to compare the keys.
 180          * @exception   E_OBJ_NOT_FOUND The specified @c key and the specified @c value pair has not been found in the map.
 181          * @see                 Add()
 182          */
 183         virtual result Remove(const KeyType& key, const ValueType& value) = 0;
 184
 185         /**
 186          * Removes all the key-value pairs in the map.
 187          *
 188          * @since 2.0
 189          */
 190         virtual void RemoveAll(void) = 0;
 191
 192         /**
 193          * Replaces the specified @c value associated with the specified @c key with a @c newValue.
 194          *
 195          * @since 2.0
 196          *
 197          * @return              An error code
 198          * @param[in]   key                             The key whose associated value is replaced
 199          * @param[in]   value                   The value associated with the key
 200          * @param[in]   newValue                The new value
 201          * @exception   E_SUCCESS               The method is successful.
 202          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 203          *                                                              - A specified input parameter is invalid.
 204          *                                                              - The comparer has failed to compare the keys.
 205          * @exception   E_OBJ_NOT_FOUND The specified @c key and the specified @c value pair has not been found in the map.
 206          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 207          * @remarks             Use the Add() method to add a new key-value pair.
 208          * @see                 Add()
 209          * @see                 GetValuesN()
 210          */
 211         virtual result SetValue(const KeyType& key, const ValueType& value, const ValueType& newValue) = 0;
 212
 213         /**
 214          * Checks whether the map contains the specified key-value pair.
 215          *
 216          * @since 2.0
 217          *
 218          * @return              An error code
 219          * @param[in]   key                             The key to locate
 220          * @param[in]   value                   The value to locate
 221          * @param[out]  out                             Set to @c true if the map contains the specified key-value pair, @n
 222          *                                                              else @c false
 223          * @exception   E_SUCCESS               The method is successful.
 224          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 225          *                                                              - A specified input parameter is invalid.
 226          *                                                              - The comparer has failed to compare the keys.
 227          * @see                 ContainsKey()
 228          * @see                 ContainsValue()
 229          */
 230         virtual result Contains(const KeyType& key, const ValueType& value, bool& out) const = 0;
 231
 232         /**
 233          * Checks whether the map contains the specified @c key.
 234          *
 235          * @since 2.0
 236          *
 237          * @return              An error code
 238          * @param[in]   key                             The key to locate
 239          * @param[out]  out                     Set to @c true if the map contains the specified key, @n
 240          *                                                              else @c false
 241          * @exception   E_SUCCESS               The method is successful.
 242          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 243          *                                                              - A specified input parameter is invalid.
 244          *                                                              - The comparer has failed to compare the keys.
 245          * @see                 ContainsValue()
 246          * @see                 Contains()
 247          */
 248         virtual result ContainsKey(const KeyType& key, bool& out) const = 0;
 249
 250         /**
 251          * Checks whether the map contains the specified @c value.
 252          *
 253          * @since 2.0
 254          *
 255          * @return              Set to @c true if the map contains the specified value, @n
 256          *                              else @c false
 257          * @param[in]   value   The value to locate
 258          *
 259          * @see                 ContainsKey()
 260          * @see                 Contains()
 261          */
 262         virtual bool ContainsValue(const ValueType& value) const = 0;
 263
 264         /**
 265          * Gets the enumerator of the map.
 266          *
 267          * @since 2.0
 268          *
 269          * @return              An instance of IMapEnumeratorT for the map, @n
 270          *                              else @c null if an exception occurs
 271          * @exception   E_SUCCESS               The method is successful.
 272          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 273          * @remarks
 274          *                              - If a key has multiple values, the enumeration proceeds as follows: @n
 275          *                              {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ...
 276          *                              - The specific error code can be accessed using the GetLastResult() method.
 277          * @see                 Tizen::Base::Collection::IEnumerator
 278          * @see                 Tizen::Base::Collection::IMapEnumerator
 279          */
 280         virtual IMapEnumeratorT< KeyType, ValueType >* GetMapEnumeratorN(void) const = 0;
 281
 282 }; // IMultiMapT
 283
 284 }}} // Tizen::Base::Collection
 285
 286 #endif // _FBASE_COL_IMULTI_MAP_T_H_