<?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> </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_d0e260809_href.jpg" placement="inline"/>
</fig> </section>
</refbody></reference>