jpayne@69: // © 2016 and later: Unicode, Inc. and others. jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html jpayne@69: /******************************************************************** jpayne@69: * COPYRIGHT: jpayne@69: * Copyright (c) 1997-2011, International Business Machines Corporation and jpayne@69: * others. All Rights Reserved. jpayne@69: * Copyright (C) 2010 , Yahoo! Inc. jpayne@69: ******************************************************************** jpayne@69: * jpayne@69: * file name: umsg.h jpayne@69: * encoding: UTF-8 jpayne@69: * tab size: 8 (not used) jpayne@69: * indentation:4 jpayne@69: * jpayne@69: * Change history: jpayne@69: * jpayne@69: * 08/5/2001 Ram Added C wrappers for C++ API. jpayne@69: ********************************************************************/ jpayne@69: jpayne@69: #ifndef UMSG_H jpayne@69: #define UMSG_H jpayne@69: jpayne@69: #include "unicode/utypes.h" jpayne@69: jpayne@69: #if !UCONFIG_NO_FORMATTING jpayne@69: jpayne@69: #include "unicode/localpointer.h" jpayne@69: #include "unicode/uloc.h" jpayne@69: #include "unicode/parseerr.h" jpayne@69: #include jpayne@69: jpayne@69: /** jpayne@69: * \file jpayne@69: * \brief C API: MessageFormat jpayne@69: * jpayne@69: *

MessageFormat C API

jpayne@69: * jpayne@69: *

MessageFormat prepares strings for display to users, jpayne@69: * with optional arguments (variables/placeholders). jpayne@69: * The arguments can occur in any order, which is necessary for translation jpayne@69: * into languages with different grammars. jpayne@69: * jpayne@69: *

The opaque UMessageFormat type is a thin C wrapper around jpayne@69: * a C++ MessageFormat. It is constructed from a pattern string jpayne@69: * with arguments in {curly braces} which will be replaced by formatted values. jpayne@69: * jpayne@69: *

Currently, the C API supports only numbered arguments. jpayne@69: * jpayne@69: *

For details about the pattern syntax and behavior, jpayne@69: * especially about the ASCII apostrophe vs. the jpayne@69: * real apostrophe (single quote) character \htmlonly’\endhtmlonly (U+2019), jpayne@69: * see the C++ MessageFormat class documentation. jpayne@69: * jpayne@69: *

Here are some examples of C API usage: jpayne@69: * Example 1: jpayne@69: * 

jpayne@69:  * \code
jpayne@69:  *     UChar *result, *tzID, *str;
jpayne@69:  *     UChar pattern[100];
jpayne@69:  *     int32_t resultLengthOut, resultlength;
jpayne@69:  *     UCalendar *cal;
jpayne@69:  *     UDate d1;
jpayne@69:  *     UDateFormat *def1;
jpayne@69:  *     UErrorCode status = U_ZERO_ERROR;
jpayne@69:  *
jpayne@69:  *     str=(UChar*)malloc(sizeof(UChar) * (strlen("disturbance in force") +1));
jpayne@69:  *     u_uastrcpy(str, "disturbance in force");
jpayne@69:  *     tzID=(UChar*)malloc(sizeof(UChar) * 4);
jpayne@69:  *     u_uastrcpy(tzID, "PST");
jpayne@69:  *     cal=ucal_open(tzID, u_strlen(tzID), "en_US", UCAL_TRADITIONAL, &status);
jpayne@69:  *     ucal_setDateTime(cal, 1999, UCAL_MARCH, 18, 0, 0, 0, &status);
jpayne@69:  *     d1=ucal_getMillis(cal, &status);
jpayne@69:  *     u_uastrcpy(pattern, "On {0, date, long}, there was a {1} on planet {2,number,integer}");
jpayne@69:  *     resultlength=0;
jpayne@69:  *     resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern), NULL, resultlength, &status, d1, str, 7);
jpayne@69:  *     if(status==U_BUFFER_OVERFLOW_ERROR){
jpayne@69:  *         status=U_ZERO_ERROR;
jpayne@69:  *         resultlength=resultLengthOut+1;
jpayne@69:  *         result=(UChar*)realloc(result, sizeof(UChar) * resultlength);
jpayne@69:  *         u_formatMessage( "en_US", pattern, u_strlen(pattern), result, resultlength, &status, d1, str, 7);
jpayne@69:  *     }
jpayne@69:  *     printf("%s\n", austrdup(result) );//austrdup( a function used to convert UChar* to char*)
jpayne@69:  *     //output>: "On March 18, 1999, there was a disturbance in force on planet 7
jpayne@69:  * \endcode
jpayne@69:  *
jpayne@69: * Typically, the message format will come from resources, and the jpayne@69: * arguments will be dynamically set at runtime. jpayne@69: *

