// 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__