inc/FBaseColIMultiMapT.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 // http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FBaseColIMultiMapT.h
  20  * @brief               This is the header file for the %IMultiMapT interface.
  21  *
  22  * This header file contains the declarations of the %IMultiMapT interface.
  23  */
  24 #ifndef _FBASE_COL_IMULTI_MAP_T_H_
  25 #define _FBASE_COL_IMULTI_MAP_T_H_
  26
  27 #include <FBaseColICollectionT.h>
  28 #include <FBaseColIMapEnumeratorT.h>
  29 #include <FBaseColMapEntryT.h>
  30
  31
  32 namespace Tizen { namespace Base { namespace Collection
  33 {
  34
  35 template< class Type > class IListT;
  36
  37 /**
  38  * @interface IMultiMapT
  39  * @brief       This interface represents a template-based collection of key-value pairs.
  40  *
  41  * @since 2.0
  42  *
  43  * The %IMultiMapT interface abstracts a template-based collection of key-value pairs.
  44  * There is no limit on the number of elements with the same key, but duplicated 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 template< class KeyType, class ValueType >
  51 class IMultiMapT
  52         : public virtual ICollectionT< MapEntryT< KeyType, ValueType > >
  53 {
  54 public:
  55         /**
  56          * This polymorphic destructor should be overridden if required. @n
  57          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
  58          *
  59          * @since 2.0
  60          */
  61         virtual ~IMultiMapT(void) {}
  62
  63         /**
  64          * Adds the specified key-value pair to the map.
  65          *
  66          * @since 2.0
  67          *
  68          * @return              An error code
  69          * @param[in]   key             The key to add
  70          * @param[in]   value   The corresponding value to add
  71          * @exception   E_SUCCESS                       The method is successful.
  72          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
  73          *                                                                      the comparer has failed to compare the keys.
  74          * @exception   E_OBJ_ALREADY_EXIST     The specified @c key and @c value already exists.
  75          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
  76          * @see Remove()
  77          */
  78         virtual result Add(const KeyType& key, const ValueType& value) = 0;
  79
  80         /**
  81          * Gets the number of values stored in the map.
  82          *
  83          * @since 2.0
  84          *
  85          * @return      The number of values currently stored in the map
  86          */
  87         virtual int GetCount(void) const = 0;
  88
  89         /**
  90          * Gets the number of values whose key matches the specified key.
  91          *
  92          * @since 2.0
  93          *
  94          * @return              The number of values whose key matches the specified key
  95          * @param[in]   key     The key to locate in the map
  96          * @param[out]  count   The number of values whose key matches the specified key
  97          * @exception   E_SUCCESS                       The method is successful.
  98          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
  99          *                                                                      the comparer has failed to compare the keys.
 100          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found in the map.
 101          */
 102         virtual result GetCount(const KeyType& key, int& count) const = 0;
 103
 104         /**
 105          * Gets an enumerator of the values associated with the specified key.
 106          *
 107          * @since 2.0
 108          *
 109          * @return              An instance of the IEnumeratorT derived class with 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   A specified input parameter is invalid, or
 114          *                                                              the comparer has failed to compare the keys.
 115          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 116          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 117          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 118          * @see                 SetValue()
 119          */
 120         virtual IEnumeratorT< ValueType >* GetValuesN(const KeyType& key) const = 0;
 121
 122         /**
 123          * Gets a list of all the keys in the map.
 124          *
 125          * @since 2.0
 126          *
 127          * @return              A pointer to a list of all the keys in the map, @n
 128          *                              else @c null if an exception occurs
 129          * @exception   E_SUCCESS               The method is successful.
 130          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 131          * @remarks             The order of the keys is the same as the corresponding values in the IListT interface returned by the GetValuesN() method.
 132          *              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 a list of all the values in the map.
 139          *
 140          * @since 2.0
 141          *
 142          * @return              A pointer to a 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 key.
 153          *
 154          * @since 2.0
 155          *
 156          * @return              An error code
 157          * @param[in]   key The key whose associated values need to remove
 158          * @exception   E_SUCCESS               The method is successful.
 159          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 160          *                                                              the comparer has failed to compare the keys.
 161          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 162          * @see                 Add()
 163          */
 164         virtual result Remove(const KeyType& key) = 0;
 165
 166         /**
 167          * Removes the specified value associated with the specified key. @n
 168          * The key is also removed if there are no more values associated with it.
 169          *
 170          * @since 2.0
 171          *
 172          * @return              An error code
 173          * @param[in]   key     The key whose mapping is to remove from the map
 174          * @param[in]   value   The value to remove
 175          * @exception   E_SUCCESS               The method is successful.
 176          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 177          *                                                              the comparer has failed to compare the keys.
 178          * @exception   E_OBJ_NOT_FOUND The specified @c key and @c value pair is not found in the map.
 179          * @see                 Add()
 180          */
 181         virtual result Remove(const KeyType& key, const ValueType& value) = 0;
 182
 183         /**
 184          * Removes all the key-value pairs in the map.
 185          *
 186          * @since 2.0
 187          */
 188         virtual void RemoveAll(void) = 0;
 189
 190         /**
 191          * Replaces the specified value associated with the specified key with a new value.
 192          *
 193          * @since 2.0
 194          *
 195          * @return              An error code
 196          * @param[in]   key                     The key whose associated value needs to replace
 197          * @param[in]   value           The value associated with the key
 198          * @param[in]   newValue        The new value
 199          * @exception   E_SUCCESS               The method is successful.
 200          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 201          *                                                              the comparer has failed to compare the keys.
 202          * @exception   E_OBJ_NOT_FOUND The specified @c key and @c value pair is not found in the map.
 203          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 204          * @remarks             Use the Add() method to add a new key-value pair.
 205          * @see                 Add()
 206          * @see                 GetValuesN()
 207          */
 208         virtual result SetValue(const KeyType& key, const ValueType& value, const ValueType& newValue) = 0;
 209
 210         /**
 211          * Checks whether the map contains the specified key-value pair.
 212          *
 213          * @since 2.0
 214          *
 215          * @return              An error code
 216          * @param[in]   key             The key to locate
 217          * @param[in]   value   The value to locate
 218          * @param[out]  out             Set to @c true if the map contains the specified key-value pair, @n
 219          *                                              else @c false
 220          * @exception   E_SUCCESS               The method is successful. @n
 221          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 222          *                                                              the comparer has failed to compare the keys.
 223          * @see                 ContainsKey()
 224          * @see                 ContainsValue()
 225          */
 226         virtual result Contains(const KeyType& key, const ValueType& value, bool& out) const = 0;
 227
 228         /**
 229          * Checks whether the map contains the specified key.
 230          *
 231          * @since 2.0
 232          *
 233          * @return              An error code
 234          * @param[in]   key             The key to locate
 235          * @param[out]  out     Set to @c true if the map contains the specified key, @n
 236          *                                              else @c false
 237          * @exception   E_SUCCESS               The method is successful. @n
 238          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 239          *                                                              the comparer has failed to compare the keys.
 240          * @see                 ContainsValue()
 241          * @see                 Contains()
 242          */
 243         virtual result ContainsKey(const KeyType& key, bool& out) const = 0;
 244
 245         /**
 246          * Checks whether the map contains the specified value.
 247          *
 248          * @since 2.0
 249          *
 250          * @return              Set to @c true if the map contains the specified value, @n
 251          *                              else @c false
 252          * @param[in]   value   The value to locate
 253          *
 254          * @see                 ContainsKey()
 255          * @see                 Contains()
 256          */
 257         virtual bool ContainsValue(const ValueType& value) const = 0;
 258
 259         /**
 260          * Gets an enumerator of the map.
 261          *
 262          * @since 2.0
 263          *
 264          * @return              An instance of the IMapEnumeratorT class for the map, @n
 265          *                              else @c null if an exception occurs
 266          * @exception   E_SUCCESS               The method is successful.
 267          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 268          * @remarks             If a key has multiple values, the enumeration proceeds as follows: @n
 269          *                              {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ... @n
 270          *                      The specific error code can be accessed using the GetLastResult() method.
 271          * @see                 Tizen::Base::Collection::IEnumerator
 272          * @see                 Tizen::Base::Collection::IMapEnumerator
 273          */
 274         virtual IMapEnumeratorT< KeyType, ValueType >* GetMapEnumeratorN(void) const = 0;
 275
 276 }; // IMultiMapT
 277
 278 }}} // Tizen::Base::Collection
 279
 280 #endif // _FBASE_COL_IMULTI_MAP_T_H_