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