X-Git-Url: https://git.saurik.com/apple/icu.git/blobdiff_plain/b75a7d8f3b4adbae880cab104ce2c6a50eee4db2..340931cb2e044a2141d11567dd0f782524e32994:/icuSources/i18n/unicode/umsg.h diff --git a/icuSources/i18n/unicode/umsg.h b/icuSources/i18n/unicode/umsg.h index 9bcc8f65..5d235e42 100644 --- a/icuSources/i18n/unicode/umsg.h +++ b/icuSources/i18n/unicode/umsg.h @@ -1,19 +1,21 @@ -/* -******************************************************************************* -* Copyright (C) 1996-2003, International Business Machines Corporation and others. All Rights Reserved. -******************************************************************************* -* -* file name: umsg.h -* encoding: US-ASCII -* tab size: 8 (not used) -* indentation:4 -* -* Change history: -* -* 08/5/2001 Ram Added C wrappers for C++ API. -* -* -*/ +// © 2016 and later: Unicode, Inc. and others. +// License & terms of use: http://www.unicode.org/copyright.html +/******************************************************************** + * COPYRIGHT: + * Copyright (c) 1997-2011, International Business Machines Corporation and + * others. All Rights Reserved. + * Copyright (C) 2010 , Yahoo! Inc. + ******************************************************************** + * + * file name: umsg.h + * encoding: UTF-8 + * tab size: 8 (not used) + * indentation:4 + * + * Change history: + * + * 08/5/2001 Ram Added C wrappers for C++ API. + ********************************************************************/ #ifndef UMSG_H #define UMSG_H @@ -22,21 +24,34 @@ #if !UCONFIG_NO_FORMATTING +#include "unicode/localpointer.h" +#include "unicode/uloc.h" #include "unicode/parseerr.h" #include + /** * \file * \brief C API: MessageFormat * - *

Message Format C API

+ *

MessageFormat C API

* - * Provides means to produce concatenated messages in language-neutral way. - * Use this for all concatenations that show up to end users. - *

- * Takes a set of objects, formats them, then inserts the formatted - * strings into the pattern at the appropriate places. - *

- * Here are some examples of usage: + *

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

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

Currently, the C API supports only numbered arguments. + * + *

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

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

  * \code
