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