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