<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 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: 

-->

<!DOCTYPE reference

  PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">

<reference id="GUID-7FCFB114-B186-5615-9134-08612BB675EE" xml:lang="en"><title>tcharexample:

TChar example</title><shortdesc>This example application demonstrates how to use <codeph>TChar</codeph>, <codeph>TCharF</codeph>, <codeph>TCharLC</codeph> and <codeph>TCharUC</codeph> classes.</shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody>

<section id="GUID-5EC052E8-4E6E-4F84-8F20-46C70AA6B637"> </section>

<section id="GUID-7ECA6815-84B4-5BA0-A73F-7E2DEBE2AFFF"><title>Purpose</title> <p> <codeph>TChar</codeph> represents

a single character. It stores the character's value as a 32-bit unsigned integer

and it provides various functions to manipulate the character and retrieve

its properties. </p> <p>TChar and its derived classes can be used to represent

Unicode values outside plane <b>0</b> (that is, Unicode values within the

extended Unicode range from <codeph>0x10000</codeph> to <codeph>0xFFFFF</codeph>).

This differentiates them from the related class <codeph>TText</codeph>, which

can only be used for 16-bit Unicode character values. </p> </section>

<section id="GUID-3615DBD7-5EEA-4548-A7A8-F183E3EF3977"><title>Class summary</title><ul>

<li><p><xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita"><apiname>TChar</apiname></xref> - Holds a character value and provides a number

of utility functions to manipulate it and test its properties.</p></li>

<li><p><xref href="GUID-02D39887-4F76-3C42-B9B0-61E7AB8553C3.dita"><apiname>TCharF</apiname></xref> - Folds a specified character and provides

functions to fold additional characters after construction of the object.</p></li>

<li><p><xref href="GUID-08D4F858-475F-3391-B2BD-2F0DAE88298A.dita"><apiname>TCharLC</apiname></xref> - Converts a specified character to lower

case and provides functions to convert additional characters after construction

of the object.</p></li>

<li><p><xref href="GUID-43BDE741-3C5B-388D-BF6B-851475FB9EAE.dita"><apiname>TCharUC</apiname></xref> - Converts a specified character to upper

case and provides functions to convert additional characters after construction

of the object.</p></li>

</ul></section>

<section id="GUID-A7AA11C2-9F69-4C1F-B078-789A34B78A37"><title>Download</title> <p>Click

on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-53527143-a65f-4fee-857a-6045a2c53370.zip" scope="external">tcharexample.zip</xref>.</p><p>click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-53527143-a65f-4fee-857a-6045a2c53370.html" scope="peer">browse</xref> to view the example code.</p> </section>

<section id="GUID-6F406325-07F5-59FC-845C-F248DF0DCB3A"><title>Design and

implementation</title> <p><b>Using TChar </b> </p> <p>The example retrieves

information about a character using: </p> <ul>

<li id="GUID-FEED5E65-C2E9-5F95-95A5-8AE6AACC6FAC"><p>various <codeph>Is...()</codeph> functions,

