X-Git-Url: https://git.saurik.com/apple/icu.git/blobdiff_plain/729e4ab9bc6618bc3d8a898e575df7f4019e29ca..refs/heads/master:/icuSources/i18n/unicode/umsg.h diff --git a/icuSources/i18n/unicode/umsg.h b/icuSources/i18n/unicode/umsg.h index 7d08fd3b..5d235e42 100644 --- a/icuSources/i18n/unicode/umsg.h +++ b/icuSources/i18n/unicode/umsg.h @@ -1,19 +1,20 @@ +// © 2016 and later: Unicode, Inc. and others. +// License & terms of use: http://www.unicode.org/copyright.html /******************************************************************** * COPYRIGHT: - * Copyright (c) 1997-2010, International Business Machines Corporation and + * Copyright (c) 1997-2011, International Business Machines Corporation and * others. All Rights Reserved. * Copyright (C) 2010 , Yahoo! Inc. ******************************************************************** * * file name: umsg.h - * encoding: US-ASCII + * 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 @@ -27,19 +28,30 @@ #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
@@ -143,102 +155,6 @@
  * }
  * \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
- *                      | "select" "," selectStyle
- *
- *       datetimeStyle := "short"
- *                      | "medium"
- *                      | "long"
- *                      | "full"
- *                      | dateFormatPattern
- *
- *       numberStyle :=   "currency"
- *                      | "percent"
- *                      | "integer"
- *                      | numberFormatPattern
- *
- *       choiceStyle :=   choiceFormatPattern
- *
- *       selectStyle :=   selectFormatPattern
- * \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. - *

- *

Warning:
The rules for using quotes within message - * format patterns unfortunately have shown to be somewhat confusing. - * In particular, it isn't always obvious to localizers whether single - * quotes need to be doubled or not. Make sure to inform localizers about - * the rules, and tell them (for example, by using comments in resource - * bundle source files) which strings will be processed by MessageFormat. - * Note that localizers may need to use single quotes in translated - * strings where the original version doesn't have them. - *
Note also that the simplest way to avoid the problem is to - * use the real apostrophe (single quote) character U+2019 (') for - * human-readable text, and to use the ASCII apostrophe (U+0027 ' ) - * only in program syntax, like quoting in MessageFormat. - * See the annotations for U+0027 Apostrophe in The Unicode Standard.

- *
- *

- * 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! - * 

- * \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}
- * \endcode
- *
- * and so on. */ /**