sl@0: // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // RMap template class implementation.
sl@0: // 
sl@0: //
sl@0: 
sl@0: /**
sl@0:  
sl@0:  Template function that compares two objects of type TPair<KEY, DATA> and
sl@0:  returns {negative, 0, positive} depending on the comparison result.
sl@0:  In order the comparison to work, the KEY template parameter has to have
sl@0:  "-" operation defined - either native or overloaded "-" operator.
sl@0:  Used by RMap<KEY, DATA> template class.
sl@0:  Note: This template function works only on objects, which have defined a "-" operation.
sl@0:  @param aLeft The first TPair<KEY, DATA> to be compared
sl@0:  @param aRight The second TPair<KEY, DATA> to be compared
sl@0:  @return An integer value, which is:
sl@0:  0, if the objects are equal;
sl@0:  negative number, the first object is bigger than the second object
sl@0:  positive number, the first object is smaller than the second object
sl@0:  @internalComponent
sl@0: */
sl@0: template <class KEY, class DATA>
sl@0: TInt Compare(const TPair<KEY, DATA>& aLeft, const TPair<KEY, DATA>& aRight)
sl@0: 	{
sl@0: 	return aRight.iKey - aLeft.iKey;
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @param aKey Key part of TPair object
sl@0: @param aData Data part of TPair object
sl@0: */
sl@0: template <class KEY, class DATA> 
sl@0: TPair<KEY, DATA>::TPair(const KEY& aKey, const DATA& aData) :
sl@0: 	iKey(aKey),
sl@0: 	iData(aData)
sl@0: 	{
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @param aKey Key part of TPair object
sl@0: */
sl@0: template <class KEY, class DATA> 
sl@0: TPair<KEY, DATA>::TPair(const KEY& aKey) :
sl@0: 	iKey(aKey)
sl@0: 	{
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: */
sl@0: template <class KEY, class DATA> 
sl@0: TPair<KEY, DATA>::TPair()
sl@0: 	{
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @param aOrder An object of TLinearOrder< TPair<KEY, DATA> type, which will be used when
sl@0: new elements are inserted into the collection.
sl@0: */
sl@0: template <class KEY, class DATA> 
sl@0: RMap<KEY, DATA>::RMap(const TLinearOrder< TPair<KEY, DATA> >& aOrder) :
sl@0: 	iOrder(aOrder)
sl@0: 	{
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Closes RMap instance and destroy all RMap data.
sl@0: */
sl@0: template <class KEY, class DATA> 
sl@0: void RMap<KEY, DATA>::Close()
sl@0: 	{
sl@0: 	iCol.Close();
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: This method will create and insert new (KEY, DATA) pair in the map.
sl@0: If the operation fails, the method will return some of system wide error codes.
sl@0: RMap instance does not allow duplicated TPair objects in the collection.
sl@0: Actually it dependes on the supplied in the constructor aOrder instance.
sl@0: @param aKey The key part of TPair object, which will be inserted
sl@0: @param aData The data part of TPair object, which will be inserted
sl@0: @return KErrNone if successful, otherwise one of the system-wide error codes
sl@0: */
sl@0: template <class KEY, class DATA> 
sl@0: TInt RMap<KEY, DATA>::Insert(const KEY& aKey, const DATA& aData)
sl@0: 	{
sl@0: 	return iCol.InsertInOrder(TPair<KEY, DATA>(aKey, aData), iOrder);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: This method removes an element with aKey key from the map.
sl@0: If there is no such element in the map, the debug verison of the method will panic.
sl@0: The destructor of the object, which is about to be removed, is not called.
sl@0: @param aKey The key of TPair object, which has to be removed from the collection.
sl@0: */
sl@0: template <class KEY, class DATA> 
sl@0: void RMap<KEY, DATA>::Remove(const KEY& aKey)
sl@0: 	{
sl@0: 	TInt index = iCol.FindInOrder(TPair<KEY, DATA>(aKey), iOrder);
sl@0: 	index != KErrNotFound ? iCol.Remove(index) : __ASSERT(0);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: This method performs a search for an element with aKey key in the map.
sl@0: If such element exists, the method will return a const reference to the element's data.
sl@0: If not, then the method will panic.
sl@0: @param aKey The key of TPair object, a reference to which DATA will be returned
sl@0: @return A const reference to the matching DATA object.
sl@0: */
sl@0: template <class KEY, class DATA> 
sl@0: const DATA& RMap<KEY, DATA>::operator[](const KEY& aKey) const
sl@0: 	{
sl@0: 	TInt index = iCol.FindInOrder(TPair<KEY, DATA>(aKey), iOrder);
sl@0: 	__ASSERT_ALWAYS(index != KErrNotFound, User::Invariant());
sl@0: 	return iCol[index].iData;
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: This method performs a search for an element with aKey key in the map.
sl@0: If such element exists, the method will set the element's data in aData parameter and
sl@0: return KErrNone.
sl@0: If not, then the method will return KErrNotFound.
sl@0: @param aKey The key of TPair object, a reference to which DATA will be returned in aData
sl@0:             parameter, if found
sl@0: @param aData An output parameter, it references the location, where the found data will be stored.
sl@0: @return KErrNone An element with aKey key exists in the map, the data part is stored in aData.
sl@0: @return KErrNotFound No map element with aKey key found.
sl@0: */
sl@0: template <class KEY, class DATA> 
sl@0: TInt RMap<KEY, DATA>::Find(const KEY& aKey, DATA& aData) const
sl@0: 	{
sl@0: 	TInt index = iCol.FindInOrder(TPair<KEY, DATA>(aKey), iOrder);
sl@0: 	if(index != KErrNotFound)
sl@0: 		{
sl@0: 		aData = iCol[index].iData;
sl@0: 		}
sl@0: 	return index;
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: This method returns the number of elements in the map.
sl@0: @return Map elements count.
sl@0: */
sl@0: template <class KEY, class DATA> 
sl@0: TInt RMap<KEY, DATA>::Count() const
sl@0: 	{
sl@0: 	return iCol.Count();
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Initializes TMapIterator instance.
sl@0: @param aMap A const reference to the RMap object, which will be iterated.
sl@0: */
sl@0: template <class KEY, class DATA> 
sl@0: TMapIterator<KEY, DATA>::TMapIterator(const RMap<KEY, DATA>& aMap) :
sl@0: 	iMap(aMap),
sl@0: 	iIndex(0)
sl@0: 	{
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Resets TMapIterator iterator for a new scan from the beginning of the controlled map sequence.
sl@0: */
sl@0: template <class KEY, class DATA> 
sl@0: void TMapIterator<KEY, DATA>::Reset()
sl@0: 	{
sl@0: 	iIndex = 0;
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: If iterator's current position is not beyond the end of the map,
sl@0: the iterator will retrieve current map entry into aPair argument, advance iterator position
sl@0: by 1 and return ETrue. 
sl@0: Otherwise the iterator will return EFalse.
sl@0: @param aPair An output parameter, which references the location, where the next RMap element will be stored.
sl@0: @return ETrue The next RMap element successfully loaded into aPair parameter. This is not the 
sl@0:               end of RMap collection.
sl@0: @return EFalse The next RMap element successfully loaded into aPair parameter. This is the 
sl@0:               end of RMap collection. Do not call Next() anymore.
sl@0: */
sl@0: template <class KEY, class DATA> 
sl@0: TBool TMapIterator<KEY, DATA>::Next(TPair<KEY, DATA>& aPair) const
sl@0: 	{
sl@0: 	return (iIndex < iMap.iCol.Count()) ? aPair = iMap.iCol[iIndex++], ETrue : EFalse;
sl@0: 	}