1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/unicode/ucat.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,158 @@
1.4 +/*
1.5 +**********************************************************************
1.6 +* Copyright (c) 2003-2004, International Business Machines
1.7 +* Corporation and others. All Rights Reserved.
1.8 +**********************************************************************
1.9 +* Author: Alan Liu
1.10 +* Created: March 19 2003
1.11 +* Since: ICU 2.6
1.12 +**********************************************************************
1.13 +*/
1.14 +#ifndef UCAT_H
1.15 +#define UCAT_H
1.16 +
1.17 +#include "unicode/utypes.h"
1.18 +#include "unicode/ures.h"
1.19 +
1.20 +/**
1.21 + * \file
1.22 + * \brief C API: Message Catalog Wrappers
1.23 + *
1.24 + * This C API provides look-alike functions that deliberately resemble
1.25 + * the POSIX catopen, catclose, and catgets functions. The underlying
1.26 + * implementation is in terms of ICU resource bundles, rather than
1.27 + * POSIX message catalogs.
1.28 + *
1.29 + * The ICU resource bundles obey standard ICU inheritance policies.
1.30 + * To facilitate this, sets and messages are flattened into one tier.
1.31 + * This is done by creating resource bundle keys of the form
1.32 + * <set_num>%<msg_num> where set_num is the set number and msg_num is
1.33 + * the message number, formatted as decimal strings.
1.34 + *
1.35 + * Example: Consider a message catalog containing two sets:
1.36 + *
1.37 + * Set 1: Message 4 = "Good morning."
1.38 + * Message 5 = "Good afternoon."
1.39 + * Message 7 = "Good evening."
1.40 + * Message 8 = "Good night."
1.41 + * Set 4: Message 14 = "Please "
1.42 + * Message 19 = "Thank you."
1.43 + * Message 20 = "Sincerely,"
1.44 + *
1.45 + * The ICU resource bundle source file would, assuming it is named
1.46 + * "greet.txt", would look like this:
1.47 + *
1.48 + * greet
1.49 + * {
1.50 + * 1%4 { "Good morning." }
1.51 + * 1%5 { "Good afternoon." }
1.52 + * 1%7 { "Good evening." }
1.53 + * 1%8 { "Good night." }
1.54 + *
1.55 + * 4%14 { "Please " }
1.56 + * 4%19 { "Thank you." }
1.57 + * 4%20 { "Sincerely," }
1.58 + * }
1.59 + *
1.60 + * The catgets function is commonly used in combination with functions
1.61 + * like printf and strftime. ICU components like message format can
1.62 + * be used instead, although they use a different format syntax.
1.63 + * There is an ICU package, icuio, that provides some of
1.64 + * the POSIX-style formatting API.
1.65 + */
1.66 +
1.67 +U_CDECL_BEGIN
1.68 +
1.69 +/**
1.70 + * An ICU message catalog descriptor, analogous to nl_catd.
1.71 + *
1.72 + * @stable ICU 2.6
1.73 + */
1.74 +typedef UResourceBundle* u_nl_catd;
1.75 +
1.76 +/**
1.77 + * Open and return an ICU message catalog descriptor. The descriptor
1.78 + * may be passed to u_catgets() to retrieve localized strings.
1.79 + *
1.80 + * @param name string containing the full path pointing to the
1.81 + * directory where the resources reside followed by the package name
1.82 + * e.g. "/usr/resource/my_app/resources/guimessages" on a Unix system.
1.83 + * If NULL, ICU default data files will be used.
1.84 + *
1.85 + * Unlike POSIX, environment variables are not interpolated within the
1.86 + * name.
1.87 + *
1.88 + * @param locale the locale for which we want to open the resource. If
1.89 + * NULL, the default ICU locale will be used (see uloc_getDefault). If
1.90 + * strlen(locale) == 0, the root locale will be used.
1.91 + *
1.92 + * @param ec input/output error code. Upon output,
1.93 + * U_USING_FALLBACK_WARNING indicates that a fallback locale was
1.94 + * used. For example, 'de_CH' was requested, but nothing was found
1.95 + * there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that the
1.96 + * default locale data or root locale data was used; neither the
1.97 + * requested locale nor any of its fallback locales were found.
1.98 + *
1.99 + * @return a message catalog descriptor that may be passed to
1.100 + * u_catgets(). If the ec parameter indicates success, then the caller
1.101 + * is responsible for calling u_catclose() to close the message
1.102 + * catalog. If the ec parameter indicates failure, then NULL will be
1.103 + * returned.
1.104 + *
1.105 + * @stable ICU 2.6
1.106 + */
1.107 +U_STABLE u_nl_catd U_EXPORT2
1.108 +u_catopen(const char* name, const char* locale, UErrorCode* ec);
1.109 +
1.110 +/**
1.111 + * Close an ICU message catalog, given its descriptor.
1.112 + *
1.113 + * @param catd a message catalog descriptor to be closed. May be NULL,
1.114 + * in which case no action is taken.
1.115 + *
1.116 + * @stable ICU 2.6
1.117 + */
1.118 +U_STABLE void U_EXPORT2
1.119 +u_catclose(u_nl_catd catd);
1.120 +
1.121 +/**
1.122 + * Retrieve a localized string from an ICU message catalog.
1.123 + *
1.124 + * @param catd a message catalog descriptor returned by u_catopen.
1.125 + *
1.126 + * @param set_num the message catalog set number. Sets need not be
1.127 + * numbered consecutively.
1.128 + *
1.129 + * @param msg_num the message catalog message number within the
1.130 + * set. Messages need not be numbered consecutively.
1.131 + *
1.132 + * @param s the default string. This is returned if the string
1.133 + * specified by the set_num and msg_num is not found. It must be
1.134 + * zero-terminated.
1.135 + *
1.136 + * @param len fill-in parameter to receive the length of the result.
1.137 + * May be NULL, in which case it is ignored.
1.138 + *
1.139 + * @param ec input/output error code. May be U_USING_FALLBACK_WARNING
1.140 + * or U_USING_DEFAULT_WARNING. U_MISSING_RESOURCE_ERROR indicates that
1.141 + * the set_num/msg_num tuple does not specify a valid message string
1.142 + * in this catalog.
1.143 + *
1.144 + * @return a pointer to a zero-terminated UChar array which lives in
1.145 + * an internal buffer area, typically a memory mapped/DLL file. The
1.146 + * caller must NOT delete this pointer. If the call is unsuccessful
1.147 + * for any reason, then s is returned. This includes the situation in
1.148 + * which ec indicates a failing error code upon entry to this
1.149 + * function.
1.150 + *
1.151 + * @stable ICU 2.6
1.152 + */
1.153 +U_STABLE const UChar* U_EXPORT2
1.154 +u_catgets(u_nl_catd catd, int32_t set_num, int32_t msg_num,
1.155 + const UChar* s,
1.156 + int32_t* len, UErrorCode* ec);
1.157 +
1.158 +U_CDECL_END
1.159 +
1.160 +#endif /*UCAT_H*/
1.161 +/*eof*/
