2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file FBaseColIMapT.h
19 * @brief This is the header file for the %IMapT interface.
21 * This header file contains the declarations of the %IMapT interface.
23 #ifndef _FBASE_COL_IMAP_T_H_
24 #define _FBASE_COL_IMAP_T_H_
26 #include <FBaseColICollectionT.h>
27 #include <FBaseColIMapEnumeratorT.h>
28 #include <FBaseColMapEntryT.h>
30 namespace Tizen { namespace Base { namespace Collection
33 template< class Type > class IListT;
37 * @brief This interface represents a template-based collection of key-value pairs.
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.
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>.
48 template< class KeyType, class ValueType >
50 : public virtual ICollectionT< MapEntryT< KeyType, ValueType > >
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.
59 virtual ~IMapT(void) {}
62 * Adds the specified key-value pair to the map.
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.
76 virtual result Add(const KeyType& key, const ValueType& value) = 0;
79 * Gets the value associated to the specified @c key.
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.
94 virtual result GetValue(const KeyType& key, ValueType& value) const = 0;
97 * Gets the value associated to the specified @c key.
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.
111 virtual result GetValue(const KeyType& key, ValueType& value) = 0;
114 * Gets the list of all the keys in the map.
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.
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.
126 virtual IListT< KeyType >* GetKeysN(void) const = 0;
129 * Gets the list of all the values in the map.
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.
140 virtual IListT< ValueType >* GetValuesN(void) const = 0;
143 * Removes the value associated to the specified @c key.
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.
156 virtual result Remove(const KeyType& key) = 0;
159 * Removes all the key-value pairs in the map.
163 virtual void RemoveAll(void) = 0;
166 * Replaces the value associated to the specified @c key with the specified @c value.
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.
181 virtual result SetValue(const KeyType& key, const ValueType& value) = 0;
184 * Checks whether the map contains the specified @c key.
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()
199 virtual result ContainsKey(const KeyType& key, bool& out) const = 0;
202 * Checks whether the map contains the specified @c value.
206 * @return @c true if the map contains the specified value, @n
208 * @param[in] value The value to locate
212 virtual bool ContainsValue(const ValueType& value) const = 0;
215 * Gets an instance of IMapEnumeratorT for the map.
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
227 virtual IMapEnumeratorT< KeyType, ValueType >* GetMapEnumeratorN(void) const = 0;
231 }}} // Tizen::Base::Collection
233 #endif // _FBASE_COL_IMAP_T_H_