# Click here for an important warning about swap space with certain build options.

## ReadMe: International Components for Unicode

Version: April 28, 2000

COPYRIGHT:
Copyright (c) 1997-2000 International Business Machines Corporation and others. All Rights Reserved.

### Contents

- Introduction
- What the International Components for Unicode Contain
- API overview
- Platform Dependencies
- Important Installation Notes
- How to Install/Build
- How ICU handles data
- Character Set Conversion Information
- Programming Notes
- Where to Find More Information
- Submitting Comments, Requesting Features and Reporting Bugs

### Introduction

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:

- UnicodeString supporting the Unicode 3.0 standard
- Resource bundles for storing and accessing localized information
- Number formatters for converting binary numbers into text strings for meaningful display
- Date and time formatters for converting internal time data into text strings for meaningful display
- Message formatters for putting together sequences of strings, numbers dates and other format to create messages
- Text collation supporting language sensitive comparison of strings
- Text boundary analysis for finding characters, word and sentence boundaries
- Changing simple data files rather than modifying program code easily localizes applications written using these tools
- Over 150 locales supported. Visit LocaleExplore (http://oss.software.ibm.com/developerworks/opensource/icu/localeexplorer) site for a demonstration and a full list of supported locales or click here for a table of supported locales.

It is possible to support additional locales by adding more locale data files, with no code changes.

Please refer to POSIX programmer's Guide for details on what the ISO locale ID means.

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.

IMPORTANT: Please make sure you understand the Copyright and License information.

### What the International Components for Unicode Contain

There are two ways to download the ICU releases,

- Official Release Snapshot:
  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 http://oss.software.ibm.com/icu/download/.
  If packaged snapshot is named ICUXXXXXX.zip , XXXXXX is the release version number.
  Please unzip this file. It will re-construct the source directory.
- CVS Source Repository:
  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:

- WebCVS:
  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.
- WinCVS:
  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:
  1.Install the WinCVS client, which you can download from the WinCVS home page.
  2.In the WinCVS preferences, specify your CVSRoot to be ":pserver:anoncvs@oss.software.ibm.com:/usr/cvs/icu"
  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".
  3.To "extract" the most recent version of ICU, select "Checkout module" from the "Cvs Admin" menu. Specify "icu" for the module name.
- CVS command line:
  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:
  export CVSROOT=:pserver:anoncvs@oss.software.ibm.com:/usr/cvs/icu
  cvs login CVS password: anoncvs
  cvs checkout icu
  cvs logout

For more details on how to download ICU directly from the web site, please also see http:/oss.software.ibm.com/developerworks/opensource/icu/project/download/index.html

Below, $Root 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.

The following files describe the code drop:

readme.html (this file) | describes the International Components for Unicode
license.html | contains IBM's public license

The following directories contain source code and data files:

$Root\source\common\ | The utility classes, such as ResourceBundle, Unicode, Locale, UnicodeString. The codepage conversion library API, UnicodeConverter.
$Root\source\i18n\ | The collation source files, Collator, RuleBasedCollator and CollationKey. The text boundary API, which locates character, word, sentence, and line breaks. The format API, which formats and parses data in numeric or date format to and from text.
$Root\source\test\intltest\ | A test suite including all C++ APIs. For information about running the test suite, see docs/intltest.html.
$Root/source/test/cintltst/ | A test suite including all C APIs. For information about running the test suite, see docs/cintltst.html.
$Root/data/ | The Unicode 3.0 data file. Please see http://www.unicode.org/ for more information. This directory also contains the resource files for all international objects. These files are of three types: TXT files contain general locale data. RES files contain non-portable locale data files which are generated by the genrb tool. COL files are non-portable packed binary collation data files which are created by the gencol tool. UCM files which contain mapping tables {from,to} Unicode in text format CNV files are non-portable packed binary conversion data generated by the makeconv tool. 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 udata.html for more information. 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 udata.html for more information.
$Root/source/tools | 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.
$Root/source/samples | Various sample programs that use ICU

The following directories are populated when you've built the framework:
(on Unix, replace $Root with the value given to the file "configure")

$Root/include/ | contains all the public header files.
$output | contains the libraries for static/dynamic linking or executable programs.

The following diagram shows the main directory structure of the International Components for Unicode:

                                      icu-NNNN

                                         |

            output                      icu

         _____|_____       ______________|______________________________

        |           |      |       |             |          |          |

     libraries   programs  include data         source      |          |

     (built)    (built)   (built)                |      readme.html license.html

                                                 |

                                _________________|__________________________

                               |       |         |       |         |        |

                             common  i18n      test     extra     tools   samples

                                                 |                 |

                                              ___|___           ___|_________________

                                              |      |          |      |      |     |

                                          intltest cintltst makeconv ctestfw genrb  ....

### API Overview

In the International Components for Unicode, there are two categories:

- Low-level Unicode/Resource Attributes: (icuuc library)

- Utility Classes
- Conversion Interface

- High-level Unicode Internationalization: (icui18n library)

- Text Boundary Classes
- Collation Classes
- Formatting Classes
- Transliterator Classes

See International Components for Unicode Coding Guidelines for a discussion of code conventions common to all library classes.

See also html/aindex.html for an alphabetical index, and html/HIERjava.html for a hierarchical index to detailed API documentation.

### Platform Dependencies

The platform dependencies have been isolated into the following 4 files:

- platform.h.in: Platform-dependent typedefs and defines:

· XP_CPLUSPLUS is defined for C++

· bool_t, TRUE and FALSE, int8_t, int16_t etc.

· U_EXPORT and U_IMPORT for specifying dynamic library import and export

- putil.c: platform-dependent implementations of various functions that are platform dependent: (declared in putil.h)

· icu_isNaN, icu_isInfinite(double), icu_getNaN(); icu_getInfinity for handling special floating point values

· icu_tzset, icu_timezone, icu_tzname and time for reading platform specific time and timezone information

· icu_getDefaultDataDirectory, icu_getDefaultLocaleID for reading the locale setting and data directory

· icu_isBigEndian for finding the endianess of the platform

· icu_nextDouble is used specifically by the ChoiceFormat API.

- mutex.h and mutex.cpp: 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 docs/mutex.html for more information.

- We supply sample implementations for WinNT, Win95, Win98, Sun/Solaris, RedHat/Linux, HP-UX and for AIX on an RS/6000.
- 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.
- 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.

- udata.h: The data-accessing interface in ICU is implemented such that there is a lot of flexibility for reading a data file. Each platform can tune the performance of file accessing for its environment by choosing to implement one of the following options:

- DLL
- Memory map
- Plain text

### Important Installation Notes

Win32 Platform

If you are building on the Win32 platform, it is important that you understand a few build details:

DLL directories and the PATH setting: 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.

To change your PATH: 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.

Link with Runtime libraries: 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.

OS/390 Platform

If you are building on the OS/390 UNIX System Services platform, it is important that you understand a
few details.
The gnu utilities gmake and gzip/gunzip are needed and can be obtained for OS/390 from
www.mks.com. Search for os/390, register, and follow download directions.
DLL directories and the LIBPATH setting: The ICU dlls libicu-i18n and libicu-uc.dll should be added
to the LIBPATH environment variable concatenation.
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.
The makedep executable is shipped with ICU for use with the OS/390 ICU build process. 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.
When running the test suite, the TZ environment variable should be set to export TZ="PST8PDT" so
that time zone comparisons are correct.

OS/400 Platform

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.

- Requirements:
  - QSHELL interpreter installed (install base option 30, operating system)
  - QShell Utilities, PRPQ 5799-XEH
  - ILE C++ for AS/400, PRPQ 5799-GDW
  - GNU facilities (the gnu facilities are currently available by request only. Send e-mail to rchasgo400@us.ibm.com )

- Build environment setup:
  1. 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.
  2. Set up the following environment variables in your build process (use ADDENVVAR or WRKENVVAR CL commands)
     CC - '/usr/bin/icc'
     CXX - ' /usr/bin/icc'
     MAKE - '/usr/bin/gmake'
     OUTPUTDIR - identifies target as400 library for *module, *pgm and *srvpgm objects

  3. Add QCXXN, to your build process library list. This results in the resolution of CRTCPPMOD used by the icc compiler
  4. Configure the Makefiles (see configure below) Note: Verify that the mh-os400 configure file is used.
     - Run 'configure --host=as400-os400'
     - Change the TARGET entries in `common/Makefile.in, i18n/Makefile.in, tools/toolutil/Makefile.in` so that instead of `TARGET=libicu-uc.$(SO)` they read `TARGET=$(LIBICU)uc.$(SO)` [remove hyphens]
     - Change Makefile.in's (under source/tools) that have LIBICU-TOOLUTIL so that it follows the other LIBICU variables on the link line: `$(LIBICU-UC) $(LIBICU-TOOLUTIL) @LIBS@ @LIB_M@`
     - The 'clean' and 'install' targets will not work without changes because of symbolic links. To delete the target module, program, or service programs replace `rm -rf` with $(RMV), and in the library installation targets (install-library) change `$(INSTALL)` to `$(INSTALL-S)`.

  5. gmake -e (-e to pickup the compilers)

Note on NULL pointer checks:

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.

### How to Install/Build on Win NT

Building International Components for Unicode requires:

- Microsoft NT 3.51 or above
- Microsoft Visual C++ 6.0 (Service Pack 2 is required to work with the release build of max speed optimization).

The steps are:

1. 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.
2. Set the environment variable ICU_DATA, the full pathname of the data directory, to indicate where the locale data files and conversion mapping tables are.
3. Start Microsoft Visual C++ 6.0.
4. Choose "File" menu and select "Open WorkSpace".
5. In the file chooser, choose icu\source\allinone\allinone.dsw. Open this workspace.
6. This workspace includes all the International Components for Unicode libraries, necessary tools as well as intltest and cintltest test suite projects.
7. Set the active Project. Choose "Project" menu and select "Set active project". In the submenu, select "all" workspace.
8. 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.)
9. 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".
10. 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.
11. Save the value of the TZ environment variable and then set it to PST8PDT.
12. Reopen the "allinone" project file and run the "intltest" test. Reset the TZ value.
13. To run the C test suite, set "cintltst" as the active project, repeat steps 11 and then run the "cintltst" test..
14. Build and run as outlined above.