for instance its case (e.g. <xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-41EB7098-6282-3C9C-9C19-1DEA3C53E8F4"><apiname>TChar::IsLower()</apiname></xref>), whether

it is alphabetic (<xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-E166314C-A8BE-32B7-A4E6-95987A5CDB76"><apiname>TChar::IsAlpha()</apiname></xref>), a decimal digit (<xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-1AFEF873-6968-34A5-A7DF-4E303B56FC3E"><apiname>TChar::IsDigit()</apiname></xref>),

and whether it is printable (<xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-A3E01D65-C348-347A-8EBA-242C9B532B3A"><apiname>TChar::IsPrint()</apiname></xref>). </p> </li>

<li id="GUID-82028A1F-A5BC-5337-9D7A-90A9BBE35291"><p>various <codeph>Get...()</codeph> functions,

for instance its upper, lower and title case versions, e.g. (<xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-D51385D5-977F-313C-966D-8015400D476F"><apiname>TChar::GetUpperCase()</apiname></xref>),

and the character width for Chinese, Japanese and Korean characters (<xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-8BD67CC9-6BCE-348B-B46A-AD2DF71CD4F5"><apiname>TChar::GetCjkWidth()</apiname></xref>). </p> </li>

<li id="GUID-6AFA657D-3CA9-5129-A359-38A9F4D377CE"><p>the <xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-AF251970-9134-3F62-99E1-05A853286113"><apiname>TChar::TCharInfo</apiname></xref> struct.

This struct holds most of the information about the character, including its

Unicode category, and is populated by calling <xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-0290D155-32E2-3240-A8E4-F31CD117BF9A"><apiname>TChar::GetInfo()</apiname></xref>. </p> </li>

</ul> <p><b>Using TCharF, TCharLC and TCharUC </b> </p><p>Related APIs</p><ul>

<li><p><xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-8BD67CC9-6BCE-348B-B46A-AD2DF71CD4F5"><apiname>TChar::GetCjkWidth()</apiname></xref></p></li>

<li><p><xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-0290D155-32E2-3240-A8E4-F31CD117BF9A"><apiname>TChar::GetInfo()</apiname></xref></p></li>

<li><p><xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-D51385D5-977F-313C-966D-8015400D476F"><apiname>TChar::GetUpperCase()</apiname></xref></p></li>

<li><p><xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-E166314C-A8BE-32B7-A4E6-95987A5CDB76"><apiname>TChar::IsAlpha()</apiname></xref></p></li>

<li><p><xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-1AFEF873-6968-34A5-A7DF-4E303B56FC3E"><apiname>TChar::IsDigit()</apiname></xref></p></li>

<li><p><xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-41EB7098-6282-3C9C-9C19-1DEA3C53E8F4"><apiname>TChar::IsLower()</apiname></xref></p></li>

<li><p><xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-A3E01D65-C348-347A-8EBA-242C9B532B3A"><apiname>TChar::IsPrint()</apiname></xref></p></li>

<li><p><xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita#GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D/GUID-AF251970-9134-3F62-99E1-05A853286113"><apiname>TChar::TCharInfo</apiname></xref> - A structure to hold information

about a Unicode character.</p></li>

</ul> <p> <xref href="GUID-02D39887-4F76-3C42-B9B0-61E7AB8553C3.dita"><apiname>TCharF</apiname></xref> represents a folded character. The example

demonstrates how folding a character removes case and accent distinctions. </p> <p>The

example also demonstrates converting characters between lower and upper case

using <xref href="GUID-08D4F858-475F-3391-B2BD-2F0DAE88298A.dita"><apiname>TCharLC</apiname></xref> and <xref href="GUID-43BDE741-3C5B-388D-BF6B-851475FB9EAE.dita"><apiname>TCharUC</apiname></xref>. </p></section>

<section id="GUID-5D7398C3-10AA-5A9F-A9EE-CE2C0E5D751F"><title>Building and

configuring</title> <p>To build the example: </p> <ul>

<li id="GUID-FC094F4A-A486-5539-AFAB-8319BCF9A762"><p>You can build the example

from your IDE or the command line. </p> <p>If you use an IDE, import the <filepath>bld.inf</filepath> file

of the example into your IDE, and use the build command of the IDE. </p> <p>If

you use the command line, open a command prompt, and set the current directory

to the source code directory of the example. You can then build the example

with the SBSv1 build tools with the following commands: </p> <p><userinput>bldmake

bldfiles</userinput> </p> <p><userinput>abld build</userinput> </p> <p> <xref href="GUID-793A5EF9-CC16-5EEB-9011-6431EA76EB15.dita">How to use bldmake</xref> and <xref href="GUID-B6B54E07-3B34-5D5C-8815-93383FA8FB4B.dita">How to use abld</xref> describe

how to use the SBSv1 build tools. </p> </li>

<li id="GUID-FE66EDF9-B29C-5847-828E-6399E633D131"><p>For the emulator, the

example builds an executable called <filepath>tcharexample.exe</filepath> in

the <filepath>epoc32\release\winscw\&lt;udeb or                 urel&gt;\</filepath> folder. </p> </li>

</ul> </section>

<section id="GUID-98BBBB36-DC53-5EC1-B724-1857E9C27A6F"><title>Running the

example</title> <p>The example application displays a list of options and

sub options to the user and takes input from the user. </p> <fig id="GUID-DE40E9EB-B045-551C-84FF-C5C116462DC2">

<title>              Screenshot for TChar example            </title>

<image href="GUID-016704BE-DC2B-5AD3-B9BE-76A327678B38_d0e357477_href.jpg" placement="inline"/>

</fig> </section>