TChar Class Reference

class TChar

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.


Nested Classes and Structures

Public Member Functions
IMPORT_C TBoolCompose(TUint &, const TDesC16 &)
IMPORT_C TBoolDecompose(TPtrC16 &)
TBool Eos()
IMPORT_C TBdCategoryGetBdCategory()
IMPORT_C TCategoryGetCategory()
IMPORT_C TCjkWidthGetCjkWidth()
IMPORT_C TIntGetCombiningClass()
IMPORT_C voidGetInfo(TCharInfo &)
IMPORT_C TUintGetLowerCase()
IMPORT_C TIntGetNumericValue()
IMPORT_C TUintGetTitleCase()
IMPORT_C TUintGetUpperCase()
IMPORT_C TBoolIsAlpha()
IMPORT_C TBoolIsAlphaDigit()
IMPORT_C TBoolIsAssigned()
IMPORT_C TBoolIsControl()
IMPORT_C TBoolIsDigit()
IMPORT_C TBoolIsGraph()
IMPORT_C TBoolIsHexDigit()
IMPORT_C TBoolIsLower()
IMPORT_C TBoolIsMirrored()
IMPORT_C TBoolIsPrint()
IMPORT_C TBoolIsPunctuation()
IMPORT_C TBoolIsSpace()
IMPORT_C TBoolIsTitle()
IMPORT_C TBoolIsUpper()
operator TUint()
TChar operator+(TUint)
TChar &operator+=(TUint)
TChar operator-(TUint)
TChar &operator-=(TUint)
Protected Member Functions
Public Member Enumerations
enumanonymous {
EFoldCase = 1, EFoldAccents = 2, EFoldDigits = 4, EFoldSpaces = 8, EFoldKana = 16, EFoldWidth = 32, EFoldStandard = EFoldCase | EFoldAccents | EFoldDigits | EFoldSpaces, EFoldAll = -1
enumTBdCategory {
ELeftToRight, ELeftToRightEmbedding, ELeftToRightOverride, ERightToLeft, ERightToLeftArabic, ERightToLeftEmbedding, ERightToLeftOverride, EPopDirectionalFormat, EEuropeanNumber, EEuropeanNumberSeparator, EEuropeanNumberTerminator, EArabicNumber, ECommonNumberSeparator, ENonSpacingMark, EBoundaryNeutral, EParagraphSeparator, ESegmentSeparator, EWhitespace, EOtherNeutral
enumTCategory {
EAlphaGroup = 0x00, ELetterOtherGroup = 0x10, ELetterModifierGroup = 0x20, EMarkGroup = 0x30, ENumberGroup = 0x40, EPunctuationGroup = 0x50, ESymbolGroup = 0x60, ESeparatorGroup = 0x70, EControlGroup = 0x80, EMaxAssignedGroup = 0xE0, EUnassignedGroup = 0xF0, ELuCategory = EAlphaGroup | 0, ELlCategory = EAlphaGroup | 1, ELtCategory = EAlphaGroup | 2, ELoCategory = ELetterOtherGroup | 0, EMaxLetterCategory = ELetterOtherGroup | 0x0F, ELmCategory = ELetterModifierGroup | 0, EMaxLetterOrLetterModifierCategory = ELetterModifierGroup | 0x0F, EMnCategory = EMarkGroup | 0, EMcCategory = EMarkGroup | 1, EMeCategory = EMarkGroup | 2, ENdCategory = ENumberGroup | 0, ENlCategory = ENumberGroup | 1, ENoCategory = ENumberGroup | 2, EPcCategory = EPunctuationGroup | 0, EPdCategory = EPunctuationGroup | 1, EPsCategory = EPunctuationGroup | 2, EPeCategory = EPunctuationGroup | 3, EPiCategory = EPunctuationGroup | 4, EPfCategory = EPunctuationGroup | 5, EPoCategory = EPunctuationGroup | 6, ESmCategory = ESymbolGroup | 0, EScCategory = ESymbolGroup | 1, ESkCategory = ESymbolGroup | 2, ESoCategory = ESymbolGroup | 3, EMaxGraphicCategory = ESymbolGroup | 0x0F, EZsCategory = ESeparatorGroup | 0, EMaxPrintableCategory = EZsCategory, EZlCategory = ESeparatorGroup | 1, EZpCategory = ESeparatorGroup | 2, ECcCategory = EControlGroup | 0, ECfCategory = EControlGroup | 1, EMaxAssignedCategory = EMaxAssignedGroup | 0x0F, ECsCategory = EUnassignedGroup | 0, ECoCategory = EUnassignedGroup | 1, ECnCategory = EUnassignedGroup | 2
enumTCjkWidth { ENeutralWidth, EHalfWidth, EFullWidth, ENarrow, EWide }
enumTEncoding { EUnicode, EShiftJIS }
Private Attributes
TUint iChar

Constructor & Destructor Documentation



Default constructor.

Constructs this character object with an undefined value.



Constructs this character object and initialises it with the specified value.


TUint aCharThe initialisation value.

Member Functions Documentation

Compose(TUint &, const TDesC16 &)

IMPORT_C TBoolCompose(TUint &aResult,
const TDesC16 &aSource

Composes a string of Unicode characters to produce a single character result.

For example, 0061 ('a') and 030A (combining ring above) compose to give 00E5 ('a' with ring above).

A canonical decomposition is a relationship between a string of characters - usually a base character and one or more diacritics - and a composed character. The Unicode standard requires that compliant software treats composed characters identically with their canonical decompositions. The mappings used by these functions are fixed and cannot be overridden for particular locales.


TUint & aResultIf successful, the composed character value. If unsuccessful, this value contains 0xFFFF.
const TDesC16 & aSourceString of source Unicode characters.

Decompose(TPtrC16 &)

IMPORT_C TBoolDecompose(TPtrC16 &aResult)const

Maps this character to its maximal canonical decomposition.

For example, 01E1 ('a' with dot above and macron) decomposes into 0061 ('a') 0307 (dot) and 0304 (macron).

Note that this function is used during collation, as performed by the Mem::CompareC() function, to convert the compared strings to their maximal canonical decompositions.

Mem::CompareC() TChar::Compose()


TPtrC16 & aResultIf successful, the descriptor represents the canonical decomposition of this character. If unsuccessful, the descriptor is empty.


TBool Eos()const [inline]

Tests whether the character is the C/C++ end-of-string character - 0.



Converts the character to a form which can be used in tolerant comparisons without control over the operations performed.

Tolerant comparisons are those which ignore character differences like case and accents.

This function can be used when searching for a string in a text file or a file in a directory. Folding performs the following conversions: converts to lowercase, strips accents, converts all digits representing the values 0..9 to the ordinary digit characters '0'..'9', converts all spaces (standard, non-break, fixed-width, ideographic, etc.) to the ordinary space character (0x0020), converts Japanese characters in the hiragana syllabary to katakana, and converts East Asian halfwidth and fullwidth variants to their ordinary forms. You can choose to perform any subset of these operations by using the other function overload.




Converts the character to a form which can be used in tolerant comparisons allowing selection of the specific fold operations to be performed.

TChar::EFoldCase User::Fold


TInt aFlagsFlags which define the operations to be performed. The values are defined in the enum beginning with EFoldCase.


IMPORT_C TBdCategoryGetBdCategory()const

Gets the bi-directional category of a character.

For more information on the bi-directional algorithm, see Unicode Technical Report No. 9 available at:


IMPORT_C TCategoryGetCategory()const

Gets this character's Unicode category.


IMPORT_C TCjkWidthGetCjkWidth()const

Gets the Chinese, Japanese, Korean (CJK) notional width.

Some display systems used in East Asia display characters on a grid of fixed-width character cells like the standard MSDOS display mode.

Some characters, e.g. the Japanese katakana syllabary, take up a single character cell and some characters, e.g., kanji, Chinese characters used in Japanese, take up two. These are called half-width and full-width characters. This property is fixed and cannot be overridden for particular locales.

For more information on returned widths, see Unicode Technical Report 11 on East Asian Width available at:


IMPORT_C TIntGetCombiningClass()const

Gets this character's combining class.

Note that diacritics and other combining characters have non-zero combining classes.

GetInfo(TCharInfo &)

IMPORT_C voidGetInfo(TCharInfo &aInfo)const

Gets this character;s standard category information.

This includes everything except its CJK width and decomposition, if any.


TCharInfo & aInfoOn return, contains the character's standard category information.


IMPORT_C TUintGetLowerCase()const

Gets the character value after conversion to lowercase or the character's own value, if no lowercase form exists.

The character object itself is not changed.


IMPORT_C TIntGetNumericValue()const

Gets the integer numeric value of this character.

Numeric values need not be in the range 0..9; the Unicode character set includes various other numeric characters such as the Roman and Tamil numerals for 500, 1000, etc.


IMPORT_C TUintGetTitleCase()const

Gets the character value after conversion to titlecase or the character's own value, if no titlecase form exists.

The titlecase form of a character is identical to its uppercase form unless a specific titlecase form exists.


IMPORT_C TUintGetUpperCase()const

Gets the character value after conversion to uppercase or the character's own value, if no uppercase form exists.

The character object itself is not changed.


IMPORT_C TBoolIsAlpha()const

Tests whether the character is alphabetic.

For Unicode, the function returns TRUE for all letters, including those from syllabaries and ideographic scripts. The function returns FALSE for letter-like characters that are in fact diacritics. Specifically, the function returns TRUE for categories: ELuCategory, ELtCategory, ELlCategory, and ELoCategory; it returns FALSE for all other categories including ELmCategory.

TChar::IsAlphaDigit() TChar::TCategory


IMPORT_C TBoolIsAlphaDigit()const

Tests whether the character is alphabetic or a decimal digit.

It is identical to (IsAlpha()||IsDigit()).

TChar::IsAlpha() TChar::IsDigit()


IMPORT_C TBoolIsAssigned()const

Tests whether this character has an assigned meaning in the Unicode encoding.

All characters outside the range 0x0000 - 0xFFFF are unassigned and there are also many unassigned characters within the Unicode range.

Locales can change the assigned/unassigned status of characters. This means that the precise behaviour of this function is locale-dependent.


IMPORT_C TBoolIsControl()const

Tests whether the character is a control character.

For Unicode, the function returns TRUE for all characters in the categories: ECcCategory, ECfCategory, ECsCategory, ECoCategory and ECnCategoryCc.



IMPORT_C TBoolIsDigit()const

Tests whether the character is a standard decimal digit.

For Unicode, this function returns TRUE only for the digits '0'...'9' (U+0030...U+0039), not for other digits in scripts like Arabic, Tamil, etc.

TChar::GetCategory() TChar::GetNumericValue


IMPORT_C TBoolIsGraph()const

Tests whether the character is a graphic character.

For Unicode, graphic characters include printable characters but not the space character. Specifically, graphic characters are any character except those in categories: EZsCategory,EZlCategory,EZpCategory, ECcCategory,ECfCategory, ECsCategory, ECoCategory, and ,ECnCategory.

Note that for ISO Latin-1, all alphanumeric and punctuation characters are graphic.



IMPORT_C TBoolIsHexDigit()const

Tests whether the character is a hexadecimal digit (0-9, a-f, A-F).


IMPORT_C TBoolIsLower()const

Tests whether the character is lowercase.


IMPORT_C TBoolIsMirrored()const

Tests whether this character has the mirrored property.

Mirrored characters, like ( ) [ ] < >, change direction according to the directionality of the surrounding characters. For example, an opening parenthesis 'faces right' in Hebrew or Arabic, and to say that 2 < 3 you would have to say that 3 > 2, where the '>' is, in this example, a less-than sign to be read right-to-left.


IMPORT_C TBoolIsPrint()const

Tests whether the character is a printable character.

For Unicode, printable characters are any character except those in categories: ECcCategory, ECfCategory, ECsCategory, ECoCategory and ECnCategory.

Note that for ISO Latin-1, all alphanumeric and punctuation characters, plus space, are printable.



IMPORT_C TBoolIsPunctuation()const

Tests whether the character is a punctuation character.

For Unicode, punctuation characters are any character in the categories: EPcCategory, EPdCategory, EPsCategory, EPeCategory, EPiCategory, EPfCategory, EPoCategory.



IMPORT_C TBoolIsSpace()const

Tests whether the character is a white space character.

White space includes spaces, tabs and separators.

For Unicode, the function returns TRUE for all characters in the categories: EZsCategory, EZlCategory and EZpCategory, and also for the characters 0x0009 (horizontal tab), 0x000A (linefeed), 0x000B (vertical tab), 0x000C (form feed), and 0x000D (carriage return).



IMPORT_C TBoolIsTitle()const

Tests whether this character is in titlecase.


IMPORT_C TBoolIsUpper()const

Tests whether the character is uppercase.



Converts the character to its lowercase form.

Characters lacking a lowercase form are unchanged.



voidSetChar(TUintaChar)[protected, inline]


TUint aChar



Converts the character to its titlecase form.

The titlecase form of a character is identical to its uppercase form unless a specific titlecase form exists. Characters lacking a titlecase form are unchanged.



Converts the character to its uppercase form.

Characters lacking an uppercase form are unchanged.


operator TUint()

operator TUint()const [inline]

Gets the value of the character as an unsigned integer.

The operator casts a TChar to a TUint, returning the TUint value wrapped by this character object.


TChar operator+(TUintaChar)[inline]

Gets the result of adding an unsigned integer value to this character object.

This character object is not changed.


TUint aCharThe value to be added.


TChar &operator+=(TUintaChar)[inline]

Adds an unsigned integer value to this character object.

This character object is changed by the operation.


TUint aCharThe value to be added.


TChar operator-(TUintaChar)[inline]

Gets the result of subtracting an unsigned integer value from this character object.

This character object is not changed.


TUint aCharThe value to be subtracted.


TChar &operator-=(TUintaChar)[inline]

Subtracts an unsigned integer value from this character object.

This character object is changed by the operation.


TUint aCharThe value to be subtracted.

Member Enumerations Documentation

Enum anonymous

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

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



EFoldCase = 1

Convert characters to their lower case form if any.

EFoldAccents = 2

Strip accents

EFoldDigits = 4

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

EFoldSpaces = 8

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

EFoldKana = 16

Convert hiragana to katakana.

EFoldWidth = 32

Fold fullwidth and halfwidth variants to their standard forms

EFoldStandard = EFoldCase | EFoldAccents | EFoldDigits | EFoldSpaces

Perform standard folding operations, i.e.those done by Fold() with no argument

EFoldAll = -1

Perform all possible folding operations

Enum TBdCategory

The bi-directional Unicode character category.

For more information on the bi-directional algorithm, see Unicode Technical Report No. 9 available at:



Left to right.


Left to right embedding.


Left-to-Right Override.


Right to left.


Right to left Arabic.


Right to left embedding.


Right-to-Left Override.


Pop Directional Format.


European number.


European number separator.


European number terminator.


Arabic number.


Common number separator.


Non Spacing Mark.


Boundary Neutral.


Paragraph Separator.


Segment separator.




Other neutrals; all other characters: punctuation, symbols.

Enum TCategory

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
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).


EAlphaGroup = 0x00

Alphabetic letters.

Includes ELuCategory, ELlCategory and ELtCategory.

ELetterOtherGroup = 0x10

Other letters.

Includes ELoCategory.

ELetterModifierGroup = 0x20

Letter modifiers.

Includes ELmCategory.

EMarkGroup = 0x30

Marks group.

Includes EMnCategory, EMcCategory and EMeCategory.

ENumberGroup = 0x40

Numbers group.

Includes ENdCategory, ENlCategory and ENoCategory.

EPunctuationGroup = 0x50

Punctuation group.

IncludesEPcCategory, PdCategory, EpeCategory, EPsCategory and EPoCategory.

ESymbolGroup = 0x60

Symbols group.

Includes ESmCategory, EScCategory, ESkCategory and ESoCategory.

ESeparatorGroup = 0x70

Separators group.

Includes EZsCategory, EZlCategory and EZlpCategory.

EControlGroup = 0x80

Control, format, private use, unassigned.

Includes ECcCategory, ECtCategory, ECsCategory, ECoCategory and ECnCategory.

EMaxAssignedGroup = 0xE0

The highest possible groups category.

EUnassignedGroup = 0xF0

Unassigned to any other group.

ELuCategory = EAlphaGroup | 0

Letter, Uppercase.

ELlCategory = EAlphaGroup | 1

Letter, Lowercase.

ELtCategory = EAlphaGroup | 2

Letter, Titlecase.

ELoCategory = ELetterOtherGroup | 0

Letter, Other.

EMaxLetterCategory = ELetterOtherGroup | 0x0F

The highest possible (non-modifier) letter category.

ELmCategory = ELetterModifierGroup | 0

Letter, Modifier.

EMaxLetterOrLetterModifierCategory = ELetterModifierGroup | 0x0F

The highest possible letter category.

EMnCategory = EMarkGroup | 0

Mark, Non-Spacing

EMcCategory = EMarkGroup | 1

Mark, Combining.

EMeCategory = EMarkGroup | 2

Mark, Enclosing.

ENdCategory = ENumberGroup | 0

Number, Decimal Digit.

ENlCategory = ENumberGroup | 1

Number, Letter.

ENoCategory = ENumberGroup | 2

Number, Other.

EPcCategory = EPunctuationGroup | 0

Punctuation, Connector.

EPdCategory = EPunctuationGroup | 1

Punctuation, Dash.

EPsCategory = EPunctuationGroup | 2

Punctuation, Open.

EPeCategory = EPunctuationGroup | 3

Punctuation, Close.

EPiCategory = EPunctuationGroup | 4

Punctuation, Initial Quote

EPfCategory = EPunctuationGroup | 5

Punctuation, Final Quote

EPoCategory = EPunctuationGroup | 6

Punctuation, Other.

ESmCategory = ESymbolGroup | 0

Symbol, Math.

EScCategory = ESymbolGroup | 1

Symbol, Currency.

ESkCategory = ESymbolGroup | 2

Symbol, Modifier.

ESoCategory = ESymbolGroup | 3

Symbol, Other.

EMaxGraphicCategory = ESymbolGroup | 0x0F

The highest possible graphic character category.

EZsCategory = ESeparatorGroup | 0

Separator, Space.

EMaxPrintableCategory = EZsCategory

The highest possible printable character category.

EZlCategory = ESeparatorGroup | 1

Separator, Line.

EZpCategory = ESeparatorGroup | 2

Separator, Paragraph.

ECcCategory = EControlGroup | 0

Other, Control.

ECfCategory = EControlGroup | 1

Other, Format.

EMaxAssignedCategory = EMaxAssignedGroup | 0x0F

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.

ECsCategory = EUnassignedGroup | 0

Other, Surrogate.

ECoCategory = EUnassignedGroup | 1

Other, Private Use.

ECnCategory = EUnassignedGroup | 2

Other, Not Assigned.

Enum TCjkWidth

Notional character width as known to East Asian (Chinese, Japanese, Korean (CJK)) coding systems.



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


Character which occupies a single cell.


Character which occupies 2 cells.


Characters that are always narrow and have explicit full-width counterparts. All of ASCII is an example of East Asian Narrow characters.


Characters that are always wide. This category includes characters that have explicit half-width counterparts.

Enum TEncoding

Encoding systems used by the translation functions.



The Unicode encoding.


The shift-JIS encoding (used in Japan).

Member Data Documentation



TUint iChar

TUint iChar[private]