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 648