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