1282 lines
74 KiB
HTML
1282 lines
74 KiB
HTML
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
|
||
<html>
|
||
<head>
|
||
<meta http-equiv=Content-Type content="text/html; charset=iso-8859-1">
|
||
<title>ReadMe for ICU</title>
|
||
</head>
|
||
|
||
<body lang="en-US">
|
||
|
||
<div class=Section1>
|
||
|
||
<h2>ReadMe: International Components for Unicode</h2>
|
||
|
||
<p>Version: February 1, 2000</p>
|
||
|
||
|
||
<div class=MsoNormal align=center style='text-align:center'>
|
||
|
||
<hr size=2 width="100%" align=center>
|
||
|
||
</div>
|
||
|
||
|
||
<p>COPYRIGHT: <br>
|
||
Copyright (c) 1997-2000 International Business Machines Corporation and others.
|
||
All Rights Reserved.</p>
|
||
|
||
|
||
<div class=MsoNormal align=center style='text-align:center'>
|
||
|
||
<hr size=2 width="100%" align=center>
|
||
|
||
</div>
|
||
|
||
|
||
<p><br>
|
||
</p>
|
||
|
||
<h3><u>Contents</u></h3>
|
||
|
||
<ul type=disc>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l3 level1 lfo3;tab-stops:list .5in'><a href="#introduction">Introduction</a></li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l3 level1 lfo3;tab-stops:list .5in'><a href="#WhatContain">What
|
||
the International Components for Unicode Contain</a></li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l3 level1 lfo3;tab-stops:list .5in'><a href="#API">API overview</a></li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l3 level1 lfo3;tab-stops:list .5in'><a
|
||
href="#PlatformDependencies">Platform Dependencies</a></li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l3 level1 lfo3;tab-stops:list .5in'><a href="#ImportantNotes">Important
|
||
Installation Notes</a></li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l3 level1 lfo3;tab-stops:list .5in'><a href="#HowToInstall">How
|
||
to Install/Build</a></li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l3 level1 lfo3;tab-stops:list .5in'><a href="#datahandling">How
|
||
ICU handles data</a></li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l3 level1 lfo3;tab-stops:list .5in'><a href="#CharsetConvert">Character
|
||
Set Conversion Information</a></li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l3 level1 lfo3;tab-stops:list .5in'><a href="#ProgrammingNotes">Programming
|
||
Notes</a></li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l3 level1 lfo3;tab-stops:list .5in'><a href="#WhereToFindMore">Where
|
||
to Find More Information</a></li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l3 level1 lfo3;tab-stops:list .5in'><a href="#SubmittingComments">Submitting
|
||
Comments, Requesting Features and Reporting Bugs</a></li>
|
||
</ul>
|
||
|
||
<h3><a name=introduction></a><u>Introduction</u></h3>
|
||
|
||
<p>Today's software market is a global one in which it is desirable to develop
|
||
and maintain one application that supports a wide variety of national
|
||
languages. International Components for Unicode provides the following tools to
|
||
help you write language independent applications: </p>
|
||
|
||
<ul type=disc>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l5 level1 lfo6;tab-stops:list .5in'>UnicodeString supporting the
|
||
Unicode 3.0 standard</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l5 level1 lfo6;tab-stops:list .5in'>Resource bundles for storing
|
||
and accessing localized information</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l5 level1 lfo6;tab-stops:list .5in'>Number formatters for
|
||
converting binary numbers into text strings for meaningful display</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l5 level1 lfo6;tab-stops:list .5in'>Date and time formatters for
|
||
converting internal time data into text strings for meaningful display</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l5 level1 lfo6;tab-stops:list .5in'>Message formatters for
|
||
putting together sequences of strings, numbers dates and other format to
|
||
create messages</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l5 level1 lfo6;tab-stops:list .5in'>Text collation supporting
|
||
language sensitive comparison of strings</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l5 level1 lfo6;tab-stops:list .5in'>Text boundary analysis for
|
||
finding characters, word and sentence boundaries</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l5 level1 lfo6;tab-stops:list .5in'>Changing simple data files
|
||
rather than modifying program code easily localizes applications written
|
||
using these tools</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l5 level1 lfo6;tab-stops:list .5in'>Over 150 locales supported.
|
||
Visit <a
|
||
href="http://oss.software.ibm.com/developerworks/opensource/icu/localeexplorer">LocaleExplorer
|
||
(http://oss.software.ibm.com/developerworks/opensource/icu/localeexplorer)</a>
|
||
site for a demonstration and a full list of supported locales or <a
|
||
href="docs/supp_loc.html">click here for a table of supported locales</a>.</li>
|
||
</ul>
|
||
|
||
<p>It is possible to support additional locales by adding more locale data
|
||
files, with no code changes. </p>
|
||
|
||
<p>Please refer to POSIX programmer's Guide for details on what the ISO locale
|
||
ID means. </p>
|
||
|
||
<p>Your comments are important to making this release successful. We are
|
||
committed to fixing any bugs, and will also use your feedback to help plan
|
||
future releases. </p>
|
||
|
||
<p style='margin-right:.5in;margin-left:.5in'><b><u>IMPORTANT</u>: Please make
|
||
sure you understand the <a href="license.html">Copyright and License
|
||
information</a>.</b></p>
|
||
|
||
<p style='margin-right:.5in;margin-left:.5in'> </p>
|
||
|
||
<h3><a name=WhatContain></a><u>What the International Components for Unicode
|
||
Contain</u></h3>
|
||
|
||
<p>There are two ways to download the ICU releases, </p>
|
||
|
||
<ul type=disc>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l10 level1 lfo9;tab-stops:list .5in'><strong>Official Release
|
||
Snapshot:</strong><b><br>
|
||
</b>If you want to use ICU (as opposed to developing it), your best bet is
|
||
to download an official, packaged ICU version of the ICU source
|
||
code. These versions are tested more thoroughly than day-to-day
|
||
development builds of the system, and they are packaged in zip and tar
|
||
files for convenient download. These packaged files can be found at <a
|
||
href="http://oss.software.ibm.com/icu/download/index.html">http://oss.software.ibm.com/icu/download/index.html</a>.<br>
|
||
If packaged snapshot is named <b>ICUXXXXXX.zip </b>, XXXXXX is the release
|
||
version number.<br>
|
||
Please unzip this file. It will re-construct the source directory. </li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l10 level1 lfo9;tab-stops:list .5in'><strong>CVS Source
|
||
Repository:</strong><b><br>
|
||
</b>If you are interested in developing features, patches, or bug fixes
|
||
for ICU, you should probably be working with the latest version of the ICU
|
||
source code. You will need to check the code out of our CVS repository to
|
||
ensure that you have the most recent version of all of the files. There
|
||
are several ways to do this:</li>
|
||
<ul type=circle>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l10 level2 lfo9;tab-stops:list 1.0in'>WebCVS:<br>
|
||
If you want to browse the code and only make occasional downloads, you
|
||
may want to use WebCVS. It provides a convenient, web-based interface for
|
||
browsing and downloading the latest version of the ICU source code and
|
||
documentation. You can also view each file's revision history, display
|
||
the differences between individual revisions, determine which revisions
|
||
were part of which official release, and so on. </li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l10 level2 lfo9;tab-stops:list 1.0in'>WinCVS:<br>
|
||
If you will be doing serious work on ICU, you should probably install a
|
||
CVS client on your own machine so that you can do batch operations
|
||
without going through the WebCVS interface. On Windows, we suggest the
|
||
WinCVS client. The following is the example instruction on how to download
|
||
ICU via WinCVS: <br>
|
||
1.Install the WinCVS client, which you can download from the WinCVS home
|
||
page. <br>
|
||
2.In the WinCVS preferences, specify your CVSRoot to be
|
||
":pserver:anoncvs@oss.software.ibm.com:/usr/cvs/icu"<br>
|
||
with the password "anoncvs". To enter the CVSRoot value, select
|
||
"Preferences" from the "Cvs Admin" pull-down menu.
|
||
Authentication should be set to "'passwd' file on the
|
||
cvs server". <br>
|
||
3.To "extract" the most recent version of ICU, select
|
||
"Checkout module" from the "Cvs Admin" menu. Specify
|
||
"icu" for the module name. </li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l10 level2 lfo9;tab-stops:list 1.0in'>CVS command line:<br>
|
||
You can also check out the repository anonymously on UNIX using the
|
||
following commands, after first setting your CVSROOT to point to the ICU
|
||
repository: <br>
|
||
<br>
|
||
export CVSROOT=:pserver:anoncvs@oss.software.ibm.com:/usr/cvs/icu<br>
|
||
cvs login CVS password: anoncvs<br>
|
||
cvs checkout icu<br>
|
||
cvs logout</li>
|
||
</ul>
|
||
</ul>
|
||
|
||
<p>For more details on how to download ICU directly from the web site, please
|
||
also see <a
|
||
href="http://oss.software.ibm.com/icu/download/index.html">http:/oss.software.ibm.com/icu/download/index.html</a></p>
|
||
|
||
<p>Below, <b>$Root</b> is the placement of the icu directory in your file
|
||
system, like "drive:\...\icu" in your environment.
|
||
"drive:\..." stands for any drive and any directory on that drive
|
||
that you chose to install icu into.</p>
|
||
|
||
<p><b>The following files describe the code drop:</b> <br>
|
||
<br>
|
||
</p>
|
||
|
||
<table border=1 cellpadding=0 style='mso-cellspacing:1.5pt;mso-padding-alt:
|
||
0in 0in 0in 0in'>
|
||
<tr>
|
||
<td style='padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>readme.html (this file)</p>
|
||
</td>
|
||
<td style='padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>describes the International Components for Unicode</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td style='padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>license.html</p>
|
||
</td>
|
||
<td style='padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>contains IBM's public license</p>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<p><b>The following directories contain source code and data files:</b> <br>
|
||
<br>
|
||
</p>
|
||
|
||
<table border=1 cellpadding=0 width=623 style='width:467.25pt;mso-cellspacing:
|
||
1.5pt;mso-padding-alt:0in 0in 0in 0in'>
|
||
<tr>
|
||
<td width="20%" style='width:20.0%;padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>$Root\source\common\</p>
|
||
</td>
|
||
<td width="80%" style='width:80.0%;padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>The utility classes, such as ResourceBundle, Unicode,
|
||
Locale, UnicodeString. The codepage conversion library API, UnicodeConverter.</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" style='width:20.0%;padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>$Root\source\i18n\</p>
|
||
</td>
|
||
<td width="80%" style='width:80.0%;padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>The collation source files, Collator, RuleBasedCollator
|
||
and CollationKey. <br>
|
||
The text boundary API, which locates character, word, sentence, and <br>
|
||
line breaks. <br>
|
||
The format API, which formats and parses data in numeric or date format to
|
||
and from text.</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" style='width:20.0%;padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>$Root\source\test\intltest\</p>
|
||
</td>
|
||
<td width="80%" style='width:80.0%;padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>A test suite including all C++ APIs. For information about
|
||
running the test suite, see <a href="docs/intltest.html">docs/intltest.html</a>.</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" style='width:20.0%;padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>$Root/source/test/cintltst/</p>
|
||
</td>
|
||
<td width="80%" style='width:80.0%;padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>A test suite including all C APIs. For information about
|
||
running the test suite, see <a href="docs/cintltst.html">docs/cintltst.html.</a></p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" style='width:20.0%;padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>$Root/data/</p>
|
||
</td>
|
||
<td width="80%" style='width:80.0%;padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>The Unicode 3.0 data file. Please see <a
|
||
href="http://www.unicode.org/">http://www.unicode.org/</a> for more
|
||
information. <br>
|
||
This directory also contains the resource files for all international
|
||
objects. These files are of three types: </p>
|
||
<ul type=disc>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l12 level1 lfo12;tab-stops:list .5in'>TXT files contain
|
||
general locale data. </li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l12 level1 lfo12;tab-stops:list .5in'>RES files contain
|
||
non-portable locale data files which are generated by the <strong>genrb</strong>
|
||
tool.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l12 level1 lfo12;tab-stops:list .5in'>COL files are non-portable
|
||
packed binary collation data files which are created by the <strong>gencol</strong>
|
||
tool. </li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l12 level1 lfo12;tab-stops:list .5in'>UCM files which
|
||
contain mapping tables {from,to} Unicode in text format</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l12 level1 lfo12;tab-stops:list .5in'>CNV files are
|
||
non-portable packed binary conversion data generated by the <strong>makeconv</strong>
|
||
tool.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l12 level1 lfo12;tab-stops:list .5in'>icudata.dll file
|
||
contains data files in a dynamic loadable library format. At this
|
||
moment, this file contains CNV files, converter aliases, timezone data
|
||
and Unicode character names. Please read <a href="docs/udata.html">udata.html</a>
|
||
for more information.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l12 level1 lfo12;tab-stops:list .5in'>icudata.dat file
|
||
contains data files in a memory mapped file format. At this moment, this
|
||
file contains CNV files, converter aliases, timezone data and Unicode
|
||
character names. Please read <a href="docs/udata.html">udata.html</a>
|
||
for more information.</li>
|
||
</ul>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" style='width:20.0%;padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>$Root/source/tools</p>
|
||
</td>
|
||
<td width="80%" style='width:80.0%;padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>Tools for generating the data files. Data files are
|
||
generated by invoking $Root/source/tools/makedata.bat on Win32 or
|
||
$Root/source/make install on Unix.</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" style='width:20.0%;padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>$Root/source/samples</p>
|
||
</td>
|
||
<td width="80%" style='width:80.0%;padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>Various sample programs that use ICU</p>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<p> <b>The following directories are populated when you've built the
|
||
framework:</b> <br>
|
||
(on Unix, replace $Root with the value given to the file
|
||
"configure") <br>
|
||
</p>
|
||
|
||
<table border=1 cellpadding=0 style='mso-cellspacing:1.5pt;mso-padding-alt:
|
||
0in 0in 0in 0in'>
|
||
<tr>
|
||
<td style='padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>$Root/include/</p>
|
||
</td>
|
||
<td style='padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>contains all the public header files.</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td style='padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>$output</p>
|
||
</td>
|
||
<td style='padding:.75pt .75pt .75pt .75pt'>
|
||
<p class=MsoNormal>contains the libraries for static/dynamic linking or
|
||
executable programs.</p>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<p><b>The following diagram shows the main directory structure of the
|
||
International Components for Unicode:</b> </p>
|
||
|
||
<pre> icu-NNNN</pre>
|
||
<pre> |</pre>
|
||
<pre> output <span style="mso-spacerun: yes"> </span> <span style="mso-spacerun: yes"> </span>icu</pre>
|
||
<pre> _____|_____<span style="mso-spacerun: yes"> </span>______________|______________________________</pre>
|
||
<pre> | <span style="mso-spacerun: yes"> </span>| <span style="mso-spacerun: yes"> </span>| <span style="mso-spacerun: yes"> </span> | | <span style="mso-spacerun: yes"> </span> |<span style="mso-spacerun: yes"> </span>|</pre>
|
||
<pre> libraries<span style="mso-spacerun: yes"> </span>programs include data source |<span style="mso-spacerun: yes"> </span>|</pre>
|
||
<pre> (built)<span style="mso-spacerun: yes"> </span>(built)<span style="mso-spacerun: yes"> </span>(built) <span style="mso-spacerun: yes"> </span> | readme.html license.html</pre>
|
||
<pre> <span style="mso-spacerun: yes"> </span> |<span style="mso-spacerun: yes"> </span></pre>
|
||
<pre> <span style="mso-spacerun: yes"> </span>_________________|__________________________</pre>
|
||
<pre> <span style="mso-spacerun: yes"> </span>|<span style="mso-spacerun: yes"> </span>|<span style="mso-spacerun: yes"> </span><span style="mso-spacerun: yes"> </span> | |<span style="mso-spacerun: yes"> </span>|<span style="mso-spacerun: yes"> </span>|</pre>
|
||
<pre> <span style="mso-spacerun: yes"> </span>common<span style="mso-spacerun: yes"> </span>i18n <span style="mso-spacerun: yes"> </span>test<span style="mso-spacerun: yes"> </span>extra<span style="mso-spacerun: yes"> </span>tools<span style="mso-spacerun: yes"> </span>samples</pre>
|
||
<pre> <span style="mso-spacerun: yes"> </span> <span style="mso-spacerun: yes"> </span>|<span style="mso-spacerun: yes"> </span>|<span style="mso-spacerun: yes"> </span></pre>
|
||
<pre> <span style="mso-spacerun: yes"> </span> ___|___ <span style="mso-spacerun: yes"> </span>___|_________________</pre>
|
||
<pre><span style="mso-spacerun: yes"> </span>|<span style="mso-spacerun: yes"> </span>|<span style="mso-spacerun: yes"> </span>|<span style="mso-spacerun: yes"> </span>|<span style="mso-spacerun: yes"> </span>|<span style="mso-spacerun: yes"> </span>| </pre>
|
||
<pre><span style="mso-spacerun: yes"> </span>intltest cintltst makeconv ctestfw genrb<span style="mso-spacerun: yes"> </span>....</pre>
|
||
|
||
<h3><a name=API></a><u>API Overview</u></h3>
|
||
|
||
<p>In the International Components for Unicode, there are two categories: </p>
|
||
|
||
<ul type=disc>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l15 level1 lfo15;tab-stops:list .5in'>Low-level Unicode/Resource
|
||
Attributes: (<strong>icuuc</strong> library)</li>
|
||
<ul type=circle>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l15 level2 lfo15;tab-stops:list 1.0in'><a
|
||
href="docs/utilCL.html">Utility Classes</a></li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l15 level2 lfo15;tab-stops:list 1.0in'><a
|
||
href="docs/conversion_interface.htm">Conversion Interface</a></li>
|
||
</ul>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l15 level1 lfo15;tab-stops:list .5in'>High-level Unicode
|
||
Internationalization: (<strong>icui18n</strong> library)</li>
|
||
<ul type=circle>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l15 level2 lfo15;tab-stops:list 1.0in'><a
|
||
href="docs/boundCL.html">Text Boundary Classes</a></li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l15 level2 lfo15;tab-stops:list 1.0in'><a
|
||
href="docs/collateCL.html">Collation Classes</a></li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l15 level2 lfo15;tab-stops:list 1.0in'><a
|
||
href="docs/formatCL.html">Formatting Classes</a></li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l15 level2 lfo15;tab-stops:list 1.0in'>Transliterator
|
||
Classes</li>
|
||
</ul>
|
||
</ul>
|
||
|
||
<p>See <A HREF="http://oss.software.ibm.com/icu/develop/codestds.html">International Components for Unicode Coding Guidelines</A>
|
||
for a discussion of code conventions common to all library classes. </p>
|
||
|
||
<p>See also <a href="../html/aindex.html">html/aindex.html</a> for an alphabetical
|
||
index, and <a href="../html/HIERjava.html">html/HIERjava.html</a> for a
|
||
hierarchical index to detailed API documentation. <br>
|
||
<br>
|
||
</p>
|
||
|
||
<h3><a name=PlatformDependencies></a><u>Platform Dependencies</u></h3>
|
||
|
||
<p>The platform dependencies have been isolated into the following 4 files: </p>
|
||
|
||
<ul type=disc>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l14 level1 lfo18;tab-stops:list .5in'><u>platform.h.in:</u>
|
||
Platform-dependent typedefs and defines:</li>
|
||
</ul>
|
||
|
||
<p class=MsoNormal style='margin-right:.5in;mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;margin-left:1.0in;text-indent:-.25in;mso-list:l13 level1 lfo20;tab-stops:
|
||
list .5in'><![if !supportLists]><span style='font-size:10.0pt;mso-bidi-font-size:
|
||
12.0pt;font-family:Symbol'><EFBFBD><span style='font:7.0pt "Times New Roman"'>
|
||
</span></span><![endif]>XP_CPLUSPLUS is defined for C++</p>
|
||
|
||
<p class=MsoNormal style='margin-right:.5in;mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;margin-left:1.0in;text-indent:-.25in;mso-list:l13 level1 lfo20;tab-stops:
|
||
list .5in'><![if !supportLists]><span style='font-size:10.0pt;mso-bidi-font-size:
|
||
12.0pt;font-family:Symbol'><EFBFBD><span style='font:7.0pt "Times New Roman"'>
|
||
</span></span><![endif]>bool_t, TRUE and FALSE, int8_t, int16_t etc.</p>
|
||
|
||
<p class=MsoNormal style='margin-right:.5in;mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;margin-left:1.0in;text-indent:-.25in;mso-list:l13 level1 lfo20;tab-stops:
|
||
list .5in'><![if !supportLists]><span style='font-size:10.0pt;mso-bidi-font-size:
|
||
12.0pt;font-family:Symbol'><EFBFBD><span style='font:7.0pt "Times New Roman"'>
|
||
</span></span><![endif]>U_EXPORT and U_IMPORT for specifying dynamic library
|
||
import and export</p>
|
||
|
||
<ul type=disc>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l6 level1 lfo23;tab-stops:list .5in'><u>putil.c:</u>
|
||
platform-dependent implementations of various functions that are platform
|
||
dependent: (declared in putil.h)</li>
|
||
</ul>
|
||
|
||
<p class=MsoNormal style='margin-right:.5in;mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;margin-left:1.0in;text-indent:-.25in;mso-list:l1 level1 lfo25;tab-stops:
|
||
list .5in'><![if !supportLists]><span style='font-size:10.0pt;mso-bidi-font-size:
|
||
12.0pt;font-family:Symbol'><EFBFBD><span style='font:7.0pt "Times New Roman"'>
|
||
</span></span><![endif]>icu_isNaN, icu_isInfinite(double), icu_getNaN();
|
||
icu_getInfinity for handling special floating point values</p>
|
||
|
||
<p class=MsoNormal style='margin-right:.5in;mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;margin-left:1.0in;text-indent:-.25in;mso-list:l1 level1 lfo25;tab-stops:
|
||
list .5in'><![if !supportLists]><span style='font-size:10.0pt;mso-bidi-font-size:
|
||
12.0pt;font-family:Symbol'><EFBFBD><span style='font:7.0pt "Times New Roman"'>
|
||
</span></span><![endif]>icu_tzset, icu_timezone, icu_tzname and time for
|
||
reading platform specific time and timezone information</p>
|
||
|
||
<p class=MsoNormal style='margin-right:.5in;mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;margin-left:1.0in;text-indent:-.25in;mso-list:l1 level1 lfo25;tab-stops:
|
||
list .5in'><![if !supportLists]><span style='font-size:10.0pt;mso-bidi-font-size:
|
||
12.0pt;font-family:Symbol'><EFBFBD><span style='font:7.0pt "Times New Roman"'>
|
||
</span></span><![endif]>icu_getDefaultDataDirectory, icu_getDefaultLocaleID for
|
||
reading the locale setting and data directory</p>
|
||
|
||
<p class=MsoNormal style='margin-right:.5in;mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;margin-left:1.0in;text-indent:-.25in;mso-list:l1 level1 lfo25;tab-stops:
|
||
list .5in'><![if !supportLists]><span style='font-size:10.0pt;mso-bidi-font-size:
|
||
12.0pt;font-family:Symbol'><EFBFBD><span style='font:7.0pt "Times New Roman"'>
|
||
</span></span><![endif]>icu_isBigEndian for finding the endianess of the
|
||
platform</p>
|
||
|
||
<p class=MsoNormal style='margin-right:.5in;mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;margin-left:1.0in;text-indent:-.25in;mso-list:l1 level1 lfo25;tab-stops:
|
||
list .5in'><![if !supportLists]><span style='font-size:10.0pt;mso-bidi-font-size:
|
||
12.0pt;font-family:Symbol'><EFBFBD><span style='font:7.0pt "Times New Roman"'>
|
||
</span></span><![endif]>icu_nextDouble is used specifically by the ChoiceFormat
|
||
API.</p>
|
||
|
||
<ul type=disc>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l7 level1 lfo28;tab-stops:list .5in'><u>mutex.h and mutex.cpp</u>:
|
||
Code for doing synchronization in multithreaded applications. If you wish
|
||
to use International Components for Unicode in a multithreaded
|
||
application, you must provide a synchronization primitive that the classes
|
||
can use to protect their global data against simultaneous modifications.
|
||
See <a href="docs/mutex.html">docs/mutex.html</a> for more information.</li>
|
||
<ul type=circle>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l7 level2 lfo28;tab-stops:list 1.0in'>We supply sample
|
||
implementations for WinNT, Win95, Win98, Sun/Solaris, RedHat/Linux, HP-UX
|
||
and for AIX on an RS/6000.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l7 level2 lfo28;tab-stops:list 1.0in'>If you are changing
|
||
the platform-dependent files, ptypes.h and putil.h may also be interesting,
|
||
but shouldn't have to be changed. If you think any other files than the
|
||
ones mentioned above have platform dependencies, please contact us.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l7 level2 lfo28;tab-stops:list 1.0in'>For the Intltest test
|
||
suite, intltest.cpp in "icu\source\test\intltest\" contains the
|
||
method pathnameInContext, which must also be adapted to any new platform.</li>
|
||
</ul>
|
||
</ul>
|
||
|
||
<ul type=disc>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l14 level1 lfo18;tab-stops:list .5in'>udata.h: The data-accessing
|
||
interface in ICU is implemented such that there is a lot of flexibility
|
||
for reading a data file.<span style="mso-spacerun: yes"> </span>Each
|
||
platform can tune the performance of file accessing for its environment by
|
||
choosing to implement one of the following options:</li>
|
||
</ul>
|
||
|
||
<ul type=disc>
|
||
<ul type=circle>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l7 level2 lfo28;tab-stops:list 1.0in'>DLL</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l7 level2 lfo28;tab-stops:list 1.0in'>Memory map</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
|
||
auto;mso-list:l7 level2 lfo28;tab-stops:list 1.0in'>Plain text </li>
|
||
</ul>
|
||
</ul>
|
||
|
||
<h3><a name=ImportantNotes></a><u>Important Installation Notes </u></h3>
|
||
|
||
<p><strong>Win32 Platform</strong></p>
|
||
|
||
<p>If you are building on the Win32 platform, it is important that you
|
||
understand a few build details: </p>
|
||
|
||
<p><u>DLL directories and the PATH setting:</u> As delivered, the International
|
||
Components for Unicode build as several DLLs. These DLLs are placed in the
|
||
directories "icu\bin\Debug" and "icu\bin\Release".
|
||
You must add either of these directories to the PATH environment variable in
|
||
your system, or any executables you build will not be able to access
|
||
International Components for Unicode libraries. Alternatively, you can copy the
|
||
DLL files into a directory already in your PATH, but we do not recommend this
|
||
-- you can wind up with multiple copies of the DLL, and wind up using the wrong
|
||
one. </p>
|
||
|
||
<p><u>To change your PATH:</u> Do this under NT by using the System
|
||
control panel. Pick the "Environment" tab, select the variable PATH
|
||
in the lower box. In the "value" box, append the string
|
||
";drive:\...\icu\bin\Debug" at the end of the path string. If
|
||
there is nothing there, just type in "drive:\...\icu\bin\Debug".
|
||
Click the Set button, then the Ok button. </p>
|
||
|
||
<p><u>Link with Runtime libraries:</u> All the DLLs link with the C runtime
|
||
library "Debug Multithreaded DLL" or "Multithreaded DLL."
|
||
(This is changed through the Project Settings dialog, on the C/C++ tab, under
|
||
Code Generation.) It is important that any executable or other DLL you build
|
||
which uses the International Components for Unicode DLLs links with these
|
||
runtime libraries as well. If you do not do this, you will seemingly get memory
|
||
errors when you run the executable. <br>
|
||
</p>
|
||
|
||
<p><a name=OS390><strong>OS/390 Platform</strong></p>
|
||
|
||
<p>If you are building on the OS/390 UNIX System Services platform, it is
|
||
important that you understand a few details:</p>
|
||
<ul>
|
||
<li>The gnu utilities gmake and gzip/gunzip are needed and can be obtained for
|
||
OS/390 from <a href="http://www.mks.com/">http://www.mks.com/</a>.
|
||
Search for OS/390, register, and follow download directions.</li>
|
||
<li>Encoding considerations: The source code assumes that it is compiled
|
||
with codepage 1047 (to be exact, the UNIX System Services variant of it).
|
||
The pax command converts all of the source code files from ASCII
|
||
to codepage 1047 (USS) EBCDIC. However, some files are binary files
|
||
and must not be converted, or must be converted back to their original
|
||
state.
|
||
Those files are:<ul>
|
||
<li>All the .brk files located in the icu/data directory (icu/data/*.brk)</li>
|
||
<li>icu/source/test/testdata/uni-text.txt</li>
|
||
<li>icu/source/test/testdata/th18057.txt</li>
|
||
</ul>
|
||
Such a conversion can be done using iconv:<br>
|
||
<code>iconv -f IBM-1047 -t ISO8859-1 uni-text.txt > uni-text.txt</code></li>
|
||
<li>DLL directories and the LIBPATH setting:
|
||
Building and testing ICU needs the ICU libraries on the LIBPATH.
|
||
In other words, the LIBPATH should contain
|
||
(each path prepended with the root directory that contains the icu directory):
|
||
<ul>
|
||
<li>icu/source/common</li>
|
||
<li>icu/source/i18n</li>
|
||
<li>icu/source/tools/ctestfw</li>
|
||
<li>icu/source/tools/toolutil</li>
|
||
<li>icu/source/extra/ustdio</li>
|
||
</ul></li>
|
||
<li><p>OS/390 supports both native S/390 hexadecimal floating point and, with Version
|
||
2.6 and later, IEEE binary
|
||
floating point. This is a compile time option. Applications built with IEEE
|
||
should use ICU dlls that are
|
||
built with IEEE (and vice versa). The environment variable IEEE390=1 will cause
|
||
the OS/390 version
|
||
of ICU to be built with IEEE floating point. The default is native hexadecimal
|
||
floating point.<br>
|
||
<em>Important: </em>Currently (ICU 1.4.2), native floating point support
|
||
is sufficient for codepage conversion, resource bundle and UnicodeString operations,
|
||
but the Format APIs, especially ChoiceFormat, require IEEE binary floating point.</p>
|
||
<p>Examples for configuring ICU:<br>
|
||
Debug build: <code>IEEE390=1 ./configure</code><br>
|
||
Release build: <code>CFLAGS=-2 IEEE390=1 ./configure</code></p></li>
|
||
<li>The makedep executable that is used with the OS/390 ICU build
|
||
process is not shipped with ICU. It is available at the
|
||
<a href="http://www.s390.ibm.com/products/oe/bpxa1ty2.html">OS/390 UNIX - Tools and Toys</a>
|
||
site. The PATH
|
||
environment variable should be updated to contain the location of this
|
||
executable prior to build.
|
||
Alternatively, makedep may be moved into an existing PATH directory.</li>
|
||
<li>When running the test suite, the TZ environment variable should be set to
|
||
export TZ="PST8PDT" so
|
||
that time zone comparisons are correct.</li>
|
||
</ul>
|
||
|
||
<p><a name=OS400><strong>OS/400 Platform</strong></a></p>
|
||
|
||
ICU Reference Release 1.4.0 contains partial support for the 400
|
||
platform, but additional work by the user is currently needed to get
|
||
it to build completely.
|
||
A future release of the ICU should work out-of-the-box
|
||
under OS/400.
|
||
<UL>
|
||
<LI> Requirements:
|
||
<UL>
|
||
<LI> QSHELL interpreter installed (install base option 30, operating
|
||
system)
|
||
<LI> QShell Utilities, PRPQ 5799-XEH
|
||
<LI> ILE C++ for AS/400, PRPQ 5799-GDW
|
||
<LI> GNU facilities (the gnu facilities are currently available by request only. Send e-mail to <A HREF="mailto:rchasgo400@us.ibm.com">rchasgo400@us.ibm.com</A> )
|
||
|
||
<P></UL> <!-- end requirements -->
|
||
<LI> Build environment setup:
|
||
<OL>
|
||
<LI> Create AS400 target library. This library will be the target for the
|
||
resulting modules, programs and service programs. You will specify this
|
||
library on the OUTPUTDIR environment variable in step 2.
|
||
<LI> Set up the following environment variables in your build process (use
|
||
ADDENVVAR or WRKENVVAR CL commands)
|
||
<UL>
|
||
CC - '/usr/bin/icc'<BR>
|
||
CXX - ' /usr/bin/icc'<BR>
|
||
MAKE - '/usr/bin/gmake'<BR>
|
||
OUTPUTDIR - <I>identifies target as400 library for *module, *pgm and
|
||
*srvpgm objects</I>
|
||
<P></UL>
|
||
<LI> Add QCXXN, to your build process library list. This results in the
|
||
resolution of CRTCPPMOD used by the icc compiler
|
||
<LI> Configure the Makefiles (see configure below) Note: Verify that the
|
||
mh-os400 configure file is used.
|
||
<UL>
|
||
<LI> Run 'configure --host=as400-os400'
|
||
<LI> The 'clean' and 'install' targets will not work without changes
|
||
because of symbolic links. To delete the target module, program, or service programs replace <TT>rm -rf</TT> with <B>$(RMV)</B>, and in the
|
||
library installation targets (install-library) change
|
||
<TT>$(INSTALL)</TT> to <B><TT>$(INSTALL-S)</TT></B>.
|
||
<P></UL>
|
||
|
||
<LI> gmake -e (-e to pickup the compilers)
|
||
<P></OL> <!-- end build environment -->
|
||
</UL>
|
||
|
||
Note on NULL pointer checks:
|
||
<UL>
|
||
In common/ucnv.c and common/unistr.c (search for U_MAX_PTR), there are
|
||
additional checks for NULL pointers. This is because pointer
|
||
comparison works differently on the AS/400 architecture.
|
||
</UL>
|
||
|
||
<h3><a name=HowToInstall></a><u>How to Install/Build on Win NT</u></h3>
|
||
|
||
<p>Building International Components for Unicode requires: </p>
|
||
|
||
<ul type=disc>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l16 level1 lfo31;tab-stops:list .5in'>Microsoft NT 3.51 or above</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l16 level1 lfo31;tab-stops:list .5in'>Microsoft Visual C++ 6.0
|
||
(Service Pack 2 is required to work with the release build of max speed
|
||
optimization).</li>
|
||
</ul>
|
||
|
||
<p>The steps are: </p>
|
||
|
||
<ol start=1 type=1>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l11 level1 lfo34;tab-stops:list .5in'>Unzip the icu-XXXX.zip
|
||
file, type "unzip -a icu-XXXX.zip -d drive:\directory" under
|
||
command prompt or use WinZip. drive:\directory\icu is the root
|
||
($Root) directory (you may but don't need to place "icu" into another
|
||
directory). If you change the root, you will change the project settings
|
||
accordingly in EACH makefile in the project, updating the "include"
|
||
and "library" paths.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l11 level1 lfo34;tab-stops:list .5in'>Set the environment
|
||
variable <strong>ICU_DATA</strong>, the full pathname of the data
|
||
directory, to indicate where the locale data files and conversion mapping
|
||
tables are.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l11 level1 lfo34;tab-stops:list .5in'>Start Microsoft Visual C++
|
||
6.0.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l11 level1 lfo34;tab-stops:list .5in'>Choose "File"
|
||
menu and select "Open WorkSpace".</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l11 level1 lfo34;tab-stops:list .5in'>In the file chooser, choose
|
||
icu\source\allinone\allinone.dsw. Open this workspace.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l11 level1 lfo34;tab-stops:list .5in'>This workspace includes all
|
||
the International Components for Unicode libraries, necessary tools as
|
||
well as intltest and cintltest test suite projects.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l11 level1 lfo34;tab-stops:list .5in'>Set the active Project.
|
||
Choose "Project" menu and select "Set active project".
|
||
In the submenu, select "all" workspace.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l11 level1 lfo34;tab-stops:list .5in'>Set the active
|
||
configuration ("Win32 Debug" or "Win32 Release") and
|
||
make sure this matches your PATH setting as described in the previous
|
||
chapter. (See note below.)</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l11 level1 lfo34;tab-stops:list .5in'>Choose "Build"
|
||
menu and select "Rebuild All". If you want to build the Debug
|
||
and Release configurations at the same time, choose "Build" menu
|
||
and select "Batch Build..." instead (and mark all configurations
|
||
as checked), then click the button named "Rebuild All".</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l11 level1 lfo34;tab-stops:list .5in'>The "all"
|
||
workspace will build all the test programs as well as the tools for
|
||
generating binary locale data files. The "makedata"
|
||
project will be run automatically to convert the locale data files from
|
||
text format into icudata.dll.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l11 level1 lfo34;tab-stops:list .5in'>Save the value of the <strong>TZ</strong>
|
||
environment variable and then set it to <strong>PST8PDT</strong>. </li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l11 level1 lfo34;tab-stops:list .5in'>Reopen the
|
||
"allinone" project file and run the "intltest" test.
|
||
Reset the <strong>TZ</strong> value.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l11 level1 lfo34;tab-stops:list .5in'>To run the C test suite,
|
||
set "cintltst" as the active project, repeat steps 11 and then
|
||
run the "cintltst" test..</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l11 level1 lfo34;tab-stops:list .5in'>Build and run as outlined
|
||
above.</li>
|
||
</ol>
|
||
|
||
<p><b>Note: </b>To set the active configuration, two different possibilities are:
|
||
</p>
|
||
|
||
<ul type=disc>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l4 level1 lfo37;tab-stops:list .5in'>Choose "Build"
|
||
menu, select "Set Active Configuration", and select "Win32
|
||
Release" or "Win32 Debug".</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l4 level1 lfo37;tab-stops:list .5in'>Another way is to select
|
||
"Customize" in the "Tools" menu, select the
|
||
"Toolbars" tab, enable "Build" instead of "Build
|
||
Minibar", and click on "Close". This will bring up a
|
||
toolbar which you can move aside the other permanent toolbars at the top
|
||
of the MSVC window. The advantage is that you now have an easy-to-reach
|
||
pop-up menu that will always show the currently selected active
|
||
configuration. Or, you can drag the project and configuration selections
|
||
and drop them on the menu bar for later selection.</li>
|
||
</ul>
|
||
|
||
<p>It is also possible to build each library individually, using the workspaces
|
||
in each respective directory. They have to be built in the following order: <br>
|
||
1. common <br>
|
||
2. i18n <br>
|
||
3. makedata (which invokes makeconv,
|
||
genrb, gencol, genccode etc.)<br>
|
||
4. ctestfw <br>
|
||
5. intltest and cintltst, if you
|
||
want to run the test suite. <br>
|
||
Regarding the test suite, please read the directions in <a
|
||
href="docs/intltest.html">docs/intltest.html</a> and <a
|
||
href="docs/cintltst.html">docs/cintltst.html</a> </p>
|
||
|
||
<h3>How to Install/Build on Unix</h3>
|
||
|
||
<p>There is a set of Makefiles for Unix that supports Linux w/gcc, Solaris
|
||
w/gcc and Workshop CC, AIX w/xlc and OS/390 with C++.</p>
|
||
|
||
<p>Building International Components for Unicode on Unix requires: </p>
|
||
|
||
<p>A UNIX C++ compiler, (gcc, cc, xlc_r, etc...) installed on the target
|
||
machine. A recent version of GNU make (3.7+). OS/390 gnu utilities
|
||
for both make (gmake) and zip (gzip/gunzip) can be found at the MKS web site at
|
||
<a href="http://www.mks.com">http://www.mks.com</a>. Please do a search
|
||
on "os/390".</p>
|
||
|
||
<p>The steps are: </p>
|
||
|
||
<ol start=1 type=1>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l2 level1 lfo40;tab-stops:list .5in'>Unzip the icuXXXX.tar (or
|
||
icuXXXX.tgz) file.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l2 level1 lfo40;tab-stops:list .5in'>Before running the test programs
|
||
or samples, please set the environment variable <strong>ICU_DATA</strong>,
|
||
the full pathname of the data directory, to indicate where the locale data
|
||
files and conversion mapping tables are. If this variable is not
|
||
set, the default user data directory will be used.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l2 level1 lfo40;tab-stops:list .5in'>Change directory to the
|
||
"icu/source".</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l2 level1 lfo40;tab-stops:list .5in'>If it is not already set,
|
||
please set the executable flag for the following files (by executing
|
||
'chmod +x' command): configure, install.sh and config.*, </li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l2 level1 lfo40;tab-stops:list .5in'>You also need to set other
|
||
environment variables for different build systems. Use this <a
|
||
href="docs/build_env.htm">table</a> or provided <a
|
||
href="source/runConfigureICU">script</a>.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l2 level1 lfo40;tab-stops:list .5in'>Type "./configure"
|
||
or type "./configure --help" to print the available options.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l2 level1 lfo40;tab-stops:list .5in'>Type "make" to compile
|
||
the libraries and all the data files. On OS/390, both IEEE binary
|
||
floating point and native S/390 hexadecimal floating point calculations
|
||
are supported. The default is to build with native floating-point
|
||
support. Please set the environment variable IEEE390=1 if you would
|
||
like to make the ICU DLLs with IEEE floating point support.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l2 level1 lfo40;tab-stops:list .5in'>Optionally, type "make
|
||
check" to verify the test suite.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l2 level1 lfo40;tab-stops:list .5in'>Type "Make
|
||
install" to install.</li>
|
||
</ol>
|
||
|
||
<p>It is also possible to build each library individually, using the Makefiles
|
||
in each respective directory. They have to be built in the following order: <br>
|
||
1. common <br>
|
||
2. i18n <br>
|
||
3. makeconv <br>
|
||
4. genrb<br>
|
||
5. gencol<br>
|
||
6. gentz<br>
|
||
7. genccode<br>
|
||
8. ctestfw <br>
|
||
9. intltest and cintltst, if you
|
||
want to run the test suite. <br>
|
||
Regarding the test suite, please read the directions in <a
|
||
href="docs/intltest.html">docs/intltest.html</a> and <a
|
||
href="docs/cintltst.html">docs/cintltst.html</a> </p>
|
||
|
||
<h1><a name=datahandling>How ICU handles data</a></h1>
|
||
|
||
<span style='mso-bookmark:datahandling'></span>
|
||
|
||
<h3><u>How to add a locale data file</u></h3>
|
||
|
||
<p>To add locale data files to International Components for Unicode do the
|
||
following: </p>
|
||
|
||
<p style='margin-right:.5in;margin-left:.5in'>1. Create a file containing the
|
||
key-value pairs which value you are overriding from the parent locale data
|
||
file. <br>
|
||
Make sure the filename is the locale ID with the extension
|
||
".txt". We recommend you copy parent file and change the values <br>
|
||
that need to be changed, remove all other key-pairs. Be sure
|
||
to update the locale ID key (the outmost brace) with <br>
|
||
the name of the locale id your a creating.</p>
|
||
|
||
<p style='margin-right:.5in;margin-left:.5in'>2. Name the file with locale ID
|
||
you are creating with a ".txt" at the end.</p>
|
||
|
||
<p style='margin-right:1.0in;margin-left:1.0in'>e.g.
|
||
fr_BF.txt <br>
|
||
Would create a locale that inherits all the key-value pairs from fr.txt.</p>
|
||
|
||
<p style='margin-right:.5in;margin-left:.5in'>3. Add the name of that file
|
||
(without the ".txt" extension) as a single line in
|
||
"index.txt" file in the default locale directory (icu/data/).</p>
|
||
|
||
<p style='margin-right:.5in;margin-left:.5in'>4. Regenerate the data DLL
|
||
file. Please see "<a href="#HowToInstall">How to Install</a>"
|
||
section for more details on how to verify the ICU release.</p>
|
||
|
||
<p><a name=addrbdatatoapp></a><b><u><span style='font-size:13.5pt'>How to add
|
||
resource bundle data to your application</span></u></b> </p>
|
||
|
||
<p>Adding resource bundle data to your application is quite simple: </p>
|
||
|
||
<p>Create resource bundle files with the right format and names in a directory
|
||
for resource bundles you create in your application directory tree.(for more
|
||
information of that format of these files see <a
|
||
href="../icuhtml/ResourceBundle.html#DOC.DOCU">resource bundle documentation</a>
|
||
or <a
|
||
href="http://www.ibm.com/java/education/international-unicode/unicodec.html">resource
|
||
bundle format)</a>. <br>
|
||
Please note that resource bundle tag names should contain only invariant 7-bit
|
||
ASCII characters (e.g. ones from the following set: A-Z, a-z, 0-9, <SP>,
|
||
", %, &, `, (, ), *, +, ,, -, ., /, :, ;, <, =, >, ?, _).<br>
|
||
Use that same directory name (absolute path) when instantiating a resource
|
||
bundle at run time.</p>
|
||
|
||
<h3><a name=WhereCollation></a><u>Where Collation Data is stored</u></h3>
|
||
|
||
<p>Collation data is stored in a single directory on a local disk. Each
|
||
locale's data is stored in a corresponding ASCII text file indicated by a
|
||
"CollationElements" tag . For instance, the data for de_CH is stored
|
||
with a tag "CollationElements" in a file named "de_CH.txt".
|
||
Reading the collation data from these files can be time-consuming, especially
|
||
for large pieces of data that occur in languages such as Japanese. For this
|
||
reason, the Collation Framework implements a second file format, a
|
||
performance-optimized, non-portable, binary format. These binary files are
|
||
generated automatically by the framework the first time a collation table is
|
||
parsed. They have names of the form "de_CH.col". Once the files are
|
||
generated by the framework, future loading of those collations occur from the
|
||
binary file, rather than the text file, at much higher speed. </p>
|
||
|
||
<p>In general, you don't have to do anything special with these files. They can
|
||
be generated directly by using the "gencol" tool. In addition,
|
||
they can also be generated and used automatically by the framework, without
|
||
intervention on your part. However, there are situations in which you will have
|
||
to regenerate them. To do so, you must manually delete the ".col"
|
||
files from your collation data directory and re-run the gencol tool.</p>
|
||
|
||
<p>You will need to regenerate your ".col" files in the following
|
||
circumstances: </p>
|
||
|
||
<ol start=1 type=1>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l0 level1 lfo43;tab-stops:list .5in'>You are moving your data to
|
||
another platform. Since the ".col" files are non-portable,
|
||
you must make sure they are regenerated.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l0 level1 lfo43;tab-stops:list .5in'><b>DO NOT </b>copy them from
|
||
one platform to another.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l0 level1 lfo43;tab-stops:list .5in'>You have changed the
|
||
"CollationElements" data in the locale's ".txt"
|
||
file. Note that if you change the default rules for some reason,
|
||
which underlie all collations, then you will have to rebuild ALL your
|
||
".col" files, since they all are merged with the default rule
|
||
set.</li>
|
||
</ol>
|
||
|
||
<h3><a name=CharsetConvert></a><u>Character Set Conversion Information</u></h3>
|
||
|
||
<p>The charset conversion library provides ways to convert simple text strings
|
||
(e.g., char*) such as ISO 8859-1 to and from Unicode. The objective is to
|
||
provide clean, simple, reliable, portable and adaptable data structures and
|
||
algorithms to support the International Components for Unicode's character
|
||
codeset Conversion APIs. The conversion data in the library originated from the
|
||
NLTC lab in IBM. The IBM character set conversion tables are publicly available
|
||
in the published IBM document called "CHARACTER DATA REPRESENTATION
|
||
ARCHITECTURE - REFERENCE AND REGISTRY". The character set conversion
|
||
library includes single-byte, double-byte and some UCS encodings to and from Unicode.
|
||
This document can be ordered through Mechanicsberg and it comes with 2 CD ROMs
|
||
which have machine-readable conversion tables on them. The license agreement is
|
||
included in International Components for Unicode agreement. </p>
|
||
|
||
<p>Click <a href="data/convrtrs.txt">here</a> to view converters implemented in
|
||
ICU. To see converters in action, please visit <a
|
||
href="http://oss.software.ibm.com/developerworks/opensource/icu/localeexplorer/?converter&">
|
||
http://oss.software.ibm.com/developerworks/opensource/icu/localeexplorer/?converter&</a></p>
|
||
|
||
<p>To order the document in the US you can call 1-800-879-2755 and request
|
||
document number SC09-2190-00. The cost of this publication is $75.00 US not
|
||
including tax. </p>
|
||
|
||
<h3><a name=ProgrammingNotes></a><u>Programming Notes</u></h3>
|
||
|
||
<h4><u>Reporting Errors</u></h4>
|
||
|
||
<p>In order for the code to be portable, only a subset of the C++ language that
|
||
will compile correctly on even the oldest of C++ compilers (and also to provide
|
||
a usable C interface) can be used in the implementation, which means that
|
||
there's no use the C++ exception mechanism in the code. </p>
|
||
|
||
<p>After considering many alternatives, the decision was that every function
|
||
that can fail takes an error-code parameter by reference. This is always the
|
||
last parameter in the function’s parameter list. The ErrorCode type is defined
|
||
as a enumerated type. Zero represents no error, positive values represent
|
||
errors, and negative values represent non-error status codes. Macros were
|
||
provided, SUCCESS and FAILURE, to check the error code. </p>
|
||
|
||
<p>The ErrorCode parameter is an input-output parameter. Every function tests
|
||
the error code before doing anything else, and immediately exits if it’s a
|
||
FAILURE error code. If the function fails later on, it sets the error code
|
||
appropriately and exits without doing any other work (except, of course, any
|
||
cleanup it has to do). If the function encounters a non-error condition it
|
||
wants to signal (such as "encountered an unmapped character" in
|
||
transcoding), it sets the error code appropriately and continues. Otherwise,
|
||
the function leaves the error code unchanged. </p>
|
||
|
||
<p>Generally, only functions that don’t take an ErrorCode parameter, but call
|
||
functions that do, have to declare one. Almost all functions that take an
|
||
ErrorCode parameter and also call other functions that do merely have to
|
||
propagate the error code they were passed down to the functions they call.
|
||
Functions that declare a new ErrorCode parameter must initialize it to
|
||
ZERO_ERROR before calling any other functions. </p>
|
||
|
||
<p>The rationale here is to allow a function to call several functions (that
|
||
take error codes) in a row without having to check the error code after each
|
||
one. [A function usually will have to check the error code before doing any
|
||
other processing, however, since it is supposed to stop immediately after
|
||
receiving an error code.] Propagating the error-code parameter down the call
|
||
chain saves the programmer from having to declare one everywhere, and also
|
||
allows us to more closely mimic the C++ exception protocol. </p>
|
||
|
||
<h4><u>C Function and Data Type Naming</u></h4>
|
||
|
||
<p><b>Function names.</b> If a function is identical (or almost identical) to
|
||
an ANSI or POSIX function, we give it the same name and (as much as possible)
|
||
the same parameter list. A "u" is prepended onto the beginning of the
|
||
name. </p>
|
||
|
||
<p>For functions that exist prior to version 1.2.1, that the function name
|
||
should begin with a lower-case "u". After the "u" is a
|
||
short code identifying the subsystem it belongs to (e.g., "loc",
|
||
"rb", "cnv", "coll", etc.). This code is
|
||
separated from the actual function name by an underscore, and the actual
|
||
function name can be anything. For example, </p>
|
||
|
||
<pre style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:
|
||
.5in;margin-bottom:.0001pt'><span style='font-size:7.5pt'>UChar* uloc_getLanguage(...);<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'>void uloc_setDefaultLocale(...);<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'>UChar* ures_getString(...);</span></pre>
|
||
|
||
<p><b>Struct and enum type names.</b> For structs and enum types, the rule is
|
||
that their names begin with a capital "U." There is no underscore for
|
||
struct names.</p>
|
||
|
||
<pre><span style='font-size:7.5pt'> UResourceBundle;<o:p></o:p></span></pre><pre><span
|
||
style='font-size:7.5pt'> UCollator;<o:p></o:p></span></pre><pre><span
|
||
style='font-size:7.5pt'><span style="mso-spacerun: yes"> </span>UCollationResult;</span></pre>
|
||
|
||
<p><b>Enum value names.</b> Enumeration values have names that begin with
|
||
"UXXX" where XXX stands for the name of the functional category.</p>
|
||
|
||
<pre style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:
|
||
.5in;margin-bottom:.0001pt'><span style='font-size:7.5pt'>UNUM_DECIMAL;<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'>UCOL_GREATER;</span></pre>
|
||
|
||
<p><b>Macro names.</b> Macro names are in all caps, but there are currently no
|
||
other requirements. </p>
|
||
|
||
<p><b>Constant names.</b> Many constant names (constants defined with
|
||
"const", not macros defined with "#define" that are used as
|
||
constants) begin with a lowercase k, but this isn’t universally enforced. </p>
|
||
|
||
<h4><u>Preflighting and Overflow Handling</u></h4>
|
||
|
||
<p>In ICU's C APIs, the user needs to adhere to the following principles for
|
||
consistency across all functional categories: </p>
|
||
|
||
<ol start=1 type=1>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l8 level1 lfo46;tab-stops:list .5in'>All the Unicode string
|
||
processing should be expressed in terms of a UChar* buffer that is always
|
||
null terminated.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l8 level1 lfo46;tab-stops:list .5in'>The APIs assume that the
|
||
input string parameters are statically allocated fix-sized character
|
||
buffers.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l8 level1 lfo46;tab-stops:list .5in'>When the value a function is
|
||
going to return is already stored as a constant value in static space
|
||
(e.g., it’s coming from a fixed table, or is stored in a cache), the
|
||
function will just return the const UChar* pointer.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l8 level1 lfo46;tab-stops:list .5in'>When the function can’t
|
||
return a UChar* to storage the user doesn’t have to delete, the caller
|
||
needs to pass in a pointer to a character buffer that the function can
|
||
fill with the result. This pointer needs to be accompanied by a int32_t
|
||
parameter that gives the size of the buffer.</li>
|
||
</ol>
|
||
|
||
<p>To find out how large the result buffer should be, ICU provides a <strong>preflighting</strong>
|
||
C interface. The interface works like this: </p>
|
||
|
||
<ol start=1 type=1>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l9 level1 lfo49;tab-stops:list .5in'>When using the "<b>preflighting</b>"
|
||
option: you need to pass the function a NULL pointer for the buffer
|
||
pointer, and the function returns the actual size of the result. You can
|
||
then choose to allocate a buffer of the correct size and re-run the
|
||
operation if you would like to.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l9 level1 lfo49;tab-stops:list .5in'>After allocating a buffer of
|
||
some reasonable size on the stack and passes that to the function, if the
|
||
result can fit in that buffer, everything works fine. If the result
|
||
doesn’t fit, the function will return the actual size needed. You
|
||
can then allocate a buffer of the correct size on the heap and try calling
|
||
the same function again.</li>
|
||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||
mso-list:l9 level1 lfo49;tab-stops:list .5in'>Now you have created a
|
||
buffer of some reasonable size on the stack and passes it to the
|
||
function. If you don't care about the completeness of the result and
|
||
the allocated buffer is too small, you can continue on using the truncated
|
||
result.</li>
|
||
</ol>
|
||
|
||
<p>The following three options demonstrates how to use the preflighting
|
||
interface, </p>
|
||
|
||
<pre style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:
|
||
.5in;margin-bottom:.0001pt'><span style='font-size:7.5pt'>/** <o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> * @param result is a pointer to where the actual result will be.<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> * @param maxResultSize is the number of characters the buffer pointed to be result has room for. <o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> * @return The actual length of the result (counting the terminating null)<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> */<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'>int32_t doSomething( /* input params */, UChar* result,<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> int32_t maxResultSize, UErrorCode* err);</span></pre>
|
||
|
||
<p>In this sample, if the actual result doesn’t fit in the space available in <span
|
||
style='font-size:10.0pt;font-family:"Courier New"'>maxResultSize</span>, this
|
||
function returns the amount of space necessary to hold the result, and result
|
||
holds as many characters of the actual result as possible. If you don’t care
|
||
about this, no further action is necessary. If you <i>do </i>care about the
|
||
truncated characters, you can then allocate a buffer on the heap of the size
|
||
specified by the return value and call the function again, passing <i>that </i>buffer’s
|
||
address for result. </p>
|
||
|
||
<p>All preflighting functions have a fill-in <span style='font-size:10.0pt;
|
||
font-family:"Courier New"'>ErrorCode</span> parameter (and follow the normal <span
|
||
style='font-size:10.0pt;font-family:"Courier New"'>ErrorCode</span> rules),
|
||
even if they are not currently doing so. Buffer overflow would be treated as a
|
||
FAILURE error condition, but would <i>not</i> be reported when the caller
|
||
passes in NULL for <span style='font-size:10.0pt;font-family:"Courier New"'>actualResultSize</span>
|
||
(presumably, a NULL for this parameter means the client doesn’t care if he got
|
||
a buffer overflow). All other failing error conditions will overwrite the
|
||
"buffer overflow" error, e.g. <span style='font-family:"Courier New"'>MISSING_RESOURCE_ERROR</span>
|
||
etc..</p>
|
||
|
||
<h4><u>Arrays as return types</u></h4>
|
||
|
||
<p>Returning an array of strings is fairly easy in C++, but very hard in C.
|
||
Instead of returning the array pointer directly, we opted for an iterative
|
||
interface instead: split the function into two functions. One returns the
|
||
number of elements in the array, and the other one returns a single specified
|
||
element from the array.</p>
|
||
|
||
<pre style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:
|
||
.5in;margin-bottom:.0001pt'><span style='font-size:7.5pt'>int32_t countArrayItems(/* params */);<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'>int32_t getArrayElement(int32_t elementIndex, /* other params */,<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> UChar* result, int32_t maxResultSize, UErrorCode* err);</span></pre>
|
||
|
||
<p>In this case, iterating across all the elements in the array would amount to
|
||
a call to the count() function followed by multiple calls to the getElement()
|
||
function. </p>
|
||
|
||
<pre style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:
|
||
.5in;margin-bottom:.0001pt'><span style='font-size:7.5pt'>for (i = 0; i < countArrayItems(...); i++) {<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> UChar element[50];<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> getArrayItem(i, ..., element, 50, &err);<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> /* do something with element */<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'>}</span></pre>
|
||
|
||
<p>In the case of the resource bundle <span style='font-family:"Courier New"'>ures_XXXX</span>
|
||
functions returning 2-dimensional arrays, the getElement() function takes both
|
||
x and y coordinates for the desired element, and the count() function returns
|
||
the number of arrays (x axis). Since the size of each array element in
|
||
the resource 2-D arrays should always be the same, this provides an easy-to-use
|
||
C interface. </p>
|
||
|
||
<pre style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:
|
||
.5in;margin-bottom:.0001pt'><span style='font-size:7.5pt'>void countArrayItems(int32_t* rows, int32_t* columns,<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> /* other params */);<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'><![if !supportEmptyParas]> <![endif]><o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'>int32_t get2dArrayElement(int32_t rowIndex, <o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> int32_t colIndex,<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> /* other params */, <o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> UChar* result, <o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> int32_t maxResultSize,<o:p></o:p></span></pre><pre
|
||
style='margin-top:0in;margin-right:.5in;margin-bottom:0in;margin-left:.5in;
|
||
margin-bottom:.0001pt'><span style='font-size:7.5pt'> UErrorCode* err);</span></pre>
|
||
|
||
<h3><a name=WhereToFindMore></a><u>Where to Find More Information</u></h3>
|
||
|
||
<p><a href="http://oss.software.ibm.com/icu/">http://oss.software.ibm.com/icu/</a>
|
||
is a pointer to general information about the International Components for
|
||
Unicode. </p>
|
||
|
||
<p><a href="docs/udata.html">docs/udata.html</a> is a raw draft of ICU data
|
||
handling.</p>
|
||
|
||
<p><a href="../icuhtml/aindex.html">html/aindex.html</a> is an alphabetical
|
||
index to detailed API documentation. <br>
|
||
<a href="../icuhtml/HIERjava.html">html/HIERjava.html</a> is a hierarchical
|
||
index to detailed API documentation. </p>
|
||
|
||
<p><a href="docs/collate.html">docs/collate.html</a> is an overview to
|
||
Collation. </p>
|
||
|
||
<p><a href="docs/BreakIterator.html">docs/BreakIterator.html</a> is a diagram
|
||
showing how BreakIterator processes text elements. </p>
|
||
|
||
<p><a href="http://www.ibm.com/developer/unicode/">http://www.ibm.com/developer/unicode/</a> is a
|
||
pointer to information on how to make applications global. <br>
|
||
</p>
|
||
|
||
<h3><a name=SubmittingComments></a><u>Submitting Comments, Requesting Features
|
||
and Reporting Bugs</u></h3>
|
||
|
||
<p>To submit comments, request features and report bugs, please contact
|
||
us. While we are not able to respond individually to each comment, we do
|
||
review all comments. Send Internet email to <a
|
||
href="mailto:icu@oss.software.ibm.com">icu@oss.software.ibm.com</a>.</p>
|
||
|
||
|
||
<div class=MsoNormal align=center style='text-align:center'>
|
||
|
||
<hr size=2 width="100%" align=center>
|
||
|
||
</div>
|
||
|
||
|
||
<p>Copyright <20> 1997-2000 International Business Machines Corporation and
|
||
others. All Rights Reserved.<br>
|
||
IBM Center for Java Technology Silicon Valley, <br>
|
||
10275 N De Anza Blvd., Cupertino, CA 95014 <br>
|
||
All rights reserved. </p>
|
||
|
||
|
||
<div class=MsoNormal align=center style='text-align:center'>
|
||
|
||
<hr size=2 width="100%" align=center>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
|
||
</body>
|
||
|
||
</html>
|