- Main Page
- Modules
- Data Structures
- Files
- Related Pages

- Search for |

- File List
- Globals

# ucat.h File Reference

C API: Message Catalog Wrappers. More...

`#include "unicode/utypes.h"`
`#include "unicode/ures.h"`

Go to the source code of this file.

## Functions
u_nl_catd | u_catopen (const char *name, const char *locale, UErrorCode *ec)
| Open and return an ICU message catalog descriptor.
void | u_catclose (u_nl_catd catd)
| Close an ICU message catalog, given its descriptor.
const UChar * | u_catgets (u_nl_catd catd, int32_t set_num, int32_t msg_num, const UChar *s, int32_t *len, UErrorCode *ec)
| Retrieve a localized string from an ICU message catalog.
## Variables
U_CDECL_BEGIN typedef UResourceBundle * | u_nl_catd
| An ICU message catalog descriptor, analogous to nl_catd.

## Detailed Description

C API: Message Catalog Wrappers.

This C API provides look-alike functions that deliberately resemble the POSIX catopen, catclose, and catgets functions. The underlying implementation is in terms of ICU resource bundles, rather than POSIX message catalogs.

The ICU resource bundles obey standard ICU inheritance policies. To facilitate this, sets and messages are flattened into one tier. This is done by creating resource bundle keys of the form <set_num>%<msg_num> where set_num is the set number and msg_num is the message number, formatted as decimal strings.

Example: Consider a message catalog containing two sets:

Set 1: Message 4 = "Good morning." Message 5 = "Good afternoon." Message 7 = "Good evening." Message 8 = "Good night." Set 4: Message 14 = "Please " Message 19 = "Thank you." Message 20 = "Sincerely,"

The ICU resource bundle source file would, assuming it is named "greet.txt", would look like this:

greet { 14 { "Good morning." } 15 { "Good afternoon." } 17 { "Good evening." } 18 { "Good night." }

414 { "Please " } 419 { "Thank you." } 420 { "Sincerely," } }

The catgets function is commonly used in combination with functions like printf and strftime. ICU components like message format can be used instead, although they use a different format syntax. There is an ICU package, icuio, that provides some of the POSIX-style formatting API.

Definition in file ucat.h.

## Function Documentation

void u_catclose | ( | u_nl_catd | catd | ) |

Close an ICU message catalog, given its descriptor.

Parameters:

  | catd | a message catalog descriptor to be closed. May be NULL, in which case no action is taken.

Stable:
  ICU 2.6

const UChar* u_catgets | ( | u_nl_catd | catd,
|  | int32_t | set_num,
|  | int32_t | msg_num,
|  | const UChar * | s,
|  | int32_t * | len,
|  | UErrorCode * | ec |
| ) |  |  |

Retrieve a localized string from an ICU message catalog.

Parameters:

  | catd | a message catalog descriptor returned by u_catopen.
  | set_num | the message catalog set number. Sets need not be numbered consecutively.
  | msg_num | the message catalog message number within the set. Messages need not be numbered consecutively.
  | s | the default string. This is returned if the string specified by the set_num and msg_num is not found. It must be zero-terminated.
  | len | fill-in parameter to receive the length of the result. May be NULL, in which case it is ignored.
  | ec | input/output error code. May be U_USING_FALLBACK_WARNING or U_USING_DEFAULT_WARNING. U_MISSING_RESOURCE_ERROR indicates that the set_num/msg_num tuple does not specify a valid message string in this catalog.

Returns:
  a pointer to a zero-terminated UChar array which lives in an internal buffer area, typically a memory mapped/DLL file. The caller must NOT delete this pointer. If the call is unsuccessful for any reason, then s is returned. This includes the situation in which ec indicates a failing error code upon entry to this function.

Stable:
  ICU 2.6

u_nl_catd u_catopen | ( | const char * | name,
|  | const char * | locale,
|  | UErrorCode * | ec |
| ) |  |  |

Open and return an ICU message catalog descriptor.

The descriptor may be passed to u_catgets() to retrieve localized strings.

Parameters:

  | name | string containing the full path pointing to the directory where the resources reside followed by the package name e.g. "/usr/resource/my_app/resources/guimessages" on a Unix system. If NULL, ICU default data files will be used.

Unlike POSIX, environment variables are not interpolated within the name.

Parameters:

  | locale | the locale for which we want to open the resource. If NULL, the default ICU locale will be used (see uloc_getDefault). If strlen(locale) == 0, the root locale will be used.
  | ec | input/output error code. Upon output, U_USING_FALLBACK_WARNING indicates that a fallback locale was used. For example, 'de_CH' was requested, but nothing was found there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that the default locale data or root locale data was used; neither the requested locale nor any of its fallback locales were found.

Returns:
  a message catalog descriptor that may be passed to u_catgets(). If the ec parameter indicates success, then the caller is responsible for calling u_catclose() to close the message catalog. If the ec parameter indicates failure, then NULL will be returned.

Stable:
  ICU 2.6

## Variable Documentation

U_CDECL_BEGIN typedef UResourceBundle* u_nl_catd

An ICU message catalog descriptor, analogous to nl_catd.

Stable:
  ICU 2.6

Definition at line 71 of file ucat.h.