1 // Copyright (C) 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: US-ASCII 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’\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 */ 178 U_STABLE int32_t U_EXPORT2 179 u_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 */ 205 U_STABLE int32_t U_EXPORT2 206 u_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 */ 230 U_STABLE void U_EXPORT2 231 u_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 */ 255 U_STABLE void U_EXPORT2 256 u_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 */ 284 U_STABLE int32_t U_EXPORT2 285 u_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 */ 313 U_STABLE int32_t U_EXPORT2 314 u_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 */ 341 U_STABLE void U_EXPORT2 342 u_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 */ 369 U_STABLE void U_EXPORT2 370 u_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 */ 384 typedef 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 */ 399 U_STABLE UMessageFormat* U_EXPORT2 400 umsg_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 */ 412 U_STABLE void U_EXPORT2 413 umsg_close(UMessageFormat* format); 414 415 #if U_SHOW_CPLUSPLUS_API 416 417 U_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 */ 428 U_DEFINE_LOCAL_OPEN_POINTER(LocalUMessageFormatPointer, UMessageFormat, umsg_close); 429 430 U_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 */ 442 U_STABLE UMessageFormat U_EXPORT2 443 umsg_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 */ 453 U_STABLE void U_EXPORT2 454 umsg_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 */ 464 U_STABLE const char* U_EXPORT2 465 umsg_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 */ 479 U_STABLE void U_EXPORT2 480 umsg_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 */ 497 U_STABLE int32_t U_EXPORT2 498 umsg_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 */ 518 U_STABLE int32_t U_EXPORT2 519 umsg_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 */ 540 U_STABLE int32_t U_EXPORT2 541 umsg_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 */ 561 U_STABLE void U_EXPORT2 562 umsg_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 */ 584 U_STABLE void U_EXPORT2 585 umsg_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 */ 616 U_STABLE int32_t U_EXPORT2 617 umsg_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
