// 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 "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.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,					

        /**

        Marks group.

        Includes EMnCategory, EMcCategory and EMeCategory.

        */

		EMarkGroup = 0x30,

        /**

        Numbers group.

	    Includes ENdCategory, ENlCategory and ENoCategory.

	    */

		ENumberGroup = 0x40,

        /**

        Punctuation group.

	    IncludesEPcCategory, PdCategory, EpeCategory, EPsCategory and EPoCategory.

	    */

		EPunctuationGroup = 0x50,

        /**

        Symbols group.

        Includes ESmCategory, EScCategory, ESkCategory and ESoCategory.

        */

		ESymbolGroup = 0x60,

        /**

        Separators group.

        Includes EZsCategory, EZlCategory and EZlpCategory.

        */

		ESeparatorGroup = 0x70,

        /**

        Control, format, private use, unassigned.

     	Includes ECcCategory, ECtCategory, ECsCategory,

     	ECoCategory and ECnCategory.

     	*/

		EControlGroup = 0x80,

	    /**

	    The highest possible groups category.

	    */

		EMaxAssignedGroup = 0xE0,

        /**

        Unassigned to any other group.

        */

		EUnassignedGroup = 0xF0,

        /**

        Letter, Uppercase.

        */

		ELuCategory = EAlphaGroup | 0,					

        /**

        Letter, Lowercase.

        */

		ELlCategory = EAlphaGroup | 1,					

	    /**

	    Letter, Titlecase.

	    */

		ELtCategory = EAlphaGroup | 2,					

     	/**

     	Letter, Other.

     	*/

		ELoCategory = ELetterOtherGroup | 0,			

	    /**

	    The highest possible (non-modifier) letter category.

	    */

		EMaxLetterCategory = ELetterOtherGroup | 0x0F,	

	    /**

	    Letter, Modifier.

	    */

		ELmCategory = ELetterModifierGroup | 0,			

	    /**

	    The highest possible letter category.

	    */

		EMaxLetterOrLetterModifierCategory = ELetterModifierGroup | 0x0F, 

	    /**

	    Mark, Non-Spacing

	    */

		EMnCategory = EMarkGroup | 0,					

        /**

        Mark, Combining.

        */

		EMcCategory = EMarkGroup | 1,					

        /**

        Mark, Enclosing.

        */

		EMeCategory = EMarkGroup | 2,					

        /**

        Number, Decimal Digit.

        */

		ENdCategory = ENumberGroup | 0,					

        /**

        Number, Letter.

        */

		ENlCategory = ENumberGroup | 1,					

        /**

        Number, Other.

        */

		ENoCategory = ENumberGroup | 2,					

        /**

        Punctuation, Connector.

        */

		EPcCategory = EPunctuationGroup | 0,			

        /**

        Punctuation, Dash.

        */

		EPdCategory = EPunctuationGroup | 1,			

        /**

        Punctuation, Open.

        */

		EPsCategory = EPunctuationGroup | 2,			

        /**

        Punctuation, Close.

        */

		EPeCategory = EPunctuationGroup | 3,

		/**

		Punctuation, Initial Quote

		*/			

		EPiCategory = EPunctuationGroup | 4,			

		/**

		Punctuation, Final Quote

		*/

		EPfCategory = EPunctuationGroup | 5,			

        /**

        Punctuation, Other.

        */

		EPoCategory = EPunctuationGroup | 6,			

        /**

        Symbol, Math.

        */

		ESmCategory = ESymbolGroup | 0,					

        /**

        Symbol, Currency.

        */

		EScCategory = ESymbolGroup | 1,					

        /**

        Symbol, Modifier.

        */

		ESkCategory = ESymbolGroup | 2,					

        /**

        Symbol, Other.

        */

		ESoCategory = ESymbolGroup | 3,					

        /**

        The highest possible graphic character category.

        */

		EMaxGraphicCategory = ESymbolGroup | 0x0F,		

        /**

        Separator, Space.

        */

		EZsCategory = ESeparatorGroup | 0,				

        /**

        The highest possible printable character category.

        */

		EMaxPrintableCategory = EZsCategory,			

        /**

        Separator, Line.

        */

		EZlCategory = ESeparatorGroup | 1,				

        /**

        Separator, Paragraph.

        */

		EZpCategory = ESeparatorGroup | 2,				

        /**

        Other, Control.

        */

		ECcCategory = EControlGroup | 0,				

        /**

        Other, Format.

        */

		ECfCategory = EControlGroup | 1,				

        /**

        The highest possible category for assigned 16-bit characters; does not

        include surrogates, which are interpreted as pairs and have no meaning

        on their own.

        */

		EMaxAssignedCategory = EMaxAssignedGroup | 0x0F,

        /**

        Other, Surrogate.

        */

		ECsCategory = EUnassignedGroup | 0,				

        /**

        Other, Private Use.

        */

		ECoCategory = EUnassignedGroup | 1,				

        /**

        Other, Not Assigned.

        */

		ECnCategory = EUnassignedGroup | 2				

		};

    /**

    The bi-directional Unicode character category.

    For more information on the bi-directional algorithm, see Unicode Technical 

    Report No. 9 available at: http://www.unicode.org/unicode/reports/tr9.

    */

	enum TBdCategory

		{

	    /**

	    Left to right.

	    */

		ELeftToRight,				// L Left-to-Right 

	    /**

	    Left to right embedding.

	    */

		ELeftToRightEmbedding,		// LRE Left-to-Right Embedding 

	    /**

	    Left-to-Right Override.

	    */

		ELeftToRightOverride,		// LRO Left-to-Right Override 

	    /**

	    Right to left.

	    */

		ERightToLeft,				// R Right-to-Left 

	    /**

	    Right to left Arabic.

	    */

		ERightToLeftArabic,			// AL Right-to-Left Arabic 

	    /**

	    Right to left embedding.

	    */

		ERightToLeftEmbedding,		// RLE Right-to-Left Embedding 

	    /**

	    Right-to-Left Override.

	    */

		ERightToLeftOverride,		// RLO Right-to-Left Override 

	    /**

	    Pop Directional Format.

	    */

		EPopDirectionalFormat,		// PDF Pop Directional Format 

	    /**

	    European number.

	    */

		EEuropeanNumber,			// EN European Number 

	    /**

	    European number separator.

	    */

		EEuropeanNumberSeparator,	// ES European Number Separator 

	    /**

	    European number terminator.

	    */

		EEuropeanNumberTerminator,	// ET European Number Terminator 

	    /**

	    Arabic number.

	    */

		EArabicNumber,				// AN Arabic Number 

	    /**

	    Common number separator.

	    */

		ECommonNumberSeparator,		// CS Common Number Separator 

	    /**

	    Non Spacing Mark.

	    */

		ENonSpacingMark,			// NSM Non-Spacing Mark 

	    /**

	    Boundary Neutral.

	    */

		EBoundaryNeutral,			// BN Boundary Neutral 

	    /**

	    Paragraph Separator.

	    */

		EParagraphSeparator,		// B Paragraph Separator 

	    /**

	    Segment separator.

	    */

		ESegmentSeparator,			// S Segment Separator 

		/**

		Whitespace

		*/

		EWhitespace,				// WS Whitespace 

	    /**

	    Other neutrals; all other characters: punctuation, symbols.

	    */

		EOtherNeutral				// ON Other Neutrals 

		};

	/**

    Notional character width as known to East Asian (Chinese, Japanese,

    Korean (CJK)) coding systems.

    */

	enum TCjkWidth

		{

	    /**

	    Includes 'ambiguous width' defined in Unicode Technical Report 11: East Asian Width

	    */

		ENeutralWidth,			

	    /**

	    Character which occupies a single cell.

	    */

		EHalfWidth,				// other categories are as defined in the report

        /**

        Character which occupies 2 cells.

        */

		EFullWidth,

        /**

        Characters that are always narrow and have explicit full-width

        counterparts. All of ASCII is an example of East Asian Narrow

        characters.

        */

		ENarrow,

	    /**

	    Characters that are always wide. This category includes characters that

	    have explicit half-width counterparts.

	    */

		EWide

		};

	/**

	@deprecated

    Encoding systems used by the translation functions.

    */

  	enum TEncoding

  		{

  		/**

  		The Unicode encoding.

  		*/

  		EUnicode,

        /**

        The shift-JIS encoding (used in Japan).

        */

  		EShiftJIS		

  		};

	/**

	Flags defining operations to be performed using TChar::Fold().

	The flag values are passed to the Fold() funtion.

	@see TChar::Fold

	*/

	enum

		{

		/**

		Convert characters to their lower case form if any.

		*/

		EFoldCase = 1,			

		/**

		Strip accents

     	*/

		EFoldAccents = 2,		

		/**

		Convert digits representing values 0..9 to characters '0'..'9'

     	*/

		EFoldDigits = 4,		

		/**

		Convert all spaces (ordinary, fixed-width, ideographic, etc.) to ' '

     	*/

		EFoldSpaces = 8,		

		/**

		Convert hiragana to katakana.

     	*/

		EFoldKana = 16,			

		/**

	    Fold fullwidth and halfwidth variants to their standard forms

     	*/

		EFoldWidth = 32,