MessageFormat prepares strings for display to users, michael@0: * with optional arguments (variables/placeholders). michael@0: * The arguments can occur in any order, which is necessary for translation michael@0: * into languages with different grammars. michael@0: * michael@0: *
A MessageFormat is constructed from a pattern string michael@0: * with arguments in {curly braces} which will be replaced by formatted values. michael@0: * michael@0: *
MessageFormat differs from the other Format
michael@0: * classes in that you create a MessageFormat object with one
michael@0: * of its constructors (not with a createInstance style factory
michael@0: * method). Factory methods aren't necessary because MessageFormat
michael@0: * itself doesn't implement locale-specific behavior. Any locale-specific
michael@0: * behavior is defined by the pattern that you provide and the
michael@0: * subformats used for inserted arguments.
michael@0: *
michael@0: *
Arguments can be named (using identifiers) or numbered (using small ASCII-digit integers). michael@0: * Some of the API methods work only with argument numbers and throw an exception michael@0: * if the pattern has named arguments (see {@link #usesNamedArguments()}). michael@0: * michael@0: *
An argument might not specify any format type. In this case, michael@0: * a Number value is formatted with a default (for the locale) NumberFormat, michael@0: * a Date value is formatted with a default (for the locale) DateFormat, michael@0: * and for any other value its toString() value is used. michael@0: * michael@0: *
An argument might specify a "simple" type for which the specified michael@0: * Format object is created, cached and used. michael@0: * michael@0: *
An argument might have a "complex" type with nested MessageFormat sub-patterns. michael@0: * During formatting, one of these sub-messages is selected according to the argument value michael@0: * and recursively formatted. michael@0: * michael@0: *
After construction, a custom Format object can be set for michael@0: * a top-level argument, overriding the default formatting and parsing behavior michael@0: * for that argument. michael@0: * However, custom formatting can be achieved more simply by writing michael@0: * a typeless argument in the pattern string michael@0: * and supplying it with a preformatted string value. michael@0: * michael@0: *
When formatting, MessageFormat takes a collection of argument values michael@0: * and writes an output string. michael@0: * The argument values may be passed as an array michael@0: * (when the pattern contains only numbered arguments) michael@0: * or as an array of names and and an array of arguments (which works for both named michael@0: * and numbered arguments). michael@0: * michael@0: *
Each argument is matched with one of the input values by array index or argument name michael@0: * and formatted according to its pattern specification michael@0: * (or using a custom Format object if one was set). michael@0: * A numbered pattern argument is matched with an argument name that contains that number michael@0: * as an ASCII-decimal-digit string (without leading zero). michael@0: * michael@0: *
MessageFormat uses patterns of the following form:
michael@0: *
michael@0: * message = messageText (argument messageText)*
michael@0: * argument = noneArg | simpleArg | complexArg
michael@0: * complexArg = choiceArg | pluralArg | selectArg | selectordinalArg
michael@0: *
michael@0: * noneArg = '{' argNameOrNumber '}'
michael@0: * simpleArg = '{' argNameOrNumber ',' argType [',' argStyle] '}'
michael@0: * choiceArg = '{' argNameOrNumber ',' "choice" ',' choiceStyle '}'
michael@0: * pluralArg = '{' argNameOrNumber ',' "plural" ',' pluralStyle '}'
michael@0: * selectArg = '{' argNameOrNumber ',' "select" ',' selectStyle '}'
michael@0: * selectordinalArg = '{' argNameOrNumber ',' "selectordinal" ',' pluralStyle '}'
michael@0: *
michael@0: * choiceStyle: see {@link ChoiceFormat}
michael@0: * pluralStyle: see {@link PluralFormat}
michael@0: * selectStyle: see {@link SelectFormat}
michael@0: *
michael@0: * argNameOrNumber = argName | argNumber
michael@0: * argName = [^[[:Pattern_Syntax:][:Pattern_White_Space:]]]+
michael@0: * argNumber = '0' | ('1'..'9' ('0'..'9')*)
michael@0: *
michael@0: * argType = "number" | "date" | "time" | "spellout" | "ordinal" | "duration"
michael@0: * argStyle = "short" | "medium" | "long" | "full" | "integer" | "currency" | "percent" | argStyleText
michael@0: *
michael@0: *
michael@0: * Recommendation: Use the real apostrophe (single quote) character michael@0: * \htmlonly’\endhtmlonly (U+2019) for michael@0: * human-readable text, and use the ASCII apostrophe ' (U+0027) michael@0: * only in program syntax, like quoting in MessageFormat. michael@0: * See the annotations for U+0027 Apostrophe in The Unicode Standard. michael@0: * michael@0: *
The choice argument type is deprecated.
michael@0: * Use plural arguments for proper plural selection,
michael@0: * and select arguments for simple selection among a fixed set of choices.
michael@0: *
michael@0: *
The argType and argStyle values are used to create
michael@0: * a Format instance for the format element. The following
michael@0: * table shows how the values map to Format instances. Combinations not
michael@0: * shown in the table are illegal. Any argStyleText must
michael@0: * be a valid pattern string for the Format subclass used.
michael@0: *
michael@0: *
| argType michael@0: * | argStyle michael@0: * | resulting Format object michael@0: * | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| (none) michael@0: * | null
michael@0: * | ||||||||||||||||||||||
number
michael@0: * | (none) michael@0: * | NumberFormat.createInstance(getLocale(), status)
michael@0: * | |||||||||||||||||||||
integer
michael@0: * | NumberFormat.createInstance(getLocale(), kNumberStyle, status)
michael@0: * | ||||||||||||||||||||||
currency
michael@0: * | NumberFormat.createCurrencyInstance(getLocale(), status)
michael@0: * | ||||||||||||||||||||||
percent
michael@0: * | NumberFormat.createPercentInstance(getLocale(), status)
michael@0: * | ||||||||||||||||||||||
| argStyleText michael@0: * | new DecimalFormat(argStyleText, new DecimalFormatSymbols(getLocale(), status), status)
michael@0: * | ||||||||||||||||||||||
date
michael@0: * | (none) michael@0: * | DateFormat.createDateInstance(kDefault, getLocale(), status)
michael@0: * | |||||||||||||||||||||
short
michael@0: * | DateFormat.createDateInstance(kShort, getLocale(), status)
michael@0: * | ||||||||||||||||||||||
medium
michael@0: * | DateFormat.createDateInstance(kDefault, getLocale(), status)
michael@0: * | ||||||||||||||||||||||
long
michael@0: * | DateFormat.createDateInstance(kLong, getLocale(), status)
michael@0: * | ||||||||||||||||||||||
full
michael@0: * | DateFormat.createDateInstance(kFull, getLocale(), status)
michael@0: * | ||||||||||||||||||||||
| argStyleText michael@0: * | new SimpleDateFormat(argStyleText, getLocale(), status)
michael@0: * | ||||||||||||||||||||||
michael@0: * michael@0: *
Here are some examples of usage: michael@0: * Example 1: michael@0: * michael@0: *
michael@0: * \code
michael@0: * UErrorCode success = U_ZERO_ERROR;
michael@0: * GregorianCalendar cal(success);
michael@0: * Formattable arguments[] = {
michael@0: * 7L,
michael@0: * Formattable( (Date) cal.getTime(success), Formattable::kIsDate),
michael@0: * "a disturbance in the Force"
michael@0: * };
michael@0: *
michael@0: * UnicodeString result;
michael@0: * MessageFormat::format(
michael@0: * "At {1,time} on {1,date}, there was {2} on planet {0,number}.",
michael@0: * arguments, 3, result, success );
michael@0: *
michael@0: * cout << "result: " << result << endl;
michael@0: * //
michael@0: *
michael@0: * Typically, the message format will come from resources, and the
michael@0: * arguments will be dynamically set at runtime.
michael@0: *
michael@0: * Example 2: michael@0: * michael@0: *
michael@0: * \code
michael@0: * success = U_ZERO_ERROR;
michael@0: * Formattable testArgs[] = {3L, "MyDisk"};
michael@0: *
michael@0: * MessageFormat form(
michael@0: * "The disk \"{1}\" contains {0} file(s).", success );
michael@0: *
michael@0: * UnicodeString string;
michael@0: * FieldPosition fpos = 0;
michael@0: * cout << "format: " << form.format(testArgs, 2, string, fpos, success ) << endl;
michael@0: *
michael@0: * // output, with different testArgs:
michael@0: * // output: The disk "MyDisk" contains 0 file(s).
michael@0: * // output: The disk "MyDisk" contains 1 file(s).
michael@0: * // output: The disk "MyDisk" contains 1,273 file(s).
michael@0: * \endcode
michael@0: *
michael@0: *
michael@0: *
michael@0: * For messages that include plural forms, you can use a plural argument: michael@0: *
michael@0: * \code
michael@0: * success = U_ZERO_ERROR;
michael@0: * MessageFormat msgFmt(
michael@0: * "{num_files, plural, "
michael@0: * "=0{There are no files on disk \"{disk_name}\".}"
michael@0: * "=1{There is one file on disk \"{disk_name}\".}"
michael@0: * "other{There are # files on disk \"{disk_name}\".}}",
michael@0: * Locale("en"),
michael@0: * success);
michael@0: * FieldPosition fpos = 0;
michael@0: * Formattable testArgs[] = {0L, "MyDisk"};
michael@0: * UnicodeString testArgsNames[] = {"num_files", "disk_name"};
michael@0: * UnicodeString result;
michael@0: * cout << msgFmt.format(testArgs, testArgsNames, 2, result, fpos, 0, success);
michael@0: * testArgs[0] = 3L;
michael@0: * cout << msgFmt.format(testArgs, testArgsNames, 2, result, fpos, 0, success);
michael@0: * \endcode
michael@0: * output:
michael@0: * There are no files on disk "MyDisk".
michael@0: * There are 3 files on "MyDisk".
michael@0: *
michael@0: * See {@link PluralFormat} and {@link PluralRules} for details.
michael@0: *
michael@0: * MessageFormats are not synchronized. michael@0: * It is recommended to create separate format instances for each thread. michael@0: * If multiple threads access a format concurrently, it must be synchronized michael@0: * externally. michael@0: * michael@0: * @stable ICU 2.0 michael@0: */ michael@0: class U_I18N_API MessageFormat : public Format { michael@0: public: michael@0: #ifndef U_HIDE_OBSOLETE_API michael@0: /** michael@0: * Enum type for kMaxFormat. michael@0: * @obsolete ICU 3.0. The 10-argument limit was removed as of ICU 2.6, michael@0: * rendering this enum type obsolete. michael@0: */ michael@0: enum EFormatNumber { michael@0: /** michael@0: * The maximum number of arguments. michael@0: * @obsolete ICU 3.0. The 10-argument limit was removed as of ICU 2.6, michael@0: * rendering this constant obsolete. michael@0: */ michael@0: kMaxFormat = 10 michael@0: }; michael@0: #endif /* U_HIDE_OBSOLETE_API */ michael@0: michael@0: /** michael@0: * Constructs a new MessageFormat using the given pattern and the michael@0: * default locale. michael@0: * michael@0: * @param pattern Pattern used to construct object. michael@0: * @param status Input/output error code. If the michael@0: * pattern cannot be parsed, set to failure code. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: MessageFormat(const UnicodeString& pattern, michael@0: UErrorCode &status); michael@0: michael@0: /** michael@0: * Constructs a new MessageFormat using the given pattern and locale. michael@0: * @param pattern Pattern used to construct object. michael@0: * @param newLocale The locale to use for formatting dates and numbers. michael@0: * @param status Input/output error code. If the michael@0: * pattern cannot be parsed, set to failure code. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: MessageFormat(const UnicodeString& pattern, michael@0: const Locale& newLocale, michael@0: UErrorCode& status); michael@0: /** michael@0: * Constructs a new MessageFormat using the given pattern and locale. michael@0: * @param pattern Pattern used to construct object. michael@0: * @param newLocale The locale to use for formatting dates and numbers. michael@0: * @param parseError Struct to receive information on the position michael@0: * of an error within the pattern. michael@0: * @param status Input/output error code. If the michael@0: * pattern cannot be parsed, set to failure code. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: MessageFormat(const UnicodeString& pattern, michael@0: const Locale& newLocale, michael@0: UParseError& parseError, michael@0: UErrorCode& status); michael@0: /** michael@0: * Constructs a new MessageFormat from an existing one. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: MessageFormat(const MessageFormat&); michael@0: michael@0: /** michael@0: * Assignment operator. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: const MessageFormat& operator=(const MessageFormat&); michael@0: michael@0: /** michael@0: * Destructor. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual ~MessageFormat(); michael@0: michael@0: /** michael@0: * Clones this Format object polymorphically. The caller owns the michael@0: * result and should delete it when done. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual Format* clone(void) const; michael@0: michael@0: /** michael@0: * Returns true if the given Format objects are semantically equal. michael@0: * Objects of different subclasses are considered unequal. michael@0: * @param other the object to be compared with. michael@0: * @return true if the given Format objects are semantically equal. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UBool operator==(const Format& other) const; michael@0: michael@0: /** michael@0: * Sets the locale to be used for creating argument Format objects. michael@0: * @param theLocale the new locale value to be set. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setLocale(const Locale& theLocale); michael@0: michael@0: /** michael@0: * Gets the locale used for creating argument Format objects. michael@0: * format information. michael@0: * @return the locale of the object. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual const Locale& getLocale(void) const; michael@0: michael@0: /** michael@0: * Applies the given pattern string to this message format. michael@0: * michael@0: * @param pattern The pattern to be applied. michael@0: * @param status Input/output error code. If the michael@0: * pattern cannot be parsed, set to failure code. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void applyPattern(const UnicodeString& pattern, michael@0: UErrorCode& status); michael@0: /** michael@0: * Applies the given pattern string to this message format. michael@0: * michael@0: * @param pattern The pattern to be applied. michael@0: * @param parseError Struct to receive information on the position michael@0: * of an error within the pattern. michael@0: * @param status Input/output error code. If the michael@0: * pattern cannot be parsed, set to failure code. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void applyPattern(const UnicodeString& pattern, michael@0: UParseError& parseError, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * Sets the UMessagePatternApostropheMode and the pattern used by this message format. michael@0: * Parses the pattern and caches Format objects for simple argument types. michael@0: * Patterns and their interpretation are specified in the michael@0: * class description. michael@0: *
michael@0: * This method is best used only once on a given object to avoid confusion about the mode, michael@0: * and after constructing the object with an empty pattern string to minimize overhead. michael@0: * michael@0: * @param pattern The pattern to be applied. michael@0: * @param aposMode The new apostrophe mode. michael@0: * @param parseError Struct to receive information on the position michael@0: * of an error within the pattern. michael@0: * Can be NULL. michael@0: * @param status Input/output error code. If the michael@0: * pattern cannot be parsed, set to failure code. michael@0: * @stable ICU 4.8 michael@0: */ michael@0: virtual void applyPattern(const UnicodeString& pattern, michael@0: UMessagePatternApostropheMode aposMode, michael@0: UParseError* parseError, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * @return this instance's UMessagePatternApostropheMode. michael@0: * @stable ICU 4.8 michael@0: */ michael@0: UMessagePatternApostropheMode getApostropheMode() const { michael@0: return msgPattern.getApostropheMode(); michael@0: } michael@0: michael@0: /** michael@0: * Returns a pattern that can be used to recreate this object. michael@0: * michael@0: * @param appendTo Output parameter to receive the pattern. michael@0: * Result is appended to existing contents. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UnicodeString& toPattern(UnicodeString& appendTo) const; michael@0: michael@0: /** michael@0: * Sets subformats. michael@0: * See the class description about format numbering. michael@0: * The caller should not delete the Format objects after this call. michael@0: * The array formatsToAdopt is not itself adopted. Its michael@0: * ownership is retained by the caller. If the call fails because michael@0: * memory cannot be allocated, then the formats will be deleted michael@0: * by this method, and this object will remain unchanged. michael@0: * michael@0: *
If this format uses named arguments, the new formats are discarded michael@0: * and this format remains unchanged. michael@0: * michael@0: * @stable ICU 2.0 michael@0: * @param formatsToAdopt the format to be adopted. michael@0: * @param count the size of the array. michael@0: */ michael@0: virtual void adoptFormats(Format** formatsToAdopt, int32_t count); michael@0: michael@0: /** michael@0: * Sets subformats. michael@0: * See the class description about format numbering. michael@0: * Each item in the array is cloned into the internal array. michael@0: * If the call fails because memory cannot be allocated, then this michael@0: * object will remain unchanged. michael@0: * michael@0: *
If this format uses named arguments, the new formats are discarded michael@0: * and this format remains unchanged. michael@0: * michael@0: * @stable ICU 2.0 michael@0: * @param newFormats the new format to be set. michael@0: * @param cnt the size of the array. michael@0: */ michael@0: virtual void setFormats(const Format** newFormats, int32_t cnt); michael@0: michael@0: michael@0: /** michael@0: * Sets one subformat. michael@0: * See the class description about format numbering. michael@0: * The caller should not delete the Format object after this call. michael@0: * If the number is over the number of formats already set, michael@0: * the item will be deleted and ignored. michael@0: * michael@0: *
If this format uses named arguments, the new format is discarded michael@0: * and this format remains unchanged. michael@0: * michael@0: * @stable ICU 2.0 michael@0: * @param formatNumber index of the subformat. michael@0: * @param formatToAdopt the format to be adopted. michael@0: */ michael@0: virtual void adoptFormat(int32_t formatNumber, Format* formatToAdopt); michael@0: michael@0: /** michael@0: * Sets one subformat. michael@0: * See the class description about format numbering. michael@0: * If the number is over the number of formats already set, michael@0: * the item will be ignored. michael@0: * @param formatNumber index of the subformat. michael@0: * @param format the format to be set. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setFormat(int32_t formatNumber, const Format& format); michael@0: michael@0: /** michael@0: * Gets format names. This function returns formatNames in StringEnumerations michael@0: * which can be used with getFormat() and setFormat() to export formattable michael@0: * array from current MessageFormat to another. It is the caller's responsibility michael@0: * to delete the returned formatNames. michael@0: * @param status output param set to success/failure code. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: virtual StringEnumeration* getFormatNames(UErrorCode& status); michael@0: michael@0: /** michael@0: * Gets subformat pointer for given format name. michael@0: * This function supports both named and numbered michael@0: * arguments. If numbered, the formatName is the michael@0: * corresponding UnicodeStrings (e.g. "0", "1", "2"...). michael@0: * The returned Format object should not be deleted by the caller, michael@0: * nor should the ponter of other object . The pointer and its michael@0: * contents remain valid only until the next call to any method michael@0: * of this class is made with this object. michael@0: * @param formatName the name or number specifying a format michael@0: * @param status output param set to success/failure code. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: virtual Format* getFormat(const UnicodeString& formatName, UErrorCode& status); michael@0: michael@0: /** michael@0: * Sets one subformat for given format name. michael@0: * See the class description about format name. michael@0: * This function supports both named and numbered michael@0: * arguments-- if numbered, the formatName is the michael@0: * corresponding UnicodeStrings (e.g. "0", "1", "2"...). michael@0: * If there is no matched formatName or wrong type, michael@0: * the item will be ignored. michael@0: * @param formatName Name of the subformat. michael@0: * @param format the format to be set. michael@0: * @param status output param set to success/failure code. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: virtual void setFormat(const UnicodeString& formatName, const Format& format, UErrorCode& status); michael@0: michael@0: /** michael@0: * Sets one subformat for given format name. michael@0: * See the class description about format name. michael@0: * This function supports both named and numbered michael@0: * arguments-- if numbered, the formatName is the michael@0: * corresponding UnicodeStrings (e.g. "0", "1", "2"...). michael@0: * If there is no matched formatName or wrong type, michael@0: * the item will be ignored. michael@0: * The caller should not delete the Format object after this call. michael@0: * @param formatName Name of the subformat. michael@0: * @param formatToAdopt Format to be adopted. michael@0: * @param status output param set to success/failure code. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: virtual void adoptFormat(const UnicodeString& formatName, Format* formatToAdopt, UErrorCode& status); michael@0: michael@0: /** michael@0: * Gets an array of subformats of this object. The returned array michael@0: * should not be deleted by the caller, nor should the pointers michael@0: * within the array. The array and its contents remain valid only michael@0: * until the next call to this format. See the class description michael@0: * about format numbering. michael@0: * michael@0: * @param count output parameter to receive the size of the array michael@0: * @return an array of count Format* objects, or NULL if out of michael@0: * memory. Any or all of the array elements may be NULL. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual const Format** getFormats(int32_t& count) const; michael@0: michael@0: michael@0: using Format::format; michael@0: michael@0: /** michael@0: * Formats the given array of arguments into a user-readable string. michael@0: * Does not take ownership of the Formattable* array or its contents. michael@0: * michael@0: *
If this format uses named arguments, appendTo is unchanged and michael@0: * status is set to U_ILLEGAL_ARGUMENT_ERROR. michael@0: * michael@0: * @param source An array of objects to be formatted. michael@0: * @param count The number of elements of 'source'. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param ignore Not used; inherited from base class API. michael@0: * @param status Input/output error code. If the michael@0: * pattern cannot be parsed, set to failure code. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& format(const Formattable* source, michael@0: int32_t count, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& ignore, michael@0: UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Formats the given array of arguments into a user-readable string michael@0: * using the given pattern. michael@0: * michael@0: *
If this format uses named arguments, appendTo is unchanged and michael@0: * status is set to U_ILLEGAL_ARGUMENT_ERROR. michael@0: * michael@0: * @param pattern The pattern. michael@0: * @param arguments An array of objects to be formatted. michael@0: * @param count The number of elements of 'source'. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param status Input/output error code. If the michael@0: * pattern cannot be parsed, set to failure code. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: static UnicodeString& format(const UnicodeString& pattern, michael@0: const Formattable* arguments, michael@0: int32_t count, michael@0: UnicodeString& appendTo, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * Formats the given array of arguments into a user-readable michael@0: * string. The array must be stored within a single Formattable michael@0: * object of type kArray. If the Formattable object type is not of michael@0: * type kArray, then returns a failing UErrorCode. michael@0: * michael@0: *
If this format uses named arguments, appendTo is unchanged and michael@0: * status is set to U_ILLEGAL_ARGUMENT_ERROR. michael@0: * michael@0: * @param obj A Formattable of type kArray containing michael@0: * arguments to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @param status Input/output error code. If the michael@0: * pattern cannot be parsed, set to failure code. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UnicodeString& format(const Formattable& obj, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos, michael@0: UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Formats the given array of arguments into a user-defined argument name michael@0: * array. This function supports both named and numbered michael@0: * arguments-- if numbered, the formatName is the michael@0: * corresponding UnicodeStrings (e.g. "0", "1", "2"...). michael@0: * michael@0: * @param argumentNames argument name array michael@0: * @param arguments An array of objects to be formatted. michael@0: * @param count The number of elements of 'argumentNames' and michael@0: * arguments. The number of argumentNames and arguments michael@0: * must be the same. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param status Input/output error code. If the michael@0: * pattern cannot be parsed, set to failure code. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: UnicodeString& format(const UnicodeString* argumentNames, michael@0: const Formattable* arguments, michael@0: int32_t count, michael@0: UnicodeString& appendTo, michael@0: UErrorCode& status) const; michael@0: /** michael@0: * Parses the given string into an array of output arguments. michael@0: * michael@0: * @param source String to be parsed. michael@0: * @param pos On input, starting position for parse. On output, michael@0: * final position after parse. Unchanged if parse michael@0: * fails. michael@0: * @param count Output parameter to receive the number of arguments michael@0: * parsed. michael@0: * @return an array of parsed arguments. The caller owns both michael@0: * the array and its contents. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual Formattable* parse(const UnicodeString& source, michael@0: ParsePosition& pos, michael@0: int32_t& count) const; michael@0: michael@0: /** michael@0: * Parses the given string into an array of output arguments. michael@0: * michael@0: *
If this format uses named arguments, status is set to michael@0: * U_ARGUMENT_TYPE_MISMATCH. michael@0: * michael@0: * @param source String to be parsed. michael@0: * @param count Output param to receive size of returned array. michael@0: * @param status Input/output error code. If the michael@0: * pattern cannot be parsed, set to failure code. michael@0: * @return an array of parsed arguments. The caller owns both michael@0: * the array and its contents. Returns NULL if status is not U_ZERO_ERROR. michael@0: * michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual Formattable* parse(const UnicodeString& source, michael@0: int32_t& count, michael@0: UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Parses the given string into an array of output arguments michael@0: * stored within a single Formattable of type kArray. michael@0: * michael@0: * @param source The string to be parsed into an object. michael@0: * @param result Formattable to be set to the parse result. michael@0: * If parse fails, return contents are undefined. michael@0: * @param pos On input, starting position for parse. On output, michael@0: * final position after parse. Unchanged if parse michael@0: * fails. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void parseObject(const UnicodeString& source, michael@0: Formattable& result, michael@0: ParsePosition& pos) const; michael@0: michael@0: /** michael@0: * Convert an 'apostrophe-friendly' pattern into a standard michael@0: * pattern. Standard patterns treat all apostrophes as michael@0: * quotes, which is problematic in some languages, e.g. michael@0: * French, where apostrophe is commonly used. This utility michael@0: * assumes that only an unpaired apostrophe immediately before michael@0: * a brace is a true quote. Other unpaired apostrophes are paired, michael@0: * and the resulting standard pattern string is returned. michael@0: * michael@0: *
Note it is not guaranteed that the returned pattern michael@0: * is indeed a valid pattern. The only effect is to convert michael@0: * between patterns having different quoting semantics. michael@0: * michael@0: * @param pattern the 'apostrophe-friendly' patttern to convert michael@0: * @param status Input/output error code. If the pattern michael@0: * cannot be parsed, the failure code is set. michael@0: * @return the standard equivalent of the original pattern michael@0: * @stable ICU 3.4 michael@0: */ michael@0: static UnicodeString autoQuoteApostrophe(const UnicodeString& pattern, michael@0: UErrorCode& status); michael@0: michael@0: michael@0: /** michael@0: * Returns true if this MessageFormat uses named arguments, michael@0: * and false otherwise. See class description. michael@0: * michael@0: * @return true if named arguments are used. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: UBool usesNamedArguments() const; michael@0: michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * This API is for ICU internal use only. michael@0: * Please do not use it. michael@0: * michael@0: * Returns argument types count in the parsed pattern. michael@0: * Used to distinguish pattern "{0} d" and "d". michael@0: * michael@0: * @return The number of formattable types in the pattern michael@0: * @internal michael@0: */ michael@0: int32_t getArgTypeCount() const; michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: /** michael@0: * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. michael@0: * This method is to implement a simple version of RTTI, since not all michael@0: * C++ compilers support genuine RTTI. Polymorphic operator==() and michael@0: * clone() methods call this method. michael@0: * michael@0: * @return The class ID for this object. All objects of a michael@0: * given class have the same class ID. Objects of michael@0: * other classes have different class IDs. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UClassID getDynamicClassID(void) const; michael@0: michael@0: /** michael@0: * Return the class ID for this class. This is useful only for michael@0: * comparing to a return value from getDynamicClassID(). For example: michael@0: *
michael@0: * . Base* polymorphic_pointer = createPolymorphicObject(); michael@0: * . if (polymorphic_pointer->getDynamicClassID() == michael@0: * . Derived::getStaticClassID()) ... michael@0: *michael@0: * @return The class ID for all objects of this class. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: static UClassID U_EXPORT2 getStaticClassID(void); michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * Compares two Format objects. This is used for constructing the hash michael@0: * tables. michael@0: * michael@0: * @param left pointer to a Format object. Must not be NULL. michael@0: * @param right pointer to a Format object. Must not be NULL. michael@0: * michael@0: * @return whether the two objects are the same michael@0: * @internal michael@0: */ michael@0: static UBool equalFormats(const void* left, const void* right); michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: private: michael@0: michael@0: Locale fLocale; michael@0: MessagePattern msgPattern; michael@0: Format** formatAliases; // see getFormats michael@0: int32_t formatAliasesCapacity; michael@0: michael@0: MessageFormat(); // default constructor not implemented michael@0: michael@0: /** michael@0: * This provider helps defer instantiation of a PluralRules object michael@0: * until we actually need to select a keyword. michael@0: * For example, if the number matches an explicit-value selector like "=1" michael@0: * we do not need any PluralRules. michael@0: */ michael@0: class U_I18N_API PluralSelectorProvider : public PluralFormat::PluralSelector { michael@0: public: michael@0: PluralSelectorProvider(const MessageFormat &mf, UPluralType type); michael@0: virtual ~PluralSelectorProvider(); michael@0: virtual UnicodeString select(void *ctx, double number, UErrorCode& ec) const; michael@0: michael@0: void reset(); michael@0: private: michael@0: const MessageFormat &msgFormat; michael@0: PluralRules* rules; michael@0: UPluralType type; michael@0: }; michael@0: michael@0: /** michael@0: * A MessageFormat formats an array of arguments. Each argument michael@0: * has an expected type, based on the pattern. For example, if michael@0: * the pattern contains the subformat "{3,number,integer}", then michael@0: * we expect argument 3 to have type Formattable::kLong. This michael@0: * array needs to grow dynamically if the MessageFormat is michael@0: * modified. michael@0: */ michael@0: Formattable::Type* argTypes; michael@0: int32_t argTypeCount; michael@0: int32_t argTypeCapacity; michael@0: michael@0: /** michael@0: * TRUE if there are different argTypes for the same argument. michael@0: * This only matters when the MessageFormat is used in the plain C (umsg_xxx) API michael@0: * where the pattern argTypes determine how the va_arg list is read. michael@0: */ michael@0: UBool hasArgTypeConflicts; michael@0: michael@0: // Variable-size array management michael@0: UBool allocateArgTypes(int32_t capacity, UErrorCode& status); michael@0: michael@0: /** michael@0: * Default Format objects used when no format is specified and a michael@0: * numeric or date argument is formatted. These are volatile michael@0: * cache objects maintained only for performance. They do not michael@0: * participate in operator=(), copy constructor(), nor michael@0: * operator==(). michael@0: */ michael@0: NumberFormat* defaultNumberFormat; michael@0: DateFormat* defaultDateFormat; michael@0: michael@0: UHashtable* cachedFormatters; michael@0: UHashtable* customFormatArgStarts; michael@0: michael@0: PluralSelectorProvider pluralProvider; michael@0: PluralSelectorProvider ordinalProvider; michael@0: michael@0: /** michael@0: * Method to retrieve default formats (or NULL on failure). michael@0: * These are semantically const, but may modify *this. michael@0: */ michael@0: const NumberFormat* getDefaultNumberFormat(UErrorCode&) const; michael@0: const DateFormat* getDefaultDateFormat(UErrorCode&) const; michael@0: michael@0: /** michael@0: * Finds the word s, in the keyword list and returns the located index. michael@0: * @param s the keyword to be searched for. michael@0: * @param list the list of keywords to be searched with. michael@0: * @return the index of the list which matches the keyword s. michael@0: */ michael@0: static int32_t findKeyword( const UnicodeString& s, michael@0: const UChar * const *list); michael@0: michael@0: /** michael@0: * Thin wrapper around the format(... AppendableWrapper ...) variant. michael@0: * Wraps the destination UnicodeString into an AppendableWrapper and michael@0: * supplies default values for some other parameters. michael@0: */ michael@0: UnicodeString& format(const Formattable* arguments, michael@0: const UnicodeString *argumentNames, michael@0: int32_t cnt, michael@0: UnicodeString& appendTo, michael@0: FieldPosition* pos, michael@0: UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Formats the arguments and writes the result into the michael@0: * AppendableWrapper, updates the field position. michael@0: * michael@0: * @param msgStart Index to msgPattern part to start formatting from. michael@0: * @param plNumber NULL except when formatting a plural argument sub-message michael@0: * where a '#' is replaced by the format string for this number. michael@0: * @param arguments The formattable objects array. (Must not be NULL.) michael@0: * @param argumentNames NULL if numbered values are used. Otherwise the same michael@0: * length as "arguments", and each entry is the name of the michael@0: * corresponding argument in "arguments". michael@0: * @param cnt The length of arguments (and of argumentNames if that is not NULL). michael@0: * @param appendTo Output parameter to receive the result. michael@0: * The result string is appended to existing contents. michael@0: * @param pos Field position status. michael@0: * @param success The error code status. michael@0: */ michael@0: void format(int32_t msgStart, michael@0: const void *plNumber, michael@0: const Formattable* arguments, michael@0: const UnicodeString *argumentNames, michael@0: int32_t cnt, michael@0: AppendableWrapper& appendTo, michael@0: FieldPosition* pos, michael@0: UErrorCode& success) const; michael@0: michael@0: UnicodeString getArgName(int32_t partIndex); michael@0: michael@0: void setArgStartFormat(int32_t argStart, Format* formatter, UErrorCode& status); michael@0: michael@0: void setCustomArgStartFormat(int32_t argStart, Format* formatter, UErrorCode& status); michael@0: michael@0: int32_t nextTopLevelArgStart(int32_t partIndex) const; michael@0: michael@0: UBool argNameMatches(int32_t partIndex, const UnicodeString& argName, int32_t argNumber); michael@0: michael@0: void cacheExplicitFormats(UErrorCode& status); michael@0: michael@0: Format* createAppropriateFormat(UnicodeString& type, michael@0: UnicodeString& style, michael@0: Formattable::Type& formattableType, michael@0: UParseError& parseError, michael@0: UErrorCode& ec); michael@0: michael@0: const Formattable* getArgFromListByName(const Formattable* arguments, michael@0: const UnicodeString *argumentNames, michael@0: int32_t cnt, UnicodeString& name) const; michael@0: michael@0: Formattable* parse(int32_t msgStart, michael@0: const UnicodeString& source, michael@0: ParsePosition& pos, michael@0: int32_t& count, michael@0: UErrorCode& ec) const; michael@0: michael@0: FieldPosition* updateMetaData(AppendableWrapper& dest, int32_t prevLength, michael@0: FieldPosition* fp, const Formattable* argId) const; michael@0: michael@0: /** michael@0: * Finds the "other" sub-message. michael@0: * @param partIndex the index of the first PluralFormat argument style part. michael@0: * @return the "other" sub-message start part index. michael@0: */ michael@0: int32_t findOtherSubMessage(int32_t partIndex) const; michael@0: michael@0: /** michael@0: * Returns the ARG_START index of the first occurrence of the plural number in a sub-message. michael@0: * Returns -1 if it is a REPLACE_NUMBER. michael@0: * Returns 0 if there is neither. michael@0: */ michael@0: int32_t findFirstPluralNumberArg(int32_t msgStart, const UnicodeString &argName) const; michael@0: michael@0: Format* getCachedFormatter(int32_t argumentNumber) const; michael@0: michael@0: UnicodeString getLiteralStringUntilNextArgument(int32_t from) const; michael@0: michael@0: void copyObjects(const MessageFormat& that, UErrorCode& ec); michael@0: michael@0: void formatComplexSubMessage(int32_t msgStart, michael@0: const void *plNumber, michael@0: const Formattable* arguments, michael@0: const UnicodeString *argumentNames, michael@0: int32_t cnt, michael@0: AppendableWrapper& appendTo, michael@0: UErrorCode& success) const; michael@0: michael@0: /** michael@0: * Convenience method that ought to be in NumberFormat michael@0: */ michael@0: NumberFormat* createIntegerFormat(const Locale& locale, UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Returns array of argument types in the parsed pattern michael@0: * for use in C API. Only for the use of umsg_vformat(). Not michael@0: * for public consumption. michael@0: * @param listCount Output parameter to receive the size of array michael@0: * @return The array of formattable types in the pattern michael@0: */ michael@0: const Formattable::Type* getArgTypeList(int32_t& listCount) const { michael@0: listCount = argTypeCount; michael@0: return argTypes; michael@0: } michael@0: michael@0: /** michael@0: * Resets the internal MessagePattern, and other associated caches. michael@0: */ michael@0: void resetPattern(); michael@0: michael@0: /** michael@0: * A DummyFormatter that we use solely to store a NULL value. UHash does michael@0: * not support storing NULL values. michael@0: */ michael@0: class U_I18N_API DummyFormat : public Format { michael@0: public: michael@0: virtual UBool operator==(const Format&) const; michael@0: virtual Format* clone() const; michael@0: virtual UnicodeString& format(const Formattable& obj, michael@0: UnicodeString& appendTo, michael@0: UErrorCode& status) const; michael@0: virtual UnicodeString& format(const Formattable&, michael@0: UnicodeString& appendTo, michael@0: FieldPosition&, michael@0: UErrorCode& status) const; michael@0: virtual UnicodeString& format(const Formattable& obj, michael@0: UnicodeString& appendTo, michael@0: FieldPositionIterator* posIter, michael@0: UErrorCode& status) const; michael@0: virtual void parseObject(const UnicodeString&, michael@0: Formattable&, michael@0: ParsePosition&) const; michael@0: }; michael@0: michael@0: friend class MessageFormatAdapter; // getFormatTypeList() access michael@0: }; michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif /* #if !UCONFIG_NO_FORMATTING */ michael@0: michael@0: #endif // _MSGFMT michael@0: //eof