// Copyright (c) 1994-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

// which accompanies this distribution, and is available

// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// e32\include\e32cmn.h

// 

//

#ifndef __E32CMN_H__

#define __E32CMN_H__

#include <e32const.h>

extern "C" {

/**

@publishedAll

@released

A Nanokernel utility function that compares two memory buffers for equality.

The two buffers are considered equal only if:

1. the buffers have the same length

and

2. the binary content of both buffers is the same.

@param aLeft     The start address of the first buffer in the comparison.

@param aLeftLen  The length of the first buffer in the comparison.

@param aRight    The start address of the second buffer in the comparison.

@param aRightLen The length of the second buffer in the comparison.

@return Zero if both buffers are equal; non-zero, otherwise.

@panic USER 88        In debug mode only, if aLeftL is negative, 

                      and the function is called on the user side.

@panic KERN-COMMON 88 In debug mode only, if aLeftL is negative,

                      and the function is called on the kernel side.

@panic USER 89        In debug mode only, if aRightL is negative, 

                      and the function is called on the user side.

@panic KERN-COMMON 89 In debug mode only, if aRightL is negative,

                      and the function is called on the kernel side.

*/

IMPORT_C TInt memcompare(const TUint8* aLeft, TInt aLeftLen, const TUint8* aRight, TInt aRightLen);

/**

@publishedAll

@released

A Nanokernel utility function that moves (copies) bytes in memory.

The function assumes that the addresses are aligned on word boundaries,

and that the length value is a multiple of 4.

@param aTrg    The target address.

@param aSrc    The source address.

@param aLength The number of bytes to be moved.

@return The target address.

@panic USER 91        In debug mode only, if aLength is not a multiple of 4,

                      and the function is called on the user side.

@panic KERN-COMMON 91 In debug mode only, if aLength is not a multiple of 4,

                      and the function is called on the kernel side.

@panic USER 92        In debug mode only, if aSrc is not aligned on a word boundary,

                      and the function is called on the user side.

@panic KERN-COMMON 92 In debug mode only, if aSrc is not aligned on a word boundary,

                      and the function is called on the kernel side.

@panic USER 93        In debug mode only, if aTrg is not aligned on a word boundary,

                      and the function is called on the user side.

@panic KERN-COMMON 93 In debug mode only, if aTrg is not aligned on a word boundary,

                      and the function is called on the kernel side.

*/

IMPORT_C TAny* wordmove(TAny* aTrg, const TAny* aSrc, unsigned int aLength);

/**

@publishedAll

@released

A Nanokernel utility function that sets the specified number of bytes

to binary zero.

@param aTrg    The start address.

@param aLength The number of bytes to be set.

@return The target address.

*/

IMPORT_C TAny* memclr(TAny* aTrg, unsigned int aLength);

}

#ifndef __TOOLS__

extern "C" {

/**

@publishedAll

@released

A Nanokernel utility function that sets all of the specified number of bytes to

the specified fill value.

@param aTrg    The start address.

@param aValue  The fill value (the first or junior byte).

@param aLength The number of bytes to be set.

@return The target address.

*/

	IMPORT_C TAny* memset(TAny* aTrg, TInt aValue, unsigned int aLength);

/**

@publishedAll

@released

A Nanokernel utility function that copies bytes in memory.

@param aTrg    The target address.

@param aSrc    The source address.

@param aLength The number of bytes to be moved.

@return The target address.

*/

	IMPORT_C TAny* memcpy(TAny* aTrg, const TAny* aSrc, unsigned int aLength);

/**

@publishedAll

@released

A Nanokernel utility function that moves (copies) bytes in memory.

@param aTrg    The target address.

@param aSrc    The source address.

@param aLength The number of bytes to be moved.

@return The target address.

*/

	IMPORT_C TAny* memmove(TAny* aTrg, const TAny* aSrc, unsigned int aLength);

}

#else

#include <string.h>

#endif

/** 

@publishedAll

@released

Tests whether the specified value is less than or equal to the

specified upper limit.

@param aVal   The value to be tested.

@param aLimit The upper limit.

@return True, if the value is less than or equal to the specified upper limit;

        false, otherwise.

*/

inline TInt Lim(TInt aVal,TUint aLimit)

	{return(((TUint)aVal)<=aLimit);}

/** 

@publishedAll

@released

Tests whether the specified value is strictly less than the

specified upper limit.

@param aVal   The value to be tested.

@param aLimit The upper limit.

@return True, if the value is strictly less than the specified upper limit;

        false, otherwise.

*/

inline TInt LimX(TInt aVal,TUint aLimit)

	{return(((TUint)aVal)<aLimit);}

/** 

@publishedAll

@released

Returns the smaller of two values.

@param aLeft  The first value to be compared.

@param aRight The second value to be compared.

@return The smaller value.

*/

template <class T>

inline T Min(T aLeft,T aRight)

	{return(aLeft<aRight ? aLeft : aRight);}

/**

@publishedAll

@released

Returns the smaller of two objects, where the right hand object is a treated

as a TInt for the  purpose of comparison.

@param aLeft  The first value to be compared.

@param aRight The second value to be compared.

@return The smaller value.

*/

