X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=inc%2FFBaseColIMap.h;h=b7593f818143c71ed812524a165e2c44156dc666;hb=ebb2ea372f640b8fe09dc5a85abb29bb349508fa;hp=cc2992faf95e21d2d6d73b28e126f6a6e520717b;hpb=82b12189e86e28bec1626c18c634de595c42462c;p=platform%2Fframework%2Fnative%2Fappfw.git diff --git a/inc/FBaseColIMap.h b/inc/FBaseColIMap.h index cc2992f..b7593f8 100644 --- a/inc/FBaseColIMap.h +++ b/inc/FBaseColIMap.h @@ -28,7 +28,6 @@ #include #include - namespace Tizen { namespace Base { namespace Collection { @@ -36,12 +35,12 @@ class IList; class MapEntry; /** - * @interface IMap - * @brief This interface represents a collection of key-value pairs. + * @interface IMap + * @brief This interface represents a collection of key-value pairs. * * @since 2.0 * - * The %IMap interface abstracts a collection of key-value pairs. An %IMap instance + * The %IMap interface represents a collection of key-value pairs. An %IMap instance * contains unique keys and each key maps to a single value. * The key and value cannot be a @c null reference. * @@ -64,18 +63,19 @@ public: * Adds the specified key-value pair to the map. * * @brief [Deprecated] - * @deprecated This method is deprecated because it has a problem of const reference argument. + * @deprecated This method is deprecated because it has a problem of constant reference argument. * Instead of using this method, use Add(Object* pKey, Object* pValue). * @since 2.0 * * @return An error code - * @param[in] key The key to add - * @param[in] value The corresponding value to add + * @param[in] key The key to add + * @param[in] value The corresponding value to add * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The comparer has failed to compare the keys. * @exception E_OBJ_ALREADY_EXIST The specified @c key already exists. - * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself. + * @remarks This method performs a shallow copy. It adds just the pointer and not the element itself. * @see Remove() * @endif */ @@ -90,29 +90,31 @@ public: * @since 2.0 * * @return An error code - * @param[in] pKey The pointer to key to add - * @param[in] pValue The pointer to corresponding value to add + * @param[in] pKey A pointer to the key to add + * @param[in] pValue A pointer to the corresponding value to add * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The comparer has failed to compare the keys. * @exception E_OBJ_ALREADY_EXIST The specified @c pKey already exists. - * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself. + * @remarks This method performs a shallow copy. It adds just the pointer and not the element itself. * @see Remove() */ virtual result Add(Object* pKey, Object* pValue) = 0; /** - * Checks if the key exists. If the key does not exist, Add() is called. Unless, SetValue() is called. + * Checks whether the key exists. If the key does not exist, the Add() method is called. Unless, the SetValue() method is called. * * @since 2.0 * * @return An error code - * @param[in] pKey The pointer to key to add - * @param[in] pValue The pointer to corresponding value to add + * @param[in] pKey A pointer to the key to add + * @param[in] pValue A pointer to the corresponding value to add * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. - * @remarks This method performs a shallow copy. It adds just the pointer; not the element itself. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The comparer has failed to compare the keys. + * @remarks This method performs a shallow copy. It adds just the pointer and not the element itself. * @see Add(Object*, Object*) * @see SetValue() */ @@ -129,34 +131,36 @@ public: } /** - * Gets the value associated with the specified key. + * Gets the value associated to the specified @c key. * * @since 2.0 * - * @return The value associated with the specified key, @n + * @return The value associated to the specified key, @n * else @c null if an exception occurs - * @param[in] key The key to find the associated value + * @param[in] key The key used to find the associated value * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG The specified input parameter is invalid, or - * the comparer has failed to compare the keys. - * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - The specified input parameter is invalid. + * - The comparer has failed to compare the keys. + * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map. * @remarks The specific error code can be accessed using the GetLastResult() method. * @see SetValue() */ virtual const Object* GetValue(const Object& key) const = 0; /** - * Gets the value associated with the specified key. + * Gets the value associated to the specified @c key. * * @since 2.0 * - * @return The value associated with the specified key, @n + * @return The value associated to the specified key, @n * else @c null if an exception occurs - * @param[in] key The key to find the associated value + * @param[in] key The key used to find the associated value * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG The specified input parameter is invalid, or - * the comparer has failed to compare the keys. - * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - The specified input parameter is invalid. + * - The comparer has failed to compare the keys. + * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map. * @remarks The specific error code can be accessed using the GetLastResult() method. * @see SetValue() */ @@ -167,47 +171,47 @@ public: * * @since 2.0 * - * @return A pointer to a list of all the keys in the map, @n + * @return A pointer to the list of all the keys in the map, @n * else @c null if an exception occurs - * @remarks + * @remarks * - The order of the keys is the same as the corresponding values in the IList interface returned by the GetValuesN() method. - * - The %IList interface stores just the pointers to the elements in the map, not the elements themselves. + * - The %IList interface stores just the pointers to the elements in the map and not the elements themselves. * - The specific error code can be accessed using the GetLastResult() method. - * @see GetValuesN() */ virtual IList* GetKeysN(void) const = 0; /** - * Gets a list of all the values in the map. + * Gets the list of all the values in the map. * * @since 2.0 * - * @return A pointer to a list of all the values in the map, @n + * @return A pointer to the list of all the values in the map, @n * else @c null if an exception occurs - * @remarks - * - The IList stores just the pointers to the elements in the map, not the elements themselves. + * @remarks + * - The IList interface stores just the pointers to the elements in the map and not the elements themselves. * - The specific error code can be accessed using the GetLastResult() method. * @see GetKeysN() */ virtual IList* GetValuesN(void) const = 0; /** - * Removes the value associated with the specified key. + * Removes the value associated to the specified @c key. * * @since 2.0 * * @return An error code - * @param[in] key The key to remove - * @param[in] forceDeletion Set to @c true to deallocate the object, @n + * @param[in] key The key to remove + * @param[in] forceDeletion Set to @c true to deallocate the object, @n * else @c false * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. - * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map. - * @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 - * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n - * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The comparer has failed to compare the keys. + * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map. + * @remarks + * - 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 + * The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n + * If both the element deleter and the @c forceDeletion are set, the remove operation follows the @c forceDeletion setting. * - Remove(key, @b true) internally works as the below code: * @code * DeleterFunctionType deleter = GetDeleter(); @@ -243,32 +247,33 @@ public: } /** - * Removes the value associated with the specified key. + * Removes the value associated to the specified @c key. * * @since 2.0 * * @return An error code - * @param[in] key The key for which the value is to remove + * @param[in] key The key for which the value is removed * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. - * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - The specified input parameter is invalid. + * - The comparer has failed to compare the keys. + * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map. * @see Add(Object*, Object*) */ virtual result Remove(const Object& key) = 0; /** * Removes all the object pointers in the collection. @n - * 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. + * 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. * * @since 2.0 * * @param[in] forceDeletion Set to @c true to deallocate all the objects, @n - * else @c false - * @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 - * The element deleter style is recommended rather than using the @c forceDeletetion argument in the remove method. @n - * If both an element deleter and forceDeleteion are set, the remove operation follows @c forceDeletion setting. + * else @c false + * @remarks + * - 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 + * The element deleter style is recommended rather than using @c forceDeletetion in the removing method. @n + * If both the element deleter and the @c forceDeletion are set, the remove operation follows the @c forceDeletion setting. * - RemoveAll(@b true) internally works as the below code: * @code * DeleterFunctionType deleter = GetDeleter(); @@ -302,31 +307,32 @@ public: } /** - * Removes all the object pointers in the collection. @n + * Removes all the object pointers from the collection. @n * * @since 2.0 */ virtual void RemoveAll(void) = 0; /** - * Replaces the value associated with the specified key with the specified value. + * Replaces the value associated to the specified @c key with the specified @c value. * * @since 2.0 * * @return An error code - * @param[in] key The key for which the value is to replace - * @param[in] value The new value + * @param[in] key The key for which the value is replaced + * @param[in] value The new value * @param[in] forceDeletion Set to @c true to deallocate the object, @n - * else @c false - * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. - * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map. - * @remarks + * else @c false + * @exception E_SUCCESS The method is successful. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The comparer has failed to compare the keys. + * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map. + * @remarks * - Use the Add(Object*, Object*) method to add a new key-value pair. - * - 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 - * The element deleter style is recommended rather than using the @c forceDeletetion argument in the set method. @n - * If both an element deleter and forceDeleteion are set, the set operation follows @c forceDeletion setting. + * - 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 + * The element deleter style is recommended rather than using @c forceDeletetion in the set method. @n + * If both the element deleter and the @c forceDeletion are set, the set operation follows the @c forceDeletion setting. * - SetValue(key, value, @b true) internally works as the below code: * @code * DeleterFunctionType deleter = GetDeleter(); @@ -362,39 +368,41 @@ public: } /** - * Replaces the value associated with the specified key with the specified value. + * Replaces the value associated to the specified @c key with the specified @c value. * * @since 2.0 * * @return An error code - * @param[in] key The key for which the value is to replace - * @param[in] pValue The pointer to new value + * @param[in] key The key for which the value is replaced + * @param[in] pValue A pointer to the new value * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. - * @exception E_OBJ_NOT_FOUND The specified @c key is not found in the map. - * @remarks Use the Add(Object*, Object*) method to add a new key-value pair. - * @see GetValue() + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The comparer has failed to compare the keys. + * @exception E_OBJ_NOT_FOUND The specified @c key has not been found in the map. + * @remarks Use the Add(Object*, Object*) method to add a new key-value pair. + * @see GetValue() */ virtual result SetValue(const Object& key, Object* pValue) = 0; /** * @if OSPDEPREC - * Checks whether the map contains the specified key. + * Checks whether the map contains the specified @c key. * * @brief [Deprecated] - * @deprecated This method is deprecated because it transfers a result of comparison in out-parameter form. - * The return type will be changed into boolean type and this method will return the result. + * @deprecated This method is deprecated because it transfers the result of the comparison in an out-parameter form. + * The return type is changed into boolean and this method returns the result. * Instead of using this method, use bool ContainsKey(const Object& key). * @since 2.0 * * @return An error code - * @param[in] key The key to locate - * @param[out] out Set to @c true if the map contains the specified key, @n - * else @c false + * @param[in] key The key to locate + * @param[out] out Set to @c true if the map contains the specified key, @n + * else @c false * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - A specified input parameter is invalid. + * - The comparer has failed to compare the keys. * @see ContainsValue() * @endif */ @@ -406,23 +414,24 @@ public: } /** - * Checks whether the map contains the specified key. + * Checks whether the map contains the specified @c key. * * @since 2.0 * * @return @c true if the map contains the specified key, @n * else @c false - * @param[in] key The key to locate + * @param[in] key The key to locate * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG A specified input parameter is invalid, or - * the comparer has failed to compare the keys. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - The specified input parameter is invalid. + * - The comparer has failed to compare the keys. * @remarks The specific error code can be accessed using the GetLastResult() method. * @see ContainsValue() */ virtual bool ContainsKey(const Object& key) const = 0; /** - * Checks whether the map contains the specified value. + * Checks whether the map contains the specified @c value. * * @since 2.0 * @@ -435,16 +444,15 @@ public: virtual bool ContainsValue(const Object& value) const = 0; /** - * Gets an instance of the IMapEnumerator for the map. + * Gets an instance of IMapEnumerator for the map. * * @since 2.0 * - * @return IMapEnumerator object of this map, @n + * @return An instance of IMapEnumerator for this map, @n * else @c null if an exception occurs * @exception E_SUCCESS The method is successful. * @remarks The specific error code can be accessed using the GetLastResult() method. * @see IEnumerator - * @see IMapEnumerator */ virtual IMapEnumerator* GetMapEnumeratorN(void) const = 0; @@ -467,7 +475,6 @@ protected: // virtual void IMap_Reserved1(void) { } - // // This method is for internal use only. Using this method can cause behavioral, security-related, // and consistency-related issues in the application.