icuSources/i18n/unicode/umsg.h

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