The Tor Browser / file comparison

comparison: intl/icu/source/common/unicode/ucat.h

intl/icu/source/common/unicode/ucat.h

branch
TOR_BUG_3246
changeset 4
fc2d59ddac77
equal deleted inserted replaced
-1:000000000000 0:4fd062c832ea
1 /*
2 **********************************************************************
3 * Copyright (c) 2003-2004, International Business Machines
4 * Corporation and others. All Rights Reserved.
5 **********************************************************************
6 * Author: Alan Liu
7 * Created: March 19 2003
8 * Since: ICU 2.6
9 **********************************************************************
10 */
11 #ifndef UCAT_H
12 #define UCAT_H
13
14 #include "unicode/utypes.h"
15 #include "unicode/ures.h"
16
17 /**
18 * \file
19 * \brief C API: Message Catalog Wrappers
20 *
21 * This C API provides look-alike functions that deliberately resemble
22 * the POSIX catopen, catclose, and catgets functions. The underlying
23 * implementation is in terms of ICU resource bundles, rather than
24 * POSIX message catalogs.
25 *
26 * The ICU resource bundles obey standard ICU inheritance policies.
27 * To facilitate this, sets and messages are flattened into one tier.
28 * This is done by creating resource bundle keys of the form
29 * <set_num>%<msg_num> where set_num is the set number and msg_num is
30 * the message number, formatted as decimal strings.
31 *
32 * Example: Consider a message catalog containing two sets:
33 *
34 * Set 1: Message 4 = "Good morning."
35 * Message 5 = "Good afternoon."
36 * Message 7 = "Good evening."
37 * Message 8 = "Good night."
38 * Set 4: Message 14 = "Please "
39 * Message 19 = "Thank you."
40 * Message 20 = "Sincerely,"
41 *
42 * The ICU resource bundle source file would, assuming it is named
43 * "greet.txt", would look like this:
44 *
45 * greet
46 * {
47 * 1%4 { "Good morning." }
48 * 1%5 { "Good afternoon." }
49 * 1%7 { "Good evening." }
50 * 1%8 { "Good night." }
51 *
52 * 4%14 { "Please " }
53 * 4%19 { "Thank you." }
54 * 4%20 { "Sincerely," }
55 * }
56 *
57 * The catgets function is commonly used in combination with functions
58 * like printf and strftime. ICU components like message format can
59 * be used instead, although they use a different format syntax.
60 * There is an ICU package, icuio, that provides some of
61 * the POSIX-style formatting API.
62 */
63
64 U_CDECL_BEGIN
65
66 /**
67 * An ICU message catalog descriptor, analogous to nl_catd.
68 *
69 * @stable ICU 2.6
70 */
71 typedef UResourceBundle* u_nl_catd;
72
73 /**
74 * Open and return an ICU message catalog descriptor. The descriptor
75 * may be passed to u_catgets() to retrieve localized strings.
76 *
77 * @param name string containing the full path pointing to the
78 * directory where the resources reside followed by the package name
79 * e.g. "/usr/resource/my_app/resources/guimessages" on a Unix system.
80 * If NULL, ICU default data files will be used.
81 *
82 * Unlike POSIX, environment variables are not interpolated within the
83 * name.
84 *
85 * @param locale the locale for which we want to open the resource. If
86 * NULL, the default ICU locale will be used (see uloc_getDefault). If
87 * strlen(locale) == 0, the root locale will be used.
88 *
89 * @param ec input/output error code. Upon output,
90 * U_USING_FALLBACK_WARNING indicates that a fallback locale was
91 * used. For example, 'de_CH' was requested, but nothing was found
92 * there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that the
93 * default locale data or root locale data was used; neither the
94 * requested locale nor any of its fallback locales were found.
95 *
96 * @return a message catalog descriptor that may be passed to
97 * u_catgets(). If the ec parameter indicates success, then the caller
98 * is responsible for calling u_catclose() to close the message
99 * catalog. If the ec parameter indicates failure, then NULL will be
100 * returned.
101 *
102 * @stable ICU 2.6
103 */
104 U_STABLE u_nl_catd U_EXPORT2
105 u_catopen(const char* name, const char* locale, UErrorCode* ec);
106
107 /**
108 * Close an ICU message catalog, given its descriptor.
109 *
110 * @param catd a message catalog descriptor to be closed. May be NULL,
111 * in which case no action is taken.
112 *
113 * @stable ICU 2.6
114 */
115 U_STABLE void U_EXPORT2
116 u_catclose(u_nl_catd catd);
117
118 /**
119 * Retrieve a localized string from an ICU message catalog.
120 *
121 * @param catd a message catalog descriptor returned by u_catopen.
122 *
123 * @param set_num the message catalog set number. Sets need not be
124 * numbered consecutively.
125 *
126 * @param msg_num the message catalog message number within the
127 * set. Messages need not be numbered consecutively.
128 *
129 * @param s the default string. This is returned if the string
130 * specified by the set_num and msg_num is not found. It must be
131 * zero-terminated.
132 *
133 * @param len fill-in parameter to receive the length of the result.
134 * May be NULL, in which case it is ignored.
135 *
136 * @param ec input/output error code. May be U_USING_FALLBACK_WARNING
137 * or U_USING_DEFAULT_WARNING. U_MISSING_RESOURCE_ERROR indicates that
138 * the set_num/msg_num tuple does not specify a valid message string
139 * in this catalog.
140 *
141 * @return a pointer to a zero-terminated UChar array which lives in
142 * an internal buffer area, typically a memory mapped/DLL file. The
143 * caller must NOT delete this pointer. If the call is unsuccessful
144 * for any reason, then s is returned. This includes the situation in
145 * which ec indicates a failing error code upon entry to this
146 * function.
147 *
148 * @stable ICU 2.6
149 */
150 U_STABLE const UChar* U_EXPORT2
151 u_catgets(u_nl_catd catd, int32_t set_num, int32_t msg_num,
152 const UChar* s,
153 int32_t* len, UErrorCode* ec);
154
155 U_CDECL_END
156
157 #endif /*UCAT_H*/
158 /*eof*/

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial