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>
32 namespace Tizen { namespace Base { namespace Collection
40 * @brief This interface represents a collection of key-value pairs.
44 * The %IMap interface abstracts a collection of key-value pairs. An %IMap instance
45 * contains unique keys and each key maps to a single value.
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>.
50 class _OSP_EXPORT_ IMap
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 ~IMap(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 already exists.
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 already exists.
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 * Checks if the key exists. If the key does not exist, Add() is called. Unless, SetValue() is called.
109 * @return An error code
110 * @param[in] pKey The pointer to key to add
111 * @param[in] pValue The pointer to corresponding value to add
112 * @exception E_SUCCESS The method is successful.
113 * @exception E_INVALID_ARG A specified input parameter is invalid, or
114 * the comparer has failed to compare the keys.
115 * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself.
116 * @see Add(Object*, Object*)
119 result AddIfNotExistOrSet(Object* pKey, Object* pValue)
121 if (!ContainsKey(*pKey))
123 return Add(pKey, pValue);
127 return SetValue(*pKey, pValue);
132 * Gets the value associated with the specified key.
136 * @return The value associated with the specified key, @n
137 * else @c null if an exception occurs
138 * @param[in] key The key to find the associated value
139 * @exception E_SUCCESS The method is successful.
140 * @exception E_INVALID_ARG The specified input parameter is invalid, or
141 * the comparer has failed to compare the keys.
142 * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map.
143 * @remarks The specific error code can be accessed using the GetLastResult() method.
146 virtual const Object* GetValue(const Object& key) const = 0;
149 * Gets the value associated with the specified key.
153 * @return The value associated with the specified key, @n
154 * else @c null if an exception occurs
155 * @param[in] key The key to find the associated value
156 * @exception E_SUCCESS The method is successful.
157 * @exception E_INVALID_ARG The specified input parameter is invalid, or
158 * the comparer has failed to compare the keys.
159 * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map.
160 * @remarks The specific error code can be accessed using the GetLastResult() method.
163 virtual Object* GetValue(const Object& key) = 0;
166 * Gets a list of all the keys in the map.
170 * @return A pointer to a list of all the keys in the map, @n
171 * else @c null if an exception occurs
173 * - The order of the keys is the same as the corresponding values in the IList interface returned by the GetValuesN() method.
174 * - The %IList interface stores just the pointers to the elements in the map, not the elements themselves.
175 * - The specific error code can be accessed using the GetLastResult() method.
178 virtual IList* GetKeysN(void) const = 0;
181 * Gets a list of all the values in the map.
185 * @return A pointer to a list of all the values in the map, @n
186 * else @c null if an exception occurs
188 * - The IList stores just the pointers to the elements in the map, not the elements themselves.
189 * - The specific error code can be accessed using the GetLastResult() method.
192 virtual IList* GetValuesN(void) const = 0;
195 * Removes the value associated with the specified key.
199 * @return An error code
200 * @param[in] key The key to remove
201 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
203 * @exception E_SUCCESS The method is successful.
204 * @exception E_INVALID_ARG A specified input parameter is invalid, or
205 * the comparer has failed to compare the keys.
206 * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map.
208 * - 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
209 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
210 * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
211 * - Remove(key, @b true) internally works as the below code:
213 * DeleterFunctionType deleter = GetDeleter();
214 * SetDeleter(SingleObjectDeleter);
216 * SetDeleter(deleter);
218 * - Remove(key, @b false) internally works as the below code:
220 * DeleterFunctionType deleter = GetDeleter();
221 * SetDeleter(NoOpDeleter);
223 * SetDeleter(deleter);
225 * @see Add(Object*, Object*)
227 result Remove(const Object& key, bool forceDeletion)
229 DeleterFunctionType deleter = GetDeleter();
233 SetDeleter(SingleObjectDeleter);
237 SetDeleter(NoOpDeleter);
240 result r = Remove(key);
246 * Removes the value associated with the specified key.
250 * @return An error code
251 * @param[in] key The key for which the value is to remove
252 * @exception E_SUCCESS The method is successful.
253 * @exception E_INVALID_ARG A specified input parameter is invalid, or
254 * the comparer has failed to compare the keys.
255 * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map.
256 * @see Add(Object*, Object*)
258 virtual result Remove(const Object& key) = 0;
261 * Removes all the object pointers in the collection. @n
262 * 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.
266 * @param[in] forceDeletion Set to @c true to deallocate all the objects, @n
269 * - 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
270 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n
271 * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting.
272 * - RemoveAll(@b true) internally works as the below code:
274 * DeleterFunctionType deleter = GetDeleter();
275 * SetDeleter(SingleObjectDeleter);
277 * SetDeleter(deleter);
279 * - RemoveAll(@b false) internally works as the below code:
281 * DeleterFunctionType deleter = GetDeleter();
282 * SetDeleter(NoOpDeleter);
284 * SetDeleter(deleter);
287 void RemoveAll(bool forceDeletion)
289 DeleterFunctionType deleter = GetDeleter();
293 SetDeleter(SingleObjectDeleter);
297 SetDeleter(NoOpDeleter);
305 * Removes all the object pointers in the collection. @n
309 virtual void RemoveAll(void) = 0;
312 * Replaces the value associated with the specified key with the specified value.
316 * @return An error code
317 * @param[in] key The key for which the value is to replace
318 * @param[in] value The new value
319 * @param[in] forceDeletion Set to @c true to deallocate the object, @n
321 * @exception E_SUCCESS The method is successful.
322 * @exception E_INVALID_ARG A specified input parameter is invalid, or
323 * the comparer has failed to compare the keys.
324 * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map.
326 * - Use the Add(Object*, Object*) method to add a new key-value pair.
327 * - 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
328 * The element deleter style is recommended rather than using the @c forceDeletetion argument in the set method. @n
329 * If both an element deleter and forceDeleteion are set, the set operation follows @c forceDeletion setting.
330 * - SetValue(key, value, @b true) internally works as the below code:
332 * DeleterFunctionType deleter = GetDeleter();
333 * SetDeleter(SingleObjectDeleter);
334 * SetValue(key, const_cast< Object* >(&value));
335 * SetDeleter(deleter);
337 * - SetValue(key, value, @b false) internally works as the below code:
339 * DeleterFunctionType deleter = GetDeleter();
340 * SetDeleter(NoOpDeleter);
341 * SetValue(key, const_cast< Object* >(&value));
342 * SetDeleter(deleter);
346 result SetValue(const Object& key, const Object& value, bool forceDeletion = false)
348 DeleterFunctionType deleter = GetDeleter();
352 SetDeleter(SingleObjectDeleter);
356 SetDeleter(NoOpDeleter);
359 result r = SetValue(key, const_cast< Object* >(&value));
365 * Replaces the value associated with the specified key with the specified value.
369 * @return An error code
370 * @param[in] key The key for which the value is to replace
371 * @param[in] pValue The pointer to new value
372 * @exception E_SUCCESS The method is successful.
373 * @exception E_INVALID_ARG A specified input parameter is invalid, or
374 * the comparer has failed to compare the keys.
375 * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map.
376 * @remarks Use the Add(Object*, Object*) method to add a new key-value pair.
379 virtual result SetValue(const Object& key, Object* pValue) = 0;
383 * Checks whether the map contains the specified key.
385 * @brief <i> [Deprecated] </i>
386 * @deprecated This method is deprecated because it transfers a result of comparison in out-parameter form.
387 * The return type will be changed into boolean type and this method will return the result.
388 * Instead of using this method, use bool ContainsKey(const Object& key).
391 * @return An error code
392 * @param[in] key The key to locate
393 * @param[out] out Set to @c true if the map contains the specified key, @n
395 * @exception E_SUCCESS The method is successful.
396 * @exception E_INVALID_ARG A specified input parameter is invalid, or
397 * the comparer has failed to compare the keys.
398 * @see ContainsValue()
401 result ContainsKey(const Object& key, bool& out) const
403 out = ContainsKey(key);
404 result r = GetLastResult();
409 * Checks whether the map contains the specified key.
413 * @return @c true if the map contains the specified key, @n
415 * @param[in] key The key to locate
416 * @exception E_SUCCESS The method is successful.
417 * @exception E_INVALID_ARG A specified input parameter is invalid, or
418 * the comparer has failed to compare the keys.
419 * @remarks The specific error code can be accessed using the GetLastResult() method.
420 * @see ContainsValue()
422 virtual bool ContainsKey(const Object& key) const = 0;
425 * Checks whether the map contains the specified value.
429 * @return @c true if the map contains the specified value, @n
431 * @param[in] value The value to locate
433 * @see ContainsKey(const Object&)
435 virtual bool ContainsValue(const Object& value) const = 0;
438 * Gets an instance of the IMapEnumerator for the map.
442 * @return IMapEnumerator object of this map, @n
443 * else @c null if an exception occurs
444 * @exception E_SUCCESS The method is successful.
445 * @remarks The specific error code can be accessed using the GetLastResult() method.
447 * @see IMapEnumerator
449 virtual IMapEnumerator* GetMapEnumeratorN(void) const = 0;
452 * Gets the element deleter of the collection.
456 * @return A function pointer to the existing element deleter
458 virtual DeleterFunctionType GetDeleter(void) const = 0;
462 // This method is for internal use only. Using this method can cause behavioral, security-related,
463 // and consistency-related issues in the application.
464 // This method is reserved and may change its name at any time without prior notice.
468 virtual void IMap_Reserved1(void) { }
472 // This method is for internal use only. Using this method can cause behavioral, security-related,
473 // and consistency-related issues in the application.
474 // This method is reserved and may change its name at any time without prior notice.
478 virtual void IMap_Reserved2(void) { }
482 * Sets the element deleter of the collection.
486 * @param[in] deleter A function pointer to the element deleter to set
488 virtual void SetDeleter(DeleterFunctionType deleter) = 0;
492 }}} // Tizen::Base::Collection
494 #endif // _FBASE_COL_IMAP_H_