My first commit on the Symbian Hg repository. Testng how branches are working.
// 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__