OLD | NEW |
| (Empty) |
1 /******************************************************************** | |
2 * COPYRIGHT: | |
3 * Copyright (c) 1997-2010, International Business Machines Corporation and | |
4 * others. All Rights Reserved. | |
5 * Copyright (C) 2010 , Yahoo! Inc. | |
6 ******************************************************************** | |
7 * | |
8 * file name: umsg.h | |
9 * encoding: US-ASCII | |
10 * tab size: 8 (not used) | |
11 * indentation:4 | |
12 * | |
13 * Change history: | |
14 * | |
15 * 08/5/2001 Ram Added C wrappers for C++ API. | |
16 * | |
17 ********************************************************************/ | |
18 | |
19 #ifndef UMSG_H | |
20 #define UMSG_H | |
21 | |
22 #include "unicode/utypes.h" | |
23 | |
24 #if !UCONFIG_NO_FORMATTING | |
25 | |
26 #include "unicode/localpointer.h" | |
27 #include "unicode/uloc.h" | |
28 #include "unicode/parseerr.h" | |
29 #include <stdarg.h> | |
30 /** | |
31 * \file | |
32 * \brief C API: MessageFormat | |
33 * | |
34 * <h2>Message Format C API </h2> | |
35 * | |
36 * Provides means to produce concatenated messages in language-neutral way. | |
37 * Use this for all concatenations that show up to end users. | |
38 * <P> | |
39 * Takes a set of objects, formats them, then inserts the formatted | |
40 * strings into the pattern at the appropriate places. | |
41 * <P> | |
42 * Here are some examples of usage: | |
43 * Example 1: | |
44 * <pre> | |
45 * \code | |
46 * UChar *result, *tzID, *str; | |
47 * UChar pattern[100]; | |
48 * int32_t resultLengthOut, resultlength; | |
49 * UCalendar *cal; | |
50 * UDate d1; | |
51 * UDateFormat *def1; | |
52 * UErrorCode status = U_ZERO_ERROR; | |
53 * | |
54 * str=(UChar*)malloc(sizeof(UChar) * (strlen("disturbance in force") +1)); | |
55 * u_uastrcpy(str, "disturbance in force"); | |
56 * tzID=(UChar*)malloc(sizeof(UChar) * 4); | |
57 * u_uastrcpy(tzID, "PST"); | |
58 * cal=ucal_open(tzID, u_strlen(tzID), "en_US", UCAL_TRADITIONAL, &status); | |
59 * ucal_setDateTime(cal, 1999, UCAL_MARCH, 18, 0, 0, 0, &status); | |
60 * d1=ucal_getMillis(cal, &status); | |
61 * u_uastrcpy(pattern, "On {0, date, long}, there was a {1} on planet {2,num
ber,integer}"); | |
62 * resultlength=0; | |
63 * resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern), NUL
L, resultlength, &status, d1, str, 7); | |
64 * if(status==U_BUFFER_OVERFLOW_ERROR){ | |
65 * status=U_ZERO_ERROR; | |
66 * resultlength=resultLengthOut+1; | |
67 * result=(UChar*)realloc(result, sizeof(UChar) * resultlength); | |
68 * u_formatMessage( "en_US", pattern, u_strlen(pattern), result, resultl
ength, &status, d1, str, 7); | |
69 * } | |
70 * printf("%s\n", austrdup(result) );//austrdup( a function used to convert
UChar* to char*) | |
71 * //output>: "On March 18, 1999, there was a disturbance in force on planet
7 | |
72 * \endcode | |
73 * </pre> | |
74 * Typically, the message format will come from resources, and the | |
75 * arguments will be dynamically set at runtime. | |
76 * <P> | |
77 * Example 2: | |
78 * <pre> | |
79 * \code | |
80 * UChar* str; | |
81 * UErrorCode status = U_ZERO_ERROR; | |
82 * UChar *result; | |
83 * UChar pattern[100]; | |
84 * int32_t resultlength, resultLengthOut, i; | |
85 * double testArgs= { 100.0, 1.0, 0.0}; | |
86 * | |
87 * str=(UChar*)malloc(sizeof(UChar) * 10); | |
88 * u_uastrcpy(str, "MyDisk"); | |
89 * u_uastrcpy(pattern, "The disk {1} contains {0,choice,0#no files|1#one fil
e|1<{0,number,integer} files}"); | |
90 * for(i=0; i<3; i++){ | |
91 * resultlength=0; | |
92 * resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern), N
ULL, resultlength, &status, testArgs[i], str); | |
93 * if(status==U_BUFFER_OVERFLOW_ERROR){ | |
94 * status=U_ZERO_ERROR; | |
95 * resultlength=resultLengthOut+1; | |
96 * result=(UChar*)malloc(sizeof(UChar) * resultlength); | |
97 * u_formatMessage( "en_US", pattern, u_strlen(pattern), result, resultl
ength, &status, testArgs[i], str); | |
98 * } | |
99 * printf("%s\n", austrdup(result) ); //austrdup( a function used to conv
ert UChar* to char*) | |
100 * free(result); | |
101 * } | |
102 * // output, with different testArgs: | |
103 * // output: The disk "MyDisk" contains 100 files. | |
104 * // output: The disk "MyDisk" contains one file. | |
105 * // output: The disk "MyDisk" contains no files. | |
106 * \endcode | |
107 * </pre> | |
108 * | |
109 * | |
110 * Example 3: | |
111 * <pre> | |
112 * \code | |
113 * UChar* str; | |
114 * UChar* str1; | |
115 * UErrorCode status = U_ZERO_ERROR; | |
116 * UChar *result; | |
117 * UChar pattern[100]; | |
118 * UChar expected[100]; | |
119 * int32_t resultlength,resultLengthOut; | |
120 | |
121 * str=(UChar*)malloc(sizeof(UChar) * 25); | |
122 * u_uastrcpy(str, "Kirti"); | |
123 * str1=(UChar*)malloc(sizeof(UChar) * 25); | |
124 * u_uastrcpy(str1, "female"); | |
125 * log_verbose("Testing message format with Select test #1\n:"); | |
126 * u_uastrcpy(pattern, "{0} est {1, select, female {all\\u00E9e} other {all\\u00
E9}} \\u00E0 Paris."); | |
127 * u_uastrcpy(expected, "Kirti est all\\u00E9e \\u00E0 Paris."); | |
128 * resultlength=0; | |
129 * resultLengthOut=u_formatMessage( "fr", pattern, u_strlen(pattern), NULL, resu
ltlength, &status, str , str1); | |
130 * if(status==U_BUFFER_OVERFLOW_ERROR) | |
131 * { | |
132 * status=U_ZERO_ERROR; | |
133 * resultlength=resultLengthOut+1; | |
134 * result=(UChar*)malloc(sizeof(UChar) * resultlength); | |
135 * u_formatMessage( "fr", pattern, u_strlen(pattern), result, resultlength,
&status, str , str1); | |
136 * if(u_strcmp(result, expected)==0) | |
137 * log_verbose("PASS: MessagFormat successful on Select test#1\n"); | |
138 * else{ | |
139 * log_err("FAIL: Error in MessageFormat on Select test#1\n GOT %s EXPE
CTED %s\n", austrdup(result), | |
140 * austrdup(expected) ); | |
141 * } | |
142 * free(result); | |
143 * } | |
144 * \endcode | |
145 * </pre> | |
146 * | |
147 | |
148 * The pattern is of the following form. Legend: | |
149 * <pre> | |
150 * \code | |
151 * {optional item} | |
152 * (group that may be repeated)* | |
153 * \endcode | |
154 * </pre> | |
155 * Do not confuse optional items with items inside quotes braces, such | |
156 * as this: "{". Quoted braces are literals. | |
157 * <pre> | |
158 * \code | |
159 * messageFormatPattern := string ( "{" messageFormatElement "}" string )* | |
160 * | |
161 * messageFormatElement := argument { "," elementFormat } | |
162 * | |
163 * elementFormat := "time" { "," datetimeStyle } | |
164 * | "date" { "," datetimeStyle } | |
165 * | "number" { "," numberStyle } | |
166 * | "choice" "," choiceStyle | |
167 * | "select" "," selectStyle | |
168 * | |
169 * datetimeStyle := "short" | |
170 * | "medium" | |
171 * | "long" | |
172 * | "full" | |
173 * | dateFormatPattern | |
174 * | |
175 * numberStyle := "currency" | |
176 * | "percent" | |
177 * | "integer" | |
178 * | numberFormatPattern | |
179 * | |
180 * choiceStyle := choiceFormatPattern | |
181 * | |
182 * selectStyle := selectFormatPattern | |
183 * \endcode | |
184 * </pre> | |
185 * If there is no elementFormat, then the argument must be a string, | |
186 * which is substituted. If there is no dateTimeStyle or numberStyle, | |
187 * then the default format is used (e.g. NumberFormat.getInstance(), | |
188 * DateFormat.getDefaultTime() or DateFormat.getDefaultDate(). For | |
189 * a ChoiceFormat, the pattern must always be specified, since there | |
190 * is no default. | |
191 * <P> | |
192 * In strings, single quotes can be used to quote the "{" sign if | |
193 * necessary. A real single quote is represented by ''. Inside a | |
194 * messageFormatElement, quotes are [not] removed. For example, | |
195 * {1,number,$'#',##} will produce a number format with the pound-sign | |
196 * quoted, with a result such as: "$#31,45". | |
197 * <P> | |
198 * If a pattern is used, then unquoted braces in the pattern, if any, | |
199 * must match: that is, "ab {0} de" and "ab '}' de" are ok, but "ab | |
200 * {0'}' de" and "ab } de" are not. | |
201 * <p> | |
202 * <dl><dt><b>Warning:</b><dd>The rules for using quotes within message | |
203 * format patterns unfortunately have shown to be somewhat confusing. | |
204 * In particular, it isn't always obvious to localizers whether single | |
205 * quotes need to be doubled or not. Make sure to inform localizers about | |
206 * the rules, and tell them (for example, by using comments in resource | |
207 * bundle source files) which strings will be processed by MessageFormat. | |
208 * Note that localizers may need to use single quotes in translated | |
209 * strings where the original version doesn't have them. | |
210 * <br>Note also that the simplest way to avoid the problem is to | |
211 * use the real apostrophe (single quote) character U+2019 (') for | |
212 * human-readable text, and to use the ASCII apostrophe (U+0027 ' ) | |
213 * only in program syntax, like quoting in MessageFormat. | |
214 * See the annotations for U+0027 Apostrophe in The Unicode Standard.</p> | |
215 * </dl> | |
216 * <P> | |
217 * The argument is a number from 0 to 9, which corresponds to the | |
218 * arguments presented in an array to be formatted. | |
219 * <P> | |
220 * It is ok to have unused arguments in the array. With missing | |
221 * arguments or arguments that are not of the right class for the | |
222 * specified format, a failing UErrorCode result is set. | |
223 * <P> | |
224 | |
225 * <P> | |
226 * [Note:] As we see above, the string produced by a choice Format in | |
227 * MessageFormat is treated specially; occurances of '{' are used to | |
228 * indicated subformats. | |
229 * <P> | |
230 * [Note:] Formats are numbered by order of variable in the string. | |
231 * This is [not] the same as the argument numbering! | |
232 * <pre> | |
233 * \code | |
234 * For example: with "abc{2}def{3}ghi{0}...", | |
235 * | |
236 * format0 affects the first variable {2} | |
237 * format1 affects the second variable {3} | |
238 * format2 affects the second variable {0} | |
239 * \endcode | |
240 * </pre> | |
241 * and so on. | |
242 */ | |
243 | |
244 /** | |
245 * Format a message for a locale. | |
246 * This function may perform re-ordering of the arguments depending on the | |
247 * locale. For all numeric arguments, double is assumed unless the type is | |
248 * explicitly integer. All choice format arguments must be of type double. | |
249 * @param locale The locale for which the message will be formatted | |
250 * @param pattern The pattern specifying the message's format | |
251 * @param patternLength The length of pattern | |
252 * @param result A pointer to a buffer to receive the formatted message. | |
253 * @param resultLength The maximum size of result. | |
254 * @param status A pointer to an UErrorCode to receive any errors | |
255 * @param ... A variable-length argument list containing the arguments specified | |
256 * in pattern. | |
257 * @return The total buffer size needed; if greater than resultLength, the | |
258 * output was truncated. | |
259 * @see u_parseMessage | |
260 * @stable ICU 2.0 | |
261 */ | |
262 U_STABLE int32_t U_EXPORT2 | |
263 u_formatMessage(const char *locale, | |
264 const UChar *pattern, | |
265 int32_t patternLength, | |
266 UChar *result, | |
267 int32_t resultLength, | |
268 UErrorCode *status, | |
269 ...); | |
270 | |
271 /** | |
272 * Format a message for a locale. | |
273 * This function may perform re-ordering of the arguments depending on the | |
274 * locale. For all numeric arguments, double is assumed unless the type is | |
275 * explicitly integer. All choice format arguments must be of type double. | |
276 * @param locale The locale for which the message will be formatted | |
277 * @param pattern The pattern specifying the message's format | |
278 * @param patternLength The length of pattern | |
279 * @param result A pointer to a buffer to receive the formatted message. | |
280 * @param resultLength The maximum size of result. | |
281 * @param ap A variable-length argument list containing the arguments specified | |
282 * @param status A pointer to an UErrorCode to receive any errors | |
283 * in pattern. | |
284 * @return The total buffer size needed; if greater than resultLength, the | |
285 * output was truncated. | |
286 * @see u_parseMessage | |
287 * @stable ICU 2.0 | |
288 */ | |
289 U_STABLE int32_t U_EXPORT2 | |
290 u_vformatMessage( const char *locale, | |
291 const UChar *pattern, | |
292 int32_t patternLength, | |
293 UChar *result, | |
294 int32_t resultLength, | |
295 va_list ap, | |
296 UErrorCode *status); | |
297 | |
298 /** | |
299 * Parse a message. | |
300 * For numeric arguments, this function will always use doubles. Integer types | |
301 * should not be passed. | |
302 * This function is not able to parse all output from {@link #u_formatMessage }. | |
303 * @param locale The locale for which the message is formatted | |
304 * @param pattern The pattern specifying the message's format | |
305 * @param patternLength The length of pattern | |
306 * @param source The text to parse. | |
307 * @param sourceLength The length of source, or -1 if null-terminated. | |
308 * @param status A pointer to an UErrorCode to receive any errors | |
309 * @param ... A variable-length argument list containing the arguments | |
310 * specified in pattern. | |
311 * @see u_formatMessage | |
312 * @stable ICU 2.0 | |
313 */ | |
314 U_STABLE void U_EXPORT2 | |
315 u_parseMessage( const char *locale, | |
316 const UChar *pattern, | |
317 int32_t patternLength, | |
318 const UChar *source, | |
319 int32_t sourceLength, | |
320 UErrorCode *status, | |
321 ...); | |
322 | |
323 /** | |
324 * Parse a message. | |
325 * For numeric arguments, this function will always use doubles. Integer types | |
326 * should not be passed. | |
327 * This function is not able to parse all output from {@link #u_formatMessage }. | |
328 * @param locale The locale for which the message is formatted | |
329 * @param pattern The pattern specifying the message's format | |
330 * @param patternLength The length of pattern | |
331 * @param source The text to parse. | |
332 * @param sourceLength The length of source, or -1 if null-terminated. | |
333 * @param ap A variable-length argument list containing the arguments | |
334 * @param status A pointer to an UErrorCode to receive any errors | |
335 * specified in pattern. | |
336 * @see u_formatMessage | |
337 * @stable ICU 2.0 | |
338 */ | |
339 U_STABLE void U_EXPORT2 | |
340 u_vparseMessage(const char *locale, | |
341 const UChar *pattern, | |
342 int32_t patternLength, | |
343 const UChar *source, | |
344 int32_t sourceLength, | |
345 va_list ap, | |
346 UErrorCode *status); | |
347 | |
348 /** | |
349 * Format a message for a locale. | |
350 * This function may perform re-ordering of the arguments depending on the | |
351 * locale. For all numeric arguments, double is assumed unless the type is | |
352 * explicitly integer. All choice format arguments must be of type double. | |
353 * @param locale The locale for which the message will be formatted | |
354 * @param pattern The pattern specifying the message's format | |
355 * @param patternLength The length of pattern | |
356 * @param result A pointer to a buffer to receive the formatted message. | |
357 * @param resultLength The maximum size of result. | |
358 * @param status A pointer to an UErrorCode to receive any errors | |
359 * @param ... A variable-length argument list containing the arguments specified | |
360 * in pattern. | |
361 * @param parseError A pointer to UParseError to receive information about erro
rs | |
362 * occurred during parsing. | |
363 * @return The total buffer size needed; if greater than resultLength, the | |
364 * output was truncated. | |
365 * @see u_parseMessage | |
366 * @stable ICU 2.0 | |
367 */ | |
368 U_STABLE int32_t U_EXPORT2 | |
369 u_formatMessageWithError( const char *locale, | |
370 const UChar *pattern, | |
371 int32_t patternLength, | |
372 UChar *result, | |
373 int32_t resultLength, | |
374 UParseError *parseError, | |
375 UErrorCode *status, | |
376 ...); | |
377 | |
378 /** | |
379 * Format a message for a locale. | |
380 * This function may perform re-ordering of the arguments depending on the | |
381 * locale. For all numeric arguments, double is assumed unless the type is | |
382 * explicitly integer. All choice format arguments must be of type double. | |
383 * @param locale The locale for which the message will be formatted | |
384 * @param pattern The pattern specifying the message's format | |
385 * @param patternLength The length of pattern | |
386 * @param result A pointer to a buffer to receive the formatted message. | |
387 * @param resultLength The maximum size of result. | |
388 * @param parseError A pointer to UParseError to receive information about erro
rs | |
389 * occurred during parsing. | |
390 * @param ap A variable-length argument list containing the arguments specified | |
391 * @param status A pointer to an UErrorCode to receive any errors | |
392 * in pattern. | |
393 * @return The total buffer size needed; if greater than resultLength, the | |
394 * output was truncated. | |
395 * @stable ICU 2.0 | |
396 */ | |
397 U_STABLE int32_t U_EXPORT2 | |
398 u_vformatMessageWithError( const char *locale, | |
399 const UChar *pattern, | |
400 int32_t patternLength, | |
401 UChar *result, | |
402 int32_t resultLength, | |
403 UParseError* parseError, | |
404 va_list ap, | |
405 UErrorCode *status); | |
406 | |
407 /** | |
408 * Parse a message. | |
409 * For numeric arguments, this function will always use doubles. Integer types | |
410 * should not be passed. | |
411 * This function is not able to parse all output from {@link #u_formatMessage }. | |
412 * @param locale The locale for which the message is formatted | |
413 * @param pattern The pattern specifying the message's format | |
414 * @param patternLength The length of pattern | |
415 * @param source The text to parse. | |
416 * @param sourceLength The length of source, or -1 if null-terminated. | |
417 * @param parseError A pointer to UParseError to receive information about erro
rs | |
418 * occurred during parsing. | |
419 * @param status A pointer to an UErrorCode to receive any errors | |
420 * @param ... A variable-length argument list containing the arguments | |
421 * specified in pattern. | |
422 * @see u_formatMessage | |
423 * @stable ICU 2.0 | |
424 */ | |
425 U_STABLE void U_EXPORT2 | |
426 u_parseMessageWithError(const char *locale, | |
427 const UChar *pattern, | |
428 int32_t patternLength, | |
429 const UChar *source, | |
430 int32_t sourceLength, | |
431 UParseError *parseError, | |
432 UErrorCode *status, | |
433 ...); | |
434 | |
435 /** | |
436 * Parse a message. | |
437 * For numeric arguments, this function will always use doubles. Integer types | |
438 * should not be passed. | |
439 * This function is not able to parse all output from {@link #u_formatMessage }. | |
440 * @param locale The locale for which the message is formatted | |
441 * @param pattern The pattern specifying the message's format | |
442 * @param patternLength The length of pattern | |
443 * @param source The text to parse. | |
444 * @param sourceLength The length of source, or -1 if null-terminated. | |
445 * @param ap A variable-length argument list containing the arguments | |
446 * @param parseError A pointer to UParseError to receive information about erro
rs | |
447 * occurred during parsing. | |
448 * @param status A pointer to an UErrorCode to receive any errors | |
449 * specified in pattern. | |
450 * @see u_formatMessage | |
451 * @stable ICU 2.0 | |
452 */ | |
453 U_STABLE void U_EXPORT2 | |
454 u_vparseMessageWithError(const char *locale, | |
455 const UChar *pattern, | |
456 int32_t patternLength, | |
457 const UChar *source, | |
458 int32_t sourceLength, | |
459 va_list ap, | |
460 UParseError *parseError, | |
461 UErrorCode* status); | |
462 | |
463 /*----------------------- New experimental API --------------------------- */ | |
464 /** | |
465 * The message format object | |
466 * @stable ICU 2.0 | |
467 */ | |
468 typedef void* UMessageFormat; | |
469 | |
470 | |
471 /** | |
472 * Open a message formatter with given pattern and for the given locale. | |
473 * @param pattern A pattern specifying the format to use. | |
474 * @param patternLength Length of the pattern to use | |
475 * @param locale The locale for which the messages are formatted. | |
476 * @param parseError A pointer to UParseError struct to receive any errors | |
477 * occured during parsing. Can be NULL. | |
478 * @param status A pointer to an UErrorCode to receive any errors. | |
479 * @return A pointer to a UMessageFormat to use for formatting | |
480 * messages, or 0 if an error occurred. | |
481 * @stable ICU 2.0 | |
482 */ | |
483 U_STABLE UMessageFormat* U_EXPORT2 | |
484 umsg_open( const UChar *pattern, | |
485 int32_t patternLength, | |
486 const char *locale, | |
487 UParseError *parseError, | |
488 UErrorCode *status); | |
489 | |
490 /** | |
491 * Close a UMessageFormat. | |
492 * Once closed, a UMessageFormat may no longer be used. | |
493 * @param format The formatter to close. | |
494 * @stable ICU 2.0 | |
495 */ | |
496 U_STABLE void U_EXPORT2 | |
497 umsg_close(UMessageFormat* format); | |
498 | |
499 #if U_SHOW_CPLUSPLUS_API | |
500 | |
501 U_NAMESPACE_BEGIN | |
502 | |
503 /** | |
504 * \class LocalUMessageFormatPointer | |
505 * "Smart pointer" class, closes a UMessageFormat via umsg_close(). | |
506 * For most methods see the LocalPointerBase base class. | |
507 * | |
508 * @see LocalPointerBase | |
509 * @see LocalPointer | |
510 * @stable ICU 4.4 | |
511 */ | |
512 U_DEFINE_LOCAL_OPEN_POINTER(LocalUMessageFormatPointer, UMessageFormat, umsg_clo
se); | |
513 | |
514 U_NAMESPACE_END | |
515 | |
516 #endif | |
517 | |
518 /** | |
519 * Open a copy of a UMessageFormat. | |
520 * This function performs a deep copy. | |
521 * @param fmt The formatter to copy | |
522 * @param status A pointer to an UErrorCode to receive any errors. | |
523 * @return A pointer to a UDateFormat identical to fmt. | |
524 * @stable ICU 2.0 | |
525 */ | |
526 U_STABLE UMessageFormat U_EXPORT2 | |
527 umsg_clone(const UMessageFormat *fmt, | |
528 UErrorCode *status); | |
529 | |
530 /** | |
531 * Sets the locale. This locale is used for fetching default number or date | |
532 * format information. | |
533 * @param fmt The formatter to set | |
534 * @param locale The locale the formatter should use. | |
535 * @stable ICU 2.0 | |
536 */ | |
537 U_STABLE void U_EXPORT2 | |
538 umsg_setLocale(UMessageFormat *fmt, | |
539 const char* locale); | |
540 | |
541 /** | |
542 * Gets the locale. This locale is used for fetching default number or date | |
543 * format information. | |
544 * @param fmt The formatter to querry | |
545 * @return the locale. | |
546 * @stable ICU 2.0 | |
547 */ | |
548 U_STABLE const char* U_EXPORT2 | |
549 umsg_getLocale(const UMessageFormat *fmt); | |
550 | |
551 /** | |
552 * Sets the pattern. | |
553 * @param fmt The formatter to use | |
554 * @param pattern The pattern to be applied. | |
555 * @param patternLength Length of the pattern to use | |
556 * @param parseError Struct to receive information on position | |
557 * of error if an error is encountered.Can be NULL. | |
558 * @param status Output param set to success/failure code on | |
559 * exit. If the pattern is invalid, this will be | |
560 * set to a failure result. | |
561 * @stable ICU 2.0 | |
562 */ | |
563 U_STABLE void U_EXPORT2 | |
564 umsg_applyPattern( UMessageFormat *fmt, | |
565 const UChar* pattern, | |
566 int32_t patternLength, | |
567 UParseError* parseError, | |
568 UErrorCode* status); | |
569 | |
570 /** | |
571 * Gets the pattern. | |
572 * @param fmt The formatter to use | |
573 * @param result A pointer to a buffer to receive the pattern. | |
574 * @param resultLength The maximum size of result. | |
575 * @param status Output param set to success/failure code on | |
576 * exit. If the pattern is invalid, this will be | |
577 * set to a failure result. | |
578 * @return the pattern of the format | |
579 * @stable ICU 2.0 | |
580 */ | |
581 U_STABLE int32_t U_EXPORT2 | |
582 umsg_toPattern(const UMessageFormat *fmt, | |
583 UChar* result, | |
584 int32_t resultLength, | |
585 UErrorCode* status); | |
586 | |
587 /** | |
588 * Format a message for a locale. | |
589 * This function may perform re-ordering of the arguments depending on the | |
590 * locale. For all numeric arguments, double is assumed unless the type is | |
591 * explicitly integer. All choice format arguments must be of type double. | |
592 * @param fmt The formatter to use | |
593 * @param result A pointer to a buffer to receive the formatted message. | |
594 * @param resultLength The maximum size of result. | |
595 * @param status A pointer to an UErrorCode to receive any errors | |
596 * @param ... A variable-length argument list containing the arguments
| |
597 * specified in pattern. | |
598 * @return The total buffer size needed; if greater than resultLeng
th, | |
599 * the output was truncated. | |
600 * @stable ICU 2.0 | |
601 */ | |
602 U_STABLE int32_t U_EXPORT2 | |
603 umsg_format( const UMessageFormat *fmt, | |
604 UChar *result, | |
605 int32_t resultLength, | |
606 UErrorCode *status, | |
607 ...); | |
608 | |
609 /** | |
610 * Format a message for a locale. | |
611 * This function may perform re-ordering of the arguments depending on the | |
612 * locale. For all numeric arguments, double is assumed unless the type is | |
613 * explicitly integer. All choice format arguments must be of type double. | |
614 * @param fmt The formatter to use | |
615 * @param result A pointer to a buffer to receive the formatted message. | |
616 * @param resultLength The maximum size of result. | |
617 * @param ap A variable-length argument list containing the arguments | |
618 * @param status A pointer to an UErrorCode to receive any errors | |
619 * specified in pattern. | |
620 * @return The total buffer size needed; if greater than resultLengt
h, | |
621 * the output was truncated. | |
622 * @stable ICU 2.0 | |
623 */ | |
624 U_STABLE int32_t U_EXPORT2 | |
625 umsg_vformat( const UMessageFormat *fmt, | |
626 UChar *result, | |
627 int32_t resultLength, | |
628 va_list ap, | |
629 UErrorCode *status); | |
630 | |
631 /** | |
632 * Parse a message. | |
633 * For numeric arguments, this function will always use doubles. Integer types | |
634 * should not be passed. | |
635 * This function is not able to parse all output from {@link #umsg_format }. | |
636 * @param fmt The formatter to use | |
637 * @param source The text to parse. | |
638 * @param sourceLength The length of source, or -1 if null-terminated. | |
639 * @param count Output param to receive number of elements returned. | |
640 * @param status A pointer to an UErrorCode to receive any errors | |
641 * @param ... A variable-length argument list containing the arguments | |
642 * specified in pattern. | |
643 * @stable ICU 2.0 | |
644 */ | |
645 U_STABLE void U_EXPORT2 | |
646 umsg_parse( const UMessageFormat *fmt, | |
647 const UChar *source, | |
648 int32_t sourceLength, | |
649 int32_t *count, | |
650 UErrorCode *status, | |
651 ...); | |
652 | |
653 /** | |
654 * Parse a message. | |
655 * For numeric arguments, this function will always use doubles. Integer types | |
656 * should not be passed. | |
657 * This function is not able to parse all output from {@link #umsg_format }. | |
658 * @param fmt The formatter to use | |
659 * @param source The text to parse. | |
660 * @param sourceLength The length of source, or -1 if null-terminated. | |
661 * @param count Output param to receive number of elements returned. | |
662 * @param ap A variable-length argument list containing the arguments | |
663 * @param status A pointer to an UErrorCode to receive any errors | |
664 * specified in pattern. | |
665 * @see u_formatMessage | |
666 * @stable ICU 2.0 | |
667 */ | |
668 U_STABLE void U_EXPORT2 | |
669 umsg_vparse(const UMessageFormat *fmt, | |
670 const UChar *source, | |
671 int32_t sourceLength, | |
672 int32_t *count, | |
673 va_list ap, | |
674 UErrorCode *status); | |
675 | |
676 | |
677 /** | |
678 * Convert an 'apostrophe-friendly' pattern into a standard | |
679 * pattern. Standard patterns treat all apostrophes as | |
680 * quotes, which is problematic in some languages, e.g. | |
681 * French, where apostrophe is commonly used. This utility | |
682 * assumes that only an unpaired apostrophe immediately before | |
683 * a brace is a true quote. Other unpaired apostrophes are paired, | |
684 * and the resulting standard pattern string is returned. | |
685 * | |
686 * <p><b>Note</b> it is not guaranteed that the returned pattern | |
687 * is indeed a valid pattern. The only effect is to convert | |
688 * between patterns having different quoting semantics. | |
689 * | |
690 * @param pattern the 'apostrophe-friendly' patttern to convert | |
691 * @param patternLength the length of pattern, or -1 if unknown and pattern is n
ull-terminated | |
692 * @param dest the buffer for the result, or NULL if preflight only | |
693 * @param destCapacity the length of the buffer, or 0 if preflighting | |
694 * @param ec the error code | |
695 * @return the length of the resulting text, not including trailing null | |
696 * if buffer has room for the trailing null, it is provided, otherwise | |
697 * not | |
698 * @stable ICU 3.4 | |
699 */ | |
700 U_STABLE int32_t U_EXPORT2 | |
701 umsg_autoQuoteApostrophe(const UChar* pattern, | |
702 int32_t patternLength, | |
703 UChar* dest, | |
704 int32_t destCapacity, | |
705 UErrorCode* ec); | |
706 | |
707 #endif /* #if !UCONFIG_NO_FORMATTING */ | |
708 | |
709 #endif | |
OLD | NEW |