Note: To set the active configuration, two different possibilities are:

- Choose "Build" menu, select "Set Active Configuration", and select "Win32 Release" or "Win32 Debug".
- 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.

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:
1. common
2. i18n
3. makedata (which invokes makeconv, genrb, gencol, genccode etc.)
4. ctestfw
5. intltest and cintltst, if you want to run the test suite.
Regarding the test suite, please read the directions in docs/intltest.html and docs/cintltst.html

### How to Install/Build on Unix

Note: In release 1.4.1.2, using runConfigureICU or directly calling `configure --enable-mapped=yes --enable-mapped-dll=yes` attempts to compile a 16 Megabyte source file. If you run out of virtual memory, you may need to increase your swap space. On a test Linux machine, 500mb of swap was required for the compile.

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

Building International Components for Unicode on Unix requires:

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 http://www.mks.com. Please do a search on "os/390".

The steps are:

1. Unzip the icuXXXX.tar (or icuXXXX.tgz) file.
2. Before running the test programs or samples, please set the environment variable ICU_DATA, 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.
3. Change directory to the "icu/source".
4. 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.*,
5. You also need to set other environment variables for different build systems. Use this table or provided script.
6. Type "./configure" or type "./configure --help" to print the available options.
7. 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.
8. Optionally, type "make check" to verify the test suite.
9. Type "Make install" to install.

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:
1. common
2. i18n
3. makeconv
4. genrb
5. gencol
6. gentz
7. genccode
8. ctestfw
9. intltest and cintltst, if you want to run the test suite.
Regarding the test suite, please read the directions in docs/intltest.html and docs/cintltst.html

