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 FBaseColIMap.h
19 * @brief This is the header file for the %IMap interface.
21 * This header file contains the declarations of the %IMap interface.
23 #ifndef _FBASE_COL_IMAP_H_
24 #define _FBASE_COL_IMAP_H_
26 #include <FBaseColICollection.h>
27 #include <FBaseColTypes.h>
28 #include <FBaseColIMapEnumerator.h>
29 #include <FBaseObject.h>
31 namespace Tizen { namespace Base { namespace Collection
39 * @brief This interface represents a collection of key-value pairs.
43 * The %IMap interface represents a collection of key-value pairs. An %IMap instance
44 * contains unique keys and each key maps to a single value.
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>.
49 class _OSP_EXPORT_ IMap
50 : public virtual ICollection
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 ~IMap(void) {}
63 * Adds the specified key-value pair to the map.
65 * @brief <i> [Deprecated] </i>
66 * @deprecated This method is deprecated because it has a problem of constant reference argument.
67 * Instead of using this method, use Add(Object* pKey, Object* pValue).
70 * @return An error code
71 * @param[in] key The key to add
72 * @param[in] value The corresponding value to add
73 * @exception E_SUCCESS The method is successful.
74 * @exception E_INVALID_ARG Either of the following conditions has occurred:
75 * - A specified input parameter is invalid.
76 * - The comparer has failed to compare the keys.
77 * @exception E_OBJ_ALREADY_EXIST The specified @c key already exists.
78 * @remarks This method performs a shallow copy. It adds just the pointer and 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 A pointer to the key to add
94 * @param[in] pValue A pointer to the corresponding value to add
95 * @exception E_SUCCESS The method is successful.
96 * @exception E_INVALID_ARG Either of the following conditions has occurred:
97 * - A specified input parameter is invalid.
98 * - The comparer has failed to compare the keys.
99 * @exception E_OBJ_ALREADY_EXIST The specified @c pKey already exists.
100 * @remarks This method performs a shallow copy. It adds just the pointer and not the element itself.
103 virtual result Add(Object* pKey, Object* pValue) = 0;
106 * Checks whether the key exists. If the key does not exist, the Add() method is called. Unless, the SetValue() method is called.
110 * @return An error code
111 * @param[in] pKey A pointer to the key to add
112 * @param[in] pValue A pointer to the corresponding value to add
113 * @exception E_SUCCESS The method is successful.
114 * @exception E_INVALID_ARG Either of the following conditions has occurred:
115 * - A specified input parameter is invalid.
116 * - The comparer has failed to compare the keys.
117 * @remarks This method performs a shallow copy. It adds just the pointer and not the element itself.
118 * @see Add(Object*, Object*)
121 result AddIfNotExistOrSet(Object* pKey, Object* pValue)
123 if (!ContainsKey(*pKey))
125 return Add(pKey, pValue);
129 return SetValue(*pKey, pValue);
134 * Gets the value associated to the specified @c key.
138 * @return The value associated to the specified key, @n
139 * else @c null if an exception occurs
140 * @param[in] key The key used to find the associated value
141 * @exception E_SUCCESS The method is successful.
142 * @exception E_INVALID_ARG Either of the following conditions has occurred:
143 * - The specified input parameter is invalid.
144 * - The comparer has failed to compare the keys.
145 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
146 * @remarks The specific error code can be accessed using the GetLastResult() method.
149 virtual const Object* GetValue(const Object& key) const = 0;
152 * Gets the value associated to the specified @c key.
156 * @return The value associated to the specified key, @n
157 * else @c null if an exception occurs
158 * @param[in] key The key used to find the associated value
159 * @exception E_SUCCESS The method is successful.
160 * @exception E_INVALID_ARG Either of the following conditions has occurred:
161 * - The specified input parameter is invalid.
162 * - The comparer has failed to compare the keys.
163 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
164 * @remarks The specific error code can be accessed using the GetLastResult() method.
167 virtual Object* GetValue(const Object& key) = 0;
170 * Gets a list of all the keys in the map.
174 * @return A pointer to the list of all the keys in the map, @n
175 * else @c null if an exception occurs
177 * - The order of the keys is the same as the corresponding values in the IList interface returned by the GetValuesN() method.
178 * - The %IList interface stores just the pointers to the elements in the map and not the elements themselves.
179 * - The specific error code can be accessed using the GetLastResult() method.
181 virtual IList* GetKeysN(void) const = 0;
184 * Gets the list of all the values in the map.
188 * @return A pointer to the list of all the values in the map, @n
189 * else @c null if an exception occurs
191 * - The IList interface stores just the pointers to the elements in the map and not the elements themselves.
192 * - The specific error code can be accessed using the GetLastResult() method.
195 virtual IList* GetValuesN(void) const = 0;
198 * Removes the value associated to the specified @c key.
202 * @return An error code
203 * @param[in] key The key to remove
204 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
206 * @exception E_SUCCESS The method is successful.
207 * @exception E_INVALID_ARG Either of the following conditions has occurred:
208 * - A specified input parameter is invalid.
209 * - The comparer has failed to compare the keys.
210 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
212 * - 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
213 * The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
214 * If both the element deleter and the @c forceDeletion are set, the remove operation follows the @c forceDeletion setting.
215 * - Remove(key, @b true) internally works as the below code:
217 * DeleterFunctionType deleter = GetDeleter();
218 * SetDeleter(SingleObjectDeleter);
220 * SetDeleter(deleter);
222 * - Remove(key, @b false) internally works as the below code:
224 * DeleterFunctionType deleter = GetDeleter();
225 * SetDeleter(NoOpDeleter);
227 * SetDeleter(deleter);
229 * @see Add(Object*, Object*)
231 result Remove(const Object& key, bool forceDeletion)
233 DeleterFunctionType deleter = GetDeleter();
237 SetDeleter(SingleObjectDeleter);
241 SetDeleter(NoOpDeleter);
244 result r = Remove(key);
250 * Removes the value associated to the specified @c key.
254 * @return An error code
255 * @param[in] key The key for which the value is removed
256 * @exception E_SUCCESS The method is successful.
257 * @exception E_INVALID_ARG Either of the following conditions has occurred:
258 * - The specified input parameter is invalid.
259 * - The comparer has failed to compare the keys.
260 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
261 * @see Add(Object*, Object*)
263 virtual result Remove(const Object& key) = 0;
266 * Removes all the object pointers in the collection. @n
267 * If @c forceDeletion is set to @c true, the method also removes all the objects. The %RemoveAll() method can be called before deleting the collection.
271 * @param[in] forceDeletion Set to @c true to deallocate all the objects, @n
274 * - 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
275 * The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n
276 * If both the element deleter and the @c forceDeletion are set, the remove operation follows the @c forceDeletion setting.
277 * - RemoveAll(@b true) internally works as the below code:
279 * DeleterFunctionType deleter = GetDeleter();
280 * SetDeleter(SingleObjectDeleter);
282 * SetDeleter(deleter);
284 * - RemoveAll(@b false) internally works as the below code:
286 * DeleterFunctionType deleter = GetDeleter();
287 * SetDeleter(NoOpDeleter);
289 * SetDeleter(deleter);
292 void RemoveAll(bool forceDeletion)
294 DeleterFunctionType deleter = GetDeleter();
298 SetDeleter(SingleObjectDeleter);
302 SetDeleter(NoOpDeleter);
310 * Removes all the object pointers from the collection. @n
314 virtual void RemoveAll(void) = 0;
317 * Replaces the value associated to the specified @c key with the specified @c value.
321 * @return An error code
322 * @param[in] key The key for which the value is replaced
323 * @param[in] value The new value
324 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
326 * @exception E_SUCCESS The method is successful.
327 * @exception E_INVALID_ARG Either of the following conditions has occurred:
328 * - A specified input parameter is invalid.
329 * - The comparer has failed to compare the keys.
330 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
332 * - Use the Add(Object*, Object*) method to add a new key-value pair.
333 * - 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
334 * The element deleter style is recommended rather than using @c forceDeletetion in the set method. @n
335 * If both the element deleter and the @c forceDeletion are set, the set operation follows the @c forceDeletion setting.
336 * - SetValue(key, value, @b true) internally works as the below code:
338 * DeleterFunctionType deleter = GetDeleter();
339 * SetDeleter(SingleObjectDeleter);
340 * SetValue(key, const_cast< Object* >(&value));
341 * SetDeleter(deleter);
343 * - SetValue(key, value, @b false) internally works as the below code:
345 * DeleterFunctionType deleter = GetDeleter();
346 * SetDeleter(NoOpDeleter);
347 * SetValue(key, const_cast< Object* >(&value));
348 * SetDeleter(deleter);
352 result SetValue(const Object& key, const Object& value, bool forceDeletion = false)
354 DeleterFunctionType deleter = GetDeleter();
358 SetDeleter(SingleObjectDeleter);
362 SetDeleter(NoOpDeleter);
365 result r = SetValue(key, const_cast< Object* >(&value));
371 * Replaces the value associated to the specified @c key with the specified @c value.
375 * @return An error code
376 * @param[in] key The key for which the value is replaced
377 * @param[in] pValue A pointer to the new value
378 * @exception E_SUCCESS The method is successful.
379 * @exception E_INVALID_ARG Either of the following conditions has occurred:
380 * - A specified input parameter is invalid.
381 * - The comparer has failed to compare the keys.
382 * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map.
383 * @remarks Use the Add(Object*, Object*) method to add a new key-value pair.
386 virtual result SetValue(const Object& key, Object* pValue) = 0;
390 * Checks whether the map contains the specified @c key.
392 * @brief <i> [Deprecated] </i>
393 * @deprecated This method is deprecated because it transfers the result of the comparison in an out-parameter form.
394 * The return type is changed into boolean and this method returns the result.
395 * Instead of using this method, use bool ContainsKey(const Object& key).
398 * @return An error code
399 * @param[in] key The key to locate
400 * @param[out] out Set to @c true if the map contains the specified key, @n
402 * @exception E_SUCCESS The method is successful.
403 * @exception E_INVALID_ARG Either of the following conditions has occurred:
404 * - A specified input parameter is invalid.
405 * - The comparer has failed to compare the keys.
406 * @see ContainsValue()
409 result ContainsKey(const Object& key, bool& out) const
411 out = ContainsKey(key);
412 result r = GetLastResult();
417 * Checks whether the map contains the specified @c key.
421 * @return @c true if the map contains the specified key, @n
423 * @param[in] key The key to locate
424 * @exception E_SUCCESS The method is successful.
425 * @exception E_INVALID_ARG Either of the following conditions has occurred:
426 * - The specified input parameter is invalid.
427 * - The comparer has failed to compare the keys.
428 * @remarks The specific error code can be accessed using the GetLastResult() method.
429 * @see ContainsValue()
431 virtual bool ContainsKey(const Object& key) const = 0;
434 * Checks whether the map contains the specified @c value.
438 * @return @c true if the map contains the specified value, @n
440 * @param[in] value The value to locate
442 * @see ContainsKey(const Object&)
444 virtual bool ContainsValue(const Object& value) const = 0;
447 * Gets an instance of IMapEnumerator for the map.
451 * @return An instance of IMapEnumerator for this map, @n
452 * else @c null if an exception occurs
453 * @exception E_SUCCESS The method is successful.
454 * @remarks The specific error code can be accessed using the GetLastResult() method.
457 virtual IMapEnumerator* GetMapEnumeratorN(void) const = 0;
460 * Gets the element deleter of the collection.
464 * @return A function pointer to the existing element deleter
466 virtual DeleterFunctionType GetDeleter(void) const = 0;
470 // This method is for internal use only. Using this method can cause behavioral, security-related,
471 // and consistency-related issues in the application.
472 // This method is reserved and may change its name at any time without prior notice.
476 virtual void IMap_Reserved1(void) { }
479 // This method is for internal use only. Using this method can cause behavioral, security-related,
480 // and consistency-related issues in the application.
481 // This method is reserved and may change its name at any time without prior notice.
485 virtual void IMap_Reserved2(void) { }
489 * Sets the element deleter of the collection.
493 * @param[in] deleter A function pointer to the element deleter to set
495 virtual void SetDeleter(DeleterFunctionType deleter) = 0;
499 }}} // Tizen::Base::Collection
501 #endif // _FBASE_COL_IMAP_H_