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 abstracts a template-based collection of key-value pairs.
  42  * There is no limit on the number of elements with the same key, but duplicated 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           A specified input parameter is invalid, or
  71          *                                                                      the comparer has failed to compare the keys.
  72          * @exception   E_OBJ_ALREADY_EXIST     The specified @c key and @c value already exists.
  73          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
  74          * @see Remove()
  75          */
  76         virtual result Add(const KeyType& key, const ValueType& value) = 0;
  77
  78         /**
  79          * Gets the number of values stored in the map.
  80          *
  81          * @since 2.0
  82          *
  83          * @return      The number of values currently stored in the map
  84          */
  85         virtual int GetCount(void) const = 0;
  86
  87         /**
  88          * Gets the number of values whose key matches the specified key.
  89          *
  90          * @since 2.0
  91          *
  92          * @return              The number of values whose key matches the specified key
  93          * @param[in]   key             The key to locate in the map
  94          * @param[out]  count   The number of values whose key matches the specified key
  95          * @exception   E_SUCCESS                       The method is successful.
  96          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
  97          *                                                                      the comparer has failed to compare the keys.
  98          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found in the map.
  99          */
 100         virtual result GetCount(const KeyType& key, int& count) const = 0;
 101
 102         /**
 103          * Gets an enumerator of the values associated with the specified key.
 104          *
 105          * @since 2.0
 106          *
 107          * @return              An instance of the IEnumeratorT derived class with the values associated with the specified key, @n
 108          *                              else @c null if an exception occurs
 109          * @param[in]   key                             The key to locate
 110          * @exception   E_SUCCESS               The method is successful.
 111          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 112          *                                                              the comparer has failed to compare the keys.
 113          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 114          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 115          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 116          * @see                 SetValue()
 117          */
 118         virtual IEnumeratorT< ValueType >* GetValuesN(const KeyType& key) const = 0;
 119
 120         /**
 121          * Gets a list of all unique keys in the map.
 122          *
 123          * @since 2.0
 124          *
 125          * @return              A pointer to a list of all unique keys in the map, @n
 126          *                              else @c null if an exception occurs
 127          * @exception   E_SUCCESS               The method is successful.
 128          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 129          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 130          * @see                 GetValuesN()
 131          */
 132         virtual IListT< KeyType >* GetKeysN(void) const = 0;
 133
 134         /**
 135          * Gets a list of all the values in the map.
 136          *
 137          * @since 2.0
 138          *
 139          * @return              A pointer to a list of all the values in the map, @n
 140          *                              else @c null if an exception occurs
 141          * @exception   E_SUCCESS               The method is successful.
 142          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 143          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 144          * @see                 GetKeysN()
 145          */
 146         virtual IListT< ValueType >* GetValuesN(void) const = 0;
 147
 148         /**
 149          * Removes all the values associated with the specified key.
 150          *
 151          * @since 2.0
 152          *
 153          * @return              An error code
 154          * @param[in]   key                             The key whose associated values need to remove
 155          * @exception   E_SUCCESS               The method is successful.
 156          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 157          *                                                              the comparer has failed to compare the keys.
 158          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 159          * @see                 Add()
 160          */
 161         virtual result Remove(const KeyType& key) = 0;
 162
 163         /**
 164          * Removes the specified value associated with the specified key. @n
 165          * The key is also removed if there are no more values associated with it.
 166          *
 167          * @since 2.0
 168          *
 169          * @return              An error code
 170          * @param[in]   key             The key whose mapping is to remove from the map
 171          * @param[in]   value   The value to remove
 172          * @exception   E_SUCCESS               The method is successful.
 173          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 174          *                                                              the comparer has failed to compare the keys.
 175          * @exception   E_OBJ_NOT_FOUND The specified @c key and @c value pair is not found in the map.
 176          * @see                 Add()
 177          */
 178         virtual result Remove(const KeyType& key, const ValueType& value) = 0;
 179
 180         /**
 181          * Removes all the key-value pairs in the map.
 182          *
 183          * @since 2.0
 184          */
 185         virtual void RemoveAll(void) = 0;
 186
 187         /**
 188          * Replaces the specified value associated with the specified key with a new value.
 189          *
 190          * @since 2.0
 191          *
 192          * @return              An error code
 193          * @param[in]   key                     The key whose associated value needs to replace
 194          * @param[in]   value           The value associated with the key
 195          * @param[in]   newValue        The new value
 196          * @exception   E_SUCCESS               The method is successful.
 197          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 198          *                                                              the comparer has failed to compare the keys.
 199          * @exception   E_OBJ_NOT_FOUND The specified @c key and @c value pair is not found in the map.
 200          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 201          * @remarks             Use the Add() method to add a new key-value pair.
 202          * @see                 Add()
 203          * @see                 GetValuesN()
 204          */
 205         virtual result SetValue(const KeyType& key, const ValueType& value, const ValueType& newValue) = 0;
 206
 207         /**
 208          * Checks whether the map contains the specified key-value pair.
 209          *
 210          * @since 2.0
 211          *
 212          * @return              An error code
 213          * @param[in]   key             The key to locate
 214          * @param[in]   value   The value to locate
 215          * @param[out]  out             Set to @c true if the map contains the specified key-value pair, @n
 216          *                                              else @c false
 217          * @exception   E_SUCCESS               The method is successful. @n
 218          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 219          *                                                              the comparer has failed to compare the keys.
 220          * @see                 ContainsKey()
 221          * @see                 ContainsValue()
 222          */
 223         virtual result Contains(const KeyType& key, const ValueType& value, bool& out) const = 0;
 224
 225         /**
 226          * Checks whether the map contains the specified key.
 227          *
 228          * @since 2.0
 229          *
 230          * @return              An error code
 231          * @param[in]   key             The key to locate
 232          * @param[out]  out     Set to @c true if the map contains the specified key, @n
 233          *                                              else @c false
 234          * @exception   E_SUCCESS               The method is successful. @n
 235          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 236          *                                                              the comparer has failed to compare the keys.
 237          * @see                 ContainsValue()
 238          * @see                 Contains()
 239          */
 240         virtual result ContainsKey(const KeyType& key, bool& out) const = 0;
 241
 242         /**
 243          * Checks whether the map contains the specified value.
 244          *
 245          * @since 2.0
 246          *
 247          * @return              Set to @c true if the map contains the specified value, @n
 248          *                              else @c false
 249          * @param[in]   value   The value to locate
 250          *
 251          * @see                 ContainsKey()
 252          * @see                 Contains()
 253          */
 254         virtual bool ContainsValue(const ValueType& value) const = 0;
 255
 256         /**
 257          * Gets an enumerator of the map.
 258          *
 259          * @since 2.0
 260          *
 261          * @return              An instance of the IMapEnumeratorT class for the map, @n
 262          *                              else @c null if an exception occurs
 263          * @exception   E_SUCCESS               The method is successful.
 264          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 265          * @remarks             If a key has multiple values, the enumeration proceeds as follows: @n
 266          *                              {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ... @n
 267          *                      The specific error code can be accessed using the GetLastResult() method.
 268          * @see                 Tizen::Base::Collection::IEnumerator
 269          * @see                 Tizen::Base::Collection::IMapEnumerator
 270          */
 271         virtual IMapEnumeratorT< KeyType, ValueType >* GetMapEnumeratorN(void) const = 0;
 272
 273 }; // IMultiMapT
 274
 275 }}} // Tizen::Base::Collection
 276
 277 #endif // _FBASE_COL_IMULTI_MAP_T_H_