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 FBaseColIMultiMap.h
19 * @brief This is the header file for the %IMultiMap interface.
21 * This header file contains the declarations of the %IMultiMap interface.
23 #ifndef _FBASE_COL_IMULTI_MAP_H_
24 #define _FBASE_COL_IMULTI_MAP_H_
26 #include <FBaseColICollection.h>
27 #include <FBaseColTypes.h>
28 #include <FBaseColIMapEnumerator.h>
29 #include <FBaseObject.h>
32 namespace Tizen { namespace Base { namespace Collection
39 * @interface IMultiMap
40 * @brief This interface represents a collection of key-value pairs.
44 * The %IMultiMap interface abstracts a collection of key-value pairs.
45 * There is no limit on the number of elements with the same key, but duplicated elements with the same key are not allowed.
46 * The key and value cannot be a @c null reference.
48 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/hashmap_multihashmap.htm">HashMap and MultiHashMap</a>.
51 class _OSP_EXPORT_ IMultiMap
52 : public virtual ICollection
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.
61 virtual ~IMultiMap(void) {}
65 * Adds the specified key-value pair to the map.
67 * @brief <i> [Deprecated] </i>
68 * @deprecated This method is deprecated because it has a problem of const reference argument.
69 * Instead of using this method, use Add(Object* pKey, Object* pValue).
72 * @return An error code
73 * @param[in] key The key to add
74 * @param[in] value The corresponding value to add
75 * @exception E_SUCCESS The method is successful.
76 * @exception E_INVALID_ARG A specified input parameter is invalid, or
77 * the comparer has failed to compare the keys.
78 * @exception E_OBJ_ALREADY_EXIST The specified @c key and @c value already exist.
79 * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself.
83 result Add(const Object& key, const Object& value)
85 return Add(const_cast< Object* >(&key), const_cast< Object* >(&value));
89 * Adds the specified key-value pair to the map.
93 * @return An error code
94 * @param[in] pKey The pointer to key to add
95 * @param[in] pValue The pointer to corresponding value to add
96 * @exception E_SUCCESS The method is successful.
97 * @exception E_INVALID_ARG A specified input parameter is invalid, or
98 * the comparer has failed to compare the keys.
99 * @exception E_OBJ_ALREADY_EXIST The specified @c pKey and @c pValue already exist.
100 * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself.
103 virtual result Add(Object* pKey, Object* pValue) = 0;
106 * Gets the number of values stored in the map.
110 * @return The number of values currently stored in the map
112 virtual int GetCount(void) const = 0;
115 * Gets the number of values with keys matching the specified key.
119 * @return The number of values with keys matching the specified key
120 * @param[in] key The key to locate in the map
121 * @param[out] count The number of values with keys matching the specified key
122 * @exception E_SUCCESS The method is successful.
123 * @exception E_INVALID_ARG The specified input parameter is invalid, or
124 * the comparer has failed to compare the keys.
125 * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map.
127 virtual result GetCount(const Object& key, int& count) const = 0;
130 * Gets an enumerator of the values associated with the specified key.
134 * @return An instance of the IEnumerator derived class with the values associated with the specified key, @n
135 * else @c null if an exception occurs
136 * @param[in] key The key to locate in the map
137 * @exception E_SUCCESS The method is successful.
138 * @exception E_INVALID_ARG A specified input parameter is invalid, or
139 * the comparer has failed to compare the keys.
140 * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map.
141 * @remarks The specific error code can be accessed using the GetLastResult() method.
143 virtual IEnumerator* GetValuesN(const Object& key) const = 0;
146 * Gets a list of all unique keys in the map.
150 * @return A pointer to a list of all unique keys in the map, @n
151 * else @c null if an exception occurs
152 * @remarks The %IList stores just the pointers to the elements in the map, not the elements themselves.
153 * @remarks The specific error code can be accessed using the GetLastResult() method.
156 virtual IList* GetKeysN(void) const = 0;
159 * Gets a list of all the values in the map.
163 * @return A pointer to a list of all the values in the map, @n
164 * else @c null if an exception occurs
165 * @remarks The IList stores just the pointers to the elements in the map, not the elements themselves.
166 * @remarks The specific error code can be accessed using the GetLastResult() method.
169 virtual IList* GetValuesN(void) const = 0;
172 * Removes all the values associated with the specified key.
176 * @return An error code
177 * @param[in] key The key for which the associated values need to remove
178 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
180 * @exception E_SUCCESS The method is successful.
181 * @exception E_INVALID_ARG A specified input parameter is invalid, or
182 * the comparer has failed to compare the keys.
183 * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map.
184 * @remarks Based on the specified element deleter, the remove operation not only gets rid of an element from a list, but also deletes its object instance. @n
185 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
186 * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
187 * @remarks Remove(key, @b true) internally works as the below code:
189 * DeleterFunctionType deleter = GetDeleter();
190 * SetDeleter(SingleObjectDeleter);
192 * SetDeleter(deleter);
194 * @remarks Remove(key, @b false) internally works as the below code:
196 * DeleterFunctionType deleter = GetDeleter();
197 * SetDeleter(NoOpDeleter);
199 * SetDeleter(deleter);
203 result Remove(const Object& key, bool forceDeletion)
205 DeleterFunctionType deleter = GetDeleter();
209 SetDeleter(SingleObjectDeleter);
213 SetDeleter(NoOpDeleter);
216 result r = Remove(key);
222 * Removes all the values associated with the specified key.
226 * @return An error code
227 * @param[in] key The key for which the associated values need to remove
228 * @exception E_SUCCESS The method is successful.
229 * @exception E_INVALID_ARG A specified input parameter is invalid, or
230 * the comparer has failed to compare the keys.
231 * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map.
234 virtual result Remove(const Object& key) = 0;
237 * Removes the specified value associated with the specified key. @n
238 * The key is also removed if there are no more values associated with it.
242 * @return An error code
243 * @param[in] key The key for which the mapping is to remove from the map
244 * @param[in] value The value to remove
245 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
247 * @exception E_SUCCESS The method is successful.
248 * @exception E_INVALID_ARG A specified input parameter is invalid, or
249 * the comparer has failed to compare the keys.
250 * @exception E_OBJ_NOT_FOUND The @c key and @c value pair is not found in the map.
251 * @remarks Based on the specified element deleter, the remove operation not only gets rid of an element from a list, but also deletes its object instance. @n
252 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
253 * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
254 * @remarks Remove(key, value, @b true) internally works as the below code:
256 * DeleterFunctionType deleter = GetDeleter();
257 * SetDeleter(SingleObjectDeleter);
258 * Remove(key, value);
259 * SetDeleter(deleter);
261 * @remarks Remove(key, value, @b false) internally works as the below code:
263 * DeleterFunctionType deleter = GetDeleter();
264 * SetDeleter(NoOpDeleter);
265 * Remove(key, value);
266 * SetDeleter(deleter);
270 result Remove(const Object& key, const Object& value, bool forceDeletion)
272 DeleterFunctionType deleter = GetDeleter();
276 SetDeleter(SingleObjectDeleter);
280 SetDeleter(NoOpDeleter);
283 result r = Remove(key, value);
289 * Removes the specified value associated with the specified key. @n
290 * The key is also removed if there are no more values associated with it.
294 * @return An error code
295 * @param[in] key The key for which the mapping is to remove from the map
296 * @param[in] value The value to remove
297 * @exception E_SUCCESS The method is successful.
298 * @exception E_INVALID_ARG A specified input parameter is invalid, or
299 * the comparer has failed to compare the keys.
300 * @exception E_OBJ_NOT_FOUND The @c key and @c value pair is not found in the map.
303 virtual result Remove(const Object& key, const Object& value) = 0;
306 * Removes all the object pointers in the collection. @n
307 * If the @c forceDeletion parameter is set to @c true, the method also removes all the objects. This method can be called before deleting the collection.
311 * @param[in] forceDeletion Set to @c true to deallocate all objects, @n
313 * @remarks Based on the specified element deleter, the remove operation not only gets rid of an element from a list, but also deletes its object instance. @n
314 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
315 * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
316 * @remarks RemoveAll(@b true) internally works as the below code:
318 * DeleterFunctionType deleter = GetDeleter();
319 * SetDeleter(SingleObjectDeleter);
321 * SetDeleter(deleter);
323 * @remarks RemoveAll(@b false) internally works as the below code:
325 * DeleterFunctionType deleter = GetDeleter();
326 * SetDeleter(NoOpDeleter);
328 * SetDeleter(deleter);
331 void RemoveAll(bool forceDeletion)
333 DeleterFunctionType deleter = GetDeleter();
337 SetDeleter(SingleObjectDeleter);
341 SetDeleter(NoOpDeleter);
349 * Removes all the object pointers in the collection. @n
350 * This method can be called before deleting the collection.
354 virtual void RemoveAll(void) = 0;
357 * Replaces the specified value associated with the specified key with a new value.
361 * @return An error code
362 * @param[in] key The key for which the associated value needs to replace
363 * @param[in] value The value associated with the key
364 * @param[in] newValue The new value
365 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
367 * @exception E_SUCCESS The method is successful.
368 * @exception E_INVALID_ARG A specified input parameter is invalid, or
369 * the comparer has failed to compare the keys.
370 * @exception E_OBJ_NOT_FOUND The key-value pair is not found in the map.
371 * @remarks Use the Add() method to add a new key-value pair.
372 * @remarks Based on the specified element deleter, the set operation not only gets rid of an element from a list, but also deletes its object instance. @n
373 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the set method. @n
374 * If both an element deleter and forceDeleteion are set, the set operation follows @c forceDeletion setting.
375 * @remarks SetValue(key, value, newValue, @b true) internally works as the below code:
377 * DeleterFunctionType deleter = GetDeleter();
378 * SetDeleter(SingleObjectDeleter);
379 * SetValue(key, value, const_cast< Object* >(&newValue));
380 * SetDeleter(deleter);
382 * @remarks SetValue(key, value, newValue, @b false) internally works as the below code:
384 * DeleterFunctionType deleter = GetDeleter();
385 * SetDeleter(NoOpDeleter);
386 * SetValue(key, value, const_cast< Object* >(&newValue));
387 * SetDeleter(deleter);
392 result SetValue(const Object& key, const Object& value, const Object& newValue, bool forceDeletion = false)
394 DeleterFunctionType deleter = GetDeleter();
398 SetDeleter(SingleObjectDeleter);
402 SetDeleter(NoOpDeleter);
405 result r = SetValue(key, value, const_cast< Object* >(&newValue));
411 * Replaces the specified value associated with the specified key with a new value.
415 * @return An error code
416 * @param[in] key The key for which the associated value needs to replace
417 * @param[in] value The value associated with the key
418 * @param[in] pNewValue The pointer to new value
419 * @exception E_SUCCESS The method is successful.
420 * @exception E_INVALID_ARG A specified input parameter is invalid, or
421 * the comparer has failed to compare the keys.
422 * @exception E_OBJ_NOT_FOUND The key-value pair is not found in the map.
423 * @remarks Use the Add() method to add a new key-value pair.
427 virtual result SetValue(const Object& key, const Object& value, Object* pNewValue) = 0;
431 * Checks whether the map contains the specified key-value pair.
433 * @brief <i> [Deprecated] </i>
434 * @deprecated This method is deprecated because it transfers a result of comparison in out-parameter form.
435 * The return type will be changed into boolean type and this method will return the result.
436 * Instead of using this method, use bool Contains(const Object& key, const Object& value).
439 * @return An error code
440 * @param[in] key The key to locate
441 * @param[in] value The value to locate
442 * @param[out] out Set to @c true if the map contains the specified key-value pair, @n
444 * @exception E_SUCCESS The method is successful.
445 * @exception E_INVALID_ARG A specified input parameter is invalid, or
446 * the comparer has failed to compare the keys.
448 * @see ContainsValue()
451 result Contains(const Object& key, const Object& value, bool& out) const
453 out = Contains(key, value);
454 result r = GetLastResult();
459 * Checks whether the map contains the specified key-value pair.
463 * @return @c true if the map contains the specified key-value pair, @n
465 * @param[in] key The key to locate
466 * @param[in] value The value to locate
467 * @exception E_SUCCESS The method is successful.
468 * @exception E_INVALID_ARG A specified input parameter is invalid, or
469 * the comparer has failed to compare the keys.
470 * @remarks The specific error code can be accessed using the GetLastResult() method.
472 * @see ContainsValue()
474 virtual bool Contains(const Object& key, const Object& value) const = 0;
478 * Checks whether the map contains the specified key.
480 * @brief <i> [Deprecated] </i>
481 * @deprecated This method is deprecated because it transfers a result of comparison in out-parameter form.
482 * The return type will be changed into boolean type and this method will return the result.
483 * Instead of using this method, use bool ContainsKey(const Object& key).
486 * @return An error code
487 * @param[in] key The key to locate
488 * @param[out] out Set to @c true if the map contains the specified key, @n
490 * @exception E_SUCCESS The method is successful.
491 * @exception E_INVALID_ARG A specified input parameter is invalid, or
492 * the comparer has failed to compare the keys.
493 * @see ContainsValue()
497 result ContainsKey(const Object& key, bool& out) const
499 out = ContainsKey(key);
500 result r = GetLastResult();
505 * Checks whether the map contains the specified key.
509 * @return @c true if the map contains the specified key, @n
511 * @param[in] key The key to locate
512 * @exception E_SUCCESS The method is successful.
513 * @exception E_INVALID_ARG A specified input parameter is invalid, or
514 * the comparer has failed to compare the keys.
515 * @remarks The specific error code can be accessed using the GetLastResult() method.
516 * @see ContainsValue()
519 virtual bool ContainsKey(const Object& key) const = 0;
522 * Checks whether the map contains the specified value.
526 * @return @c true if the map contains the specified value, @n
528 * @param[in] value The value to locate
533 virtual bool ContainsValue(const Object& value) const = 0;
536 * Gets an enumerator of the map.
540 * @return An instance of the IMapEnumerator class for the map, @n
541 * else @c null if an exception occurs
542 * @exception E_SUCCESS The method is successful.
543 * @remarks If a key has multiple values, the enumeration proceeds as follows: @n
544 * {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ...
545 * @remarks The specific error code can be accessed using the GetLastResult() method.
547 * @see IMapEnumerator
549 virtual IMapEnumerator* GetMapEnumeratorN(void) const = 0;
552 * Gets the element deleter of the collection.
556 * @return A function pointer to the existing element deleter
558 virtual DeleterFunctionType GetDeleter(void) const = 0;
562 // This method is for internal use only. Using this method can cause behavioral, security-related,
563 // and consistency-related issues in the application.
564 // This method is reserved and may change its name at any time without prior notice.
568 virtual void IMultiMap_Reserved1(void) { }
572 // This method is for internal use only. Using this method can cause behavioral, security-related,
573 // and consistency-related issues in the application.
574 // This method is reserved and may change its name at any time without prior notice.
578 virtual void IMultiMap_Reserved2(void) { }
582 * Sets the element deleter of the collection.
586 * @param[in] deleter A function pointer to the element deleter to set
588 virtual void SetDeleter(DeleterFunctionType deleter) = 0;
592 }}} // Tizen::Base::Collection
594 #endif // _FBASE_COL_IMULTI_MAP_H_