# How ICU handles data

### How to add a locale data file

To add locale data files to International Components for Unicode do the following:

1. Create a file containing the key-value pairs which value you are overriding from the parent locale data file.
Make sure the filename is the locale ID with the extension ".txt". We recommend you copy parent file and change the values
that need to be changed, remove all other key-pairs. Be sure to update the locale ID key (the outmost brace) with
the name of the locale id your a creating.

2. Name the file with locale ID you are creating with a ".txt" at the end.

e.g. fr_BF.txt
Would create a locale that inherits all the key-value pairs from fr.txt.

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

4. Regenerate the data DLL file. Please see "How to Install" section for more details on how to verify the ICU release.

How to add resource bundle data to your application

Adding resource bundle data to your application is quite simple:

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 resource bundle documentation or resource bundle format).
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>, ", %, &, `, (, ), *, +, ,, -, ., /, :, ;, <, =, >, ?, _).
Use that same directory name (absolute path) when instantiating a resource bundle at run time.

### Where Collation Data is stored

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.

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.

You will need to regenerate your ".col" files in the following circumstances:

1. You are moving your data to another platform. Since the ".col" files are non-portable, you must make sure they are regenerated.
2. DO NOT copy them from one platform to another.
3. 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.

### Character Set Conversion Information

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.

