// Copyright (c) 1996-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\collate.h

 // Definitions needed for Unicode collation.

 // Collation is the comparison of two Unicode strings to produce an ordering

 // that may be used in a dictionary or other list.

 // Collation is implemented using the Standard Unicode Collation algorithm. There

 // are four levels of comparison:

 // primary: basic character identity

 // secondary: accents and diacritics

 // tertiary: upper and lower case, and other minor attributes

 // quaternary: Unicode character value

 // Punctuation is normally ignored but can optionally be taken into account.

 // Strings are fully expanded using the standard Unicode canonical expansions before

 // they are compared. Thai and Lao vowels are swapped with the following character

 // if any.

 // EUSER contains the 'basic collation method'. This method assigns the standard Unicode collation key values

 // to the characters in the WGL4 repertoire, plus commonly used control characters and fixed-width spaces, plus

 // the CJK ideograms (for which the keys can be generated algorithmically). Other characters are collated after

 // all the characters for which keys are defined, and ordered by their Unicode values.

 // Locales can supply any number of other collation methods. They will usually supply a 'tailoring' of the standard

 // method. This is done by using the standard table as the main key table (signalled by placing NULL in

 // TCollationMethod::iMainTable) and specifying an override table (TCollationMethod::iOverrideTable).

 // Locale-specific collation data resides in ELOCL.

 // 

 // WARNING: This file contains some APIs which are internal and are subject

 //          to change without notice. Such APIs should therefore not be used

 //          outside the Kernel and Hardware Services package.

 //

 #ifndef __COLLATE_H__

 #define __COLLATE_H__

 #ifdef __KERNEL_MODE__

 #include <e32cmn.h>

 #else

 #include <e32std.h>

 #endif

 //This material is used in the Unicode build only.

 #ifdef _UNICODE

 /**

 Collation key table structure.

 @publishedPartner

 @released

 */

 struct TCollationKeyTable

 	{

 public:

 	/**

 	Masks for the various parts of the elements of the iKey array.

 	*/

 	enum

 		{

 		ELevel0Mask = 0xFFFF0000,	// primary key - basic character identity

 		ELevel1Mask = 0x0000FF00,	// secondary key - accents and diacritics

 		ELevel2Mask = 0x000000FC,	// tertiary key - case, etc.

 		EIgnoreFlag = 0x2,			// if set, this key is normally ignored

 		EStopFlag = 0x1				// if set, this key is the last in a sequence representing a Unicode value or values

 		};

 	/**

 	An array containing all of the keys and strings of keys concatenated

 	together. Each key has EStopFlag set only if it is the last key in its

 	string. Eack key contains the keys for levels 0, 1 and 2, and a flag

 	EIgnoreFlag if the key is usually ignored (for punctuation & spaces

 	etc.).

 	*/

 	const TUint32* iKey;

 	/**

 	An array of indices into the iKey array. Each element has its high 16

 	bits indicating a Unicode value and its low 16 bits indicating an index

 	into the iKey array at which its key starts. For surrogate pairs, high

 	surrogate code is in index[i]:16-31, and low surrogate code is in 

 	index[i+1]:16-31. These two elements are combined to represent a surrogate

 	pair. The elements are sorted by Unicode value.

 	*/

 	const TUint32* iIndex;

 	/**

 	The size of the iIndex array.

 	*/

 	TInt iIndices;

 	/**

 	Concatenated Unicode strings. Each is a strings that is to be converted

 	to keys differently from how it would be if each letter were converted

 	independently. An example is "ch" in Spanish, which sorts as though it

 	were a single letter. Each Unicode string is preceeded by a 16-bit value

 	indicating the string's length (in 16-bit). The end of the string is not 

 	delimited. A surrogate pair is represented by two ajacent 16-bit values.

 	*/

 	const TUint16* iString;

 	/**

 	An array of elements mapping elements of iString to elements of iIndex.

 	Each element has its high 16 bits indicating the index of the start of

 	an element of iString, and its low 16 bits indicating the corresponding

 	element in iIndex. This array is sorted on the string index.

 	*/

 	const TUint32* iStringIndex;

 	/**

 	The size of the iStringIndex array.

 	*/

 	TInt iStringIndices;

 	};

 /**

 Defines a collation method. 

 Collation means sorting pieces of text. It needs to take into account characters, 

 accents and case; spaces and punctuation are usually ignored. It differs from 

 ordinary methods of sorting in that it is locale-dependent - different 

 languages use different ordering methods. Additionally, multiple collation 

 methods may exist within the same locale.

 A collation method provides the collation keys and other data needed to customise 

 collation; the Mem and TDesC16 collation functions (e.g. Mem::CompareC()) 

 perform the collation. Note that these functions use the standard collation 

 method for the current locale - you only need to specify an object of class 

 TCollationMethod to customise this collation scheme. Collation methods can 

 be retrieved using member functions of the Mem class. Each one has a unique 

 identifier.

 A collation method specifies a main table of collation keys, and optionally 

 an overriding table that contains keys for which the values in the main table 

 are overridden. A collation key table (TCollationKeyTable) is the set of collation 

 keys: primary (basic character identity), secondary (accents and diacritics) 

 and tertiary (case). The quaternary key is the Unicode character values themselves.

 The simplest way to customise a collation method is to create a local copy 

 of the standard collation method and change it. For example, you could use 

 the standard method, but not ignore punctuation and spaces:

 @code

 TCollationMethod m = *Mem::CollationMethodByIndex(0); // get the standard method

 m.iFlags |= TCollationMethod::EIgnoreNone; // dont ignore punctuation and spaces

 @endcode

 @publishedPartner

 @released

 */

 struct TCollationMethod

 	{

 	public:

 	/**

 	The UID of this collation method.

 	*/

 	TUint iId;

 	/**

 	The main collation key table; if NULL, use the standard table.

 	*/

 	const TCollationKeyTable* iMainTable;

 	/**

 	If non-NULL, tailoring for collation keys.

 	*/

 	const TCollationKeyTable* iOverrideTable;

 	enum

 		{

 		/**

 		Don't ignore any keys (punctuation, etc. is normally ignored).

 		*/

 		EIgnoreNone = 1,

 		/**

 		Reverse the normal order for characters differing only in case

 		*/

 		ESwapCase = 2,

 		/**

 		Compare secondary keys which represent accents in reverse

 		order (from right to left); this is needed for French when comparing

 		words that differ only in accents.

 		*/

 		EAccentsBackwards = 4,	

 		/**

 		Reverse the normal order for characters differing only in whether they

 		are katakana or hiragana.

 		*/

 		ESwapKana = 8,

 		/**

 		Fold all characters to lower case before extracting keys; needed for

 		comparison of filenames, for which case is ignored but other

 		tertiary (level-2) distinctions are not.

 		*/

 		EFoldCase = 16,

 		/** Flag to indicate a collation method for matching purpose 

 		This flag is only needed if we wish to specify a particular collation method

 		to be used for matching purpose.

 		*/

 		EMatchingTable = 32,

 		/** Ignore the check for adjacent combining characters.  A combining

 		character effectively changes the character it combines with to something

 		else and so a match doesn't occur.  Setting this flag will allow character

 		matching regardless of any combining characters.

 		*/

 		EIgnoreCombining = 64

 		};

 	/**

 	Flags.

 	@see TCollationMethod::EIgnoreNone

 	@see TCollationMethod::ESwapCase

 	@see TCollationMethod::EAccentsBackwards

 	@see TCollationMethod::ESwapKana

 	@see TCollationMethod::EFoldCase

 	*/

 	TUint iFlags;

 	};

 /**

 A collation data set provides any collation methods needed by a locale.

 @publishedPartner

 @released

 */

 struct TCollationDataSet

 	{

 	public:

 	const TCollationMethod* iMethod;

 	TInt iMethods;

 	};

 // Collation method IDs

 /**

 A collation data set provides any collation methods needed by a locale.

 @internalTechnology

 @released

 */

 const TUint KUidBasicCollationMethod = 0x10004F4E;

 /**

 A collation data set provides any collation methods needed by a locale.

 @internalTechnology

 @released

 */

 const TUint KUidStandardUnicodeCollationMethod = 0x10004E96;

 #ifndef __KERNEL_MODE__

 //Forward declarations

 class TUTF32Iterator;

 struct LCharSet;

 /**

 Provides low-level collation functions.

 @internalComponent

 @released

 */

 class TCollate

 	{

 public:

 	/**

 	Construct a TCollate object based on the collation method specified

 	within aCharSet, if any. If there is none, or aCharSet is null, the

 	standard collation method will be used. aMask and aFlags provide a

 	method for overriding the flags in the collation method: Each flag set

 	to 1 in aMask is a flag that will be overridden and set to the

 	corresponding flag value in aFlags. Ownership of aCharSet is not passed.

 	*/

 	TCollate(const LCharSet* aCharSet,TUint aMask = 0,TUint aFlags = 0xFFFFFFFF);

 	/**

 	Construct a TCollate object based on an already constructed

 	TCollationMethod specified in aMethod. Ownership is not passed.

 	*/

 	TCollate(const TCollationMethod& aMethod);

 	enum TComparisonResult

 		{

 		ELeftComparesLessAndIsNotPrefix = -2,

 		ELeftIsPrefixOfRight = -1,

 		EStringsIdentical = 0,

 		ERightIsPrefixOfLeft = 1,

 		ERightComparesLessAndIsNotPrefix = 2

 		};

 	/**

 	Compare the string beginning at aString1 of length aLength1 against the

 	string beginning at aString2 of length aLength2.

 	aMaxLevel determines the tightness of the collation. At level 0, only

 	character identities are distinguished. At level 1 accents are

 	distinguished as well. At level 2 case is distinguishes as well. At

 	level 3 all valid different Unicode characters are considered different.

 	*/

 	TComparisonResult Compare(const TUint16* aString1,TInt aLength1,

 							  const TUint16* aString2,TInt aLength2,

 							  TInt aMaxLevel = 3) const;

 	/**

 	Find the string beginning at aString2 of length aLength2 in the string

 	beginning at aString1 of length aLength1. aMaxLevel determines

 	the tightness of the collation, see Compare for details.

 	*/

 	TInt Find(const TUint16 *aString1,TInt aLength1,const TUint16 *aString2,TInt aLength2,

 			  TInt aMaxLevel,TUint aString2WildChar = 0) const;

 	TInt Find(const TUint16 *aString1,TInt aLength1,const TUint16 *aString2,TInt aLength2,

 		      TInt &aLengthFound,TInt aMaxLevel,TUint aString2WildChar = 0) const;

 	/**

 	Test if the string beginning at aSearchTerm of length aSearchTermLength

 	matches the string beginning at aCandidate of length aCandidateLength.

 	aMaxLevel determines the tightness of the collation, see

 	Compare for details. The search term may have wild card characters as

 	specified by aWildChar (for matching a single grapheme- i.e. character

 	and any characters that combine with it, such as accents) and

 	aWildSequenceChar (for matching any sequence of whole graphemes). The

 	return value is KErrNotFound iff the search term does not match the

 	candidate string exactly. To find a match within the candidate string,

 	the search term must begin and end with a wild sequence character. If

 	the search term does match the candidate string, 0 will be returned,

 	unless the first character of the search term is a wild sequence

 	character in which case the value returned will be the index into

 	aCandidate at which the first non-wild sequence character matched.

 	aWildSequenceChar must be a valid (non-surrogate) Unicode character

 	below FFFE.

 	*/

 	TInt Match(const TUint16 *aCandidate, TInt aCandidateLength,

 			   const TUint16 *aSearchTerm,TInt aSearchTermLength,

 			   TInt aMaxLevel, TUint aWildChar = '?', TUint aWildSequenceChar = '*', TUint aEscapeChar = 0) const;

 private:

 	/**

 	Compare values output from the iterators. After the comparison, if

 	ERightIsPrefixOfLeft or EStringsIdentical is returned, then aLeft and

 	aRight will be pointing at the next key (at MaxLevel) after the match.

 	If right is shown to be a prefix of left, this means that it has been

 	checked at all requested levels. If it is reported that the right is a

 	prefix of the left, then this will mean also that there are no unmatched

 	combining characters on the left.

 	*/

 	TComparisonResult CompareKeySequences(TUTF32Iterator& aLeft, TUTF32Iterator& aRight,

 										  TInt aMaxLevel, TInt aRightStringWildChar, TInt aEscapeChar) const;

 	/**

 	Finds search term inside candidate string. Returns KErrNotFound if there

 	is no match, returns the offset into the candidate string at which the

 	search term was found (note that this is the offset from the start of

 	the iteration, not from where the iteration was when the function was

 	called). If a string was found, the search term iterator is left

 	pointing at the end of the search term, and the candidate iterator is

 	left pointing just after the matched keys. aMatchPos returns where in

 	the candidate string the match was found.

 	*/

 	TInt FindKeySequence(TUTF32Iterator& aCandidate, TUTF32Iterator& aSearchTerm,

 						 TInt aMaxLevel, TInt aWildChar, TInt aEscapeChar, TInt& aLengthFound) const;

 private:

 	TCollationMethod iMethod;

 	};

 #endif	// __KERNEL_MODE__

 #endif // _UNICODE

 #endif // __COLLATE_H__