1096 lines
43 KiB
C++
1096 lines
43 KiB
C++
// © 2016 and later: Unicode, Inc. and others.
|
|
// License & terms of use: http://www.unicode.org/copyright.html
|
|
/*
|
|
* 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/> .setDefaultRuleset(argStyleText, status);</code>
|
|
* <tr>
|
|
* <td><code>ordinal</code>
|
|
* <td><i>argStyleText (optional)</i>
|
|
* <td><code>new RuleBasedNumberFormat(URBNF_ORDINAL, getLocale(), status)
|
|
* <br/> .setDefaultRuleset(argStyleText, status);</code>
|
|
* <tr>
|
|
* <td><code>duration</code>
|
|
* <td><i>argStyleText (optional)</i>
|
|
* <td><code>new RuleBasedNumberFormat(URBNF_DURATION, getLocale(), status)
|
|
* <br/> .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 char16_t * 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
|