Click here to view converters implemented in ICU. To see converters in action, please visit http://oss.software.ibm.com/developerworks/opensource/icu/localeexplorer/?converter&

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.

### Programming Notes

#### Reporting Errors

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.

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.

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.

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.

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.

#### C Function and Data Type Naming

Function names. 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.

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,

    UChar* uloc_getLanguage(...);

    void uloc_setDefaultLocale(...);

    UChar* ures_getString(...);

Struct and enum type names. For structs and enum types, the rule is that their names begin with a capital "U." There is no underscore for struct names.

           UResourceBundle;

           UCollator;

           UCollationResult;

Enum value names. Enumeration values have names that begin with "UXXX" where XXX stands for the name of the functional category.

    UNUM_DECIMAL;

    UCOL_GREATER;

Macro names. Macro names are in all caps, but there are currently no other requirements.

Constant names. 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.

#### Preflighting and Overflow Handling

In ICU's C APIs, the user needs to adhere to the following principles for consistency across all functional categories:

1. All the Unicode string processing should be expressed in terms of a UChar* buffer that is always null terminated.
2. The APIs assume that the input string parameters are statically allocated fix-sized character buffers.
3. 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.
4. 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.

To find out how large the result buffer should be, ICU provides a preflighting C interface. The interface works like this:

1. When using the "preflighting" 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.
2. 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.
3. 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.

The following three options demonstrates how to use the preflighting interface,

    /**

     * @param result is a pointer to where the actual result will be.

     * @param maxResultSize is the number of characters the buffer pointed to be result has room for.

     * @return The actual length of the result (counting the terminating null)

     */

    int32_t doSomething( /* input params */, UChar* result,

                    int32_t maxResultSize, UErrorCode* err);

In this sample, if the actual result doesn’t fit in the space available in maxResultSize, 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 do 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 that buffer’s address for result.

All preflighting functions have a fill-in ErrorCode parameter (and follow the normal ErrorCode rules), even if they are not currently doing so. Buffer overflow would be treated as a FAILURE error condition, but would not be reported when the caller passes in NULL for actualResultSize (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. MISSING_RESOURCE_ERROR etc..

#### Arrays as return types

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.

    int32_t countArrayItems(/* params */);

    int32_t getArrayElement(int32_t elementIndex, /* other params */,

                 UChar* result, int32_t maxResultSize, UErrorCode* err);

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.

    for (i = 0; i < countArrayItems(...); i++) {

            UChar element[50];

            getArrayItem(i, ..., element, 50, &err);

            /* do something with element */

    }

In the case of the resource bundle ures_XXXX 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.

    void countArrayItems(int32_t* rows, int32_t* columns,

                            /* other params */);

    int32_t get2dArrayElement(int32_t rowIndex,

                    int32_t colIndex,

                    /* other params */,

                    UChar* result,

                    int32_t maxResultSize,

                    UErrorCode* err);

### Where to Find More Information

http://oss.software.ibm.com/icu is a pointer to general information about the International Components for Unicode.

docs/udata.html is a raw draft of ICU data handling.

html/aindex.html is an alphabetical index to detailed API documentation.
html/HIERjava.html is a hierarchical index to detailed API documentation.

docs/collate.html is an overview to Collation.

docs/BreakIterator.html is a diagram showing how BreakIterator processes text elements.

http://www.ibm.com/unicode is a pointer to information on how to make applications global.

### Submitting Comments, Requesting Features and Reporting Bugs

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 icu@oss.software.ibm.com.

Copyright © 1997-2000 International Business Machines Corporation and others. All Rights Reserved.
IBM Center for Java Technology Silicon Valley,
10275 N De Anza Blvd., Cupertino, CA 95014
All rights reserved.