PHP  
 PHP: Test and Code Coverage Analysis
downloads | QA | documentation | faq | getting help | mailing lists | reporting bugs | php.net sites | links | my php.net 
 

LCOV - code coverage report
Current view: top level - usr/include/unicode - msgfmt.h (source / functions) Hit Total Coverage
Test: PHP Code Coverage Lines: 3 3 100.0 %
Date: 2014-11-15 Functions: 1 1 100.0 %
Legend: Lines: hit not hit

          Line data    Source code
       1             : /*
       2             : * Copyright (C) 2007-2009, International Business Machines Corporation and others. All Rights Reserved.
       3             : ********************************************************************************
       4             : *
       5             : * File MSGFMT.H
       6             : *
       7             : * Modification History:
       8             : *
       9             : *   Date        Name        Description
      10             : *   02/19/97    aliu        Converted from java.
      11             : *   03/20/97    helena      Finished first cut of implementation.
      12             : *   07/22/98    stephen     Removed operator!= (defined in Format)
      13             : *   08/19/2002  srl         Removing Javaisms
      14             : ********************************************************************************
      15             : */
      16             : 
      17             : #ifndef MSGFMT_H
      18             : #define MSGFMT_H
      19             : 
      20             : #include "unicode/utypes.h"
      21             : 
      22             : /**
      23             :  * \file 
      24             :  * \brief C++ API: Formats messages in a language-neutral way.
      25             :  */
      26             :  
      27             : #if !UCONFIG_NO_FORMATTING
      28             : 
      29             : #include "unicode/format.h"
      30             : #include "unicode/locid.h"
      31             : #include "unicode/parseerr.h"
      32             : #include "unicode/uchar.h"
      33             : 
      34             : U_NAMESPACE_BEGIN
      35             : 
      36             : class NumberFormat;
      37             : class DateFormat;
      38             : 
      39             : /**
      40             :  *
      41             :  * A MessageFormat produces concatenated messages in a
      42             :  * language-neutral way.  It should be used for all string
      43             :  * concatenations that are visible to end users.
      44             :  * <P>
      45             :  * A MessageFormat contains an array of <EM>subformats</EM> arranged
      46             :  * within a <EM>template string</EM>.  Together, the subformats and
      47             :  * template string determine how the MessageFormat will operate during
      48             :  * formatting and parsing.
      49             :  * <P>
      50             :  * Typically, both the subformats and the template string are
      51             :  * specified at once in a <EM>pattern</EM>.  By using different
      52             :  * patterns for different locales, messages may be localized.
      53             :  * <P>
      54             :  * During formatting, the MessageFormat takes an array of arguments
      55             :  * and produces a user-readable string.  Each argument is a
      56             :  * Formattable object; they may be passed in in an array, or as a
      57             :  * single Formattable object which itself contains an array.  Each
      58             :  * argument is matched up with its corresponding subformat, which then
      59             :  * formats it into a string.  The resultant strings are then assembled
      60             :  * within the string template of the MessageFormat to produce the
      61             :  * final output string.
      62             :  * <p>
      63             :  * <strong>Note:</strong>
      64             :  * In ICU 4.0 MessageFormat supports named arguments.  If a named argument
      65             :  * is used, all arguments must be named.  Names start with a character in 
      66             :  * <code>UCHAR_ID_START</code> and continue with characters in 
      67             :  * <code>UCHARID_CONTINUE</code>, in particular they do not start with a digit.
      68             :  * If named arguments are used, {@link #usesNamedArguments()} will return true.
      69             :  * <p>
      70             :  * The other new methods supporting named arguments are 
      71             :  * {@link #getFormatNames(UErrorCode& status)},
      72             :  * {@link #getFormat(const UnicodeString& formatName, UErrorCode& status)}
      73             :  * {@link #setFormat(const UnicodeString& formatName, const Format& format, UErrorCode& status)},
      74             :  * {@link #adoptFormat(const UnicodeString& formatName, Format* formatToAdopt, UErrorCode& status)},
      75             :  * {@link #format(const Formattable* arguments, const UnicodeString *argumentNames, int32_t cnt, UnicodeString& appendTo, FieldPosition& status, int32_t recursionProtection, UErrorCode& success)},
      76             :  * {@link #format(const UnicodeString* argumentNames, const Formattable* arguments, int32_t count, UnicodeString& appendTo,UErrorCode& status)}.
      77             :  * These methods are all compatible with patterns that do not used named arguments-- 
      78             :  * in these cases the keys in the input or output use <code>UnicodeString</code>s 
      79             :  * that name the argument indices, e.g. "0", "1", "2"... etc.
      80             :  * <p>
      81             :  * When named arguments are used, certain methods on MessageFormat that take or
      82             :  * return arrays do not perform any action, since it is not possible to
      83             :  * identify positions in an array using a name.  UErrorCode is set to
      84             :  * U_ARGUMENT_TYPE_MISMATCH if there is a status/success field in the method.
      85             :  * These methods are 
      86             :  * {@link #adoptFormats(Format** formatsToAdopt, int32_t count)},
      87             :  * {@link #setFormats(const Format** newFormats,int32_t count)},
      88             :  * {@link #adoptFormat(int32_t n, Format *newFormat)},
      89             :  * {@link #getFormats(int32_t& count)},
      90             :  * {@link #format(const Formattable* source,int32_t cnt,UnicodeString& appendTo, FieldPosition& ignore, UErrorCode& success)},
      91             :  * {@link #format(const UnicodeString& pattern,const Formattable* arguments,int32_t cnt,UnicodeString& appendTo,UErrorCode& success)},
      92             :  * {@link #format(const Formattable& source, UnicodeString& appendTo,FieldPosition& ignore, UErrorCode& success)},
      93             :  * {@link #format(const Formattable* arguments, int32_t cnt, UnicodeString& appendTo, FieldPosition& status, int32_t recursionProtection,UErrorCode& success)},
      94             :  * {@link #parse(const UnicodeString& source, ParsePosition& pos,int32_t& count)},
      95             :  * {@link #parse(const UnicodeString& source, int32_t& cnt, UErrorCode& status)}
      96             :  * <p>
      97             :  *
      98             :  * <P>
      99             :  * During parsing, an input string is matched against the string
     100             :  * template of the MessageFormat to produce an array of Formattable
     101             :  * objects.  Plain text of the template string is matched directly
     102             :  * against intput text.  At each position in the template string where
     103             :  * a subformat is located, the subformat is called to parse the
     104             :  * corresponding segment of input text to produce an output argument.
     105             :  * In this way, an array of arguments is created which together
     106             :  * constitute the parse result.
     107             :  * <P>
     108             :  * Parsing may fail or produce unexpected results in a number of
     109             :  * circumstances.
     110             :  * <UL>
     111             :  * <LI>If one of the arguments does not occur in the pattern, it
     112             :  * will be returned as a default Formattable.
     113             :  * <LI>If the format of an argument is loses information, such as with
     114             :  * a choice format where a large number formats to "many", then the
     115             :  * parse may not correspond to the originally formatted argument.
     116             :  * <LI>MessageFormat does not handle ChoiceFormat recursion during
     117             :  * parsing; such parses will fail.
     118             :  * <LI>Parsing will not always find a match (or the correct match) if
     119             :  * some part of the parse is ambiguous.  For example, if the pattern
     120             :  * "{1},{2}" is used with the string arguments {"a,b", "c"}, it will
     121             :  * format as "a,b,c".  When the result is parsed, it will return {"a",
     122             :  * "b,c"}.
     123             :  * <LI>If a single argument is formatted more than once in the string,
     124             :  * then the rightmost subformat in the pattern string will produce the
     125             :  * parse result; prior subformats with the same argument index will
     126             :  * have no effect.
     127             :  * </UL>
     128             :  * Here are some examples of usage:
     129             :  * <P>
     130             :  * Example 1:
     131             :  * <pre>
     132             :  * \code
     133             :  *     UErrorCode success = U_ZERO_ERROR;
     134             :  *     GregorianCalendar cal(success);
     135             :  *     Formattable arguments[] = {
     136             :  *         7L,
     137             :  *         Formattable( (Date) cal.getTime(success), Formattable::kIsDate),
     138             :  *         "a disturbance in the Force"
     139             :  *     };
     140             :  *
     141             :  *     UnicodeString result;
     142             :  *     MessageFormat::format(
     143             :  *          "At {1,time} on {1,date}, there was {2} on planet {0,number}.",
     144             :  *          arguments, 3, result, success );
     145             :  *
     146             :  *     cout << "result: " << result << endl;
     147             :  *     //<output>: At 4:34:20 PM on 23-Mar-98, there was a disturbance
     148             :  *     //             in the Force on planet 7.
     149             :  * \endcode
     150             :  * </pre>
     151             :  * Typically, the message format will come from resources, and the
     152             :  * arguments will be dynamically set at runtime.
     153             :  * <P>
     154             :  * Example 2:
     155             :  * <pre>
     156             :  *  \code
     157             :  *     success = U_ZERO_ERROR;
     158             :  *     Formattable testArgs[] = {3L, "MyDisk"};
     159             :  *
     160             :  *     MessageFormat form(
     161             :  *         "The disk \"{1}\" contains {0} file(s).", success );
     162             :  *
     163             :  *     UnicodeString string;
     164             :  *     FieldPosition fpos = 0;
     165             :  *     cout << "format: " << form.format(testArgs, 2, string, fpos, success ) << endl;
     166             :  *
     167             :  *     // output, with different testArgs:
     168             :  *     // output: The disk "MyDisk" contains 0 file(s).
     169             :  *     // output: The disk "MyDisk" contains 1 file(s).
     170             :  *     // output: The disk "MyDisk" contains 1,273 file(s).
     171             :  *  \endcode
     172             :  *  </pre>
     173             :  *
     174             :  *  The pattern is of the following form.  Legend:
     175             :  *  <pre>
     176             :  * \code
     177             :  *       {optional item}
     178             :  *       (group that may be repeated)*
     179             :  * \endcode
     180             :  *  </pre>
     181             :  *  Do not confuse optional items with items inside quotes braces, such
     182             :  *  as this: "{".  Quoted braces are literals.
     183             :  *  <pre>
     184             :  *  \code
     185             :  *       messageFormatPattern := string ( "{" messageFormatElement "}" string )*
     186             :  *
     187             :  *       messageFormatElement := argumentIndex | argumentName { "," elementFormat }
     188             :  *
     189             :  *       elementFormat := "time" { "," datetimeStyle }
     190             :  *                      | "date" { "," datetimeStyle }
     191             :  *                      | "number" { "," numberStyle }
     192             :  *                      | "choice" "," choiceStyle
     193             :  *
     194             :  *       datetimeStyle := "short"
     195             :  *                      | "medium"
     196             :  *                      | "long"
     197             :  *                      | "full"
     198             :  *                      | dateFormatPattern
     199             :  *
     200             :  *       numberStyle :=   "currency"
     201             :  *                      | "percent"
     202             :  *                      | "integer"
     203             :  *                      | numberFormatPattern
     204             :  *
     205             :  *       choiceStyle :=   choiceFormatPattern
     206             :  * 
     207             :  *       pluralStyle := pluralFormatPattern
     208             :  * \endcode
     209             :  * </pre>
     210             :  * If there is no elementFormat, then the argument must be a string,
     211             :  * which is substituted. If there is no dateTimeStyle or numberStyle,
     212             :  * then the default format is used (e.g.  NumberFormat::createInstance(),
     213             :  * DateFormat::createTimeInstance(DateFormat::kDefault, ...) or DateFormat::createDateInstance(DateFormat::kDefault, ...). For
     214             :  * a ChoiceFormat, the pattern must always be specified, since there
     215             :  * is no default.
     216             :  * <P>
     217             :  * In strings, single quotes can be used to quote syntax characters.
     218             :  * A literal single quote is represented by '', both within and outside
     219             :  * of single-quoted segments.  Inside a
     220             :  * messageFormatElement, quotes are <EM>not</EM> removed. For example,
     221             :  * {1,number,$'#',##} will produce a number format with the pound-sign
     222             :  * quoted, with a result such as: "$#31,45".
     223             :  * <P>
     224             :  * If a pattern is used, then unquoted braces in the pattern, if any,
     225             :  * must match: that is, "ab {0} de" and "ab '}' de" are ok, but "ab
     226             :  * {0'}' de" and "ab } de" are not.
     227             :  * <p>
     228             :  * <dl><dt><b>Warning:</b><dd>The rules for using quotes within message
     229             :  * format patterns unfortunately have shown to be somewhat confusing.
     230             :  * In particular, it isn't always obvious to localizers whether single
     231             :  * quotes need to be doubled or not. Make sure to inform localizers about
     232             :  * the rules, and tell them (for example, by using comments in resource
     233             :  * bundle source files) which strings will be processed by MessageFormat.
     234             :  * Note that localizers may need to use single quotes in translated
     235             :  * strings where the original version doesn't have them.
     236             :  * <br>Note also that the simplest way to avoid the problem is to
     237             :  * use the real apostrophe (single quote) character U+2019 (') for
     238             :  * human-readable text, and to use the ASCII apostrophe (U+0027 ' )
     239             :  * only in program syntax, like quoting in MessageFormat.
     240             :  * See the annotations for U+0027 Apostrophe in The Unicode Standard.</p>
     241             :  * </dl>
     242             :  * <P>
     243             :  * The argumentIndex is a non-negative integer, which corresponds to the
     244             :  * index of the arguments presented in an array to be formatted.  The
     245             :  * first argument has argumentIndex 0.
     246             :  * <P>
     247             :  * It is acceptable to have unused arguments in the array.  With missing
     248             :  * arguments or arguments that are not of the right class for the
     249             :  * specified format, a failing UErrorCode result is set.
     250             :  * <P>
     251             :  * For more sophisticated patterns, you can use a ChoiceFormat to get
     252             :  * output:
     253             :  * <pre>
     254             :  * \code
     255             :  *     UErrorCode success = U_ZERO_ERROR;
     256             :  *     MessageFormat* form("The disk \"{1}\" contains {0}.", success);
     257             :  *     double filelimits[] = {0,1,2};
     258             :  *     UnicodeString filepart[] = {"no files","one file","{0,number} files"};
     259             :  *     ChoiceFormat* fileform = new ChoiceFormat(filelimits, filepart, 3);
     260             :  *     form.setFormat(1, *fileform); // NOT zero, see below
     261             :  *
     262             :  *     Formattable testArgs[] = {1273L, "MyDisk"};
     263             :  *
     264             :  *     UnicodeString string;
     265             :  *     FieldPosition fpos = 0;
     266             :  *     cout << form.format(testArgs, 2, string, fpos, success) << endl;
     267             :  *
     268             :  *     // output, with different testArgs
     269             :  *     // output: The disk "MyDisk" contains no files.
     270             :  *     // output: The disk "MyDisk" contains one file.
     271             :  *     // output: The disk "MyDisk" contains 1,273 files.
     272             :  * \endcode
     273             :  * </pre>
     274             :  * You can either do this programmatically, as in the above example,
     275             :  * or by using a pattern (see ChoiceFormat for more information) as in:
     276             :  * <pre>
     277             :  * \code
     278             :  *    form.applyPattern(
     279             :  *      "There {0,choice,0#are no files|1#is one file|1<are {0,number,integer} files}.");
     280             :  * \endcode
     281             :  * </pre>
     282             :  * <P>
     283             :  * <EM>Note:</EM> As we see above, the string produced by a ChoiceFormat in
     284             :  * MessageFormat is treated specially; occurences of '{' are used to
     285             :  * indicated subformats, and cause recursion.  If you create both a
     286             :  * MessageFormat and ChoiceFormat programmatically (instead of using
     287             :  * the string patterns), then be careful not to produce a format that
     288             :  * recurses on itself, which will cause an infinite loop.
     289             :  * <P>
     290             :  * <EM>Note:</EM> Subformats are numbered by their order in the pattern.
     291             :  * This is <EM>not</EM> the same as the argumentIndex.
     292             :  * <pre>
     293             :  * \code
     294             :  *    For example: with "abc{2}def{3}ghi{0}...",
     295             :  *
     296             :  *    format0 affects the first variable {2}
     297             :  *    format1 affects the second variable {3}
     298             :  *    format2 affects the second variable {0}
     299             :  * \endcode
     300             :  * </pre>
     301             :  *
     302             :  * <p><em>User subclasses are not supported.</em> While clients may write
     303             :  * subclasses, such code will not necessarily work and will not be
     304             :  * guaranteed to work stably from release to release.
     305             :  */
     306             : class U_I18N_API MessageFormat : public Format {
     307             : public:
     308             :     /**
     309             :      * Enum type for kMaxFormat.
     310             :      * @obsolete ICU 3.0.  The 10-argument limit was removed as of ICU 2.6,
     311             :      * rendering this enum type obsolete.
     312             :      */
     313             :     enum EFormatNumber {
     314             :         /**
     315             :          * The maximum number of arguments.
     316             :          * @obsolete ICU 3.0.  The 10-argument limit was removed as of ICU 2.6,
     317             :          * rendering this constant obsolete.
     318             :          */
     319             :         kMaxFormat = 10
     320             :     };
     321             : 
     322             :     /**
     323             :      * Constructs a new MessageFormat using the given pattern and the
     324             :      * default locale.
     325             :      *
     326             :      * @param pattern   Pattern used to construct object.
     327             :      * @param status    Input/output error code.  If the
     328             :      *                  pattern cannot be parsed, set to failure code.
     329             :      * @stable ICU 2.0
     330             :      */
     331             :     MessageFormat(const UnicodeString& pattern,
     332             :                   UErrorCode &status);
     333             : 
     334             :     /**
     335             :      * Constructs a new MessageFormat using the given pattern and locale.
     336             :      * @param pattern   Pattern used to construct object.
     337             :      * @param newLocale The locale to use for formatting dates and numbers.
     338             :      * @param status    Input/output error code.  If the
     339             :      *                  pattern cannot be parsed, set to failure code.
     340             :      * @stable ICU 2.0
     341             :      */
     342             :     MessageFormat(const UnicodeString& pattern,
     343             :                   const Locale& newLocale,
     344             :                         UErrorCode& status);
     345             :     /**
     346             :      * Constructs a new MessageFormat using the given pattern and locale.
     347             :      * @param pattern   Pattern used to construct object.
     348             :      * @param newLocale The locale to use for formatting dates and numbers.
     349             :      * @param parseError Struct to recieve information on position 
     350             :      *                   of error within the pattern.
     351             :      * @param status    Input/output error code.  If the
     352             :      *                  pattern cannot be parsed, set to failure code.
     353             :      * @stable ICU 2.0
     354             :      */
     355             :     MessageFormat(const UnicodeString& pattern,
     356             :                   const Locale& newLocale,
     357             :                   UParseError& parseError,
     358             :                   UErrorCode& status);
     359             :     /**
     360             :      * Constructs a new MessageFormat from an existing one.
     361             :      * @stable ICU 2.0
     362             :      */
     363             :     MessageFormat(const MessageFormat&);
     364             : 
     365             :     /**
     366             :      * Assignment operator.
     367             :      * @stable ICU 2.0
     368             :      */
     369             :     const MessageFormat& operator=(const MessageFormat&);
     370             : 
     371             :     /**
     372             :      * Destructor.
     373             :      * @stable ICU 2.0
     374             :      */
     375             :     virtual ~MessageFormat();
     376             : 
     377             :     /**
     378             :      * Clones this Format object polymorphically.  The caller owns the
     379             :      * result and should delete it when done.
     380             :      * @stable ICU 2.0
     381             :      */
     382             :     virtual Format* clone(void) const;
     383             : 
     384             :     /**
     385             :      * Returns true if the given Format objects are semantically equal.
     386             :      * Objects of different subclasses are considered unequal.
     387             :      * @param other  the object to be compared with.
     388             :      * @return       true if the given Format objects are semantically equal.
     389             :      * @stable ICU 2.0
     390             :      */
     391             :     virtual UBool operator==(const Format& other) const;
     392             : 
     393             :     /**
     394             :      * Sets the locale. This locale is used for fetching default number or date
     395             :      * format information.
     396             :      * @param theLocale    the new locale value to be set.
     397             :      * @stable ICU 2.0
     398             :      */
     399             :     virtual void setLocale(const Locale& theLocale);
     400             : 
     401             :     /**
     402             :      * Gets the locale. This locale is used for fetching default number or date
     403             :      * format information.
     404             :      * @return    the locale of the object.
     405             :      * @stable ICU 2.0
     406             :      */
     407             :     virtual const Locale& getLocale(void) const;
     408             : 
     409             :     /**
     410             :      * Applies the given pattern string to this message format.
     411             :      *
     412             :      * @param pattern   The pattern to be applied.
     413             :      * @param status    Input/output error code.  If the
     414             :      *                  pattern cannot be parsed, set to failure code.
     415             :      * @stable ICU 2.0
     416             :      */
     417             :     virtual void applyPattern(const UnicodeString& pattern,
     418             :                               UErrorCode& status);
     419             :     /**
     420             :      * Applies the given pattern string to this message format.
     421             :      *
     422             :      * @param pattern    The pattern to be applied.
     423             :      * @param parseError Struct to recieve information on position 
     424             :      *                   of error within pattern.
     425             :      * @param status    Input/output error code.  If the
     426             :      *                  pattern cannot be parsed, set to failure code.
     427             :      * @stable ICU 2.0
     428             :      */
     429             :     virtual void applyPattern(const UnicodeString& pattern,
     430             :                              UParseError& parseError,
     431             :                              UErrorCode& status);
     432             : 
     433             :     /**
     434             :      * Returns a pattern that can be used to recreate this object.
     435             :      *
     436             :      * @param appendTo  Output parameter to receive the pattern.
     437             :      *                  Result is appended to existing contents.
     438             :      * @return          Reference to 'appendTo' parameter.
     439             :      * @stable ICU 2.0
     440             :      */
     441             :     virtual UnicodeString& toPattern(UnicodeString& appendTo) const;
     442             : 
     443             :     /**
     444             :      * Sets subformats.
     445             :      * See the class description about format numbering.
     446             :      * The caller should not delete the Format objects after this call.
     447             :      * <EM>The array formatsToAdopt is not itself adopted.</EM> Its
     448             :      * ownership is retained by the caller. If the call fails because
     449             :      * memory cannot be allocated, then the formats will be deleted
     450             :      * by this method, and this object will remain unchanged.
     451             :      * 
     452             :      * @stable ICU 2.0
     453             :      * @param formatsToAdopt    the format to be adopted.
     454             :      * @param count             the size of the array.
     455             :      */
     456             :     virtual void adoptFormats(Format** formatsToAdopt, int32_t count);
     457             : 
     458             :     /**
     459             :      * Sets subformats.
     460             :      * See the class description about format numbering.
     461             :      * Each item in the array is cloned into the internal array.
     462             :      * If the call fails because memory cannot be allocated, then this
     463             :      * object will remain unchanged.
     464             :      * 
     465             :      * @stable ICU 2.0
     466             :      * @param newFormats the new format to be set.
     467             :      * @param cnt        the size of the array.
     468             :      */
     469             :     virtual void setFormats(const Format** newFormats, int32_t cnt);
     470             : 
     471             : 
     472             :     /**
     473             :      * Sets one subformat.
     474             :      * See the class description about format numbering.
     475             :      * The caller should not delete the Format object after this call.
     476             :      * If the number is over the number of formats already set,
     477             :      * the item will be deleted and ignored.
     478             :      * @stable ICU 2.0
     479             :      * @param formatNumber     index of the subformat.
     480             :      * @param formatToAdopt    the format to be adopted.
     481             :      */
     482             :     virtual void adoptFormat(int32_t formatNumber, Format* formatToAdopt);
     483             : 
     484             :     /**
     485             :      * Sets one subformat.
     486             :      * See the class description about format numbering.
     487             :      * If the number is over the number of formats already set,
     488             :      * the item will be ignored.
     489             :      * @param formatNumber     index of the subformat.
     490             :      * @param format    the format to be set.
     491             :      * @stable ICU 2.0
     492             :      */
     493             :     virtual void setFormat(int32_t formatNumber, const Format& format);
     494             : 
     495             :     /**
     496             :      * Gets format names. This function returns formatNames in StringEnumerations
     497             :      * which can be used with getFormat() and setFormat() to export formattable 
     498             :      * array from current MessageFormat to another.  It is caller's resposibility 
     499             :      * to delete the returned formatNames.
     500             :      * @param status  output param set to success/failure code.
     501             :      * @stable ICU 4.0
     502             :      */
     503             :     virtual StringEnumeration* getFormatNames(UErrorCode& status);
     504             :     
     505             :     /**
     506             :      * Gets subformat pointer for given format name.   
     507             :      * This function supports both named and numbered
     508             :      * arguments-- if numbered, the formatName is the
     509             :      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
     510             :      * The returned Format object should not be deleted by the caller,
     511             :      * nor should the ponter of other object .  The pointer and its 
     512             :      * contents remain valid only until the next call to any method
     513             :      * of this class is made with this object. 
     514             :      * @param formatName the name or number specifying a format
     515             :      * @param status  output param set to success/failure code.
     516             :      * @stable ICU 4.0
     517             :      */
     518             :     virtual Format* getFormat(const UnicodeString& formatName, UErrorCode& status);
     519             :     
     520             :     /**
     521             :      * Sets one subformat for given format name.
     522             :      * See the class description about format name. 
     523             :      * This function supports both named and numbered
     524             :      * arguments-- if numbered, the formatName is the
     525             :      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
     526             :      * If there is no matched formatName or wrong type,
     527             :      * the item will be ignored.
     528             :      * @param formatName  Name of the subformat.
     529             :      * @param format      the format to be set.
     530             :      * @param status  output param set to success/failure code.
     531             :      * @stable ICU 4.0
     532             :      */
     533             :     virtual void setFormat(const UnicodeString& formatName, const Format& format, UErrorCode& status);
     534             :     
     535             :     /**
     536             :      * Sets one subformat for given format name.
     537             :      * See the class description about format name. 
     538             :      * This function supports both named and numbered
     539             :      * arguments-- if numbered, the formatName is the
     540             :      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
     541             :      * If there is no matched formatName or wrong type,
     542             :      * the item will be ignored.
     543             :      * The caller should not delete the Format object after this call.
     544             :      * @param formatName  Name of the subformat.
     545             :      * @param formatToAdopt  Format to be adopted.
     546             :      * @param status      output param set to success/failure code.
     547             :      * @stable ICU 4.0
     548             :      */
     549             :     virtual void adoptFormat(const UnicodeString& formatName, Format* formatToAdopt, UErrorCode& status);
     550             : 
     551             : 
     552             :     /**
     553             :      * Gets an array of subformats of this object.  The returned array
     554             :      * should not be deleted by the caller, nor should the pointers
     555             :      * within the array.  The array and its contents remain valid only
     556             :      * until the next call to any method of this class is made with
     557             :      * this object.  See the class description about format numbering.
     558             :      * @param count output parameter to receive the size of the array
     559             :      * @return an array of count Format* objects, or NULL if out of
     560             :      * memory.  Any or all of the array elements may be NULL.
     561             :      * @stable ICU 2.0
     562             :      */
     563             :     virtual const Format** getFormats(int32_t& count) const;
     564             : 
     565             :     /**
     566             :      * Formats the given array of arguments into a user-readable string.
     567             :      * Does not take ownership of the Formattable* array or its contents.
     568             :      *
     569             :      * @param source    An array of objects to be formatted.
     570             :      * @param count     The number of elements of 'source'.
     571             :      * @param appendTo  Output parameter to receive result.
     572             :      *                  Result is appended to existing contents.
     573             :      * @param ignore    Not used; inherited from base class API.
     574             :      * @param status    Input/output error code.  If the
     575             :      *                  pattern cannot be parsed, set to failure code.
     576             :      * @return          Reference to 'appendTo' parameter.
     577             :      * @stable ICU 2.0
     578             :      */
     579             :     UnicodeString& format(  const Formattable* source,
     580             :                             int32_t count,
     581             :                             UnicodeString& appendTo,
     582             :                             FieldPosition& ignore,
     583             :                             UErrorCode& status) const;
     584             : 
     585             :     /**
     586             :      * Formats the given array of arguments into a user-readable string
     587             :      * using the given pattern.
     588             :      *
     589             :      * @param pattern   The pattern.
     590             :      * @param arguments An array of objects to be formatted.
     591             :      * @param count     The number of elements of 'source'.
     592             :      * @param appendTo  Output parameter to receive result.
     593             :      *                  Result is appended to existing contents.
     594             :      * @param status    Input/output error code.  If the
     595             :      *                  pattern cannot be parsed, set to failure code.
     596             :      * @return          Reference to 'appendTo' parameter.
     597             :      * @stable ICU 2.0
     598             :      */
     599             :     static UnicodeString& format(const UnicodeString& pattern,
     600             :                                  const Formattable* arguments,
     601             :                                  int32_t count,
     602             :                                  UnicodeString& appendTo,
     603             :                                  UErrorCode& status);
     604             : 
     605             :     /**
     606             :      * Formats the given array of arguments into a user-readable
     607             :      * string.  The array must be stored within a single Formattable
     608             :      * object of type kArray. If the Formattable object type is not of
     609             :      * type kArray, then returns a failing UErrorCode.
     610             :      *
     611             :      * @param obj       A Formattable of type kArray containing
     612             :      *                  arguments to be formatted.
     613             :      * @param appendTo  Output parameter to receive result.
     614             :      *                  Result is appended to existing contents.
     615             :      * @param pos       On input: an alignment field, if desired.
     616             :      *                  On output: the offsets of the alignment field.
     617             :      * @param status    Input/output error code.  If the
     618             :      *                  pattern cannot be parsed, set to failure code.
     619             :      * @return          Reference to 'appendTo' parameter.
     620             :      * @stable ICU 2.0
     621             :      */
     622             :     virtual UnicodeString& format(const Formattable& obj,
     623             :                                   UnicodeString& appendTo,
     624             :                                   FieldPosition& pos,
     625             :                                   UErrorCode& status) const;
     626             : 
     627             :     /**
     628             :      * Formats the given array of arguments into a user-readable
     629             :      * string.  The array must be stored within a single Formattable
     630             :      * object of type kArray. If the Formattable object type is not of
     631             :      * type kArray, then returns a failing UErrorCode.
     632             :      *
     633             :      * @param obj       The object to format
     634             :      * @param appendTo  Output parameter to receive result.
     635             :      *                  Result is appended to existing contents.
     636             :      * @param status    Input/output error code.  If the
     637             :      *                  pattern cannot be parsed, set to failure code.
     638             :      * @return          Reference to 'appendTo' parameter.
     639             :      * @stable ICU 2.0
     640             :      */
     641             :     UnicodeString& format(const Formattable& obj,
     642             :                           UnicodeString& appendTo,
     643             :                           UErrorCode& status) const;
     644             :     
     645             : 
     646             :     /**
     647             :      * Formats the given array of arguments into a user-defined argument name
     648             :      * array. This function supports both named and numbered
     649             :      * arguments-- if numbered, the formatName is the
     650             :      * corresponding UnicodeStrings (e.g. "0", "1", "2"...).
     651             :      *
     652             :      * @param argumentNames argument name array
     653             :      * @param arguments An array of objects to be formatted.
     654             :      * @param count     The number of elements of 'argumentNames' and 
     655             :      *                  arguments.  The number of argumentNames and arguments
     656             :      *                  must be the same.
     657             :      * @param appendTo  Output parameter to receive result.
     658             :      *                  Result is appended to existing contents.
     659             :      * @param status    Input/output error code.  If the
     660             :      *                  pattern cannot be parsed, set to failure code.
     661             :      * @return          Reference to 'appendTo' parameter.
     662             :      * @stable ICU 4.0
     663             :      */
     664             :     UnicodeString& format(const UnicodeString* argumentNames,
     665             :                           const Formattable* arguments,
     666             :                           int32_t count,
     667             :                           UnicodeString& appendTo,
     668             :                           UErrorCode& status) const;
     669             :     /**
     670             :      * Parses the given string into an array of output arguments.
     671             :      *
     672             :      * @param source    String to be parsed.
     673             :      * @param pos       On input, starting position for parse. On output,
     674             :      *                  final position after parse.  Unchanged if parse
     675             :      *                  fails.
     676             :      * @param count     Output parameter to receive the number of arguments
     677             :      *                  parsed.
     678             :      * @return an array of parsed arguments.  The caller owns both
     679             :      * the array and its contents.
     680             :      * @stable ICU 2.0
     681             :      */
     682             :     virtual Formattable* parse( const UnicodeString& source,
     683             :                                 ParsePosition& pos,
     684             :                                 int32_t& count) const;
     685             : 
     686             :     /**
     687             :      * Parses the given string into an array of output arguments.
     688             :      *
     689             :      * @param source    String to be parsed.
     690             :      * @param count     Output param to receive size of returned array.
     691             :      * @param status    Input/output error code.  If the
     692             :      *                  pattern cannot be parsed, set to failure code. 
     693             :      *                  If the MessageFormat is named argument, the status is 
     694             :      *                  set to U_ARGUMENT_TYPE_MISMATCH.
     695             :      * @return an array of parsed arguments.  The caller owns both
     696             :      * the array and its contents. Return NULL if status is not U_ZERO_ERROR.
     697             :      * 
     698             :      * @stable ICU 2.0
     699             :      */
     700             :     virtual Formattable* parse( const UnicodeString& source,
     701             :                                 int32_t& count,
     702             :                                 UErrorCode& status) const;
     703             : 
     704             :     /**
     705             :      * Parses the given string into an array of output arguments
     706             :      * stored within a single Formattable of type kArray.
     707             :      *
     708             :      * @param source    The string to be parsed into an object.
     709             :      * @param result    Formattable to be set to the parse result.
     710             :      *                  If parse fails, return contents are undefined.
     711             :      * @param pos       On input, starting position for parse. On output,
     712             :      *                  final position after parse.  Unchanged if parse
     713             :      *                  fails.
     714             :      * @stable ICU 2.0
     715             :      */
     716             :     virtual void parseObject(const UnicodeString& source,
     717             :                              Formattable& result,
     718             :                              ParsePosition& pos) const;
     719             : 
     720             :     /**
     721             :      * Convert an 'apostrophe-friendly' pattern into a standard
     722             :      * pattern.  Standard patterns treat all apostrophes as
     723             :      * quotes, which is problematic in some languages, e.g. 
     724             :      * French, where apostrophe is commonly used.  This utility
     725             :      * assumes that only an unpaired apostrophe immediately before
     726             :      * a brace is a true quote.  Other unpaired apostrophes are paired,
     727             :      * and the resulting standard pattern string is returned.
     728             :      *
     729             :      * <p><b>Note</b> it is not guaranteed that the returned pattern
     730             :      * is indeed a valid pattern.  The only effect is to convert
     731             :      * between patterns having different quoting semantics.
     732             :      *
     733             :      * @param pattern the 'apostrophe-friendly' patttern to convert
     734             :      * @param status    Input/output error code.  If the pattern
     735             :      *                  cannot be parsed, the failure code is set.
     736             :      * @return the standard equivalent of the original pattern
     737             :      * @stable ICU 3.4
     738             :      */
     739             :     static UnicodeString autoQuoteApostrophe(const UnicodeString& pattern, 
     740             :         UErrorCode& status);
     741             :     
     742             :     /**
     743             :      * Returns true if this MessageFormat uses named arguments,
     744             :      * and false otherwise.  See class description.
     745             :      *
     746             :      * @return true if named arguments are used.
     747             :      * @stable ICU 4.0
     748             :      */
     749             :     UBool usesNamedArguments() const;
     750             :     
     751             : 
     752             :     /**
     753             :      * This API is for ICU internal use only.
     754             :      * Please do not use it.
     755             :      *
     756             :      * Returns argument types count in the parsed pattern.
     757             :      * Used to distinguish pattern "{0} d" and "d".
     758             :      *
     759             :      * @return           The number of formattable types in the pattern
     760             :      * @internal
     761             :      */
     762             :     int32_t getArgTypeCount() const;
     763             : 
     764             :     /**
     765             :      * Returns a unique class ID POLYMORPHICALLY.  Pure virtual override.
     766             :      * This method is to implement a simple version of RTTI, since not all
     767             :      * C++ compilers support genuine RTTI.  Polymorphic operator==() and
     768             :      * clone() methods call this method.
     769             :      *
     770             :      * @return          The class ID for this object. All objects of a
     771             :      *                  given class have the same class ID.  Objects of
     772             :      *                  other classes have different class IDs.
     773             :      * @stable ICU 2.0
     774             :      */
     775             :     virtual UClassID getDynamicClassID(void) const;
     776             : 
     777             :     /**
     778             :      * Return the class ID for this class.  This is useful only for
     779             :      * comparing to a return value from getDynamicClassID().  For example:
     780             :      * <pre>
     781             :      * .   Base* polymorphic_pointer = createPolymorphicObject();
     782             :      * .   if (polymorphic_pointer->getDynamicClassID() ==
     783             :      * .      Derived::getStaticClassID()) ...
     784             :      * </pre>
     785             :      * @return          The class ID for all objects of this class.
     786             :      * @stable ICU 2.0
     787             :      */
     788             :     static UClassID U_EXPORT2 getStaticClassID(void);
     789             :     
     790             : private:
     791             : 
     792             :     Locale              fLocale;
     793             :     UnicodeString       fPattern;
     794             :     Format**            formatAliases; // see getFormats
     795             :     int32_t             formatAliasesCapacity;
     796             :     UProperty           idStart;
     797             :     UProperty           idContinue;
     798             : 
     799             :     MessageFormat(); // default constructor not implemented
     800             : 
     801             :     /*
     802             :      * A structure representing one subformat of this MessageFormat.
     803             :      * Each subformat has a Format object, an offset into the plain
     804             :      * pattern text fPattern, and an argument number.  The argument
     805             :      * number corresponds to the array of arguments to be formatted.
     806             :      * @internal
     807             :      */
     808             :     class Subformat;
     809             : 
     810             :     /**
     811             :      * A MessageFormat contains an array of subformats.  This array
     812             :      * needs to grow dynamically if the MessageFormat is modified.
     813             :      */
     814             :     Subformat* subformats;
     815             :     int32_t    subformatCount;
     816             :     int32_t    subformatCapacity;
     817             : 
     818             :     /**
     819             :      * A MessageFormat formats an array of arguments.  Each argument
     820             :      * has an expected type, based on the pattern.  For example, if
     821             :      * the pattern contains the subformat "{3,number,integer}", then
     822             :      * we expect argument 3 to have type Formattable::kLong.  This
     823             :      * array needs to grow dynamically if the MessageFormat is
     824             :      * modified.
     825             :      */
     826             :     Formattable::Type* argTypes;
     827             :     int32_t            argTypeCount;
     828             :     int32_t            argTypeCapacity;
     829             : 
     830             :     /**
     831             :       * Is true iff all argument names are non-negative numbers.
     832             :       * 
     833             :       */
     834             :     UBool isArgNumeric;
     835             : 
     836             :     // Variable-size array management
     837             :     UBool allocateSubformats(int32_t capacity);
     838             :     UBool allocateArgTypes(int32_t capacity);
     839             : 
     840             :     /**
     841             :      * Default Format objects used when no format is specified and a
     842             :      * numeric or date argument is formatted.  These are volatile
     843             :      * cache objects maintained only for performance.  They do not
     844             :      * participate in operator=(), copy constructor(), nor
     845             :      * operator==().
     846             :      */
     847             :     NumberFormat* defaultNumberFormat;
     848             :     DateFormat*   defaultDateFormat;
     849             : 
     850             :     /**
     851             :      * Method to retrieve default formats (or NULL on failure).
     852             :      * These are semantically const, but may modify *this.
     853             :      */
     854             :     const NumberFormat* getDefaultNumberFormat(UErrorCode&) const;
     855             :     const DateFormat*   getDefaultDateFormat(UErrorCode&) const;
     856             : 
     857             :     /**
     858             :      * Finds the word s, in the keyword list and returns the located index.
     859             :      * @param s the keyword to be searched for.
     860             :      * @param list the list of keywords to be searched with.
     861             :      * @return the index of the list which matches the keyword s.
     862             :      */
     863             :     static int32_t findKeyword( const UnicodeString& s,
     864             :                                 const UChar * const *list);
     865             : 
     866             :     /**
     867             :      * Formats the array of arguments and copies the result into the
     868             :      * result buffer, updates the field position.
     869             :      *
     870             :      * @param arguments The formattable objects array.
     871             :      * @param cnt       The array count.
     872             :      * @param appendTo  Output parameter to receive result.
     873             :      *                  Result is appended to existing contents.
     874             :      * @param status    Field position status.
     875             :      * @param recursionProtection
     876             :      *                  Initially zero. Bits 0..9 are used to indicate
     877             :      *                  that a parameter has already been seen, to
     878             :      *                  avoid recursion.  Currently unused.
     879             :      * @param success   The error code status.
     880             :      * @return          Reference to 'appendTo' parameter.
     881             :      */
     882             :     UnicodeString&  format( const Formattable* arguments,
     883             :                             int32_t cnt,
     884             :                             UnicodeString& appendTo,
     885             :                             FieldPosition& status,
     886             :                             int32_t recursionProtection,
     887             :                             UErrorCode& success) const;
     888             :     
     889             :     UnicodeString&  format( const Formattable* arguments, 
     890             :                             const UnicodeString *argumentNames,
     891             :                             int32_t cnt,
     892             :                             UnicodeString& appendTo,
     893             :                             FieldPosition& status,
     894             :                             int32_t recursionProtection,
     895             :                             UErrorCode& success) const;
     896             : 
     897             :     void             makeFormat(int32_t offsetNumber,
     898             :                                 UnicodeString* segments,
     899             :                                 UParseError& parseError,
     900             :                                 UErrorCode& success);
     901             : 
     902             :     /**
     903             :      * Convenience method that ought to be in NumberFormat
     904             :      */
     905             :     NumberFormat* createIntegerFormat(const Locale& locale, UErrorCode& status) const;
     906             : 
     907             :     /**
     908             :      * Checks the range of the source text to quote the special
     909             :      * characters, { and ' and copy to target buffer.
     910             :      * @param source
     911             :      * @param start the text offset to start the process of in the source string
     912             :      * @param end the text offset to end the process of in the source string
     913             :      * @param appendTo  Output parameter to receive result.
     914             :      *                  Result is appended to existing contents.
     915             :      */
     916             :     static void copyAndFixQuotes(const UnicodeString& appendTo, int32_t start, int32_t end, UnicodeString& target);
     917             : 
     918             :     /**
     919             :      * Returns array of argument types in the parsed pattern 
     920             :      * for use in C API.  Only for the use of umsg_vformat().  Not
     921             :      * for public consumption.
     922             :      * @param listCount  Output parameter to receive the size of array
     923             :      * @return           The array of formattable types in the pattern
     924             :      * @internal
     925             :      */
     926          60 :     const Formattable::Type* getArgTypeList(int32_t& listCount) const {
     927          60 :         listCount = argTypeCount;
     928          60 :         return argTypes; 
     929             :     }
     930             :     
     931             :     /**
     932             :      * Returns FALSE if the argument name is not legal.
     933             :      * @param  argName   argument name.
     934             :      * @return TRUE if the argument name is legal, otherwise return FALSE.
     935             :      */
     936             :     UBool isLegalArgName(const UnicodeString& argName) const;
     937             :     
     938             :     friend class MessageFormatAdapter; // getFormatTypeList() access
     939             : };
     940             : 
     941             : inline UnicodeString&
     942             : MessageFormat::format(const Formattable& obj,
     943             :                       UnicodeString& appendTo,
     944             :                       UErrorCode& status) const {
     945             :     return Format::format(obj, appendTo, status);
     946             : }
     947             : U_NAMESPACE_END
     948             : 
     949             : #endif /* #if !UCONFIG_NO_FORMATTING */
     950             : 
     951             : #endif // _MSGFMT
     952             : //eof
     953             : 

Generated by: LCOV version 1.10

Generated at Sat, 15 Nov 2014 06:19:25 +0000 (7 days ago)

Copyright © 2005-2014 The PHP Group
All rights reserved.