jpayne@69: * Example 2: jpayne@69: * 

jpayne@69:  * \code
jpayne@69:  *     UChar* str;
jpayne@69:  *     UErrorCode status = U_ZERO_ERROR;
jpayne@69:  *     UChar *result;
jpayne@69:  *     UChar pattern[100];
jpayne@69:  *     int32_t resultlength, resultLengthOut, i;
jpayne@69:  *     double testArgs= { 100.0, 1.0, 0.0};
jpayne@69:  *
jpayne@69:  *     str=(UChar*)malloc(sizeof(UChar) * 10);
jpayne@69:  *     u_uastrcpy(str, "MyDisk");
jpayne@69:  *     u_uastrcpy(pattern, "The disk {1} contains {0,choice,0#no files|1#one file|1<{0,number,integer} files}");
jpayne@69:  *     for(i=0; i<3; i++){
jpayne@69:  *       resultlength=0; 
jpayne@69:  *       resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern), NULL, resultlength, &status, testArgs[i], str); 
jpayne@69:  *       if(status==U_BUFFER_OVERFLOW_ERROR){
jpayne@69:  *         status=U_ZERO_ERROR;
jpayne@69:  *         resultlength=resultLengthOut+1;
jpayne@69:  *         result=(UChar*)malloc(sizeof(UChar) * resultlength);
jpayne@69:  *         u_formatMessage( "en_US", pattern, u_strlen(pattern), result, resultlength, &status, testArgs[i], str);
jpayne@69:  *       }
jpayne@69:  *       printf("%s\n", austrdup(result) );  //austrdup( a function used to convert UChar* to char*)
jpayne@69:  *       free(result);
jpayne@69:  *     }
jpayne@69:  *     // output, with different testArgs:
jpayne@69:  *     // output: The disk "MyDisk" contains 100 files.
jpayne@69:  *     // output: The disk "MyDisk" contains one file.
jpayne@69:  *     // output: The disk "MyDisk" contains no files.
jpayne@69:  * \endcode
jpayne@69:  *
jpayne@69: * jpayne@69: * jpayne@69: * Example 3: jpayne@69: * 
jpayne@69:  * \code
jpayne@69:  * UChar* str;
jpayne@69:  * UChar* str1;
jpayne@69:  * UErrorCode status = U_ZERO_ERROR;
jpayne@69:  * UChar *result;
jpayne@69:  * UChar pattern[100];
jpayne@69:  * UChar expected[100];
jpayne@69:  * int32_t resultlength,resultLengthOut;
jpayne@69: 
jpayne@69:  * str=(UChar*)malloc(sizeof(UChar) * 25);
jpayne@69:  * u_uastrcpy(str, "Kirti");
jpayne@69:  * str1=(UChar*)malloc(sizeof(UChar) * 25);
jpayne@69:  * u_uastrcpy(str1, "female");
jpayne@69:  * log_verbose("Testing message format with Select test #1\n:");
jpayne@69:  * u_uastrcpy(pattern, "{0} est {1, select, female {all\\u00E9e} other {all\\u00E9}} \\u00E0 Paris.");
jpayne@69:  * u_uastrcpy(expected, "Kirti est all\\u00E9e \\u00E0 Paris.");
jpayne@69:  * resultlength=0;
jpayne@69:  * resultLengthOut=u_formatMessage( "fr", pattern, u_strlen(pattern), NULL, resultlength, &status, str , str1);
jpayne@69:  * if(status==U_BUFFER_OVERFLOW_ERROR)
jpayne@69:  *  {
jpayne@69:  *      status=U_ZERO_ERROR;
jpayne@69:  *      resultlength=resultLengthOut+1;
jpayne@69:  *      result=(UChar*)malloc(sizeof(UChar) * resultlength);
jpayne@69:  *      u_formatMessage( "fr", pattern, u_strlen(pattern), result, resultlength, &status, str , str1);
jpayne@69:  *      if(u_strcmp(result, expected)==0)
jpayne@69:  *          log_verbose("PASS: MessagFormat successful on Select test#1\n");
jpayne@69:  *      else{
jpayne@69:  *          log_err("FAIL: Error in MessageFormat on Select test#1\n GOT %s EXPECTED %s\n", austrdup(result),
jpayne@69:  *          austrdup(expected) );
jpayne@69:  *      }
jpayne@69:  *      free(result);
jpayne@69:  * }
jpayne@69:  * \endcode
jpayne@69:  *
jpayne@69: */ jpayne@69: jpayne@69: /** jpayne@69: * Format a message for a locale. jpayne@69: * This function may perform re-ordering of the arguments depending on the jpayne@69: * locale. For all numeric arguments, double is assumed unless the type is jpayne@69: * explicitly integer. All choice format arguments must be of type double. jpayne@69: * @param locale The locale for which the message will be formatted jpayne@69: * @param pattern The pattern specifying the message's format jpayne@69: * @param patternLength The length of pattern jpayne@69: * @param result A pointer to a buffer to receive the formatted message. jpayne@69: * @param resultLength The maximum size of result. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @param ... A variable-length argument list containing the arguments specified jpayne@69: * in pattern. jpayne@69: * @return The total buffer size needed; if greater than resultLength, the jpayne@69: * output was truncated. jpayne@69: * @see u_parseMessage jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_formatMessage(const char *locale, jpayne@69: const UChar *pattern, jpayne@69: int32_t patternLength, jpayne@69: UChar *result, jpayne@69: int32_t resultLength, jpayne@69: UErrorCode *status, jpayne@69: ...); jpayne@69: jpayne@69: /** jpayne@69: * Format a message for a locale. jpayne@69: * This function may perform re-ordering of the arguments depending on the jpayne@69: * locale. For all numeric arguments, double is assumed unless the type is jpayne@69: * explicitly integer. All choice format arguments must be of type double. jpayne@69: * @param locale The locale for which the message will be formatted jpayne@69: * @param pattern The pattern specifying the message's format jpayne@69: * @param patternLength The length of pattern jpayne@69: * @param result A pointer to a buffer to receive the formatted message. jpayne@69: * @param resultLength The maximum size of result. jpayne@69: * @param ap A variable-length argument list containing the arguments specified jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * in pattern. jpayne@69: * @return The total buffer size needed; if greater than resultLength, the jpayne@69: * output was truncated. jpayne@69: * @see u_parseMessage jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_vformatMessage( const char *locale, jpayne@69: const UChar *pattern, jpayne@69: int32_t patternLength, jpayne@69: UChar *result, jpayne@69: int32_t resultLength, jpayne@69: va_list ap, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Parse a message. jpayne@69: * For numeric arguments, this function will always use doubles. Integer types jpayne@69: * should not be passed. jpayne@69: * This function is not able to parse all output from {@link #u_formatMessage }. jpayne@69: * @param locale The locale for which the message is formatted jpayne@69: * @param pattern The pattern specifying the message's format jpayne@69: * @param patternLength The length of pattern jpayne@69: * @param source The text to parse. jpayne@69: * @param sourceLength The length of source, or -1 if null-terminated. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @param ... A variable-length argument list containing the arguments jpayne@69: * specified in pattern. jpayne@69: * @see u_formatMessage jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: u_parseMessage( const char *locale, jpayne@69: const UChar *pattern, jpayne@69: int32_t patternLength, jpayne@69: const UChar *source, jpayne@69: int32_t sourceLength, jpayne@69: UErrorCode *status, jpayne@69: ...); jpayne@69: jpayne@69: /** jpayne@69: * Parse a message. jpayne@69: * For numeric arguments, this function will always use doubles. Integer types jpayne@69: * should not be passed. jpayne@69: * This function is not able to parse all output from {@link #u_formatMessage }. jpayne@69: * @param locale The locale for which the message is formatted jpayne@69: * @param pattern The pattern specifying the message's format jpayne@69: * @param patternLength The length of pattern jpayne@69: * @param source The text to parse. jpayne@69: * @param sourceLength The length of source, or -1 if null-terminated. jpayne@69: * @param ap A variable-length argument list containing the arguments jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * specified in pattern. jpayne@69: * @see u_formatMessage jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: u_vparseMessage(const char *locale, jpayne@69: const UChar *pattern, jpayne@69: int32_t patternLength, jpayne@69: const UChar *source, jpayne@69: int32_t sourceLength, jpayne@69: va_list ap, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Format a message for a locale. jpayne@69: * This function may perform re-ordering of the arguments depending on the jpayne@69: * locale. For all numeric arguments, double is assumed unless the type is jpayne@69: * explicitly integer. All choice format arguments must be of type double. jpayne@69: * @param locale The locale for which the message will be formatted jpayne@69: * @param pattern The pattern specifying the message's format jpayne@69: * @param patternLength The length of pattern jpayne@69: * @param result A pointer to a buffer to receive the formatted message. jpayne@69: * @param resultLength The maximum size of result. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @param ... A variable-length argument list containing the arguments specified jpayne@69: * in pattern. jpayne@69: * @param parseError A pointer to UParseError to receive information about errors jpayne@69: * occurred during parsing. jpayne@69: * @return The total buffer size needed; if greater than resultLength, the jpayne@69: * output was truncated. jpayne@69: * @see u_parseMessage jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_formatMessageWithError( const char *locale, jpayne@69: const UChar *pattern, jpayne@69: int32_t patternLength, jpayne@69: UChar *result, jpayne@69: int32_t resultLength, jpayne@69: UParseError *parseError, jpayne@69: UErrorCode *status, jpayne@69: ...); jpayne@69: jpayne@69: /** jpayne@69: * Format a message for a locale. jpayne@69: * This function may perform re-ordering of the arguments depending on the jpayne@69: * locale. For all numeric arguments, double is assumed unless the type is jpayne@69: * explicitly integer. All choice format arguments must be of type double. jpayne@69: * @param locale The locale for which the message will be formatted jpayne@69: * @param pattern The pattern specifying the message's format jpayne@69: * @param patternLength The length of pattern jpayne@69: * @param result A pointer to a buffer to receive the formatted message. jpayne@69: * @param resultLength The maximum size of result. jpayne@69: * @param parseError A pointer to UParseError to receive information about errors jpayne@69: * occurred during parsing. jpayne@69: * @param ap A variable-length argument list containing the arguments specified jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * in pattern. jpayne@69: * @return The total buffer size needed; if greater than resultLength, the jpayne@69: * output was truncated. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_vformatMessageWithError( const char *locale, jpayne@69: const UChar *pattern, jpayne@69: int32_t patternLength, jpayne@69: UChar *result, jpayne@69: int32_t resultLength, jpayne@69: UParseError* parseError, jpayne@69: va_list ap, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Parse a message. jpayne@69: * For numeric arguments, this function will always use doubles. Integer types jpayne@69: * should not be passed. jpayne@69: * This function is not able to parse all output from {@link #u_formatMessage }. jpayne@69: * @param locale The locale for which the message is formatted jpayne@69: * @param pattern The pattern specifying the message's format jpayne@69: * @param patternLength The length of pattern jpayne@69: * @param source The text to parse. jpayne@69: * @param sourceLength The length of source, or -1 if null-terminated. jpayne@69: * @param parseError A pointer to UParseError to receive information about errors jpayne@69: * occurred during parsing. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @param ... A variable-length argument list containing the arguments jpayne@69: * specified in pattern. jpayne@69: * @see u_formatMessage jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: u_parseMessageWithError(const char *locale, jpayne@69: const UChar *pattern, jpayne@69: int32_t patternLength, jpayne@69: const UChar *source, jpayne@69: int32_t sourceLength, jpayne@69: UParseError *parseError, jpayne@69: UErrorCode *status, jpayne@69: ...); jpayne@69: jpayne@69: /** jpayne@69: * Parse a message. jpayne@69: * For numeric arguments, this function will always use doubles. Integer types jpayne@69: * should not be passed. jpayne@69: * This function is not able to parse all output from {@link #u_formatMessage }. jpayne@69: * @param locale The locale for which the message is formatted jpayne@69: * @param pattern The pattern specifying the message's format jpayne@69: * @param patternLength The length of pattern jpayne@69: * @param source The text to parse. jpayne@69: * @param sourceLength The length of source, or -1 if null-terminated. jpayne@69: * @param ap A variable-length argument list containing the arguments jpayne@69: * @param parseError A pointer to UParseError to receive information about errors jpayne@69: * occurred during parsing. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * specified in pattern. jpayne@69: * @see u_formatMessage jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: u_vparseMessageWithError(const char *locale, jpayne@69: const UChar *pattern, jpayne@69: int32_t patternLength, jpayne@69: const UChar *source, jpayne@69: int32_t sourceLength, jpayne@69: va_list ap, jpayne@69: UParseError *parseError, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /*----------------------- New experimental API --------------------------- */ jpayne@69: /** jpayne@69: * The message format object jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: typedef void* UMessageFormat; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Open a message formatter with given pattern and for the given locale. jpayne@69: * @param pattern A pattern specifying the format to use. jpayne@69: * @param patternLength Length of the pattern to use jpayne@69: * @param locale The locale for which the messages are formatted. jpayne@69: * @param parseError A pointer to UParseError struct to receive any errors jpayne@69: * occured during parsing. Can be NULL. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors. jpayne@69: * @return A pointer to a UMessageFormat to use for formatting jpayne@69: * messages, or 0 if an error occurred. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE UMessageFormat* U_EXPORT2 jpayne@69: umsg_open( const UChar *pattern, jpayne@69: int32_t patternLength, jpayne@69: const char *locale, jpayne@69: UParseError *parseError, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Close a UMessageFormat. jpayne@69: * Once closed, a UMessageFormat may no longer be used. jpayne@69: * @param format The formatter to close. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: umsg_close(UMessageFormat* format); jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: /** jpayne@69: * \class LocalUMessageFormatPointer jpayne@69: * "Smart pointer" class, closes a UMessageFormat via umsg_close(). jpayne@69: * For most methods see the LocalPointerBase base class. jpayne@69: * jpayne@69: * @see LocalPointerBase jpayne@69: * @see LocalPointer jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_DEFINE_LOCAL_OPEN_POINTER(LocalUMessageFormatPointer, UMessageFormat, umsg_close); jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif jpayne@69: jpayne@69: /** jpayne@69: * Open a copy of a UMessageFormat. jpayne@69: * This function performs a deep copy. jpayne@69: * @param fmt The formatter to copy jpayne@69: * @param status A pointer to an UErrorCode to receive any errors. jpayne@69: * @return A pointer to a UDateFormat identical to fmt. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE UMessageFormat U_EXPORT2 jpayne@69: umsg_clone(const UMessageFormat *fmt, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Sets the locale. This locale is used for fetching default number or date jpayne@69: * format information. jpayne@69: * @param fmt The formatter to set jpayne@69: * @param locale The locale the formatter should use. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: umsg_setLocale(UMessageFormat *fmt, jpayne@69: const char* locale); jpayne@69: jpayne@69: /** jpayne@69: * Gets the locale. This locale is used for fetching default number or date jpayne@69: * format information. jpayne@69: * @param fmt The formatter to querry jpayne@69: * @return the locale. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE const char* U_EXPORT2 jpayne@69: umsg_getLocale(const UMessageFormat *fmt); jpayne@69: jpayne@69: /** jpayne@69: * Sets the pattern. jpayne@69: * @param fmt The formatter to use jpayne@69: * @param pattern The pattern to be applied. jpayne@69: * @param patternLength Length of the pattern to use jpayne@69: * @param parseError Struct to receive information on position jpayne@69: * of error if an error is encountered.Can be NULL. jpayne@69: * @param status Output param set to success/failure code on jpayne@69: * exit. If the pattern is invalid, this will be jpayne@69: * set to a failure result. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: umsg_applyPattern( UMessageFormat *fmt, jpayne@69: const UChar* pattern, jpayne@69: int32_t patternLength, jpayne@69: UParseError* parseError, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Gets the pattern. jpayne@69: * @param fmt The formatter to use jpayne@69: * @param result A pointer to a buffer to receive the pattern. jpayne@69: * @param resultLength The maximum size of result. jpayne@69: * @param status Output param set to success/failure code on jpayne@69: * exit. If the pattern is invalid, this will be jpayne@69: * set to a failure result. jpayne@69: * @return the pattern of the format jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: umsg_toPattern(const UMessageFormat *fmt, jpayne@69: UChar* result, jpayne@69: int32_t resultLength, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Format a message for a locale. jpayne@69: * This function may perform re-ordering of the arguments depending on the jpayne@69: * locale. For all numeric arguments, double is assumed unless the type is jpayne@69: * explicitly integer. All choice format arguments must be of type double. jpayne@69: * @param fmt The formatter to use jpayne@69: * @param result A pointer to a buffer to receive the formatted message. jpayne@69: * @param resultLength The maximum size of result. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @param ... A variable-length argument list containing the arguments jpayne@69: * specified in pattern. jpayne@69: * @return The total buffer size needed; if greater than resultLength, jpayne@69: * the output was truncated. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: umsg_format( const UMessageFormat *fmt, jpayne@69: UChar *result, jpayne@69: int32_t resultLength, jpayne@69: UErrorCode *status, jpayne@69: ...); jpayne@69: jpayne@69: /** jpayne@69: * Format a message for a locale. jpayne@69: * This function may perform re-ordering of the arguments depending on the jpayne@69: * locale. For all numeric arguments, double is assumed unless the type is jpayne@69: * explicitly integer. All choice format arguments must be of type double. jpayne@69: * @param fmt The formatter to use jpayne@69: * @param result A pointer to a buffer to receive the formatted message. jpayne@69: * @param resultLength The maximum size of result. jpayne@69: * @param ap A variable-length argument list containing the arguments jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * specified in pattern. jpayne@69: * @return The total buffer size needed; if greater than resultLength, jpayne@69: * the output was truncated. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: umsg_vformat( const UMessageFormat *fmt, jpayne@69: UChar *result, jpayne@69: int32_t resultLength, jpayne@69: va_list ap, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Parse a message. jpayne@69: * For numeric arguments, this function will always use doubles. Integer types jpayne@69: * should not be passed. jpayne@69: * This function is not able to parse all output from {@link #umsg_format }. jpayne@69: * @param fmt The formatter to use jpayne@69: * @param source The text to parse. jpayne@69: * @param sourceLength The length of source, or -1 if null-terminated. jpayne@69: * @param count Output param to receive number of elements returned. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @param ... A variable-length argument list containing the arguments jpayne@69: * specified in pattern. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: umsg_parse( const UMessageFormat *fmt, jpayne@69: const UChar *source, jpayne@69: int32_t sourceLength, jpayne@69: int32_t *count, jpayne@69: UErrorCode *status, jpayne@69: ...); jpayne@69: jpayne@69: /** jpayne@69: * Parse a message. jpayne@69: * For numeric arguments, this function will always use doubles. Integer types jpayne@69: * should not be passed. jpayne@69: * This function is not able to parse all output from {@link #umsg_format }. jpayne@69: * @param fmt The formatter to use jpayne@69: * @param source The text to parse. jpayne@69: * @param sourceLength The length of source, or -1 if null-terminated. jpayne@69: * @param count Output param to receive number of elements returned. jpayne@69: * @param ap A variable-length argument list containing the arguments jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * specified in pattern. jpayne@69: * @see u_formatMessage jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: umsg_vparse(const UMessageFormat *fmt, jpayne@69: const UChar *source, jpayne@69: int32_t sourceLength, jpayne@69: int32_t *count, jpayne@69: va_list ap, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Convert an 'apostrophe-friendly' pattern into a standard jpayne@69: * pattern. Standard patterns treat all apostrophes as jpayne@69: * quotes, which is problematic in some languages, e.g. jpayne@69: * French, where apostrophe is commonly used. This utility jpayne@69: * assumes that only an unpaired apostrophe immediately before jpayne@69: * a brace is a true quote. Other unpaired apostrophes are paired, jpayne@69: * and the resulting standard pattern string is returned. jpayne@69: * jpayne@69: *

Note it is not guaranteed that the returned pattern jpayne@69: * is indeed a valid pattern. The only effect is to convert jpayne@69: * between patterns having different quoting semantics. jpayne@69: * jpayne@69: * @param pattern the 'apostrophe-friendly' patttern to convert jpayne@69: * @param patternLength the length of pattern, or -1 if unknown and pattern is null-terminated jpayne@69: * @param dest the buffer for the result, or NULL if preflight only jpayne@69: * @param destCapacity the length of the buffer, or 0 if preflighting jpayne@69: * @param ec the error code jpayne@69: * @return the length of the resulting text, not including trailing null jpayne@69: * if buffer has room for the trailing null, it is provided, otherwise jpayne@69: * not jpayne@69: * @stable ICU 3.4 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: umsg_autoQuoteApostrophe(const UChar* pattern, jpayne@69: int32_t patternLength, jpayne@69: UChar* dest, jpayne@69: int32_t destCapacity, jpayne@69: UErrorCode* ec); jpayne@69: jpayne@69: #endif /* #if !UCONFIG_NO_FORMATTING */ jpayne@69: jpayne@69: #endif