1// © 2016 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
3/********************************************************************
4 * COPYRIGHT:
5 * Copyright (c) 1997-2011, International Business Machines Corporation and
6 * others. All Rights Reserved.
7 * Copyright (C) 2010 , Yahoo! Inc.
8 ********************************************************************
9 *
10 * file name: umsg.h
11 * encoding: UTF-8
12 * tab size: 8 (not used)
13 * indentation:4
14 *
15 * Change history:
16 *
17 * 08/5/2001 Ram Added C wrappers for C++ API.
18 ********************************************************************/
19
20#ifndef UMSG_H
21#define UMSG_H
22
23#include "unicode/utypes.h"
24
25#if !UCONFIG_NO_FORMATTING
26
27#include "unicode/localpointer.h"
28#include "unicode/uloc.h"
29#include "unicode/parseerr.h"
30#include <stdarg.h>
31
32/**
33 * \file
34 * \brief C API: MessageFormat
35 *
36 * <h2>MessageFormat C API </h2>
37 *
38 * <p>MessageFormat prepares strings for display to users,
39 * with optional arguments (variables/placeholders).
40 * The arguments can occur in any order, which is necessary for translation
41 * into languages with different grammars.
42 *
43 * <p>The opaque UMessageFormat type is a thin C wrapper around
44 * a C++ MessageFormat. It is constructed from a <em>pattern</em> string
45 * with arguments in {curly braces} which will be replaced by formatted values.
46 *
47 * <p>Currently, the C API supports only numbered arguments.
48 *
49 * <p>For details about the pattern syntax and behavior,
50 * especially about the ASCII apostrophe vs. the
51 * real apostrophe (single quote) character \htmlonly&#x2019;\endhtmlonly (U+2019),
52 * see the C++ MessageFormat class documentation.
53 *
54 * <p>Here are some examples of C API usage:
55 * Example 1:
56 * <pre>
57 * \code
58 * UChar *result, *tzID, *str;
59 * UChar pattern[100];
60 * int32_t resultLengthOut, resultlength;
61 * UCalendar *cal;
62 * UDate d1;
63 * UDateFormat *def1;
64 * UErrorCode status = U_ZERO_ERROR;
65 *
66 * str=(UChar*)malloc(sizeof(UChar) * (strlen("disturbance in force") +1));
67 * u_uastrcpy(str, "disturbance in force");
68 * tzID=(UChar*)malloc(sizeof(UChar) * 4);
69 * u_uastrcpy(tzID, "PST");
70 * cal=ucal_open(tzID, u_strlen(tzID), "en_US", UCAL_TRADITIONAL, &status);
71 * ucal_setDateTime(cal, 1999, UCAL_MARCH, 18, 0, 0, 0, &status);
72 * d1=ucal_getMillis(cal, &status);
73 * u_uastrcpy(pattern, "On {0, date, long}, there was a {1} on planet {2,number,integer}");
74 * resultlength=0;
75 * resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern), NULL, resultlength, &status, d1, str, 7);
76 * if(status==U_BUFFER_OVERFLOW_ERROR){
77 * status=U_ZERO_ERROR;
78 * resultlength=resultLengthOut+1;
79 * result=(UChar*)realloc(result, sizeof(UChar) * resultlength);
80 * u_formatMessage( "en_US", pattern, u_strlen(pattern), result, resultlength, &status, d1, str, 7);
81 * }
82 * printf("%s\n", austrdup(result) );//austrdup( a function used to convert UChar* to char*)
83 * //output>: "On March 18, 1999, there was a disturbance in force on planet 7
84 * \endcode
85 * </pre>
86 * Typically, the message format will come from resources, and the
87 * arguments will be dynamically set at runtime.
88 * <P>
89 * Example 2:
90 * <pre>
91 * \code
92 * UChar* str;
93 * UErrorCode status = U_ZERO_ERROR;
94 * UChar *result;
95 * UChar pattern[100];
96 * int32_t resultlength, resultLengthOut, i;
97 * double testArgs= { 100.0, 1.0, 0.0};
98 *
99 * str=(UChar*)malloc(sizeof(UChar) * 10);
100 * u_uastrcpy(str, "MyDisk");
101 * u_uastrcpy(pattern, "The disk {1} contains {0,choice,0#no files|1#one file|1<{0,number,integer} files}");
102 * for(i=0; i<3; i++){
103 * resultlength=0;
104 * resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern), NULL, resultlength, &status, testArgs[i], str);
105 * if(status==U_BUFFER_OVERFLOW_ERROR){
106 * status=U_ZERO_ERROR;
107 * resultlength=resultLengthOut+1;
108 * result=(UChar*)malloc(sizeof(UChar) * resultlength);
109 * u_formatMessage( "en_US", pattern, u_strlen(pattern), result, resultlength, &status, testArgs[i], str);
110 * }
111 * printf("%s\n", austrdup(result) ); //austrdup( a function used to convert UChar* to char*)
112 * free(result);
113 * }
114 * // output, with different testArgs:
115 * // output: The disk "MyDisk" contains 100 files.
116 * // output: The disk "MyDisk" contains one file.
117 * // output: The disk "MyDisk" contains no files.
118 * \endcode
119 * </pre>
120 *
121 *
122 * Example 3:
123 * <pre>
124 * \code
125 * UChar* str;
126 * UChar* str1;
127 * UErrorCode status = U_ZERO_ERROR;
128 * UChar *result;
129 * UChar pattern[100];
130 * UChar expected[100];
131 * int32_t resultlength,resultLengthOut;
132
133 * str=(UChar*)malloc(sizeof(UChar) * 25);
134 * u_uastrcpy(str, "Kirti");
135 * str1=(UChar*)malloc(sizeof(UChar) * 25);
136 * u_uastrcpy(str1, "female");
137 * log_verbose("Testing message format with Select test #1\n:");
138 * u_uastrcpy(pattern, "{0} est {1, select, female {all\\u00E9e} other {all\\u00E9}} \\u00E0 Paris.");
139 * u_uastrcpy(expected, "Kirti est all\\u00E9e \\u00E0 Paris.");
140 * resultlength=0;
141 * resultLengthOut=u_formatMessage( "fr", pattern, u_strlen(pattern), NULL, resultlength, &status, str , str1);
142 * if(status==U_BUFFER_OVERFLOW_ERROR)
143 * {
144 * status=U_ZERO_ERROR;
145 * resultlength=resultLengthOut+1;
146 * result=(UChar*)malloc(sizeof(UChar) * resultlength);
147 * u_formatMessage( "fr", pattern, u_strlen(pattern), result, resultlength, &status, str , str1);
148 * if(u_strcmp(result, expected)==0)
149 * log_verbose("PASS: MessagFormat successful on Select test#1\n");
150 * else{
151 * log_err("FAIL: Error in MessageFormat on Select test#1\n GOT %s EXPECTED %s\n", austrdup(result),
152 * austrdup(expected) );
153 * }
154 * free(result);
155 * }
156 * \endcode
157 * </pre>
158 */
159
160/**
161 * Format a message for a locale.
162 * This function may perform re-ordering of the arguments depending on the
163 * locale. For all numeric arguments, double is assumed unless the type is
164 * explicitly integer. All choice format arguments must be of type double.
165 * @param locale The locale for which the message will be formatted
166 * @param pattern The pattern specifying the message's format
167 * @param patternLength The length of pattern
168 * @param result A pointer to a buffer to receive the formatted message.
169 * @param resultLength The maximum size of result.
170 * @param status A pointer to an UErrorCode to receive any errors
171 * @param ... A variable-length argument list containing the arguments specified
172 * in pattern.
173 * @return The total buffer size needed; if greater than resultLength, the
174 * output was truncated.
175 * @see u_parseMessage
176 * @stable ICU 2.0
177 */
178U_STABLE int32_t U_EXPORT2
179u_formatMessage(const char *locale,
180 const UChar *pattern,
181 int32_t patternLength,
182 UChar *result,
183 int32_t resultLength,
184 UErrorCode *status,
185 ...);
186
187/**
188 * Format a message for a locale.
189 * This function may perform re-ordering of the arguments depending on the
190 * locale. For all numeric arguments, double is assumed unless the type is
191 * explicitly integer. All choice format arguments must be of type double.
192 * @param locale The locale for which the message will be formatted
193 * @param pattern The pattern specifying the message's format
194 * @param patternLength The length of pattern
195 * @param result A pointer to a buffer to receive the formatted message.
196 * @param resultLength The maximum size of result.
197 * @param ap A variable-length argument list containing the arguments specified
198 * @param status A pointer to an UErrorCode to receive any errors
199 * in pattern.
200 * @return The total buffer size needed; if greater than resultLength, the
201 * output was truncated.
202 * @see u_parseMessage
203 * @stable ICU 2.0
204 */
205U_STABLE int32_t U_EXPORT2
206u_vformatMessage( const char *locale,
207 const UChar *pattern,
208 int32_t patternLength,
209 UChar *result,
210 int32_t resultLength,
211 va_list ap,
212 UErrorCode *status);
213
214/**
215 * Parse a message.
216 * For numeric arguments, this function will always use doubles. Integer types
217 * should not be passed.
218 * This function is not able to parse all output from {@link #u_formatMessage }.
219 * @param locale The locale for which the message is formatted
220 * @param pattern The pattern specifying the message's format
221 * @param patternLength The length of pattern
222 * @param source The text to parse.
223 * @param sourceLength The length of source, or -1 if null-terminated.
224 * @param status A pointer to an UErrorCode to receive any errors
225 * @param ... A variable-length argument list containing the arguments
226 * specified in pattern.
227 * @see u_formatMessage
228 * @stable ICU 2.0
229 */
230U_STABLE void U_EXPORT2
231u_parseMessage( const char *locale,
232 const UChar *pattern,
233 int32_t patternLength,
234 const UChar *source,
235 int32_t sourceLength,
236 UErrorCode *status,
237 ...);
238
239/**
240 * Parse a message.
241 * For numeric arguments, this function will always use doubles. Integer types
242 * should not be passed.
243 * This function is not able to parse all output from {@link #u_formatMessage }.
244 * @param locale The locale for which the message is formatted
245 * @param pattern The pattern specifying the message's format
246 * @param patternLength The length of pattern
247 * @param source The text to parse.
248 * @param sourceLength The length of source, or -1 if null-terminated.
249 * @param ap A variable-length argument list containing the arguments
250 * @param status A pointer to an UErrorCode to receive any errors
251 * specified in pattern.
252 * @see u_formatMessage
253 * @stable ICU 2.0
254 */
255U_STABLE void U_EXPORT2
256u_vparseMessage(const char *locale,
257 const UChar *pattern,
258 int32_t patternLength,
259 const UChar *source,
260 int32_t sourceLength,
261 va_list ap,
262 UErrorCode *status);
263
264/**
265 * Format a message for a locale.
266 * This function may perform re-ordering of the arguments depending on the
267 * locale. For all numeric arguments, double is assumed unless the type is
268 * explicitly integer. All choice format arguments must be of type double.
269 * @param locale The locale for which the message will be formatted
270 * @param pattern The pattern specifying the message's format
271 * @param patternLength The length of pattern
272 * @param result A pointer to a buffer to receive the formatted message.
273 * @param resultLength The maximum size of result.
274 * @param status A pointer to an UErrorCode to receive any errors
275 * @param ... A variable-length argument list containing the arguments specified
276 * in pattern.
277 * @param parseError A pointer to UParseError to receive information about errors
278 * occurred during parsing.
279 * @return The total buffer size needed; if greater than resultLength, the
280 * output was truncated.
281 * @see u_parseMessage
282 * @stable ICU 2.0
283 */
284U_STABLE int32_t U_EXPORT2
285u_formatMessageWithError( const char *locale,
286 const UChar *pattern,
287 int32_t patternLength,
288 UChar *result,
289 int32_t resultLength,
290 UParseError *parseError,
291 UErrorCode *status,
292 ...);
293
294/**
295 * Format a message for a locale.
296 * This function may perform re-ordering of the arguments depending on the
297 * locale. For all numeric arguments, double is assumed unless the type is
298 * explicitly integer. All choice format arguments must be of type double.
299 * @param locale The locale for which the message will be formatted
300 * @param pattern The pattern specifying the message's format
301 * @param patternLength The length of pattern
302 * @param result A pointer to a buffer to receive the formatted message.
303 * @param resultLength The maximum size of result.
304 * @param parseError A pointer to UParseError to receive information about errors
305 * occurred during parsing.
306 * @param ap A variable-length argument list containing the arguments specified
307 * @param status A pointer to an UErrorCode to receive any errors
308 * in pattern.
309 * @return The total buffer size needed; if greater than resultLength, the
310 * output was truncated.
311 * @stable ICU 2.0
312 */
313U_STABLE int32_t U_EXPORT2
314u_vformatMessageWithError( const char *locale,
315 const UChar *pattern,
316 int32_t patternLength,
317 UChar *result,
318 int32_t resultLength,
319 UParseError* parseError,
320 va_list ap,
321 UErrorCode *status);
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 parseError A pointer to UParseError to receive information about errors
334 * occurred during parsing.
335 * @param status A pointer to an UErrorCode to receive any errors
336 * @param ... A variable-length argument list containing the arguments
337 * specified in pattern.
338 * @see u_formatMessage
339 * @stable ICU 2.0
340 */
341U_STABLE void U_EXPORT2
342u_parseMessageWithError(const char *locale,
343 const UChar *pattern,
344 int32_t patternLength,
345 const UChar *source,
346 int32_t sourceLength,
347 UParseError *parseError,
348 UErrorCode *status,
349 ...);
350
351/**
352 * Parse a message.
353 * For numeric arguments, this function will always use doubles. Integer types
354 * should not be passed.
355 * This function is not able to parse all output from {@link #u_formatMessage }.
356 * @param locale The locale for which the message is formatted
357 * @param pattern The pattern specifying the message's format
358 * @param patternLength The length of pattern
359 * @param source The text to parse.
360 * @param sourceLength The length of source, or -1 if null-terminated.
361 * @param ap A variable-length argument list containing the arguments
362 * @param parseError A pointer to UParseError to receive information about errors
363 * occurred during parsing.
364 * @param status A pointer to an UErrorCode to receive any errors
365 * specified in pattern.
366 * @see u_formatMessage
367 * @stable ICU 2.0
368 */
369U_STABLE void U_EXPORT2
370u_vparseMessageWithError(const char *locale,
371 const UChar *pattern,
372 int32_t patternLength,
373 const UChar *source,
374 int32_t sourceLength,
375 va_list ap,
376 UParseError *parseError,
377 UErrorCode* status);
378
379/*----------------------- New experimental API --------------------------- */
380/**
381 * The message format object
382 * @stable ICU 2.0
383 */
384typedef void* UMessageFormat;
385
386
387/**
388 * Open a message formatter with given pattern and for the given locale.
389 * @param pattern A pattern specifying the format to use.
390 * @param patternLength Length of the pattern to use
391 * @param locale The locale for which the messages are formatted.
392 * @param parseError A pointer to UParseError struct to receive any errors
393 * occured during parsing. Can be NULL.
394 * @param status A pointer to an UErrorCode to receive any errors.
395 * @return A pointer to a UMessageFormat to use for formatting
396 * messages, or 0 if an error occurred.
397 * @stable ICU 2.0
398 */
399U_STABLE UMessageFormat* U_EXPORT2
400umsg_open( const UChar *pattern,
401 int32_t patternLength,
402 const char *locale,
403 UParseError *parseError,
404 UErrorCode *status);
405
406/**
407 * Close a UMessageFormat.
408 * Once closed, a UMessageFormat may no longer be used.
409 * @param format The formatter to close.
410 * @stable ICU 2.0
411 */
412U_STABLE void U_EXPORT2
413umsg_close(UMessageFormat* format);
414
415#if U_SHOW_CPLUSPLUS_API
416
417U_NAMESPACE_BEGIN
418
419/**
420 * \class LocalUMessageFormatPointer
421 * "Smart pointer" class, closes a UMessageFormat via umsg_close().
422 * For most methods see the LocalPointerBase base class.
423 *
424 * @see LocalPointerBase
425 * @see LocalPointer
426 * @stable ICU 4.4
427 */
428U_DEFINE_LOCAL_OPEN_POINTER(LocalUMessageFormatPointer, UMessageFormat, umsg_close);
429
430U_NAMESPACE_END
431
432#endif
433
434/**
435 * Open a copy of a UMessageFormat.
436 * This function performs a deep copy.
437 * @param fmt The formatter to copy
438 * @param status A pointer to an UErrorCode to receive any errors.
439 * @return A pointer to a UDateFormat identical to fmt.
440 * @stable ICU 2.0
441 */
442U_STABLE UMessageFormat U_EXPORT2
443umsg_clone(const UMessageFormat *fmt,
444 UErrorCode *status);
445
446/**
447 * Sets the locale. This locale is used for fetching default number or date
448 * format information.
449 * @param fmt The formatter to set
450 * @param locale The locale the formatter should use.
451 * @stable ICU 2.0
452 */
453U_STABLE void U_EXPORT2
454umsg_setLocale(UMessageFormat *fmt,
455 const char* locale);
456
457/**
458 * Gets the locale. This locale is used for fetching default number or date
459 * format information.
460 * @param fmt The formatter to querry
461 * @return the locale.
462 * @stable ICU 2.0
463 */
464U_STABLE const char* U_EXPORT2
465umsg_getLocale(const UMessageFormat *fmt);
466
467/**
468 * Sets the pattern.
469 * @param fmt The formatter to use
470 * @param pattern The pattern to be applied.
471 * @param patternLength Length of the pattern to use
472 * @param parseError Struct to receive information on position
473 * of error if an error is encountered.Can be NULL.
474 * @param status Output param set to success/failure code on
475 * exit. If the pattern is invalid, this will be
476 * set to a failure result.
477 * @stable ICU 2.0
478 */
479U_STABLE void U_EXPORT2
480umsg_applyPattern( UMessageFormat *fmt,
481 const UChar* pattern,
482 int32_t patternLength,
483 UParseError* parseError,
484 UErrorCode* status);
485
486/**
487 * Gets the pattern.
488 * @param fmt The formatter to use
489 * @param result A pointer to a buffer to receive the pattern.
490 * @param resultLength The maximum size of result.
491 * @param status Output param set to success/failure code on
492 * exit. If the pattern is invalid, this will be
493 * set to a failure result.
494 * @return the pattern of the format
495 * @stable ICU 2.0
496 */
497U_STABLE int32_t U_EXPORT2
498umsg_toPattern(const UMessageFormat *fmt,
499 UChar* result,
500 int32_t resultLength,
501 UErrorCode* status);
502
503/**
504 * Format a message for a locale.
505 * This function may perform re-ordering of the arguments depending on the
506 * locale. For all numeric arguments, double is assumed unless the type is
507 * explicitly integer. All choice format arguments must be of type double.
508 * @param fmt The formatter to use
509 * @param result A pointer to a buffer to receive the formatted message.
510 * @param resultLength The maximum size of result.
511 * @param status A pointer to an UErrorCode to receive any errors
512 * @param ... A variable-length argument list containing the arguments
513 * specified in pattern.
514 * @return The total buffer size needed; if greater than resultLength,
515 * the output was truncated.
516 * @stable ICU 2.0
517 */
518U_STABLE int32_t U_EXPORT2
519umsg_format( const UMessageFormat *fmt,
520 UChar *result,
521 int32_t resultLength,
522 UErrorCode *status,
523 ...);
524
525/**
526 * Format a message for a locale.
527 * This function may perform re-ordering of the arguments depending on the
528 * locale. For all numeric arguments, double is assumed unless the type is
529 * explicitly integer. All choice format arguments must be of type double.
530 * @param fmt The formatter to use
531 * @param result A pointer to a buffer to receive the formatted message.
532 * @param resultLength The maximum size of result.
533 * @param ap A variable-length argument list containing the arguments
534 * @param status A pointer to an UErrorCode to receive any errors
535 * specified in pattern.
536 * @return The total buffer size needed; if greater than resultLength,
537 * the output was truncated.
538 * @stable ICU 2.0
539 */
540U_STABLE int32_t U_EXPORT2
541umsg_vformat( const UMessageFormat *fmt,
542 UChar *result,
543 int32_t resultLength,
544 va_list ap,
545 UErrorCode *status);
546
547/**
548 * Parse a message.
549 * For numeric arguments, this function will always use doubles. Integer types
550 * should not be passed.
551 * This function is not able to parse all output from {@link #umsg_format }.
552 * @param fmt The formatter to use
553 * @param source The text to parse.
554 * @param sourceLength The length of source, or -1 if null-terminated.
555 * @param count Output param to receive number of elements returned.
556 * @param status A pointer to an UErrorCode to receive any errors
557 * @param ... A variable-length argument list containing the arguments
558 * specified in pattern.
559 * @stable ICU 2.0
560 */
561U_STABLE void U_EXPORT2
562umsg_parse( const UMessageFormat *fmt,
563 const UChar *source,
564 int32_t sourceLength,
565 int32_t *count,
566 UErrorCode *status,
567 ...);
568
569/**
570 * Parse a message.
571 * For numeric arguments, this function will always use doubles. Integer types
572 * should not be passed.
573 * This function is not able to parse all output from {@link #umsg_format }.
574 * @param fmt The formatter to use
575 * @param source The text to parse.
576 * @param sourceLength The length of source, or -1 if null-terminated.
577 * @param count Output param to receive number of elements returned.
578 * @param ap A variable-length argument list containing the arguments
579 * @param status A pointer to an UErrorCode to receive any errors
580 * specified in pattern.
581 * @see u_formatMessage
582 * @stable ICU 2.0
583 */
584U_STABLE void U_EXPORT2
585umsg_vparse(const UMessageFormat *fmt,
586 const UChar *source,
587 int32_t sourceLength,
588 int32_t *count,
589 va_list ap,
590 UErrorCode *status);
591
592
593/**
594 * Convert an 'apostrophe-friendly' pattern into a standard
595 * pattern. Standard patterns treat all apostrophes as
596 * quotes, which is problematic in some languages, e.g.
597 * French, where apostrophe is commonly used. This utility
598 * assumes that only an unpaired apostrophe immediately before
599 * a brace is a true quote. Other unpaired apostrophes are paired,
600 * and the resulting standard pattern string is returned.
601 *
602 * <p><b>Note</b> it is not guaranteed that the returned pattern
603 * is indeed a valid pattern. The only effect is to convert
604 * between patterns having different quoting semantics.
605 *
606 * @param pattern the 'apostrophe-friendly' patttern to convert
607 * @param patternLength the length of pattern, or -1 if unknown and pattern is null-terminated
608 * @param dest the buffer for the result, or NULL if preflight only
609 * @param destCapacity the length of the buffer, or 0 if preflighting
610 * @param ec the error code
611 * @return the length of the resulting text, not including trailing null
612 * if buffer has room for the trailing null, it is provided, otherwise
613 * not
614 * @stable ICU 3.4
615 */
616U_STABLE int32_t U_EXPORT2
617umsg_autoQuoteApostrophe(const UChar* pattern,
618 int32_t patternLength,
619 UChar* dest,
620 int32_t destCapacity,
621 UErrorCode* ec);
622
623#endif /* #if !UCONFIG_NO_FORMATTING */
624
625#endif
626