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>
31 namespace Tizen { namespace Base { namespace Collection
38 * @interface IMultiMap
39 * @brief This interface represents a collection of key-value pairs.
43 * The %IMultiMap interface represents a collection of key-value pairs.
44 * There is no limit on the number of elements having the same key, but duplicate elements with the same key are not allowed.
45 * The key and value cannot be a @c null reference.
47 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/hashmap_multihashmap.htm">HashMap and MultiHashMap</a>.
50 class _OSP_EXPORT_ IMultiMap
51 : public virtual ICollection
55 * This polymorphic destructor should be overridden if required. @n
56 * This way, the destructors of the derived classes are called when the destructor of this interface is called.
60 virtual ~IMultiMap(void) {}
64 * Adds the specified key-value pair to the map.
66 * @brief <i> [Deprecated] </i>
67 * @deprecated This method is deprecated because it has a problem of constant reference argument.
68 * Instead of using this method, use Add(Object* pKey, Object* pValue).
71 * @return An error code
72 * @param[in] key The key to add
73 * @param[in] value The corresponding value to add
74 * @exception E_SUCCESS The method is successful.
75 * @exception E_INVALID_ARG Either of the following conditions has occurred:
76 * - A specified input parameter is invalid.
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 and 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 A pointer to the key to add
95 * @param[in] pValue A pointer to the corresponding value to add
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_ALREADY_EXIST The specified @c pKey and @c pValue already exist.
101 * @remarks This method performs a shallow copy. It adds just the pointer and not the element itself.
104 virtual result Add(Object* pKey, Object* pValue) = 0;
107 * Gets the number of values stored in the map.
111 * @return The number of values currently stored in the map
113 virtual int GetCount(void) const = 0;
116 * Gets the number of values with keys matching the specified @c key.
120 * @return The number of values with keys matching the specified key
121 * @param[in] key The key to locate in the map
122 * @param[out] count The number of values with keys matching the specified key
123 * @exception E_SUCCESS The method is successful.
124 * @exception E_INVALID_ARG Either of the following conditions has occurred:
125 * - A specified input parameter is invalid.
126 * - The comparer has failed to compare the keys.
127 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
129 virtual result GetCount(const Object& key, int& count) const = 0;
132 * Gets the enumerator of the values associated with the specified @c key.
136 * @return An instance of the IEnumerator derived class that contains the values associated with the specified key, @n
137 * else @c null if an exception occurs
138 * @param[in] key The key to locate in the map
139 * @exception E_SUCCESS The method is successful.
140 * @exception E_INVALID_ARG Either of the following conditions has occurred:
141 * - A specified input parameter is invalid.
142 * - The comparer has failed to compare the keys.
143 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
144 * @remarks The specific error code can be accessed using the GetLastResult() method.
146 virtual IEnumerator* GetValuesN(const Object& key) const = 0;
149 * Gets the list of all the unique keys in the map.
153 * @return A pointer to the list of all the unique keys in the map, @n
154 * else @c null if an exception occurs
156 * - The IList stores just the pointers to the elements in the map and not the elements themselves.
157 * - The specific error code can be accessed using the GetLastResult() method.
160 virtual IList* GetKeysN(void) const = 0;
163 * Gets the list of all the values in the map.
167 * @return A pointer to the list of all the values in the map, @n
168 * else @c null if an exception occurs
170 * - The IList stores just the pointers to the elements in the map and not the elements themselves.
171 * - The specific error code can be accessed using the GetLastResult() method.
174 virtual IList* GetValuesN(void) const = 0;
177 * Removes all the values associated with the specified @c key.
181 * @return An error code
182 * @param[in] key The key for which the associated values are removed
183 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
185 * @exception E_SUCCESS The method is successful.
186 * @exception E_INVALID_ARG Either of the following conditions has occurred:
187 * - A specified input parameter is invalid.
188 * - The comparer has failed to compare the keys.
189 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
191 * - Based on the specified element deleter, the remove operation not only gets rid of an element from the list, but also deletes its object instance. @n
192 * The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
193 * If both the element deleter and the @c forceDeleteion are set, the remove operation follows the @c forceDeletion setting.
194 * - Remove(key, @b true) internally works as the below code:
196 * DeleterFunctionType deleter = GetDeleter();
197 * SetDeleter(SingleObjectDeleter);
199 * SetDeleter(deleter);
201 * - Remove(key, @b false) internally works as the below code:
203 * DeleterFunctionType deleter = GetDeleter();
204 * SetDeleter(NoOpDeleter);
206 * SetDeleter(deleter);
208 * @see Add(Object*, Object*)
210 result Remove(const Object& key, bool forceDeletion)
212 DeleterFunctionType deleter = GetDeleter();
216 SetDeleter(SingleObjectDeleter);
220 SetDeleter(NoOpDeleter);
223 result r = Remove(key);
229 * Removes all the values associated with the specified @c key.
233 * @return An error code
234 * @param[in] key The key for which the associated values are removed
235 * @exception E_SUCCESS The method is successful.
236 * @exception E_INVALID_ARG Either of the following conditions has occurred:
237 * - A specified input parameter is invalid.
238 * - The comparer has failed to compare the keys.
239 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
240 * @see Add(Object*, Object*)
242 virtual result Remove(const Object& key) = 0;
245 * Removes the specified @c value associated with the specified @c key. @n
246 * The @c key is also removed if there are no more values associated with it.
250 * @return An error code
251 * @param[in] key The key for which the mapping is removed from the map
252 * @param[in] value The value to remove
253 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
255 * @exception E_SUCCESS The method is successful.
256 * @exception E_INVALID_ARG Either of the following conditions has occurred:
257 * - A specified input parameter is invalid.
258 * - The comparer has failed to compare the keys.
259 * @exception E_OBJ_NOT_FOUND The specified @c key and the specified @c value pair has not been found in the map.
261 * - Based on the specified element deleter, the remove operation not only gets rid of an element from the list, but also deletes its object instance. @n
262 * - The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
263 * - If both the element deleter and the @c forceDeleteion are set, the remove operation follows the @c forceDeletion setting.
264 * - Remove(key, value, @b true) internally works as the below code:
266 * DeleterFunctionType deleter = GetDeleter();
267 * SetDeleter(SingleObjectDeleter);
268 * Remove(key, value);
269 * SetDeleter(deleter);
271 * - Remove(key, value, @b false) internally works as the below code:
273 * DeleterFunctionType deleter = GetDeleter();
274 * SetDeleter(NoOpDeleter);
275 * Remove(key, value);
276 * SetDeleter(deleter);
278 * @see Add(Object*, Object*)
280 result Remove(const Object& key, const Object& value, bool forceDeletion)
282 DeleterFunctionType deleter = GetDeleter();
286 SetDeleter(SingleObjectDeleter);
290 SetDeleter(NoOpDeleter);
293 result r = Remove(key, value);
299 * Removes the specified @c value associated with the specified @c key. @n
300 * The @c key is also removed if there are no more values associated with it.
304 * @return An error code
305 * @param[in] key The key for which the mapping is removed from the map
306 * @param[in] value The value to remove
307 * @exception E_SUCCESS The method is successful.
308 * @exception E_INVALID_ARG Either of the following conditions has occurred:
309 * - A specified input parameter is invalid.
310 * - The comparer has failed to compare the keys.
311 * @exception E_OBJ_NOT_FOUND The specified @c key and the specified @c value pair has not been found in the map.
312 * @see Add(Object*, Object*)
314 virtual result Remove(const Object& key, const Object& value) = 0;
317 * Removes all the object pointers in the collection. @n
318 * If @c forceDeletion is set to @c true, the method also removes all the objects. This method can be called before deleting the collection.
322 * @param[in] forceDeletion Set to @c true to deallocate all objects, @n
325 * - Based on the specified element deleter, the remove operation not only gets rid of an element from the list, but also deletes its object instance. @n
326 * - The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
327 * - If both the element deleter and the @c forceDeletion are set, the remove operation follows the @c forceDeletion setting.
328 * - RemoveAll(@b true) internally works as the below code:
330 * DeleterFunctionType deleter = GetDeleter();
331 * SetDeleter(SingleObjectDeleter);
333 * SetDeleter(deleter);
335 * - RemoveAll(@b false) internally works as the below code:
337 * DeleterFunctionType deleter = GetDeleter();
338 * SetDeleter(NoOpDeleter);
340 * SetDeleter(deleter);
343 void RemoveAll(bool forceDeletion)
345 DeleterFunctionType deleter = GetDeleter();
349 SetDeleter(SingleObjectDeleter);
353 SetDeleter(NoOpDeleter);
361 * Removes all the object pointers in the collection. @n
362 * The %RemoveAll() method can be called before deleting the collection.
366 virtual void RemoveAll(void) = 0;
369 * Replaces the specified @c value associated with the specified @c key with a @c newValue.
373 * @return An error code
374 * @param[in] key The key for which the associated value is replaced
375 * @param[in] value The value associated with the key
376 * @param[in] newValue The new value
377 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
379 * @exception E_SUCCESS The method is successful.
380 * @exception E_INVALID_ARG Either of the following conditions has occurred:
381 * - A specified input parameter is invalid.
382 * - The comparer has failed to compare the keys.
383 * @exception E_OBJ_NOT_FOUND The key-value pair has not been found in the map.
385 * - Use the Add(Object*, Object*) method to add a new key-value pair.
386 * - Based on the specified element deleter, the set operation not only gets rid of an element from the list, but also deletes its object instance. @n
387 * The element deleter style is recommended rather than using @c forceDeletetion in the set method. @n
388 * If both the element deleter and the @c forceDeleteion are set, the set operation follows the @c forceDeletion setting.
389 * - SetValue(key, value, newValue, @b true) internally works as the below code:
391 * DeleterFunctionType deleter = GetDeleter();
392 * SetDeleter(SingleObjectDeleter);
393 * SetValue(key, value, const_cast< Object* >(&newValue));
394 * SetDeleter(deleter);
396 * - SetValue(key, value, newValue, @b false) internally works as the below code:
398 * DeleterFunctionType deleter = GetDeleter();
399 * SetDeleter(NoOpDeleter);
400 * SetValue(key, value, const_cast< Object* >(&newValue));
401 * SetDeleter(deleter);
405 result SetValue(const Object& key, const Object& value, const Object& newValue, bool forceDeletion = false)
407 DeleterFunctionType deleter = GetDeleter();
411 SetDeleter(SingleObjectDeleter);
415 SetDeleter(NoOpDeleter);
418 result r = SetValue(key, value, const_cast< Object* >(&newValue));
424 * Replaces the specified @c value associated with the specified @c key with a @c pNewValue.
428 * @return An error code
429 * @param[in] key The key for which the associated value is replaced
430 * @param[in] value The value associated with the key
431 * @param[in] pNewValue A pointer to the new value
432 * @exception E_SUCCESS The method is successful.
433 * @exception E_INVALID_ARG Either of the following conditions has occurred:
434 * - A specified input parameter is invalid.
435 * - The comparer has failed to compare the keys.
436 * @exception E_OBJ_NOT_FOUND The key-value pair has not been found in the map.
437 * @remarks Use the Add(Object*, Object*) method to add a new key-value pair.
440 virtual result SetValue(const Object& key, const Object& value, Object* pNewValue) = 0;
444 * Checks whether the map contains the specified key-value pair.
446 * @brief <i> [Deprecated] </i>
447 * @deprecated This method is deprecated because it transfers the result of the comparison in an out-parameter form.
448 * The return type is changed into boolean and this method returns the result.
449 * Instead of using this method, use bool Contains(const Object& key, const Object& value).
452 * @return An error code
453 * @param[in] key The key to locate
454 * @param[in] value The value to locate
455 * @param[out] out Set to @c true if the map contains the specified key-value pair, @n
457 * @exception E_SUCCESS The method is successful.
458 * @exception E_INVALID_ARG Either of the following conditions has occurred:
459 * - A specified input parameter is invalid.
460 * - The comparer has failed to compare the keys.
462 * @see ContainsValue()
465 result Contains(const Object& key, const Object& value, bool& out) const
467 out = Contains(key, value);
468 result r = GetLastResult();
473 * Checks whether the map contains the specified key-value pair.
477 * @return @c true if the map contains the specified key-value pair, @n
479 * @param[in] key The key to locate
480 * @param[in] value The value to locate
481 * @exception E_SUCCESS The method is successful.
482 * @exception E_INVALID_ARG Either of the following conditions has occurred:
483 * - A specified input parameter is invalid.
484 * - The comparer has failed to compare the keys.
485 * @remarks The specific error code can be accessed using the GetLastResult() method.
486 * @see ContainsKey(const Object&) const
487 * @see ContainsValue()
489 virtual bool Contains(const Object& key, const Object& value) const = 0;
493 * Checks whether the map contains the specified @c key.
495 * @brief <i> [Deprecated] </i>
496 * @deprecated This method is deprecated because it transfers the result of the comparison in an out-parameter form.
497 * The return type is changed into boolean and this method returns the result.
498 * Instead of using this method, use bool ContainsKey(const Object& key).
501 * @return An error code
502 * @param[in] key The key to locate
503 * @param[out] out Set to @c true if the map contains the specified key, @n
505 * @exception E_SUCCESS The method is successful.
506 * @exception E_INVALID_ARG Either of the following conditions has occurred:
507 * - A specified input parameter is invalid.
508 * - The comparer has failed to compare the keys.
509 * @see ContainsValue()
510 * @see Contains(const Object&, const Object&)
513 result ContainsKey(const Object& key, bool& out) const
515 out = ContainsKey(key);
516 result r = GetLastResult();
521 * Checks whether the map contains the specified @c key.
525 * @return @c true if the map contains the specified key, @n
527 * @param[in] key The key to locate
528 * @exception E_SUCCESS The method is successful.
529 * @exception E_INVALID_ARG Either of the following conditions has occurred:
530 * - A specified input parameter is invalid.
531 * - The comparer has failed to compare the keys.
532 * @remarks The specific error code can be accessed using the GetLastResult() method.
533 * @see ContainsValue()
534 * @see Contains(const Object&, const Object&) const
536 virtual bool ContainsKey(const Object& key) const = 0;
539 * Checks whether the map contains the specified @c value.
543 * @return @c true if the map contains the specified value, @n
545 * @param[in] value The value to locate
547 * @see ContainsKey(const Object&) const
548 * @see Contains(const Object&, const Object&) const
550 virtual bool ContainsValue(const Object& value) const = 0;
553 * Gets the enumerator of the map.
557 * @return An instance of IMapEnumerator for the map, @n
558 * else @c null if an exception occurs
559 * @exception E_SUCCESS The method is successful.
561 * - If a key has multiple values, the enumeration proceeds as follows: @n
562 * {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ...
563 * - The specific error code can be accessed using the GetLastResult() method.
566 virtual IMapEnumerator* GetMapEnumeratorN(void) const = 0;
569 * Gets the element deleter of the collection.
573 * @return A function pointer to the existing element deleter
575 virtual DeleterFunctionType GetDeleter(void) const = 0;
579 // This method is for internal use only. Using this method can cause behavioral, security-related,
580 // and consistency-related issues in the application.
581 // This method is reserved and may change its name at any time without prior notice.
585 virtual void IMultiMap_Reserved1(void) { }
588 // This method is for internal use only. Using this method can cause behavioral, security-related,
589 // and consistency-related issues in the application.
590 // This method is reserved and may change its name at any time without prior notice.
594 virtual void IMultiMap_Reserved2(void) { }
598 * Sets the element deleter of the collection.
602 * @param[in] deleter A function pointer to the element deleter to set
604 virtual void SetDeleter(DeleterFunctionType deleter) = 0;
608 }}} // Tizen::Base::Collection
610 #endif // _FBASE_COL_IMULTI_MAP_H_