@@ -85,8 +100,8 @@
  *     u_uastrcpy(str, "MyDisk");
  *     u_uastrcpy(pattern, "The disk {1} contains {0,choice,0#no files|1#one file|1<{0,number,integer} files}");
  *     for(i=0; i<3; i++){
- *       resultlength=0;
- *       resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern), NULL, resultlength, &status, testArgs[i], str);
+ *       resultlength=0; 
+ *       resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern), NULL, resultlength, &status, testArgs[i], str); 
  *       if(status==U_BUFFER_OVERFLOW_ERROR){
  *         status=U_ZERO_ERROR;
  *         resultlength=resultLengthOut+1;
@@ -103,82 +118,43 @@
  * \endcode
  *
* - * The pattern is of the following form. Legend: - * 
- * \code
- *       {optional item}
- *       (group that may be repeated)*
- * \endcode
- *
- * Do not confuse optional items with items inside quotes braces, such - * as this: "{". Quoted braces are literals. - * 
- * \code
- *       messageFormatPattern := string ( "{" messageFormatElement "}" string )*
- *
- *       messageFormatElement := argument { "," elementFormat }
- *
- *       elementFormat := "time" { "," datetimeStyle }
- *                      | "date" { "," datetimeStyle }
- *                      | "number" { "," numberStyle }
- *                      | "choice" "," choiceStyle
- *
- *       datetimeStyle := "short"
- *                      | "medium"
- *                      | "long"
- *                      | "full"
- *                      | dateFormatPattern
- *
- *       numberStyle :=   "currency"
- *                      | "percent"
- *                      | "integer"
- *                      | numberFormatPattern
  *
- *       choiceStyle :=   choiceFormatPattern
- * \endcode
- *
- * If there is no elementFormat, then the argument must be a string, - * which is substituted. If there is no dateTimeStyle or numberStyle, - * then the default format is used (e.g. NumberFormat.getInstance(), - * DateFormat.getDefaultTime() or DateFormat.getDefaultDate(). For - * a ChoiceFormat, the pattern must always be specified, since there - * is no default. - *

- * In strings, single quotes can be used to quote the "{" sign if - * necessary. A real single quote is represented by ''. Inside a - * messageFormatElement, quotes are [not] removed. For example, - * {1,number,$'#',##} will produce a number format with the pound-sign - * quoted, with a result such as: "$#31,45". - *

- * If a pattern is used, then unquoted braces in the pattern, if any, - * must match: that is, "ab {0} de" and "ab '}' de" are ok, but "ab - * {0'}' de" and "ab } de" are not. - *

- * The argument is a number from 0 to 9, which corresponds to the - * arguments presented in an array to be formatted. - *

- * It is ok to have unused arguments in the array. With missing - * arguments or arguments that are not of the right class for the - * specified format, a failing UErrorCode result is set. - *

- - *

- * [Note:] As we see above, the string produced by a choice Format in - * MessageFormat is treated specially; occurances of '{' are used to - * indicated subformats. - *

- * [Note:] Formats are numbered by order of variable in the string. - * This is [not] the same as the argument numbering! + * Example 3: * 

  * \code
- *    For example: with "abc{2}def{3}ghi{0}...",
- *
- *    format0 affects the first variable {2}
- *    format1 affects the second variable {3}
- *    format2 affects the second variable {0}
+ * UChar* str;
+ * UChar* str1;
+ * UErrorCode status = U_ZERO_ERROR;
+ * UChar *result;
+ * UChar pattern[100];
+ * UChar expected[100];
+ * int32_t resultlength,resultLengthOut;
+
+ * str=(UChar*)malloc(sizeof(UChar) * 25);
+ * u_uastrcpy(str, "Kirti");
+ * str1=(UChar*)malloc(sizeof(UChar) * 25);
+ * u_uastrcpy(str1, "female");
+ * log_verbose("Testing message format with Select test #1\n:");
+ * u_uastrcpy(pattern, "{0} est {1, select, female {all\\u00E9e} other {all\\u00E9}} \\u00E0 Paris.");
+ * u_uastrcpy(expected, "Kirti est all\\u00E9e \\u00E0 Paris.");
+ * resultlength=0;
+ * resultLengthOut=u_formatMessage( "fr", pattern, u_strlen(pattern), NULL, resultlength, &status, str , str1);
+ * if(status==U_BUFFER_OVERFLOW_ERROR)
+ *  {
+ *      status=U_ZERO_ERROR;
+ *      resultlength=resultLengthOut+1;
+ *      result=(UChar*)malloc(sizeof(UChar) * resultlength);
+ *      u_formatMessage( "fr", pattern, u_strlen(pattern), result, resultlength, &status, str , str1);
+ *      if(u_strcmp(result, expected)==0)
+ *          log_verbose("PASS: MessagFormat successful on Select test#1\n");
+ *      else{
+ *          log_err("FAIL: Error in MessageFormat on Select test#1\n GOT %s EXPECTED %s\n", austrdup(result),
+ *          austrdup(expected) );
+ *      }
+ *      free(result);
+ * }
  * \endcode
- *
- * and so on. + * */ /** @@ -199,7 +175,7 @@ * @see u_parseMessage * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 u_formatMessage(const char *locale, const UChar *pattern, int32_t patternLength, @@ -226,7 +202,7 @@ u_formatMessage(const char *locale, * @see u_parseMessage * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 u_vformatMessage( const char *locale, const UChar *pattern, int32_t patternLength, @@ -239,7 +215,7 @@ u_vformatMessage( const char *locale, * Parse a message. * For numeric arguments, this function will always use doubles. Integer types * should not be passed. - * This function is not able to parse all output from \Ref{u_formatMessage}. + * This function is not able to parse all output from {@link #u_formatMessage }. * @param locale The locale for which the message is formatted * @param pattern The pattern specifying the message's format * @param patternLength The length of pattern @@ -251,7 +227,7 @@ u_vformatMessage( const char *locale, * @see u_formatMessage * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 u_parseMessage( const char *locale, const UChar *pattern, int32_t patternLength, @@ -264,7 +240,7 @@ u_parseMessage( const char *locale, * Parse a message. * For numeric arguments, this function will always use doubles. Integer types * should not be passed. - * This function is not able to parse all output from \Ref{u_formatMessage}. + * This function is not able to parse all output from {@link #u_formatMessage }. * @param locale The locale for which the message is formatted * @param pattern The pattern specifying the message's format * @param patternLength The length of pattern @@ -276,7 +252,7 @@ u_parseMessage( const char *locale, * @see u_formatMessage * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 u_vparseMessage(const char *locale, const UChar *pattern, int32_t patternLength, @@ -305,7 +281,7 @@ u_vparseMessage(const char *locale, * @see u_parseMessage * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 u_formatMessageWithError( const char *locale, const UChar *pattern, int32_t patternLength, @@ -334,7 +310,7 @@ u_formatMessageWithError( const char *locale, * output was truncated. * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 u_vformatMessageWithError( const char *locale, const UChar *pattern, int32_t patternLength, @@ -348,7 +324,7 @@ u_vformatMessageWithError( const char *locale, * Parse a message. * For numeric arguments, this function will always use doubles. Integer types * should not be passed. - * This function is not able to parse all output from \Ref{u_formatMessage}. + * This function is not able to parse all output from {@link #u_formatMessage }. * @param locale The locale for which the message is formatted * @param pattern The pattern specifying the message's format * @param patternLength The length of pattern @@ -362,7 +338,7 @@ u_vformatMessageWithError( const char *locale, * @see u_formatMessage * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 u_parseMessageWithError(const char *locale, const UChar *pattern, int32_t patternLength, @@ -376,7 +352,7 @@ u_parseMessageWithError(const char *locale, * Parse a message. * For numeric arguments, this function will always use doubles. Integer types * should not be passed. - * This function is not able to parse all output from \Ref{u_formatMessage}. + * This function is not able to parse all output from {@link #u_formatMessage }. * @param locale The locale for which the message is formatted * @param pattern The pattern specifying the message's format * @param patternLength The length of pattern @@ -390,7 +366,7 @@ u_parseMessageWithError(const char *locale, * @see u_formatMessage * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 u_vparseMessageWithError(const char *locale, const UChar *pattern, int32_t patternLength, @@ -420,7 +396,7 @@ typedef void* UMessageFormat; * messages, or 0 if an error occurred. * @stable ICU 2.0 */ -U_CAPI UMessageFormat* U_EXPORT2 +U_STABLE UMessageFormat* U_EXPORT2 umsg_open( const UChar *pattern, int32_t patternLength, const char *locale, @@ -433,9 +409,28 @@ umsg_open( const UChar *pattern, * @param format The formatter to close. * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 umsg_close(UMessageFormat* format); +#if U_SHOW_CPLUSPLUS_API + +U_NAMESPACE_BEGIN + +/** + * \class LocalUMessageFormatPointer + * "Smart pointer" class, closes a UMessageFormat via umsg_close(). + * For most methods see the LocalPointerBase base class. + * + * @see LocalPointerBase + * @see LocalPointer + * @stable ICU 4.4 + */ +U_DEFINE_LOCAL_OPEN_POINTER(LocalUMessageFormatPointer, UMessageFormat, umsg_close); + +U_NAMESPACE_END + +#endif + /** * Open a copy of a UMessageFormat. * This function performs a deep copy. @@ -444,7 +439,7 @@ umsg_close(UMessageFormat* format); * @return A pointer to a UDateFormat identical to fmt. * @stable ICU 2.0 */ -U_CAPI UMessageFormat U_EXPORT2 +U_STABLE UMessageFormat U_EXPORT2 umsg_clone(const UMessageFormat *fmt, UErrorCode *status); @@ -455,7 +450,7 @@ umsg_clone(const UMessageFormat *fmt, * @param locale The locale the formatter should use. * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 umsg_setLocale(UMessageFormat *fmt, const char* locale); @@ -466,8 +461,8 @@ umsg_setLocale(UMessageFormat *fmt, * @return the locale. * @stable ICU 2.0 */ -U_CAPI const char* U_EXPORT2 -umsg_getLocale(UMessageFormat *fmt); +U_STABLE const char* U_EXPORT2 +umsg_getLocale(const UMessageFormat *fmt); /** * Sets the pattern. @@ -481,7 +476,7 @@ umsg_getLocale(UMessageFormat *fmt); * set to a failure result. * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 umsg_applyPattern( UMessageFormat *fmt, const UChar* pattern, int32_t patternLength, @@ -499,8 +494,8 @@ umsg_applyPattern( UMessageFormat *fmt, * @return the pattern of the format * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 -umsg_toPattern(UMessageFormat *fmt, +U_STABLE int32_t U_EXPORT2 +umsg_toPattern(const UMessageFormat *fmt, UChar* result, int32_t resultLength, UErrorCode* status); @@ -520,8 +515,8 @@ umsg_toPattern(UMessageFormat *fmt, * the output was truncated. * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 -umsg_format( UMessageFormat *fmt, +U_STABLE int32_t U_EXPORT2 +umsg_format( const UMessageFormat *fmt, UChar *result, int32_t resultLength, UErrorCode *status, @@ -542,8 +537,8 @@ umsg_format( UMessageFormat *fmt, * the output was truncated. * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 -umsg_vformat( UMessageFormat *fmt, +U_STABLE int32_t U_EXPORT2 +umsg_vformat( const UMessageFormat *fmt, UChar *result, int32_t resultLength, va_list ap, @@ -553,7 +548,7 @@ umsg_vformat( UMessageFormat *fmt, * Parse a message. * For numeric arguments, this function will always use doubles. Integer types * should not be passed. - * This function is not able to parse all output from \Ref{umsg_format}. + * This function is not able to parse all output from {@link #umsg_format }. * @param fmt The formatter to use * @param source The text to parse. * @param sourceLength The length of source, or -1 if null-terminated. @@ -563,8 +558,8 @@ umsg_vformat( UMessageFormat *fmt, * specified in pattern. * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 -umsg_parse( UMessageFormat *fmt, +U_STABLE void U_EXPORT2 +umsg_parse( const UMessageFormat *fmt, const UChar *source, int32_t sourceLength, int32_t *count, @@ -575,7 +570,7 @@ umsg_parse( UMessageFormat *fmt, * Parse a message. * For numeric arguments, this function will always use doubles. Integer types * should not be passed. - * This function is not able to parse all output from \Ref{umsg_format}. + * This function is not able to parse all output from {@link #umsg_format }. * @param fmt The formatter to use * @param source The text to parse. * @param sourceLength The length of source, or -1 if null-terminated. @@ -586,14 +581,45 @@ umsg_parse( UMessageFormat *fmt, * @see u_formatMessage * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 -umsg_vparse(UMessageFormat *fmt, +U_STABLE void U_EXPORT2 +umsg_vparse(const UMessageFormat *fmt, const UChar *source, int32_t sourceLength, int32_t *count, va_list ap, UErrorCode *status); + +/** + * Convert an 'apostrophe-friendly' pattern into a standard + * pattern. Standard patterns treat all apostrophes as + * quotes, which is problematic in some languages, e.g. + * French, where apostrophe is commonly used. This utility + * assumes that only an unpaired apostrophe immediately before + * a brace is a true quote. Other unpaired apostrophes are paired, + * and the resulting standard pattern string is returned. + * + *

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