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 unique keys in the map.
 124          *
 125          * @since 2.0
 126          *
 127          * @return              A pointer to a list of all unique 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 specific error code can be accessed using the GetLastResult() method.
 132          * @see                 GetValuesN()
 133          */
 134         virtual IListT< KeyType >* GetKeysN(void) const = 0;
 135
 136         /**
 137          * Gets a list of all the values in the map.
 138          *
 139          * @since 2.0
 140          *
 141          * @return              A pointer to a list of all the values in the map, @n
 142          *                              else @c null if an exception occurs
 143          * @exception   E_SUCCESS               The method is successful.
 144          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 145          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 146          * @see                 GetKeysN()
 147          */
 148         virtual IListT< ValueType >* GetValuesN(void) const = 0;
 149
 150         /**
 151          * Removes all the values associated with the specified key.
 152          *
 153          * @since 2.0
 154          *
 155          * @return              An error code
 156          * @param[in]   key The key whose associated values need to remove
 157          * @exception   E_SUCCESS               The method is successful.
 158          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 159          *                                                              the comparer has failed to compare the keys.
 160          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 161          * @see                 Add()
 162          */
 163         virtual result Remove(const KeyType& key) = 0;
 164
 165         /**
 166          * Removes the specified value associated with the specified key. @n
 167          * The key is also removed if there are no more values associated with it.
 168          *
 169          * @since 2.0
 170          *
 171          * @return              An error code
 172          * @param[in]   key     The key whose mapping is to remove from the map
 173          * @param[in]   value   The value to remove
 174          * @exception   E_SUCCESS               The method is successful.
 175          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 176          *                                                              the comparer has failed to compare the keys.
 177          * @exception   E_OBJ_NOT_FOUND The specified @c key and @c value pair is not found in the map.
 178          * @see                 Add()
 179          */
 180         virtual result Remove(const KeyType& key, const ValueType& value) = 0;
 181
 182         /**
 183          * Removes all the key-value pairs in the map.
 184          *
 185          * @since 2.0
 186          */
 187         virtual void RemoveAll(void) = 0;
 188
 189         /**
 190          * Replaces the specified value associated with the specified key with a new value.
 191          *
 192          * @since 2.0
 193          *
 194          * @return              An error code
 195          * @param[in]   key                     The key whose associated value needs to replace
 196          * @param[in]   value           The value associated with the key
 197          * @param[in]   newValue        The new value
 198          * @exception   E_SUCCESS               The method is successful.
 199          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 200          *                                                              the comparer has failed to compare the keys.
 201          * @exception   E_OBJ_NOT_FOUND The specified @c key and @c value pair is not found in the map.
 202          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 203          * @remarks             Use the Add() method to add a new key-value pair.
 204          * @see                 Add()
 205          * @see                 GetValuesN()
 206          */
 207         virtual result SetValue(const KeyType& key, const ValueType& value, const ValueType& newValue) = 0;
 208
 209         /**
 210          * Checks whether the map contains the specified key-value pair.
 211          *
 212          * @since 2.0
 213          *
 214          * @return              An error code
 215          * @param[in]   key             The key to locate
 216          * @param[in]   value   The value to locate
 217          * @param[out]  out             Set to @c true if the map contains the specified key-value pair, @n
 218          *                                              else @c false
 219          * @exception   E_SUCCESS               The method is successful. @n
 220          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 221          *                                                              the comparer has failed to compare the keys.
 222          * @see                 ContainsKey()
 223          * @see                 ContainsValue()
 224          */
 225         virtual result Contains(const KeyType& key, const ValueType& value, bool& out) const = 0;
 226
 227         /**
 228          * Checks whether the map contains the specified key.
 229          *
 230          * @since 2.0
 231          *
 232          * @return              An error code
 233          * @param[in]   key             The key to locate
 234          * @param[out]  out     Set to @c true if the map contains the specified key, @n
 235          *                                              else @c false
 236          * @exception   E_SUCCESS               The method is successful. @n
 237          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 238          *                                                              the comparer has failed to compare the keys.
 239          * @see                 ContainsValue()
 240          * @see                 Contains()
 241          */
 242         virtual result ContainsKey(const KeyType& key, bool& out) const = 0;
 243
 244         /**
 245          * Checks whether the map contains the specified value.
 246          *
 247          * @since 2.0
 248          *
 249          * @return              Set to @c true if the map contains the specified value, @n
 250          *                              else @c false
 251          * @param[in]   value   The value to locate
 252          *
 253          * @see                 ContainsKey()
 254          * @see                 Contains()
 255          */
 256         virtual bool ContainsValue(const ValueType& value) const = 0;
 257
 258         /**
 259          * Gets an enumerator of the map.
 260          *
 261          * @since 2.0
 262          *
 263          * @return              An instance of the IMapEnumeratorT class for the map, @n
 264          *                              else @c null if an exception occurs
 265          * @exception   E_SUCCESS               The method is successful.
 266          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 267          * @remarks             If a key has multiple values, the enumeration proceeds as follows: @n
 268          *                              {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ... @n
 269          *                      The specific error code can be accessed using the GetLastResult() method.
 270          * @see                 Tizen::Base::Collection::IEnumerator
 271          * @see                 Tizen::Base::Collection::IMapEnumerator
 272          */
 273         virtual IMapEnumeratorT< KeyType, ValueType >* GetMapEnumeratorN(void) const = 0;
 274
 275 }; // IMultiMapT
 276
 277 }}} // Tizen::Base::Collection
 278
 279 #endif // _FBASE_COL_IMULTI_MAP_T_H_