inc/FBaseColIMapT.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                FBaseColIMapT.h
  19  * @brief               This is the header file for the %IMapT interface.
  20  *
  21  * This header file contains the declarations of the %IMapT interface.
  22  */
  23 #ifndef _FBASE_COL_IMAP_T_H_
  24 #define _FBASE_COL_IMAP_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 IMapT
  38  * @brief       This interface abstracts a template-based collection of key-value pairs.
  39  *
  40  * @since 2.0
  41  *
  42  * The %IMapT interface abstracts a template-based collection of key-value pairs. An %IMapT
  43  * contains unique keys and each key maps to a single value.
  44  * The key and value cannot be a @c null reference.
  45  *
  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 IMapT
  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 ~IMapT(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 already exists.
  74          * @see Remove()
  75          */
  76         virtual result Add(const KeyType& key, const ValueType& value) = 0;
  77
  78         /**
  79          * Gets the value associated with the specified @c key.
  80          *
  81          * @since 2.0
  82          *
  83          * @return              The value associated with the specified @c key, @n
  84          *                              else @c null if an exception occurs
  85          * @param[in]   key             The key to find the associated value
  86          * @param[out]  value   The value associated with the key
  87          * @exception   E_SUCCESS               The method is successful.
  88          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
  89          *                                                              the comparer has failed to compare the keys.
  90          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
  91          * @see                 SetValue()
  92          */
  93         virtual result GetValue(const KeyType& key, ValueType& value) const = 0;
  94
  95         /**
  96          * Gets the value associated with the specified @c key.
  97          *
  98          * @since 2.0
  99          *
 100          * @return              An error code
 101          * @param[in]   key             The key to find the associated value
 102          * @param[out]  value   The value associated with the key
 103          * @exception   E_SUCCESS               The method is successful.
 104          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 105          *                                                              the comparer has failed to compare the keys.
 106          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 107          * @see                 SetValue()
 108          */
 109         virtual result GetValue(const KeyType& key, ValueType& value) = 0;
 110
 111         /**
 112          * Gets a list of all the keys in the map.
 113          *
 114          * @since 2.0
 115          *
 116          * @return              A pointer to a list of all the keys in the map, @n
 117          *                              else @c null if an exception occurs
 118          * @exception   E_SUCCESS               The method is successful.
 119          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 120          * @remarks             The order of the keys is the same as the corresponding values in the IListT interface returned by the GetValuesN() method.
 121          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 122          * @see                 GetValuesN()
 123          */
 124         virtual IListT< KeyType >* GetKeysN(void) const = 0;
 125
 126         /**
 127          * Gets a list of all the values in the map.
 128          *
 129          * @since 2.0
 130          *
 131          * @return              A pointer to a list of all values in the map, @n
 132          *                              else @c null if an exception occurs
 133          * @exception   E_SUCCESS               The method is successful.
 134          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 135          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 136          * @see                 GetKeysN()
 137          */
 138         virtual IListT< ValueType >* GetValuesN(void) const = 0;
 139
 140         /**
 141          * Removes the value associated with the specified @c key.
 142          *
 143          * @since 2.0
 144          *
 145          * @return              An error code
 146          * @param[in]   key The key for which the value is to remove
 147          * @exception   E_SUCCESS               The method is successful.
 148          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 149          *                                                              the comparer has failed to compare the keys.
 150          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 151          * @see                 Add()
 152          */
 153         virtual result Remove(const KeyType& key) = 0;
 154
 155         /**
 156          * Removes all key-value pairs in the map.
 157          *
 158          * @since 2.0
 159          */
 160         virtual void RemoveAll(void) = 0;
 161
 162         /**
 163          * Replaces the value associated with the specified @c key with the specified @c value.
 164          *
 165          * @since 2.0
 166          *
 167          * @return              An error code
 168          * @param[in]   key             The key whose value is to replace
 169          * @param[in]   value   The new value
 170          * @exception   E_SUCCESS               The method is successful.
 171          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 172          *                                                              the comparer has failed to compare the keys.
 173          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
 174          * @remarks             Use the Add() method to add a new key-value pair.
 175          * @see                 Add()
 176          * @see                 GetValue()
 177          */
 178         virtual result SetValue(const KeyType& key, const ValueType& value) = 0;
 179
 180         /**
 181          * Checks whether the map contains the specified @c key.
 182          *
 183          * @since 2.0
 184          *
 185          * @return              An error code
 186          * @param[in]   key             The key to locate
 187          * @param[out]  out     Set to @c true if the map contains the specified @c key, @n
 188          *                                              else @c false
 189          * @exception   E_SUCCESS               The method is successful, or
 190          *                                                              the map contains the specified @c key.
 191          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
 192          *                                                              the comparer has failed to compare the keys.
 193          * @see                 ContainsValue()
 194          */
 195         virtual result ContainsKey(const KeyType& key, bool& out) const = 0;
 196
 197         /**
 198          * Checks whether the map contains the specified @c value.
 199          *
 200          * @since 2.0
 201          *
 202          * @return              @c true if the map contains the specified @c value, @n
 203          *                              else @c false
 204          * @param[in]   value   The value to locate
 205          *
 206          * @see                 ContainsKey()
 207          */
 208         virtual bool ContainsValue(const ValueType& value) const = 0;
 209
 210         /**
 211          * Gets an instance of the IMapEnumeratorT class for the map.
 212          *
 213          * @since 2.0
 214          *
 215          * @return              An object of this map, @n
 216          *                              else @c null if an exception occurs
 217          * @exception   E_SUCCESS               The method is successful.
 218          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 219          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 220          * @see                 Tizen::Base::Collection::IEnumerator
 221          * @see                 Tizen::Base::Collection::IMapEnumerator
 222          */
 223         virtual IMapEnumeratorT< KeyType, ValueType >* GetMapEnumeratorN(void) const = 0;
 224
 225 }; // IMapT
 226
 227 }}} // Tizen::Base::Collection
 228
 229 #endif // _FBASE_COL_IMAP_T_H_