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