icuSources/i18n/unicode/umsg.h

   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  */
 176 U_STABLE int32_t U_EXPORT2
 177 u_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  */
 203 U_STABLE int32_t U_EXPORT2
 204 u_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  */
 228 U_STABLE void U_EXPORT2
 229 u_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  */
 253 U_STABLE void U_EXPORT2
 254 u_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  */
 282 U_STABLE int32_t U_EXPORT2
 283 u_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  */
 311 U_STABLE int32_t U_EXPORT2
 312 u_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  */
 339 U_STABLE void U_EXPORT2
 340 u_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  */
 367 U_STABLE void U_EXPORT2
 368 u_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  */
 382 typedef 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  */
 397 U_STABLE UMessageFormat* U_EXPORT2
 398 umsg_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  */
 410 U_STABLE void U_EXPORT2
 411 umsg_close(UMessageFormat* format);
 412
 413 #if U_SHOW_CPLUSPLUS_API
 414
 415 U_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  */
 426 U_DEFINE_LOCAL_OPEN_POINTER(LocalUMessageFormatPointer, UMessageFormat, umsg_close);
 427
 428 U_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  */
 440 U_STABLE UMessageFormat U_EXPORT2
 441 umsg_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  */
 451 U_STABLE void  U_EXPORT2
 452 umsg_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  */
 462 U_STABLE const char*  U_EXPORT2
 463 umsg_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  */
 477 U_STABLE void  U_EXPORT2
 478 umsg_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  */
 495 U_STABLE int32_t  U_EXPORT2
 496 umsg_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  */
 516 U_STABLE int32_t U_EXPORT2
 517 umsg_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  */
 538 U_STABLE int32_t U_EXPORT2
 539 umsg_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  */
 559 U_STABLE void U_EXPORT2
 560 umsg_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  */
 582 U_STABLE void U_EXPORT2
 583 umsg_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  */
 614 U_STABLE int32_t U_EXPORT2
 615 umsg_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