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 FBaseColIMultiMapT.h
19 * @brief This is the header file for the %IMultiMapT interface.
21 * This header file contains the declarations of the %IMultiMapT interface.
23 #ifndef _FBASE_COL_IMULTI_MAP_T_H_
24 #define _FBASE_COL_IMULTI_MAP_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;
36 * @interface IMultiMapT
37 * @brief This interface represents a template-based collection of key-value pairs.
41 * The %IMultiMapT interface represents a template-based collection of key-value pairs.
42 * There is no limit on the number of elements having the same key, but duplicate elements with the same key are not allowed.
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 ~IMultiMapT(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 and the specified @c value already exists.
74 * @exception E_OUT_OF_MEMORY The memory is insufficient.
77 virtual result Add(const KeyType& key, const ValueType& value) = 0;
80 * Gets the number of values stored in the map.
84 * @return The number of values currently stored in the map
86 virtual int GetCount(void) const = 0;
89 * Gets the number of values whose key matches the specified @c key.
93 * @return The number of values whose key matches the specified key
94 * @param[in] key The key to locate in the map
95 * @param[out] count The number of values whose key matches the specified key
96 * @exception E_SUCCESS The method is successful.
97 * @exception E_INVALID_ARG Either of the following conditions has occurred:
98 * - A specified input parameter is invalid.
99 * - The comparer has failed to compare the keys.
100 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
102 virtual result GetCount(const KeyType& key, int& count) const = 0;
105 * Gets the enumerator of the values associated with the specified @c key.
109 * @return An instance of the IEnumeratorT derived class that contains the values associated with the specified key, @n
110 * else @c null if an exception occurs
111 * @param[in] key The key to locate
112 * @exception E_SUCCESS The method is successful.
113 * @exception E_INVALID_ARG Either of the following conditions has occurred:
114 * - A specified input parameter is invalid.
115 * - The comparer has failed to compare the keys.
116 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
117 * @exception E_OUT_OF_MEMORY The memory is insufficient.
118 * @remarks The specific error code can be accessed using the GetLastResult() method.
121 virtual IEnumeratorT< ValueType >* GetValuesN(const KeyType& key) const = 0;
124 * Gets the list of all the unique keys in the map.
128 * @return A pointer to the list of all the unique keys in the map, @n
129 * else @c null if an exception occurs
130 * @exception E_SUCCESS The method is successful.
131 * @exception E_OUT_OF_MEMORY The memory is insufficient.
132 * @remarks The specific error code can be accessed using the GetLastResult() method.
135 virtual IListT< KeyType >* GetKeysN(void) const = 0;
138 * Gets the list of all the values in the map.
142 * @return A pointer to the list of all the values in the map, @n
143 * else @c null if an exception occurs
144 * @exception E_SUCCESS The method is successful.
145 * @exception E_OUT_OF_MEMORY The memory is insufficient.
146 * @remarks The specific error code can be accessed using the GetLastResult() method.
149 virtual IListT< ValueType >* GetValuesN(void) const = 0;
152 * Removes all the values associated with the specified @c key.
156 * @return An error code
157 * @param[in] key The key whose associated values are removed
158 * @exception E_SUCCESS The method is successful.
159 * @exception E_INVALID_ARG Either of the following conditions has occurred:
160 * - A specified input parameter is invalid.
161 * - The comparer has failed to compare the keys.
162 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
165 virtual result Remove(const KeyType& key) = 0;
168 * Removes the specified value associated with the specified key. @n
169 * The key is also removed if there are no more values associated with it.
173 * @return An error code
174 * @param[in] key The key whose mapping is removed from the map
175 * @param[in] value The value to remove
176 * @exception E_SUCCESS The method is successful.
177 * @exception E_INVALID_ARG Either of the following conditions has occurred:
178 * - A specified input parameter is invalid.
179 * - The comparer has failed to compare the keys.
180 * @exception E_OBJ_NOT_FOUND The specified @c key and the specified @c value pair has not been found in the map.
183 virtual result Remove(const KeyType& key, const ValueType& value) = 0;
186 * Removes all the key-value pairs in the map.
190 virtual void RemoveAll(void) = 0;
193 * Replaces the specified @c value associated with the specified @c key with a @c newValue.
197 * @return An error code
198 * @param[in] key The key whose associated value is replaced
199 * @param[in] value The value associated with the key
200 * @param[in] newValue The new value
201 * @exception E_SUCCESS The method is successful.
202 * @exception E_INVALID_ARG Either of the following conditions has occurred:
203 * - A specified input parameter is invalid.
204 * - The comparer has failed to compare the keys.
205 * @exception E_OBJ_NOT_FOUND The specified @c key and the specified @c value pair has not been found in the map.
206 * @exception E_OUT_OF_MEMORY The memory is insufficient.
207 * @remarks Use the Add() method to add a new key-value pair.
211 virtual result SetValue(const KeyType& key, const ValueType& value, const ValueType& newValue) = 0;
214 * Checks whether the map contains the specified key-value pair.
218 * @return An error code
219 * @param[in] key The key to locate
220 * @param[in] value The value to locate
221 * @param[out] out Set to @c true if the map contains the specified key-value pair, @n
223 * @exception E_SUCCESS The method is successful.
224 * @exception E_INVALID_ARG Either of the following conditions has occurred:
225 * - A specified input parameter is invalid.
226 * - The comparer has failed to compare the keys.
228 * @see ContainsValue()
230 virtual result Contains(const KeyType& key, const ValueType& value, bool& out) const = 0;
233 * Checks whether the map contains the specified @c key.
237 * @return An error code
238 * @param[in] key The key to locate
239 * @param[out] out Set to @c true if the map contains the specified key, @n
241 * @exception E_SUCCESS The method is successful.
242 * @exception E_INVALID_ARG Either of the following conditions has occurred:
243 * - A specified input parameter is invalid.
244 * - The comparer has failed to compare the keys.
245 * @see ContainsValue()
248 virtual result ContainsKey(const KeyType& key, bool& out) const = 0;
251 * Checks whether the map contains the specified @c value.
255 * @return Set to @c true if the map contains the specified value, @n
257 * @param[in] value The value to locate
262 virtual bool ContainsValue(const ValueType& value) const = 0;
265 * Gets the enumerator of the map.
269 * @return An instance of IMapEnumeratorT for the map, @n
270 * else @c null if an exception occurs
271 * @exception E_SUCCESS The method is successful.
272 * @exception E_OUT_OF_MEMORY The memory is insufficient.
274 * - If a key has multiple values, the enumeration proceeds as follows: @n
275 * {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ...
276 * - The specific error code can be accessed using the GetLastResult() method.
277 * @see Tizen::Base::Collection::IEnumerator
278 * @see Tizen::Base::Collection::IMapEnumerator
280 virtual IMapEnumeratorT< KeyType, ValueType >* GetMapEnumeratorN(void) const = 0;
284 }}} // Tizen::Base::Collection
286 #endif // _FBASE_COL_IMULTI_MAP_T_H_