1c2a8a4fcba1817ed6f2eb7f14591070b8ca15eb
[platform/framework/native/appfw.git] / inc / FBaseColIMultiMapT.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                FBaseColIMultiMapT.h
19  * @brief               This is the header file for the %IMultiMapT interface.
20  *
21  * This header file contains the declarations of the %IMultiMapT interface.
22  */
23 #ifndef _FBASE_COL_IMULTI_MAP_T_H_
24 #define _FBASE_COL_IMULTI_MAP_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   IMultiMapT
37  * @brief               This interface represents a template-based collection of key-value pairs.
38  *
39  * @since 2.0
40  *
41  * The %IMultiMapT interface abstracts a template-based collection of key-value pairs.
42  * There is no limit on the number of elements with the same key, but duplicated elements with the same key are not allowed.
43  * The key and value cannot be a @c null reference.
44  * @n
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 IMultiMapT
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 ~IMultiMapT(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 and @c value already exists.
73          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
74          * @see Remove()
75          */
76         virtual result Add(const KeyType& key, const ValueType& value) = 0;
77
78         /**
79          * Gets the number of values stored in the map.
80          *
81          * @since 2.0
82          *
83          * @return      The number of values currently stored in the map
84          */
85         virtual int GetCount(void) const = 0;
86
87         /**
88          * Gets the number of values whose key matches the specified key.
89          *
90          * @since 2.0
91          *
92          * @return              The number of values whose key matches the specified key
93          * @param[in]   key             The key to locate in the map
94          * @param[out]  count   The number of values whose key matches the specified key
95          * @exception   E_SUCCESS                       The method is successful.
96          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
97          *                                                                      the comparer has failed to compare the keys.
98          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found in the map.
99          */
100         virtual result GetCount(const KeyType& key, int& count) const = 0;
101
102         /**
103          * Gets an enumerator of the values associated with the specified key.
104          *
105          * @since 2.0
106          *
107          * @return              An instance of the IEnumeratorT derived class with the values associated with the specified key, @n
108          *                              else @c null if an exception occurs
109          * @param[in]   key                             The key to locate
110          * @exception   E_SUCCESS               The method is successful.
111          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
112          *                                                              the comparer has failed to compare the keys.
113          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
114          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
115          * @remarks             The specific error code can be accessed using the GetLastResult() method.
116          * @see                 SetValue()
117          */
118         virtual IEnumeratorT< ValueType >* GetValuesN(const KeyType& key) const = 0;
119
120         /**
121          * Gets a list of all unique keys in the map.
122          *
123          * @since 2.0
124          *
125          * @return              A pointer to a list of all unique keys in the map, @n
126          *                              else @c null if an exception occurs
127          * @exception   E_SUCCESS               The method is successful.
128          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
129          * @remarks             The specific error code can be accessed using the GetLastResult() method.
130          * @see                 GetValuesN()
131          */
132         virtual IListT< KeyType >* GetKeysN(void) const = 0;
133
134         /**
135          * Gets a list of all the values in the map.
136          *
137          * @since 2.0
138          *
139          * @return              A pointer to a list of all the values in the map, @n
140          *                              else @c null if an exception occurs
141          * @exception   E_SUCCESS               The method is successful.
142          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
143          * @remarks             The specific error code can be accessed using the GetLastResult() method.
144          * @see                 GetKeysN()
145          */
146         virtual IListT< ValueType >* GetValuesN(void) const = 0;
147
148         /**
149          * Removes all the values associated with the specified key.
150          *
151          * @since 2.0
152          *
153          * @return              An error code
154          * @param[in]   key                             The key whose associated values need to remove
155          * @exception   E_SUCCESS               The method is successful.
156          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
157          *                                                              the comparer has failed to compare the keys.
158          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found in the map.
159          * @see                 Add()
160          */
161         virtual result Remove(const KeyType& key) = 0;
162
163         /**
164          * Removes the specified value associated with the specified key. @n
165          * The key is also removed if there are no more values associated with it.
166          *
167          * @since 2.0
168          *
169          * @return              An error code
170          * @param[in]   key             The key whose mapping is to remove from the map
171          * @param[in]   value   The value to remove
172          * @exception   E_SUCCESS               The method is successful.
173          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
174          *                                                              the comparer has failed to compare the keys.
175          * @exception   E_OBJ_NOT_FOUND The specified @c key and @c value pair is not found in the map.
176          * @see                 Add()
177          */
178         virtual result Remove(const KeyType& key, const ValueType& value) = 0;
179
180         /**
181          * Removes all the key-value pairs in the map.
182          *
183          * @since 2.0
184          */
185         virtual void RemoveAll(void) = 0;
186
187         /**
188          * Replaces the specified value associated with the specified key with a new value.
189          *
190          * @since 2.0
191          *
192          * @return              An error code
193          * @param[in]   key                     The key whose associated value needs to replace
194          * @param[in]   value           The value associated with the key
195          * @param[in]   newValue        The new value
196          * @exception   E_SUCCESS               The method is successful.
197          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
198          *                                                              the comparer has failed to compare the keys.
199          * @exception   E_OBJ_NOT_FOUND The specified @c key and @c value pair is not found in the map.
200          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
201          * @remarks             Use the Add() method to add a new key-value pair.
202          * @see                 Add()
203          * @see                 GetValuesN()
204          */
205         virtual result SetValue(const KeyType& key, const ValueType& value, const ValueType& newValue) = 0;
206
207         /**
208          * Checks whether the map contains the specified key-value pair.
209          *
210          * @since 2.0
211          *
212          * @return              An error code
213          * @param[in]   key             The key to locate
214          * @param[in]   value   The value to locate
215          * @param[out]  out             Set to @c true if the map contains the specified key-value pair, @n
216          *                                              else @c false
217          * @exception   E_SUCCESS               The method is successful. @n
218          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
219          *                                                              the comparer has failed to compare the keys.
220          * @see                 ContainsKey()
221          * @see                 ContainsValue()
222          */
223         virtual result Contains(const KeyType& key, const ValueType& value, bool& out) const = 0;
224
225         /**
226          * Checks whether the map contains the specified key.
227          *
228          * @since 2.0
229          *
230          * @return              An error code
231          * @param[in]   key             The key to locate
232          * @param[out]  out     Set to @c true if the map contains the specified key, @n
233          *                                              else @c false
234          * @exception   E_SUCCESS               The method is successful. @n
235          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or
236          *                                                              the comparer has failed to compare the keys.
237          * @see                 ContainsValue()
238          * @see                 Contains()
239          */
240         virtual result ContainsKey(const KeyType& key, bool& out) const = 0;
241
242         /**
243          * Checks whether the map contains the specified value.
244          *
245          * @since 2.0
246          *
247          * @return              Set to @c true if the map contains the specified value, @n
248          *                              else @c false
249          * @param[in]   value   The value to locate
250          *
251          * @see                 ContainsKey()
252          * @see                 Contains()
253          */
254         virtual bool ContainsValue(const ValueType& value) const = 0;
255
256         /**
257          * Gets an enumerator of the map.
258          *
259          * @since 2.0
260          *
261          * @return              An instance of the IMapEnumeratorT class for the map, @n
262          *                              else @c null if an exception occurs
263          * @exception   E_SUCCESS               The method is successful.
264          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
265          * @remarks             If a key has multiple values, the enumeration proceeds as follows: @n
266          *                              {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ... @n
267          *                      The specific error code can be accessed using the GetLastResult() method.
268          * @see                 Tizen::Base::Collection::IEnumerator
269          * @see                 Tizen::Base::Collection::IMapEnumerator
270          */
271         virtual IMapEnumeratorT< KeyType, ValueType >* GetMapEnumeratorN(void) const = 0;
272
273 }; // IMultiMapT
274
275 }}} // Tizen::Base::Collection
276
277 #endif // _FBASE_COL_IMULTI_MAP_T_H_