template <class T>

inline T Min(T aLeft,TUint aRight)

	{return(aLeft<(TInt)aRight ? aLeft : (T)aRight);}

/** 

@publishedAll

@released

Returns the larger of two values.

@param aLeft  The first value to be compared.

@param aRight The second value to be compared.

@return The larger value.

*/

template <class T>

inline T Max(T aLeft,T aRight)

	{return(aLeft<aRight ? aRight : aLeft);}

/**

@publishedAll

@released

Returns the larger of two objects, where the right hand object is a treated

as a TInt for the  purpose of comparison.

@param aLeft  The first value to be compared.

@param aRight The second value to be compared.

@return The larger value.

*/

template <class T>

inline T Max(T aLeft,TUint aRight)

	{return(aLeft<(TInt)aRight ? (TInt)aRight : aLeft);}

/**

@publishedAll

@released

Returns an absolute value.

@param aVal The source value.

@return The absolute value

*/

template <class T>

inline T Abs(T aVal)

	{return(aVal<0 ? -aVal : aVal);}

/** 

@publishedAll

@released

Determines whether a specified value lies within a defined range of values.

@param aMin The lower value of the range.

@param aVal The value to be compared.

@param aMax The higher value of the range.

@return True, if the specified value lies within the range; false, otherwise.

*/

template <class T>

inline TBool Rng(T aMin,T aVal,T aMax)

	{return(aVal>=aMin && aVal<=aMax);}

/**

@publishedAll

@released

Adds a value to a pointer.

@param aPtr Pointer to an object of type T.

@param aVal The value to be added.

@return The resulting pointer value, as a pointer to a type T.

*/

template <class T,class S>

inline T* PtrAdd(T* aPtr,S aVal)

	{return((T*)(((TUint8*)aPtr)+aVal));}

/**

@publishedAll

@released

Subtracts a value from a pointer.

@param aPtr Pointer to an object of type T.

@param aVal The value to be added.

@return The resulting pointer value, as a pointer to a type T.

*/

template <class T,class S>

inline T* PtrSub(T* aPtr,S aVal)

	{return((T*)(((TUint8*)aPtr)-aVal));}

/**

@publishedAll

@released

Aligns the specified value onto a 2-byte boundary.

@param aValue The value to be aligned.

@return The aligned value. 

*/

template <class T>

inline T Align2(T aValue)

	{return((T)((((TUint)aValue)+sizeof(TUint16)-1)&~(sizeof(TUint16)-1)));}

/**

@publishedAll

@released

Aligns the specified value onto a 4-byte boundary.

@param aValue The value to be aligned.

@return The aligned value. 

*/

template <class T>

inline T Align4(T aValue)

	{return((T)((((TUint)aValue)+sizeof(TUint32)-1)&~(sizeof(TUint32)-1)));}

/**

@publishedAll

@released

A templated class which encapsulates a reference to an object within a wrapper.

The wrapper object can be passed to a function as a value type. This allows 

a reference to be passed to a function as a value type.

This wrapper object is commonly termed a value reference.

*/

template <class T>

class TRefByValue

	{

public:

	inline TRefByValue(T& aRef);

	inline operator T&();

private:

	TRefByValue& operator=(TRefByValue aRef);

private:

	T &iRef;

	};

#if !defined (__KERNEL_MODE__)

class TDesC16;	// forward declaration for TChar member functions

class TPtrC16;	// forward declaration for TChar member functions

#endif

/**

@publishedAll

@released

Holds a character value and provides a number of utility functions to

manipulate it and test its properties.

For example, there are functions to convert the character 

to uppercase and test whether or not it is a control character.

The character value is stored as a 32-bit unsigned integer. The shorthand 

"TChar value" is used to describe the character value wrapped by a TChar 

object.

TChar can be used to represent Unicode values outside plane 0 (that is, the 

extended Unicode range from 0x10000 to 0xFFFFF). This differentiates it from 

TText which can only be used for 16-bit Unicode character values.

@see TText

*/

class TChar

	{

public:

    /**

    General Unicode character category.

    The high nibble encodes the major category (Mark, Number, etc.) and a low 

    nibble encodes the subdivisions of that category.

    The category codes can be used in three ways:

    (i) as unique constants: there is one for each Unicode category, with a

    name of the form

    @code

    E<XX>Category

    @endcode

    where

    @code

    <XX>

    @endcode

    is the category name given by

    the Unicode database (e.g., the constant ELuCategory is used for lowercase

    letters, category Lu);

    (ii) as numbers in certain ranges: letter categories are all <= EMaxLetterCategory;

    (iii) as codes in which the upper nibble gives the category group

    (e.g., punctuation categories all yield TRUE for

    the test (category & 0xF0) ==EPunctuationGroup).

    */

	enum TCategory

		{

        /**

        Alphabetic letters.

        Includes ELuCategory, ELlCategory and ELtCategory.

        */

		EAlphaGroup = 0x00,								

        /**

        Other letters.

        Includes ELoCategory.

        */

		ELetterOtherGroup = 0x10,						

        /**

        Letter modifiers.

        Includes ELmCategory.

        */

		ELetterModifierGroup = 0x20,