The Tor Browser / file revision

 /*

 * Copyright (C) 2007-2013, International Business Machines Corporation and

 * others. All Rights Reserved.

 ********************************************************************************

 *

 * File MSGFMT.H

 *

 * Modification History:

 *

 *   Date        Name        Description

 *   02/19/97    aliu        Converted from java.

 *   03/20/97    helena      Finished first cut of implementation.

 *   07/22/98    stephen     Removed operator!= (defined in Format)

 *   08/19/2002  srl         Removing Javaisms

 *******************************************************************************/

 #ifndef MSGFMT_H

 #define MSGFMT_H

 #include "unicode/utypes.h"

 /**

  * \file

  * \brief C++ API: Formats messages in a language-neutral way.

  */

 #if !UCONFIG_NO_FORMATTING

 #include "unicode/format.h"

 #include "unicode/locid.h"

 #include "unicode/messagepattern.h"

 #include "unicode/parseerr.h"

 #include "unicode/plurfmt.h"

 #include "unicode/plurrule.h"

 U_CDECL_BEGIN

 // Forward declaration.

 struct UHashtable;

 typedef struct UHashtable UHashtable; /**< @internal */

 U_CDECL_END

 U_NAMESPACE_BEGIN

 class AppendableWrapper;

 class DateFormat;

 class NumberFormat;

 /**

  * <p>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.

  *

  * <p>A MessageFormat is constructed from a <em>pattern</em> string

  * with arguments in {curly braces} which will be replaced by formatted values.

  *

  * <p><code>MessageFormat</code> differs from the other <code>Format</code>

  * classes in that you create a <code>MessageFormat</code> object with one

  * of its constructors (not with a <code>createInstance</code> style factory

  * method). Factory methods aren't necessary because <code>MessageFormat</code>

  * itself doesn't implement locale-specific behavior. Any locale-specific

  * behavior is defined by the pattern that you provide and the

  * subformats used for inserted arguments.

  *

  * <p>Arguments can be named (using identifiers) or numbered (using small ASCII-digit integers).

  * Some of the API methods work only with argument numbers and throw an exception

  * if the pattern has named arguments (see {@link #usesNamedArguments()}).

  *

  * <p>An argument might not specify any format type. In this case,

  * a Number value is formatted with a default (for the locale) NumberFormat,

  * a Date value is formatted with a default (for the locale) DateFormat,

  * and for any other value its toString() value is used.

  *

  * <p>An argument might specify a "simple" type for which the specified

  * Format object is created, cached and used.

  *

  * <p>An argument might have a "complex" type with nested MessageFormat sub-patterns.

  * During formatting, one of these sub-messages is selected according to the argument value

  * and recursively formatted.

  *

  * <p>After construction, a custom Format object can be set for

  * a top-level argument, overriding the default formatting and parsing behavior

  * for that argument.

  * However, custom formatting can be achieved more simply by writing

  * a typeless argument in the pattern string

  * and supplying it with a preformatted string value.

  *

  * <p>When formatting, MessageFormat takes a collection of argument values

  * and writes an output string.

  * The argument values may be passed as an array

  * (when the pattern contains only numbered arguments)

  * or as an array of names and and an array of arguments (which works for both named

  * and numbered arguments).

  *

  * <p>Each argument is matched with one of the input values by array index or argument name

  * and formatted according to its pattern specification

  * (or using a custom Format object if one was set).

  * A numbered pattern argument is matched with an argument name that contains that number

  * as an ASCII-decimal-digit string (without leading zero).

  *

  * <h4><a name="patterns">Patterns and Their Interpretation</a></h4>

  *

  * <code>MessageFormat</code> uses patterns of the following form:

  * <pre>

  * message = messageText (argument messageText)*

  * argument = noneArg | simpleArg | complexArg

  * complexArg = choiceArg | pluralArg | selectArg | selectordinalArg

  *

  * noneArg = '{' argNameOrNumber '}'

  * simpleArg = '{' argNameOrNumber ',' argType [',' argStyle] '}'

  * choiceArg = '{' argNameOrNumber ',' "choice" ',' choiceStyle '}'

  * pluralArg = '{' argNameOrNumber ',' "plural" ',' pluralStyle '}'

  * selectArg = '{' argNameOrNumber ',' "select" ',' selectStyle '}'

  * selectordinalArg = '{' argNameOrNumber ',' "selectordinal" ',' pluralStyle '}'

  *

  * choiceStyle: see {@link ChoiceFormat}

  * pluralStyle: see {@link PluralFormat}

  * selectStyle: see {@link SelectFormat}

  *

  * argNameOrNumber = argName | argNumber

  * argName = [^[[:Pattern_Syntax:][:Pattern_White_Space:]]]+

  * argNumber = '0' | ('1'..'9' ('0'..'9')*)

  *

  * argType = "number" | "date" | "time" | "spellout" | "ordinal" | "duration"

  * argStyle = "short" | "medium" | "long" | "full" | "integer" | "currency" | "percent" | argStyleText

  * </pre>

  *

  * <ul>

  *   <li>messageText can contain quoted literal strings including syntax characters.

  *       A quoted literal string begins with an ASCII apostrophe and a syntax character

  *       (usually a {curly brace}) and continues until the next single apostrophe.

  *       A double ASCII apostrohpe inside or outside of a quoted string represents

  *       one literal apostrophe.

  *   <li>Quotable syntax characters are the {curly braces} in all messageText parts,

  *       plus the '#' sign in a messageText immediately inside a pluralStyle,

  *       and the '|' symbol in a messageText immediately inside a choiceStyle.

  *   <li>See also {@link #UMessagePatternApostropheMode}

  *   <li>In argStyleText, every single ASCII apostrophe begins and ends quoted literal text,

  *       and unquoted {curly braces} must occur in matched pairs.

  * </ul>

  *

  * <p>Recommendation: Use the real apostrophe (single quote) character

  * \htmlonly’\endhtmlonly (U+2019) for

  * human-readable text, and 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.

  *

  * <p>The <code>choice</code> argument type is deprecated.

  * Use <code>plural</code> arguments for proper plural selection,

  * and <code>select</code> arguments for simple selection among a fixed set of choices.

  *

  * <p>The <code>argType</code> and <code>argStyle</code> values are used to create

  * a <code>Format</code> instance for the format element. The following

  * table shows how the values map to Format instances. Combinations not

  * shown in the table are illegal. Any <code>argStyleText</code> must

  * be a valid pattern string for the Format subclass used.

  *

  * <p><table border=1>

  *    <tr>

  *       <th>argType

  *       <th>argStyle

  *       <th>resulting Format object

  *    <tr>

  *       <td colspan=2><i>(none)</i>

  *       <td><code>null</code>

  *    <tr>

  *       <td rowspan=5><code>number</code>

  *       <td><i>(none)</i>

  *       <td><code>NumberFormat.createInstance(getLocale(), status)</code>

  *    <tr>

  *       <td><code>integer</code>

  *       <td><code>NumberFormat.createInstance(getLocale(), kNumberStyle, status)</code>

  *    <tr>

  *       <td><code>currency</code>

  *       <td><code>NumberFormat.createCurrencyInstance(getLocale(), status)</code>

  *    <tr>

  *       <td><code>percent</code>

  *       <td><code>NumberFormat.createPercentInstance(getLocale(), status)</code>

  *    <tr>

  *       <td><i>argStyleText</i>

  *       <td><code>new DecimalFormat(argStyleText, new DecimalFormatSymbols(getLocale(), status), status)</code>

  *    <tr>

  *       <td rowspan=6><code>date</code>

  *       <td><i>(none)</i>

  *       <td><code>DateFormat.createDateInstance(kDefault, getLocale(), status)</code>

  *    <tr>

  *       <td><code>short</code>

  *       <td><code>DateFormat.createDateInstance(kShort, getLocale(), status)</code>

  *    <tr>

  *       <td><code>medium</code>

  *       <td><code>DateFormat.createDateInstance(kDefault, getLocale(), status)</code>

  *    <tr>

  *       <td><code>long</code>

  *       <td><code>DateFormat.createDateInstance(kLong, getLocale(), status)</code>

  *    <tr>

  *       <td><code>full</code>

  *       <td><code>DateFormat.createDateInstance(kFull, getLocale(), status)</code>

  *    <tr>

  *       <td><i>argStyleText</i>

  *       <td><code>new SimpleDateFormat(argStyleText, getLocale(), status)

  *    <tr>

  *       <td rowspan=6><code>time</code>

  *       <td><i>(none)</i>

  *       <td><code>DateFormat.createTimeInstance(kDefault, getLocale(), status)</code>

  *    <tr>

  *       <td><code>short</code>

  *       <td><code>DateFormat.createTimeInstance(kShort, getLocale(), status)</code>

  *    <tr>

  *       <td><code>medium</code>

  *       <td><code>DateFormat.createTimeInstance(kDefault, getLocale(), status)</code>

  *    <tr>

  *       <td><code>long</code>

  *       <td><code>DateFormat.createTimeInstance(kLong, getLocale(), status)</code>

  *    <tr>

  *       <td><code>full</code>

  *       <td><code>DateFormat.createTimeInstance(kFull, getLocale(), status)</code>

  *    <tr>

  *       <td><i>argStyleText</i>

  *       <td><code>new SimpleDateFormat(argStyleText, getLocale(), status)

  *    <tr>

  *       <td><code>spellout</code>

  *       <td><i>argStyleText (optional)</i>

  *       <td><code>new RuleBasedNumberFormat(URBNF_SPELLOUT, getLocale(), status)

  *           <br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(argStyleText, status);</code>

  *    <tr>

  *       <td><code>ordinal</code>

  *       <td><i>argStyleText (optional)</i>

  *       <td><code>new RuleBasedNumberFormat(URBNF_ORDINAL, getLocale(), status)

  *           <br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(argStyleText, status);</code>

  *    <tr>

  *       <td><code>duration</code>

  *       <td><i>argStyleText (optional)</i>

  *       <td><code>new RuleBasedNumberFormat(URBNF_DURATION, getLocale(), status)

  *           <br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(argStyleText, status);</code>

  * </table>

  * <p>

  *

  * <h4>Usage Information</h4>

  *

  * <p>Here are some examples of usage:

  * Example 1:

  *

  * <pre>

  * \code

  *     UErrorCode success = U_ZERO_ERROR;

  *     GregorianCalendar cal(success);

  *     Formattable arguments[] = {

  *         7L,

  *         Formattable( (Date) cal.getTime(success), Formattable::kIsDate),

  *         "a disturbance in the Force"

  *     };

  *

  *     UnicodeString result;

  *     MessageFormat::format(

  *          "At {1,time} on {1,date}, there was {2} on planet {0,number}.",

  *          arguments, 3, result, success );

  *

  *     cout << "result: " << result << endl;

  *     //<output>: At 4:34:20 PM on 23-Mar-98, there was a disturbance

  *     //             in the Force on planet 7.

  * \endcode

  * </pre>

  *

  * Typically, the message format will come from resources, and the

  * arguments will be dynamically set at runtime.

  *

  * <p>Example 2:

  *

  * <pre>

  *  \code

  *     success = U_ZERO_ERROR;

  *     Formattable testArgs[] = {3L, "MyDisk"};

  *

  *     MessageFormat form(

  *         "The disk \"{1}\" contains {0} file(s).", success );

  *

  *     UnicodeString string;

  *     FieldPosition fpos = 0;

  *     cout << "format: " << form.format(testArgs, 2, string, fpos, success ) << endl;

  *

  *     // output, with different testArgs:

  *     // output: The disk "MyDisk" contains 0 file(s).

  *     // output: The disk "MyDisk" contains 1 file(s).

  *     // output: The disk "MyDisk" contains 1,273 file(s).

  *  \endcode

  *  </pre>

  *

  *

  * <p>For messages that include plural forms, you can use a plural argument:

  * <pre>

  * \code

  *  success = U_ZERO_ERROR;

  *  MessageFormat msgFmt(

  *       "{num_files, plural, "

  *       "=0{There are no files on disk \"{disk_name}\".}"

  *       "=1{There is one file on disk \"{disk_name}\".}"

  *       "other{There are # files on disk \"{disk_name}\".}}",

  *      Locale("en"),

  *      success);

  *  FieldPosition fpos = 0;

  *  Formattable testArgs[] = {0L, "MyDisk"};

  *  UnicodeString testArgsNames[] = {"num_files", "disk_name"};

  *  UnicodeString result;

  *  cout << msgFmt.format(testArgs, testArgsNames, 2, result, fpos, 0, success);

  *  testArgs[0] = 3L;

  *  cout << msgFmt.format(testArgs, testArgsNames, 2, result, fpos, 0, success);

  * \endcode

  * <em>output</em>:

  * There are no files on disk "MyDisk".

  * There are 3 files on "MyDisk".

  * </pre>

  * See {@link PluralFormat} and {@link PluralRules} for details.

  *

  * <h4><a name="synchronization">Synchronization</a></h4>

  *

  * <p>MessageFormats are not synchronized.

  * It is recommended to create separate format instances for each thread.

  * If multiple threads access a format concurrently, it must be synchronized

  * externally.

  *

  * @stable ICU 2.0

  */

 class U_I18N_API MessageFormat : public Format {

 public:

 #ifndef U_HIDE_OBSOLETE_API

     /**

      * Enum type for kMaxFormat.

      * @obsolete ICU 3.0.  The 10-argument limit was removed as of ICU 2.6,

      * rendering this enum type obsolete.

      */

     enum EFormatNumber {

         /**

          * The maximum number of arguments.

          * @obsolete ICU 3.0.  The 10-argument limit was removed as of ICU 2.6,

          * rendering this constant obsolete.

          */

         kMaxFormat = 10

     };

 #endif  /* U_HIDE_OBSOLETE_API */

     /**

      * Constructs a new MessageFormat using the given pattern and the

      * default locale.

      *

      * @param pattern   Pattern used to construct object.

      * @param status    Input/output error code.  If the

      *                  pattern cannot be parsed, set to failure code.

      * @stable ICU 2.0

      */

     MessageFormat(const UnicodeString& pattern,

                   UErrorCode &status);

     /**

      * Constructs a new MessageFormat using the given pattern and locale.

      * @param pattern   Pattern used to construct object.

      * @param newLocale The locale to use for formatting dates and numbers.

      * @param status    Input/output error code.  If the

      *                  pattern cannot be parsed, set to failure code.

      * @stable ICU 2.0

      */

     MessageFormat(const UnicodeString& pattern,

                   const Locale& newLocale,

                         UErrorCode& status);

     /**

      * Constructs a new MessageFormat using the given pattern and locale.

      * @param pattern   Pattern used to construct object.

      * @param newLocale The locale to use for formatting dates and numbers.

      * @param parseError Struct to receive information on the position

      *                   of an error within the pattern.

      * @param status    Input/output error code.  If the

      *                  pattern cannot be parsed, set to failure code.

      * @stable ICU 2.0

      */

     MessageFormat(const UnicodeString& pattern,

                   const Locale& newLocale,

                   UParseError& parseError,

                   UErrorCode& status);

     /**

      * Constructs a new MessageFormat from an existing one.

      * @stable ICU 2.0

      */

     MessageFormat(const MessageFormat&);

     /**

      * Assignment operator.

      * @stable ICU 2.0

      */

     const MessageFormat& operator=(const MessageFormat&);

     /**

      * Destructor.

      * @stable ICU 2.0

      */

     virtual ~MessageFormat();

     /**

      * Clones this Format object polymorphically.  The caller owns the

      * result and should delete it when done.

      * @stable ICU 2.0

      */

     virtual Format* clone(void) const;

     /**

      * Returns true if the given Format objects are semantically equal.

      * Objects of different subclasses are considered unequal.

      * @param other  the object to be compared with.

      * @return       true if the given Format objects are semantically equal.

      * @stable ICU 2.0

      */

     virtual UBool operator==(const Format& other) const;

     /**

      * Sets the locale to be used for creating argument Format objects.

      * @param theLocale    the new locale value to be set.

      * @stable ICU 2.0

      */

     virtual void setLocale(const Locale& theLocale);

     /**

      * Gets the locale used for creating argument Format objects.

      * format information.

      * @return    the locale of the object.

      * @stable ICU 2.0

      */

     virtual const Locale& getLocale(void) const;

     /**

      * Applies the given pattern string to this message format.

      *

      * @param pattern   The pattern to be applied.

      * @param status    Input/output error code.  If the

      *                  pattern cannot be parsed, set to failure code.

      * @stable ICU 2.0

      */

     virtual void applyPattern(const UnicodeString& pattern,

                               UErrorCode& status);

     /**

      * Applies the given pattern string to this message format.

      *

      * @param pattern    The pattern to be applied.

      * @param parseError Struct to receive information on the position

      *                   of an error within the pattern.

      * @param status    Input/output error code.  If the

      *                  pattern cannot be parsed, set to failure code.

      * @stable ICU 2.0

      */

     virtual void applyPattern(const UnicodeString& pattern,

                              UParseError& parseError,

                              UErrorCode& status);

     /**

      * Sets the UMessagePatternApostropheMode and the pattern used by this message format.

      * Parses the pattern and caches Format objects for simple argument types.

      * Patterns and their interpretation are specified in the

      * <a href="#patterns">class description</a>.

      * <p>

      * This method is best used only once on a given object to avoid confusion about the mode,

      * and after constructing the object with an empty pattern string to minimize overhead.

      *

      * @param pattern    The pattern to be applied.

      * @param aposMode   The new apostrophe mode.

      * @param parseError Struct to receive information on the position

      *                   of an error within the pattern.

      *                   Can be NULL.

      * @param status    Input/output error code.  If the

      *                  pattern cannot be parsed, set to failure code.

      * @stable ICU 4.8

      */

     virtual void applyPattern(const UnicodeString& pattern,

                               UMessagePatternApostropheMode aposMode,

                               UParseError* parseError,

                               UErrorCode& status);

     /**

      * @return this instance's UMessagePatternApostropheMode.

      * @stable ICU 4.8

      */

     UMessagePatternApostropheMode getApostropheMode() const {

         return msgPattern.getApostropheMode();

     }

     /**

      * Returns a pattern that can be used to recreate this object.

      *

      * @param appendTo  Output parameter to receive the pattern.

      *                  Result is appended to existing contents.

      * @return          Reference to 'appendTo' parameter.

      * @stable ICU 2.0

      */

     virtual UnicodeString& toPattern(UnicodeString& appendTo) const;

     /**

      * Sets subformats.

      * See the class description about format numbering.

      * The caller should not delete the Format objects after this call.

      * <EM>The array formatsToAdopt is not itself adopted.</EM> Its

      * ownership is retained by the caller. If the call fails because

      * memory cannot be allocated, then the formats will be deleted

      * by this method, and this object will remain unchanged.

      *

      * <p>If this format uses named arguments, the new formats are discarded

      * and this format remains unchanged.

      *

      * @stable ICU 2.0

      * @param formatsToAdopt    the format to be adopted.

      * @param count             the size of the array.

      */

     virtual void adoptFormats(Format** formatsToAdopt, int32_t count);

     /**

      * Sets subformats.

      * See the class description about format numbering.

      * Each item in the array is cloned into the internal array.

      * If the call fails because memory cannot be allocated, then this

      * object will remain unchanged.

      *

      * <p>If this format uses named arguments, the new formats are discarded

      * and this format remains unchanged.

      *

      * @stable ICU 2.0

      * @param newFormats the new format to be set.

      * @param cnt        the size of the array.

      */

     virtual void setFormats(const Format** newFormats, int32_t cnt);

     /**

      * Sets one subformat.

      * See the class description about format numbering.

      * The caller should not delete the Format object after this call.

      * If the number is over the number of formats already set,

      * the item will be deleted and ignored.

      *

      * <p>If this format uses named arguments, the new format is discarded

      * and this format remains unchanged.

      *

      * @stable ICU 2.0

      * @param formatNumber     index of the subformat.

      * @param formatToAdopt    the format to be adopted.

      */

     virtual void adoptFormat(int32_t formatNumber, Format* formatToAdopt);

     /**

      * Sets one subformat.

      * See the class description about format numbering.

      * If the number is over the number of formats already set,

      * the item will be ignored.

      * @param formatNumber     index of the subformat.

      * @param format    the format to be set.

      * @stable ICU 2.0

      */

     virtual void setFormat(int32_t formatNumber, const Format& format);

     /**

      * Gets format names. This function returns formatNames in StringEnumerations

      * which can be used with getFormat() and setFormat() to export formattable

      * array from current MessageFormat to another.  It is the caller's responsibility

      * to delete the returned formatNames.

      * @param status  output param set to success/failure code.

      * @stable ICU 4.0

      */

     virtual StringEnumeration* getFormatNames(UErrorCode& status);

     /**

      * Gets subformat pointer for given format name.

      * This function supports both named and numbered

      * arguments. If numbered, the formatName is the

      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).

      * The returned Format object should not be deleted by the caller,

      * nor should the ponter of other object .  The pointer and its

      * contents remain valid only until the next call to any method

      * of this class is made with this object.

      * @param formatName the name or number specifying a format

      * @param status  output param set to success/failure code.

      * @stable ICU 4.0

      */

     virtual Format* getFormat(const UnicodeString& formatName, UErrorCode& status);

     /**

      * Sets one subformat for given format name.

      * See the class description about format name.

      * This function supports both named and numbered

      * arguments-- if numbered, the formatName is the

      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).

      * If there is no matched formatName or wrong type,

      * the item will be ignored.

      * @param formatName  Name of the subformat.

      * @param format      the format to be set.

      * @param status  output param set to success/failure code.

      * @stable ICU 4.0

      */

     virtual void setFormat(const UnicodeString& formatName, const Format& format, UErrorCode& status);

     /**

      * Sets one subformat for given format name.

      * See the class description about format name.

      * This function supports both named and numbered

      * arguments-- if numbered, the formatName is the

      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).

      * If there is no matched formatName or wrong type,

      * the item will be ignored.

      * The caller should not delete the Format object after this call.

      * @param formatName  Name of the subformat.

      * @param formatToAdopt  Format to be adopted.

      * @param status      output param set to success/failure code.

      * @stable ICU 4.0

      */

     virtual void adoptFormat(const UnicodeString& formatName, Format* formatToAdopt, UErrorCode& status);

     /**

      * Gets an array of subformats of this object.  The returned array

      * should not be deleted by the caller, nor should the pointers

      * within the array.  The array and its contents remain valid only

      * until the next call to this format. See the class description

      * about format numbering.

      *

      * @param count output parameter to receive the size of the array

      * @return an array of count Format* objects, or NULL if out of

      * memory.  Any or all of the array elements may be NULL.

      * @stable ICU 2.0

      */

     virtual const Format** getFormats(int32_t& count) const;

     using Format::format;

     /**

      * Formats the given array of arguments into a user-readable string.

      * Does not take ownership of the Formattable* array or its contents.

      *

      * <p>If this format uses named arguments, appendTo is unchanged and

      * status is set to U_ILLEGAL_ARGUMENT_ERROR.

      *

      * @param source    An array of objects to be formatted.

      * @param count     The number of elements of 'source'.

      * @param appendTo  Output parameter to receive result.

      *                  Result is appended to existing contents.

      * @param ignore    Not used; inherited from base class API.

      * @param status    Input/output error code.  If the

      *                  pattern cannot be parsed, set to failure code.

      * @return          Reference to 'appendTo' parameter.

      * @stable ICU 2.0

      */

     UnicodeString& format(const Formattable* source,

                           int32_t count,

                           UnicodeString& appendTo,

                           FieldPosition& ignore,

                           UErrorCode& status) const;

     /**

      * Formats the given array of arguments into a user-readable string

      * using the given pattern.

      *

      * <p>If this format uses named arguments, appendTo is unchanged and

      * status is set to U_ILLEGAL_ARGUMENT_ERROR.

      *

      * @param pattern   The pattern.

      * @param arguments An array of objects to be formatted.

      * @param count     The number of elements of 'source'.

      * @param appendTo  Output parameter to receive result.

      *                  Result is appended to existing contents.

      * @param status    Input/output error code.  If the

      *                  pattern cannot be parsed, set to failure code.

      * @return          Reference to 'appendTo' parameter.

      * @stable ICU 2.0

      */

     static UnicodeString& format(const UnicodeString& pattern,

                                  const Formattable* arguments,

                                  int32_t count,

                                  UnicodeString& appendTo,

                                  UErrorCode& status);

     /**

      * Formats the given array of arguments into a user-readable

      * string.  The array must be stored within a single Formattable

      * object of type kArray. If the Formattable object type is not of

      * type kArray, then returns a failing UErrorCode.

      *

      * <p>If this format uses named arguments, appendTo is unchanged and

      * status is set to U_ILLEGAL_ARGUMENT_ERROR.

      *

      * @param obj       A Formattable of type kArray containing

      *                  arguments to be formatted.

      * @param appendTo  Output parameter to receive result.

      *                  Result is appended to existing contents.

      * @param pos       On input: an alignment field, if desired.

      *                  On output: the offsets of the alignment field.

      * @param status    Input/output error code.  If the

      *                  pattern cannot be parsed, set to failure code.

      * @return          Reference to 'appendTo' parameter.

      * @stable ICU 2.0

      */

     virtual UnicodeString& format(const Formattable& obj,

                                   UnicodeString& appendTo,

                                   FieldPosition& pos,

                                   UErrorCode& status) const;

     /**

      * Formats the given array of arguments into a user-defined argument name

      * array. This function supports both named and numbered

      * arguments-- if numbered, the formatName is the

      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).

      *

      * @param argumentNames argument name array

      * @param arguments An array of objects to be formatted.

      * @param count     The number of elements of 'argumentNames' and

      *                  arguments.  The number of argumentNames and arguments

      *                  must be the same.

      * @param appendTo  Output parameter to receive result.

      *                  Result is appended to existing contents.

      * @param status    Input/output error code.  If the

      *                  pattern cannot be parsed, set to failure code.

      * @return          Reference to 'appendTo' parameter.

      * @stable ICU 4.0

      */

     UnicodeString& format(const UnicodeString* argumentNames,

                           const Formattable* arguments,

                           int32_t count,

                           UnicodeString& appendTo,

                           UErrorCode& status) const;

     /**

      * Parses the given string into an array of output arguments.

      *

      * @param source    String to be parsed.

      * @param pos       On input, starting position for parse. On output,

      *                  final position after parse.  Unchanged if parse

      *                  fails.

      * @param count     Output parameter to receive the number of arguments

      *                  parsed.

      * @return an array of parsed arguments.  The caller owns both

      * the array and its contents.

      * @stable ICU 2.0

      */

     virtual Formattable* parse(const UnicodeString& source,

                                ParsePosition& pos,

                                int32_t& count) const;

     /**

      * Parses the given string into an array of output arguments.

      *

      * <p>If this format uses named arguments, status is set to

      * U_ARGUMENT_TYPE_MISMATCH.

      *

      * @param source    String to be parsed.

      * @param count     Output param to receive size of returned array.

      * @param status    Input/output error code.  If the

      *                  pattern cannot be parsed, set to failure code.

      * @return an array of parsed arguments.  The caller owns both

      * the array and its contents. Returns NULL if status is not U_ZERO_ERROR.

      *

      * @stable ICU 2.0

      */

     virtual Formattable* parse(const UnicodeString& source,

                                int32_t& count,

                                UErrorCode& status) const;

     /**

      * Parses the given string into an array of output arguments

      * stored within a single Formattable of type kArray.

      *

      * @param source    The string to be parsed into an object.

      * @param result    Formattable to be set to the parse result.

      *                  If parse fails, return contents are undefined.

      * @param pos       On input, starting position for parse. On output,

      *                  final position after parse.  Unchanged if parse

      *                  fails.

      * @stable ICU 2.0

      */

     virtual void parseObject(const UnicodeString& source,

                              Formattable& result,

                              ParsePosition& pos) const;

     /**

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

      *

      * <p><b>Note</b> 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 status    Input/output error code.  If the pattern

      *                  cannot be parsed, the failure code is set.

      * @return the standard equivalent of the original pattern

      * @stable ICU 3.4

      */

     static UnicodeString autoQuoteApostrophe(const UnicodeString& pattern,

         UErrorCode& status);

     /**

      * Returns true if this MessageFormat uses named arguments,

      * and false otherwise.  See class description.

      *

      * @return true if named arguments are used.

      * @stable ICU 4.0

      */

     UBool usesNamedArguments() const;

 #ifndef U_HIDE_INTERNAL_API

     /**

      * This API is for ICU internal use only.

      * Please do not use it.

      *

      * Returns argument types count in the parsed pattern.

      * Used to distinguish pattern "{0} d" and "d".

      *

      * @return           The number of formattable types in the pattern

      * @internal

      */

     int32_t getArgTypeCount() const;

 #endif  /* U_HIDE_INTERNAL_API */

     /**

      * Returns a unique class ID POLYMORPHICALLY.  Pure virtual override.

      * This method is to implement a simple version of RTTI, since not all

      * C++ compilers support genuine RTTI.  Polymorphic operator==() and

      * clone() methods call this method.

      *

      * @return          The class ID for this object. All objects of a

      *                  given class have the same class ID.  Objects of

      *                  other classes have different class IDs.

      * @stable ICU 2.0

      */

     virtual UClassID getDynamicClassID(void) const;

     /**

      * Return the class ID for this class.  This is useful only for

      * comparing to a return value from getDynamicClassID().  For example:

      * <pre>

      * .   Base* polymorphic_pointer = createPolymorphicObject();

      * .   if (polymorphic_pointer->getDynamicClassID() ==

      * .      Derived::getStaticClassID()) ...

      * </pre>

      * @return          The class ID for all objects of this class.

      * @stable ICU 2.0

      */

     static UClassID U_EXPORT2 getStaticClassID(void);

 #ifndef U_HIDE_INTERNAL_API

     /**

      * Compares two Format objects. This is used for constructing the hash

      * tables.

      *

      * @param left pointer to a Format object. Must not be NULL.

      * @param right pointer to a Format object. Must not be NULL.

      *

      * @return whether the two objects are the same

      * @internal

      */

     static UBool equalFormats(const void* left, const void* right);

 #endif  /* U_HIDE_INTERNAL_API */

 private:

     Locale              fLocale;

     MessagePattern      msgPattern;

     Format**            formatAliases; // see getFormats

     int32_t             formatAliasesCapacity;

     MessageFormat(); // default constructor not implemented

      /**

       * This provider helps defer instantiation of a PluralRules object

       * until we actually need to select a keyword.

       * For example, if the number matches an explicit-value selector like "=1"

       * we do not need any PluralRules.

       */

     class U_I18N_API PluralSelectorProvider : public PluralFormat::PluralSelector {

     public:

         PluralSelectorProvider(const MessageFormat &mf, UPluralType type);

         virtual ~PluralSelectorProvider();

         virtual UnicodeString select(void *ctx, double number, UErrorCode& ec) const;

         void reset();

     private:

         const MessageFormat &msgFormat;

         PluralRules* rules;

         UPluralType type;

     };

     /**

      * A MessageFormat formats an array of arguments.  Each argument

      * has an expected type, based on the pattern.  For example, if

      * the pattern contains the subformat "{3,number,integer}", then

      * we expect argument 3 to have type Formattable::kLong.  This

      * array needs to grow dynamically if the MessageFormat is

      * modified.

      */

     Formattable::Type* argTypes;

     int32_t            argTypeCount;

     int32_t            argTypeCapacity;

     /**

      * TRUE if there are different argTypes for the same argument.

      * This only matters when the MessageFormat is used in the plain C (umsg_xxx) API

      * where the pattern argTypes determine how the va_arg list is read.

      */

     UBool hasArgTypeConflicts;

     // Variable-size array management

     UBool allocateArgTypes(int32_t capacity, UErrorCode& status);

     /**

      * Default Format objects used when no format is specified and a

      * numeric or date argument is formatted.  These are volatile

      * cache objects maintained only for performance.  They do not

      * participate in operator=(), copy constructor(), nor

      * operator==().

      */

     NumberFormat* defaultNumberFormat;

     DateFormat*   defaultDateFormat;

     UHashtable* cachedFormatters;

     UHashtable* customFormatArgStarts;

     PluralSelectorProvider pluralProvider;

     PluralSelectorProvider ordinalProvider;

     /**

      * Method to retrieve default formats (or NULL on failure).

      * These are semantically const, but may modify *this.

      */

     const NumberFormat* getDefaultNumberFormat(UErrorCode&) const;

     const DateFormat*   getDefaultDateFormat(UErrorCode&) const;

     /**

      * Finds the word s, in the keyword list and returns the located index.

      * @param s the keyword to be searched for.

      * @param list the list of keywords to be searched with.

      * @return the index of the list which matches the keyword s.

      */

     static int32_t findKeyword( const UnicodeString& s,

                                 const UChar * const *list);

     /**

      * Thin wrapper around the format(... AppendableWrapper ...) variant.

      * Wraps the destination UnicodeString into an AppendableWrapper and

      * supplies default values for some other parameters.

      */

     UnicodeString& format(const Formattable* arguments,

                           const UnicodeString *argumentNames,

                           int32_t cnt,

                           UnicodeString& appendTo,

                           FieldPosition* pos,

                           UErrorCode& status) const;

     /**

      * Formats the arguments and writes the result into the

      * AppendableWrapper, updates the field position.

      *

      * @param msgStart      Index to msgPattern part to start formatting from.

      * @param plNumber      NULL except when formatting a plural argument sub-message

      *                      where a '#' is replaced by the format string for this number.

      * @param arguments     The formattable objects array. (Must not be NULL.)

      * @param argumentNames NULL if numbered values are used. Otherwise the same

      *                      length as "arguments", and each entry is the name of the

      *                      corresponding argument in "arguments".

      * @param cnt           The length of arguments (and of argumentNames if that is not NULL).

      * @param appendTo      Output parameter to receive the result.

      *                      The result string is appended to existing contents.

      * @param pos           Field position status.

      * @param success       The error code status.

      */

     void format(int32_t msgStart,

                 const void *plNumber,

                 const Formattable* arguments,

                 const UnicodeString *argumentNames,

                 int32_t cnt,

                 AppendableWrapper& appendTo,

                 FieldPosition* pos,

                 UErrorCode& success) const;

     UnicodeString getArgName(int32_t partIndex);

     void setArgStartFormat(int32_t argStart, Format* formatter, UErrorCode& status);

     void setCustomArgStartFormat(int32_t argStart, Format* formatter, UErrorCode& status);

     int32_t nextTopLevelArgStart(int32_t partIndex) const;

     UBool argNameMatches(int32_t partIndex, const UnicodeString& argName, int32_t argNumber);

     void cacheExplicitFormats(UErrorCode& status);

     Format* createAppropriateFormat(UnicodeString& type,

                                     UnicodeString& style,

                                     Formattable::Type& formattableType,

                                     UParseError& parseError,

                                     UErrorCode& ec);

     const Formattable* getArgFromListByName(const Formattable* arguments,

                                             const UnicodeString *argumentNames,

                                             int32_t cnt, UnicodeString& name) const;

     Formattable* parse(int32_t msgStart,

                        const UnicodeString& source,

                        ParsePosition& pos,

                        int32_t& count,

                        UErrorCode& ec) const;

     FieldPosition* updateMetaData(AppendableWrapper& dest, int32_t prevLength,

                                   FieldPosition* fp, const Formattable* argId) const;

     /**

      * Finds the "other" sub-message.

      * @param partIndex the index of the first PluralFormat argument style part.

      * @return the "other" sub-message start part index.

      */

     int32_t findOtherSubMessage(int32_t partIndex) const;

     /**

      * Returns the ARG_START index of the first occurrence of the plural number in a sub-message.

      * Returns -1 if it is a REPLACE_NUMBER.

      * Returns 0 if there is neither.

      */

     int32_t findFirstPluralNumberArg(int32_t msgStart, const UnicodeString &argName) const;

     Format* getCachedFormatter(int32_t argumentNumber) const;

     UnicodeString getLiteralStringUntilNextArgument(int32_t from) const;

     void copyObjects(const MessageFormat& that, UErrorCode& ec);

     void formatComplexSubMessage(int32_t msgStart,

                                  const void *plNumber,

                                  const Formattable* arguments,

                                  const UnicodeString *argumentNames,

                                  int32_t cnt,

                                  AppendableWrapper& appendTo,

                                  UErrorCode& success) const;

     /**

      * Convenience method that ought to be in NumberFormat

      */

     NumberFormat* createIntegerFormat(const Locale& locale, UErrorCode& status) const;

     /**

      * Returns array of argument types in the parsed pattern

      * for use in C API.  Only for the use of umsg_vformat().  Not

      * for public consumption.

      * @param listCount  Output parameter to receive the size of array

      * @return           The array of formattable types in the pattern

      */

     const Formattable::Type* getArgTypeList(int32_t& listCount) const {

         listCount = argTypeCount;

         return argTypes;

     }

     /**

      * Resets the internal MessagePattern, and other associated caches.

      */

     void resetPattern();

     /**

      * A DummyFormatter that we use solely to store a NULL value. UHash does

      * not support storing NULL values.

      */

     class U_I18N_API DummyFormat : public Format {

     public:

         virtual UBool operator==(const Format&) const;

         virtual Format* clone() const;

         virtual UnicodeString& format(const Formattable& obj,

                               UnicodeString& appendTo,

                               UErrorCode& status) const;

         virtual UnicodeString& format(const Formattable&,

                                       UnicodeString& appendTo,

                                       FieldPosition&,

                                       UErrorCode& status) const;

         virtual UnicodeString& format(const Formattable& obj,

                                       UnicodeString& appendTo,

                                       FieldPositionIterator* posIter,

                                       UErrorCode& status) const;

         virtual void parseObject(const UnicodeString&,

                                  Formattable&,

                                  ParsePosition&) const;

     };

     friend class MessageFormatAdapter; // getFormatTypeList() access

 };

 U_NAMESPACE_END

 #endif /* #if !UCONFIG_NO_FORMATTING */

 #endif // _MSGFMT

 //eof