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 abstracts a collection of key-value pairs.
44 * There is no limit on the number of elements with the same key, but duplicated 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 const 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 A specified input parameter is invalid, or
76 * the comparer has failed to compare the keys.
77 * @exception E_OBJ_ALREADY_EXIST The specified @c key and @c value already exist.
78 * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself.
82 result Add(const Object& key, const Object& value)
84 return Add(const_cast< Object* >(&key), const_cast< Object* >(&value));
88 * Adds the specified key-value pair to the map.
92 * @return An error code
93 * @param[in] pKey The pointer to key to add
94 * @param[in] pValue The pointer to corresponding value to add
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_ALREADY_EXIST The specified @c pKey and @c pValue already exist.
99 * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself.
102 virtual result Add(Object* pKey, Object* pValue) = 0;
105 * Gets the number of values stored in the map.
109 * @return The number of values currently stored in the map
111 virtual int GetCount(void) const = 0;
114 * Gets the number of values with keys matching the specified key.
118 * @return The number of values with keys matching the specified key
119 * @param[in] key The key to locate in the map
120 * @param[out] count The number of values with keys matching the specified key
121 * @exception E_SUCCESS The method is successful.
122 * @exception E_INVALID_ARG The specified input parameter is invalid, or
123 * the comparer has failed to compare the keys.
124 * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map.
126 virtual result GetCount(const Object& key, int& count) const = 0;
129 * Gets an enumerator of the values associated with the specified key.
133 * @return An instance of the IEnumerator derived class with the values associated with the specified key, @n
134 * else @c null if an exception occurs
135 * @param[in] key The key to locate in the map
136 * @exception E_SUCCESS The method is successful.
137 * @exception E_INVALID_ARG A specified input parameter is invalid, or
138 * the comparer has failed to compare the keys.
139 * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map.
140 * @remarks The specific error code can be accessed using the GetLastResult() method.
142 virtual IEnumerator* GetValuesN(const Object& key) const = 0;
145 * Gets a list of all unique keys in the map.
149 * @return A pointer to a list of all unique keys in the map, @n
150 * else @c null if an exception occurs
152 * - The %IList stores just the pointers to the elements in the map, not the elements themselves.
153 * - 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
166 * - The IList stores just the pointers to the elements in the map, not the elements themselves.
167 * - The specific error code can be accessed using the GetLastResult() method.
170 virtual IList* GetValuesN(void) const = 0;
173 * Removes all the values associated with the specified key.
177 * @return An error code
178 * @param[in] key The key for which the associated values need to remove
179 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
181 * @exception E_SUCCESS The method is successful.
182 * @exception E_INVALID_ARG A specified input parameter is invalid, or
183 * the comparer has failed to compare the keys.
184 * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map.
186 * - 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
187 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
188 * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
189 * - Remove(key, @b true) internally works as the below code:
191 * DeleterFunctionType deleter = GetDeleter();
192 * SetDeleter(SingleObjectDeleter);
194 * SetDeleter(deleter);
196 * - Remove(key, @b false) internally works as the below code:
198 * DeleterFunctionType deleter = GetDeleter();
199 * SetDeleter(NoOpDeleter);
201 * SetDeleter(deleter);
203 * @see Add(Object*, Object*)
205 result Remove(const Object& key, bool forceDeletion)
207 DeleterFunctionType deleter = GetDeleter();
211 SetDeleter(SingleObjectDeleter);
215 SetDeleter(NoOpDeleter);
218 result r = Remove(key);
224 * Removes all the values associated with the specified key.
228 * @return An error code
229 * @param[in] key The key for which the associated values need to remove
230 * @exception E_SUCCESS The method is successful.
231 * @exception E_INVALID_ARG A specified input parameter is invalid, or
232 * the comparer has failed to compare the keys.
233 * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map.
234 * @see Add(Object*, Object*)
236 virtual result Remove(const Object& key) = 0;
239 * Removes the specified value associated with the specified key. @n
240 * The key is also removed if there are no more values associated with it.
244 * @return An error code
245 * @param[in] key The key for which the mapping is to remove from the map
246 * @param[in] value The value to remove
247 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
249 * @exception E_SUCCESS The method is successful.
250 * @exception E_INVALID_ARG A specified input parameter is invalid, or
251 * the comparer has failed to compare the keys.
252 * @exception E_OBJ_NOT_FOUND The @c key and @c value pair is not found in the map.
254 * - 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
255 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
256 * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
257 * - Remove(key, value, @b true) internally works as the below code:
259 * DeleterFunctionType deleter = GetDeleter();
260 * SetDeleter(SingleObjectDeleter);
261 * Remove(key, value);
262 * SetDeleter(deleter);
264 * - Remove(key, value, @b false) internally works as the below code:
266 * DeleterFunctionType deleter = GetDeleter();
267 * SetDeleter(NoOpDeleter);
268 * Remove(key, value);
269 * SetDeleter(deleter);
271 * @see Add(Object*, Object*)
273 result Remove(const Object& key, const Object& value, bool forceDeletion)
275 DeleterFunctionType deleter = GetDeleter();
279 SetDeleter(SingleObjectDeleter);
283 SetDeleter(NoOpDeleter);
286 result r = Remove(key, value);
292 * Removes the specified value associated with the specified key. @n
293 * The key is also removed if there are no more values associated with it.
297 * @return An error code
298 * @param[in] key The key for which the mapping is to remove from the map
299 * @param[in] value The value to remove
300 * @exception E_SUCCESS The method is successful.
301 * @exception E_INVALID_ARG A specified input parameter is invalid, or
302 * the comparer has failed to compare the keys.
303 * @exception E_OBJ_NOT_FOUND The @c key and @c value pair is not found in the map.
304 * @see Add(Object*, Object*)
306 virtual result Remove(const Object& key, const Object& value) = 0;
309 * Removes all the object pointers in the collection. @n
310 * 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.
314 * @param[in] forceDeletion Set to @c true to deallocate all objects, @n
317 * - 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
318 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
319 * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
320 * - RemoveAll(@b true) internally works as the below code:
322 * DeleterFunctionType deleter = GetDeleter();
323 * SetDeleter(SingleObjectDeleter);
325 * SetDeleter(deleter);
327 * - RemoveAll(@b false) internally works as the below code:
329 * DeleterFunctionType deleter = GetDeleter();
330 * SetDeleter(NoOpDeleter);
332 * SetDeleter(deleter);
335 void RemoveAll(bool forceDeletion)
337 DeleterFunctionType deleter = GetDeleter();
341 SetDeleter(SingleObjectDeleter);
345 SetDeleter(NoOpDeleter);
353 * Removes all the object pointers in the collection. @n
354 * This method can be called before deleting the collection.
358 virtual void RemoveAll(void) = 0;
361 * Replaces the specified value associated with the specified key with a new value.
365 * @return An error code
366 * @param[in] key The key for which the associated value needs to replace
367 * @param[in] value The value associated with the key
368 * @param[in] newValue The new value
369 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
371 * @exception E_SUCCESS The method is successful.
372 * @exception E_INVALID_ARG A specified input parameter is invalid, or
373 * the comparer has failed to compare the keys.
374 * @exception E_OBJ_NOT_FOUND The key-value pair is not found in the map.
376 * - Use the Add(Object*, Object*) method to add a new key-value pair.
377 * - 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
378 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the set method. @n
379 * If both an element deleter and forceDeleteion are set, the set operation follows @c forceDeletion setting.
380 * - SetValue(key, value, newValue, @b true) internally works as the below code:
382 * DeleterFunctionType deleter = GetDeleter();
383 * SetDeleter(SingleObjectDeleter);
384 * SetValue(key, value, const_cast< Object* >(&newValue));
385 * SetDeleter(deleter);
387 * - SetValue(key, value, newValue, @b false) internally works as the below code:
389 * DeleterFunctionType deleter = GetDeleter();
390 * SetDeleter(NoOpDeleter);
391 * SetValue(key, value, const_cast< Object* >(&newValue));
392 * SetDeleter(deleter);
396 result SetValue(const Object& key, const Object& value, const Object& newValue, bool forceDeletion = false)
398 DeleterFunctionType deleter = GetDeleter();
402 SetDeleter(SingleObjectDeleter);
406 SetDeleter(NoOpDeleter);
409 result r = SetValue(key, value, const_cast< Object* >(&newValue));
415 * Replaces the specified value associated with the specified key with a new value.
419 * @return An error code
420 * @param[in] key The key for which the associated value needs to replace
421 * @param[in] value The value associated with the key
422 * @param[in] pNewValue The pointer to new value
423 * @exception E_SUCCESS The method is successful.
424 * @exception E_INVALID_ARG A specified input parameter is invalid, or
425 * the comparer has failed to compare the keys.
426 * @exception E_OBJ_NOT_FOUND The key-value pair is not found in the map.
427 * @remarks Use the Add(Object*, Object*) method to add a new key-value pair.
430 virtual result SetValue(const Object& key, const Object& value, Object* pNewValue) = 0;
434 * Checks whether the map contains the specified key-value pair.
436 * @brief <i> [Deprecated] </i>
437 * @deprecated This method is deprecated because it transfers a result of comparison in out-parameter form.
438 * The return type will be changed into boolean type and this method will return the result.
439 * Instead of using this method, use bool Contains(const Object& key, const Object& value).
442 * @return An error code
443 * @param[in] key The key to locate
444 * @param[in] value The value to locate
445 * @param[out] out Set to @c true if the map contains the specified key-value pair, @n
447 * @exception E_SUCCESS The method is successful.
448 * @exception E_INVALID_ARG A specified input parameter is invalid, or
449 * the comparer has failed to compare the keys.
451 * @see ContainsValue()
454 result Contains(const Object& key, const Object& value, bool& out) const
456 out = Contains(key, value);
457 result r = GetLastResult();
462 * Checks whether the map contains the specified key-value pair.
466 * @return @c true if the map contains the specified key-value pair, @n
468 * @param[in] key The key to locate
469 * @param[in] value The value to locate
470 * @exception E_SUCCESS The method is successful.
471 * @exception E_INVALID_ARG A specified input parameter is invalid, or
472 * the comparer has failed to compare the keys.
473 * @remarks The specific error code can be accessed using the GetLastResult() method.
474 * @see ContainsKey(const Object&) const
475 * @see ContainsValue()
477 virtual bool Contains(const Object& key, const Object& value) const = 0;
481 * Checks whether the map contains the specified key.
483 * @brief <i> [Deprecated] </i>
484 * @deprecated This method is deprecated because it transfers a result of comparison in out-parameter form.
485 * The return type will be changed into boolean type and this method will return the result.
486 * Instead of using this method, use bool ContainsKey(const Object& key).
489 * @return An error code
490 * @param[in] key The key to locate
491 * @param[out] out Set to @c true if the map contains the specified key, @n
493 * @exception E_SUCCESS The method is successful.
494 * @exception E_INVALID_ARG A specified input parameter is invalid, or
495 * the comparer has failed to compare the keys.
496 * @see ContainsValue()
497 * @see Contains(const Object&, const Object&)
500 result ContainsKey(const Object& key, bool& out) const
502 out = ContainsKey(key);
503 result r = GetLastResult();
508 * Checks whether the map contains the specified key.
512 * @return @c true if the map contains the specified key, @n
514 * @param[in] key The key to locate
515 * @exception E_SUCCESS The method is successful.
516 * @exception E_INVALID_ARG A specified input parameter is invalid, or
517 * the comparer has failed to compare the keys.
518 * @remarks The specific error code can be accessed using the GetLastResult() method.
519 * @see ContainsValue()
520 * @see Contains(const Object&, const Object&) const
522 virtual bool ContainsKey(const Object& key) const = 0;
525 * Checks whether the map contains the specified value.
529 * @return @c true if the map contains the specified value, @n
531 * @param[in] value The value to locate
533 * @see ContainsKey(const Object&) const
534 * @see Contains(const Object&, const Object&) const
536 virtual bool ContainsValue(const Object& value) const = 0;
539 * Gets an enumerator of the map.
543 * @return An instance of the IMapEnumerator class for the map, @n
544 * else @c null if an exception occurs
545 * @exception E_SUCCESS The method is successful.
547 * - If a key has multiple values, the enumeration proceeds as follows: @n
548 * {A: a}, {B: b}, {B: c}, {B, d}, {C: e}, ...
549 * - The specific error code can be accessed using the GetLastResult() method.
551 * @see IMapEnumerator
553 virtual IMapEnumerator* GetMapEnumeratorN(void) const = 0;
556 * Gets the element deleter of the collection.
560 * @return A function pointer to the existing element deleter
562 virtual DeleterFunctionType GetDeleter(void) const = 0;
566 // This method is for internal use only. Using this method can cause behavioral, security-related,
567 // and consistency-related issues in the application.
568 // This method is reserved and may change its name at any time without prior notice.
572 virtual void IMultiMap_Reserved1(void) { }
575 // This method is for internal use only. Using this method can cause behavioral, security-related,
576 // and consistency-related issues in the application.
577 // This method is reserved and may change its name at any time without prior notice.
581 virtual void IMultiMap_Reserved2(void) { }
585 * Sets the element deleter of the collection.
589 * @param[in] deleter A function pointer to the element deleter to set
591 virtual void SetDeleter(DeleterFunctionType deleter) = 0;
595 }}} // Tizen::Base::Collection
597 #endif // _FBASE_COL_IMULTI_MAP_H_