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