1 /*

     2 * Copyright (c) 2002-2004 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Associative container.

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef CXNMAP_H

    21 #define CXNMAP_H

    22 

    23 //  INCLUDES

    24 #include <e32base.h>

    25 

    26 // CONSTANTS

    27 //const ?type ?constant_var = ?constant;

    28 

    29 // MACROS

    30 //#define ?macro ?macro_def

    31 

    32 // DATA TYPES

    33 //enum ?declaration

    34 //typedef ?declaration

    35 //extern ?data_type;

    36 

    37 // FUNCTION PROTOTYPES

    38 //?type ?function_name(?arg_list);

    39 

    40 // FORWARD DECLARATIONS

    41 //class ?FORWARD_CLASSNAME;

    42 class MXnComparator;

    43 // CLASS DECLARATION

    44 

    45 /**

    46 * @ingroup group_xnutils

    47 * 

    48 *  Associative container, works like a map or a hashtable

    49 *  @since Series 60 3.1

    50 */

    51 class CXnMap : public CBase

    52     {

    53     public:  // Constructors and destructor

    54         

    55         /**

    56         * Two-phased constructor.

    57         * @param aComparatorFunctor A comparator used for testing object equality. Must not be NULL. Map assumes ownership of the comparator.

    58         */

    59         IMPORT_C static CXnMap* NewL(MXnComparator* aComparatorFunctor);

    60 

    61         /**

    62         * Destructor.

    63         */

    64         virtual ~CXnMap();

    65         

    66     public: // New functions

    67         

    68         /**

    69         * Puts an object to the map. The map will assume ownership of the object. If an equal object is already in the map, it will be replaced with the new object and the old object will be destroyed.

    70         * @since Series 60 3.1

    71         * @param aObject Object to add. 

    72         * @exception KXnErrAppendingMapItemFailed_1 Appending new map item failed.

    73         * @exception KXnErrAppendingMapItemFailed_2 Appending new map item failed.

    74         */

    75 		IMPORT_C void PutL(CBase* aObject);

    76 

    77         /**

    78         * Gets an object from the map. The map will retain ownership of the object, the caller must not destroy the object. The returned pointer will become invalid if the object is replaced in the map by a subsequent PutL().

    79         * @since Series 60 3.1

    80         * @param aObject Object key

    81         * @return The object mapped to the key or NULL if not found. 

    82         */

    83 		IMPORT_C CBase* Get(CBase& aObject) const;

    84 

    85         /**

    86         * Gets access to the underlying container

    87         * @since Series 60 3.1

    88         * @return The undelying container

    89         */

    90 		IMPORT_C RPointerArray<CBase>& Container();

    91 

    92         /**

    93         * Find an object from the map. The map will retain ownership of the object, the caller must not destroy the object. The returned pointer will become invalid if the object is replaced in the map by a subsequent PutL().

    94         * @since Series 60 3.1

    95         * @param aObject Object key

    96 		* @param aComparator Comparator used for finding the object

    97         * @return The object mapped to the key matching the comparator or NULL if not found. 

    98         */

    99 		IMPORT_C CBase* Find(CBase& aObject, MXnComparator& aComparator) const;

   100 

   101 

   102     public: // Functions from base classes

   103 

   104         /**

   105         * From ?base_class ?member_description.

   106         * @since Series ?XX ?SeriesXX_version

   107         * @param ?arg1 ?description

   108         * @return ?description

   109         */

   110         //?type ?member_function( ?type ?arg1 );

   111         

   112     protected:  // New functions

   113         

   114         /**

   115         * ?member_description.

   116         * @since Series ?XX ?SeriesXX_version

   117         * @param ?arg1 ?description

   118         * @return ?description

   119         */

   120         //?type ?member_function( ?type ?arg1 );

   121 

   122 

   123     protected:  // Functions from base classes

   124         

   125         /**

   126         * From ?base_class ?member_description

   127         */

   128         //?type ?member_function();

   129 

   130     private:

   131 

   132         /**

   133         * C++ default constructor.

   134         */

   135         CXnMap();

   136 

   137         /**

   138         * 2nd phase constructor.

   139         * @param aComparatorFunctor A comparator used for testing object equality

   140         */

   141         void ConstructL(MXnComparator* aComparatorFunctor);

   142 

   143         // Prohibit copy constructor if not deriving from CBase.

   144         // ?classname( const ?classname& );

   145         // Prohibit assigment operator if not deriving from CBase.

   146         // ?classname& operator=( const ?classname& );

   147 

   148     public:     // Data

   149         // ?one_line_short_description_of_data

   150         //?data_declaration;

   151     

   152     protected:  // Data

   153         // ?one_line_short_description_of_data

   154         //?data_declaration;

   155 

   156     private:    // Data

   157         // ?one_line_short_description_of_data

   158         //?data_declaration;

   159         // Reserved pointer for future extension

   160         //TAny* iReserved;

   161         // Internal container

   162         RPointerArray<CBase> iContainer;

   163         // Comparator functor;

   164         MXnComparator* iComparator;

   165     public:     // Friend classes

   166         //?friend_class_declaration;

   167     protected:  // Friend classes

   168         //?friend_class_declaration;

   169     private:    // Friend classes

   170         //?friend_class_declaration;

   171 

   172     };

   173 

   174 #endif      // CXnMAP_H

   175             

   176 // End of File