michael@0: /*
michael@0: *******************************************************************************
michael@0: *   Copyright (C) 2011-2013, International Business Machines
michael@0: *   Corporation and others.  All Rights Reserved.
michael@0: *******************************************************************************
michael@0: *   file name:  messagepattern.h
michael@0: *   encoding:   US-ASCII
michael@0: *   tab size:   8 (not used)
michael@0: *   indentation:4
michael@0: *
michael@0: *   created on: 2011mar14
michael@0: *   created by: Markus W. Scherer
michael@0: */
michael@0: 
michael@0: #ifndef __MESSAGEPATTERN_H__
michael@0: #define __MESSAGEPATTERN_H__
michael@0: 
michael@0: /**
michael@0:  * \file
michael@0:  * \brief C++ API: MessagePattern class: Parses and represents ICU MessageFormat patterns.
michael@0:  */
michael@0: 
michael@0: #include "unicode/utypes.h"
michael@0: 
michael@0: #if !UCONFIG_NO_FORMATTING
michael@0: 
michael@0: #include "unicode/parseerr.h"
michael@0: #include "unicode/unistr.h"
michael@0: 
michael@0: /**
michael@0:  * Mode for when an apostrophe starts quoted literal text for MessageFormat output.
michael@0:  * The default is DOUBLE_OPTIONAL unless overridden via uconfig.h
michael@0:  * (UCONFIG_MSGPAT_DEFAULT_APOSTROPHE_MODE).
michael@0:  * <p>
michael@0:  * A pair of adjacent apostrophes always results in a single apostrophe in the output,
michael@0:  * even when the pair is between two single, text-quoting apostrophes.
michael@0:  * <p>
michael@0:  * The following table shows examples of desired MessageFormat.format() output
michael@0:  * with the pattern strings that yield that output.
michael@0:  * <p>
michael@0:  * <table>
michael@0:  *   <tr>
michael@0:  *     <th>Desired output</th>
michael@0:  *     <th>DOUBLE_OPTIONAL</th>
michael@0:  *     <th>DOUBLE_REQUIRED</th>
michael@0:  *   </tr>
michael@0:  *   <tr>
michael@0:  *     <td>I see {many}</td>
michael@0:  *     <td>I see '{many}'</td>
michael@0:  *     <td>(same)</td>
michael@0:  *   </tr>
michael@0:  *   <tr>
michael@0:  *     <td>I said {'Wow!'}</td>
michael@0:  *     <td>I said '{''Wow!''}'</td>
michael@0:  *     <td>(same)</td>
michael@0:  *   </tr>
michael@0:  *   <tr>
michael@0:  *     <td>I don't know</td>
michael@0:  *     <td>I don't know OR<br> I don''t know</td>
michael@0:  *     <td>I don''t know</td>
michael@0:  *   </tr>
michael@0:  * </table>
michael@0:  * @stable ICU 4.8
michael@0:  * @see UCONFIG_MSGPAT_DEFAULT_APOSTROPHE_MODE
michael@0:  */
michael@0: enum UMessagePatternApostropheMode {
michael@0:     /**
michael@0:      * A literal apostrophe is represented by
michael@0:      * either a single or a double apostrophe pattern character.
michael@0:      * Within a MessageFormat pattern, a single apostrophe only starts quoted literal text
michael@0:      * if it immediately precedes a curly brace {},
michael@0:      * or a pipe symbol | if inside a choice format,
michael@0:      * or a pound symbol # if inside a plural format.
michael@0:      * <p>
michael@0:      * This is the default behavior starting with ICU 4.8.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_APOS_DOUBLE_OPTIONAL,
michael@0:     /**
michael@0:      * A literal apostrophe must be represented by
michael@0:      * a double apostrophe pattern character.
michael@0:      * A single apostrophe always starts quoted literal text.
michael@0:      * <p>
michael@0:      * This is the behavior of ICU 4.6 and earlier, and of the JDK.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_APOS_DOUBLE_REQUIRED
michael@0: };
michael@0: /**
michael@0:  * @stable ICU 4.8
michael@0:  */
michael@0: typedef enum UMessagePatternApostropheMode UMessagePatternApostropheMode;
michael@0: 
michael@0: /**
michael@0:  * MessagePattern::Part type constants.
michael@0:  * @stable ICU 4.8
michael@0:  */
michael@0: enum UMessagePatternPartType {
michael@0:     /**
michael@0:      * Start of a message pattern (main or nested).
michael@0:      * The length is 0 for the top-level message
michael@0:      * and for a choice argument sub-message, otherwise 1 for the '{'.
michael@0:      * The value indicates the nesting level, starting with 0 for the main message.
michael@0:      * <p>
michael@0:      * There is always a later MSG_LIMIT part.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_PART_TYPE_MSG_START,
michael@0:     /**
michael@0:      * End of a message pattern (main or nested).
michael@0:      * The length is 0 for the top-level message and
michael@0:      * the last sub-message of a choice argument,
michael@0:      * otherwise 1 for the '}' or (in a choice argument style) the '|'.
michael@0:      * The value indicates the nesting level, starting with 0 for the main message.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_PART_TYPE_MSG_LIMIT,
michael@0:     /**
michael@0:      * Indicates a substring of the pattern string which is to be skipped when formatting.
michael@0:      * For example, an apostrophe that begins or ends quoted text
michael@0:      * would be indicated with such a part.
michael@0:      * The value is undefined and currently always 0.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_PART_TYPE_SKIP_SYNTAX,
michael@0:     /**
michael@0:      * Indicates that a syntax character needs to be inserted for auto-quoting.
michael@0:      * The length is 0.
michael@0:      * The value is the character code of the insertion character. (U+0027=APOSTROPHE)
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_PART_TYPE_INSERT_CHAR,
michael@0:     /**
michael@0:      * Indicates a syntactic (non-escaped) # symbol in a plural variant.
michael@0:      * When formatting, replace this part's substring with the
michael@0:      * (value-offset) for the plural argument value.
michael@0:      * The value is undefined and currently always 0.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_PART_TYPE_REPLACE_NUMBER,
michael@0:     /**
michael@0:      * Start of an argument.
michael@0:      * The length is 1 for the '{'.
michael@0:      * The value is the ordinal value of the ArgType. Use getArgType().
michael@0:      * <p>
michael@0:      * This part is followed by either an ARG_NUMBER or ARG_NAME,
michael@0:      * followed by optional argument sub-parts (see UMessagePatternArgType constants)
michael@0:      * and finally an ARG_LIMIT part.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_PART_TYPE_ARG_START,
michael@0:     /**
michael@0:      * End of an argument.
michael@0:      * The length is 1 for the '}'.
michael@0:      * The value is the ordinal value of the ArgType. Use getArgType().
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_PART_TYPE_ARG_LIMIT,
michael@0:     /**
michael@0:      * The argument number, provided by the value.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_PART_TYPE_ARG_NUMBER,
michael@0:     /**
michael@0:      * The argument name.
michael@0:      * The value is undefined and currently always 0.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_PART_TYPE_ARG_NAME,
michael@0:     /**
michael@0:      * The argument type.
michael@0:      * The value is undefined and currently always 0.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_PART_TYPE_ARG_TYPE,
michael@0:     /**
michael@0:      * The argument style text.
michael@0:      * The value is undefined and currently always 0.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_PART_TYPE_ARG_STYLE,
michael@0:     /**
michael@0:      * A selector substring in a "complex" argument style.
michael@0:      * The value is undefined and currently always 0.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_PART_TYPE_ARG_SELECTOR,
michael@0:     /**
michael@0:      * An integer value, for example the offset or an explicit selector value
michael@0:      * in a PluralFormat style.
michael@0:      * The part value is the integer value.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_PART_TYPE_ARG_INT,
michael@0:     /**
michael@0:      * A numeric value, for example the offset or an explicit selector value
michael@0:      * in a PluralFormat style.
michael@0:      * The part value is an index into an internal array of numeric values;
michael@0:      * use getNumericValue().
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_PART_TYPE_ARG_DOUBLE
michael@0: };
michael@0: /**
michael@0:  * @stable ICU 4.8
michael@0:  */
michael@0: typedef enum UMessagePatternPartType UMessagePatternPartType;
michael@0: 
michael@0: /**
michael@0:  * Argument type constants.
michael@0:  * Returned by Part.getArgType() for ARG_START and ARG_LIMIT parts.
michael@0:  *
michael@0:  * Messages nested inside an argument are each delimited by MSG_START and MSG_LIMIT,
michael@0:  * with a nesting level one greater than the surrounding message.
michael@0:  * @stable ICU 4.8
michael@0:  */
michael@0: enum UMessagePatternArgType {
michael@0:     /**
michael@0:      * The argument has no specified type.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_ARG_TYPE_NONE,
michael@0:     /**
michael@0:      * The argument has a "simple" type which is provided by the ARG_TYPE part.
michael@0:      * An ARG_STYLE part might follow that.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_ARG_TYPE_SIMPLE,
michael@0:     /**
michael@0:      * The argument is a ChoiceFormat with one or more
michael@0:      * ((ARG_INT | ARG_DOUBLE), ARG_SELECTOR, message) tuples.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_ARG_TYPE_CHOICE,
michael@0:     /**
michael@0:      * The argument is a cardinal-number PluralFormat with an optional ARG_INT or ARG_DOUBLE offset
michael@0:      * (e.g., offset:1)
michael@0:      * and one or more (ARG_SELECTOR [explicit-value] message) tuples.
michael@0:      * If the selector has an explicit value (e.g., =2), then
michael@0:      * that value is provided by the ARG_INT or ARG_DOUBLE part preceding the message.
michael@0:      * Otherwise the message immediately follows the ARG_SELECTOR.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_ARG_TYPE_PLURAL,
michael@0:     /**
michael@0:      * The argument is a SelectFormat with one or more (ARG_SELECTOR, message) pairs.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_ARG_TYPE_SELECT,
michael@0:     /**
michael@0:      * The argument is an ordinal-number PluralFormat
michael@0:      * with the same style parts sequence and semantics as UMSGPAT_ARG_TYPE_PLURAL.
michael@0:      * @stable ICU 50
michael@0:      */
michael@0:     UMSGPAT_ARG_TYPE_SELECTORDINAL
michael@0: };
michael@0: /**
michael@0:  * @stable ICU 4.8
michael@0:  */
michael@0: typedef enum UMessagePatternArgType UMessagePatternArgType;
michael@0: 
michael@0: /**
michael@0:  * \def UMSGPAT_ARG_TYPE_HAS_PLURAL_STYLE
michael@0:  * Returns TRUE if the argument type has a plural style part sequence and semantics,
michael@0:  * for example UMSGPAT_ARG_TYPE_PLURAL and UMSGPAT_ARG_TYPE_SELECTORDINAL.
michael@0:  * @stable ICU 50
michael@0:  */
michael@0: #define UMSGPAT_ARG_TYPE_HAS_PLURAL_STYLE(argType) \
michael@0:     ((argType)==UMSGPAT_ARG_TYPE_PLURAL || (argType)==UMSGPAT_ARG_TYPE_SELECTORDINAL)
michael@0: 
michael@0: enum {
michael@0:     /**
michael@0:      * Return value from MessagePattern.validateArgumentName() for when
michael@0:      * the string is a valid "pattern identifier" but not a number.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_ARG_NAME_NOT_NUMBER=-1,
michael@0: 
michael@0:     /**
michael@0:      * Return value from MessagePattern.validateArgumentName() for when
michael@0:      * the string is invalid.
michael@0:      * It might not be a valid "pattern identifier",
michael@0:      * or it have only ASCII digits but there is a leading zero or the number is too large.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMSGPAT_ARG_NAME_NOT_VALID=-2
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * Special value that is returned by getNumericValue(Part) when no
michael@0:  * numeric value is defined for a part.
michael@0:  * @see MessagePattern.getNumericValue()
michael@0:  * @stable ICU 4.8
michael@0:  */
michael@0: #define UMSGPAT_NO_NUMERIC_VALUE ((double)(-123456789))
michael@0: 
michael@0: U_NAMESPACE_BEGIN
michael@0: 
michael@0: class MessagePatternDoubleList;
michael@0: class MessagePatternPartsList;
michael@0: 
michael@0: /**
michael@0:  * Parses and represents ICU MessageFormat patterns.
michael@0:  * Also handles patterns for ChoiceFormat, PluralFormat and SelectFormat.
michael@0:  * Used in the implementations of those classes as well as in tools
michael@0:  * for message validation, translation and format conversion.
michael@0:  * <p>
michael@0:  * The parser handles all syntax relevant for identifying message arguments.
michael@0:  * This includes "complex" arguments whose style strings contain
michael@0:  * nested MessageFormat pattern substrings.
michael@0:  * For "simple" arguments (with no nested MessageFormat pattern substrings),
michael@0:  * the argument style is not parsed any further.
michael@0:  * <p>
michael@0:  * The parser handles named and numbered message arguments and allows both in one message.
michael@0:  * <p>
michael@0:  * Once a pattern has been parsed successfully, iterate through the parsed data
michael@0:  * with countParts(), getPart() and related methods.
michael@0:  * <p>
michael@0:  * The data logically represents a parse tree, but is stored and accessed
michael@0:  * as a list of "parts" for fast and simple parsing and to minimize object allocations.
michael@0:  * Arguments and nested messages are best handled via recursion.
michael@0:  * For every _START "part", MessagePattern.getLimitPartIndex() efficiently returns
michael@0:  * the index of the corresponding _LIMIT "part".
michael@0:  * <p>
michael@0:  * List of "parts":
michael@0:  * <pre>
michael@0:  * message = MSG_START (SKIP_SYNTAX | INSERT_CHAR | REPLACE_NUMBER | argument)* MSG_LIMIT
michael@0:  * argument = noneArg | simpleArg | complexArg
michael@0:  * complexArg = choiceArg | pluralArg | selectArg
michael@0:  *
michael@0:  * noneArg = ARG_START.NONE (ARG_NAME | ARG_NUMBER) ARG_LIMIT.NONE
michael@0:  * simpleArg = ARG_START.SIMPLE (ARG_NAME | ARG_NUMBER) ARG_TYPE [ARG_STYLE] ARG_LIMIT.SIMPLE
michael@0:  * choiceArg = ARG_START.CHOICE (ARG_NAME | ARG_NUMBER) choiceStyle ARG_LIMIT.CHOICE
michael@0:  * pluralArg = ARG_START.PLURAL (ARG_NAME | ARG_NUMBER) pluralStyle ARG_LIMIT.PLURAL
michael@0:  * selectArg = ARG_START.SELECT (ARG_NAME | ARG_NUMBER) selectStyle ARG_LIMIT.SELECT
michael@0:  *
michael@0:  * choiceStyle = ((ARG_INT | ARG_DOUBLE) ARG_SELECTOR message)+
michael@0:  * pluralStyle = [ARG_INT | ARG_DOUBLE] (ARG_SELECTOR [ARG_INT | ARG_DOUBLE] message)+
michael@0:  * selectStyle = (ARG_SELECTOR message)+
michael@0:  * </pre>
michael@0:  * <ul>
michael@0:  *   <li>Literal output text is not represented directly by "parts" but accessed
michael@0:  *       between parts of a message, from one part's getLimit() to the next part's getIndex().
michael@0:  *   <li><code>ARG_START.CHOICE</code> stands for an ARG_START Part with ArgType CHOICE.
michael@0:  *   <li>In the choiceStyle, the ARG_SELECTOR has the '<', the '#' or
michael@0:  *       the less-than-or-equal-to sign (U+2264).
michael@0:  *   <li>In the pluralStyle, the first, optional numeric Part has the "offset:" value.
michael@0:  *       The optional numeric Part between each (ARG_SELECTOR, message) pair
michael@0:  *       is the value of an explicit-number selector like "=2",
michael@0:  *       otherwise the selector is a non-numeric identifier.
michael@0:  *   <li>The REPLACE_NUMBER Part can occur only in an immediate sub-message of the pluralStyle.
michael@0:  * </ul>
michael@0:  * <p>
michael@0:  * This class is not intended for public subclassing.
michael@0:  *
michael@0:  * @stable ICU 4.8
michael@0:  */
michael@0: class U_COMMON_API MessagePattern : public UObject {
michael@0: public:
michael@0:     /**
michael@0:      * Constructs an empty MessagePattern with default UMessagePatternApostropheMode.
michael@0:      * @param errorCode Standard ICU error code. Its input value must
michael@0:      *                  pass the U_SUCCESS() test, or else the function returns
michael@0:      *                  immediately. Check for U_FAILURE() on output or use with
michael@0:      *                  function chaining. (See User Guide for details.)
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     MessagePattern(UErrorCode &errorCode);
michael@0: 
michael@0:     /**
michael@0:      * Constructs an empty MessagePattern.
michael@0:      * @param mode Explicit UMessagePatternApostropheMode.
michael@0:      * @param errorCode Standard ICU error code. Its input value must
michael@0:      *                  pass the U_SUCCESS() test, or else the function returns
michael@0:      *                  immediately. Check for U_FAILURE() on output or use with
michael@0:      *                  function chaining. (See User Guide for details.)
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     MessagePattern(UMessagePatternApostropheMode mode, UErrorCode &errorCode);
michael@0: 
michael@0:     /**
michael@0:      * Constructs a MessagePattern with default UMessagePatternApostropheMode and
michael@0:      * parses the MessageFormat pattern string.
michael@0:      * @param pattern a MessageFormat pattern string
michael@0:      * @param parseError Struct to receive information on the position
michael@0:      *                   of an error within the pattern.
michael@0:      *                   Can be NULL.
michael@0:      * @param errorCode Standard ICU error code. Its input value must
michael@0:      *                  pass the U_SUCCESS() test, or else the function returns
michael@0:      *                  immediately. Check for U_FAILURE() on output or use with
michael@0:      *                  function chaining. (See User Guide for details.)
michael@0:      * TODO: turn @throws into UErrorCode specifics?
michael@0:      * @throws IllegalArgumentException for syntax errors in the pattern string
michael@0:      * @throws IndexOutOfBoundsException if certain limits are exceeded
michael@0:      *         (e.g., argument number too high, argument name too long, etc.)
michael@0:      * @throws NumberFormatException if a number could not be parsed
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     MessagePattern(const UnicodeString &pattern, UParseError *parseError, UErrorCode &errorCode);
michael@0: 
michael@0:     /**
michael@0:      * Copy constructor.
michael@0:      * @param other Object to copy.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     MessagePattern(const MessagePattern &other);
michael@0: 
michael@0:     /**
michael@0:      * Assignment operator.
michael@0:      * @param other Object to copy.
michael@0:      * @return *this=other
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     MessagePattern &operator=(const MessagePattern &other);
michael@0: 
michael@0:     /**
michael@0:      * Destructor.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     virtual ~MessagePattern();
michael@0: 
michael@0:     /**
michael@0:      * Parses a MessageFormat pattern string.
michael@0:      * @param pattern a MessageFormat pattern string
michael@0:      * @param parseError Struct to receive information on the position
michael@0:      *                   of an error within the pattern.
michael@0:      *                   Can be NULL.
michael@0:      * @param errorCode Standard ICU error code. Its input value must
michael@0:      *                  pass the U_SUCCESS() test, or else the function returns
michael@0:      *                  immediately. Check for U_FAILURE() on output or use with
michael@0:      *                  function chaining. (See User Guide for details.)
michael@0:      * @return *this
michael@0:      * @throws IllegalArgumentException for syntax errors in the pattern string
michael@0:      * @throws IndexOutOfBoundsException if certain limits are exceeded
michael@0:      *         (e.g., argument number too high, argument name too long, etc.)
michael@0:      * @throws NumberFormatException if a number could not be parsed
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     MessagePattern &parse(const UnicodeString &pattern,
michael@0:                           UParseError *parseError, UErrorCode &errorCode);
michael@0: 
michael@0:     /**
michael@0:      * Parses a ChoiceFormat pattern string.
michael@0:      * @param pattern a ChoiceFormat pattern string
michael@0:      * @param parseError Struct to receive information on the position
michael@0:      *                   of an error within the pattern.
michael@0:      *                   Can be NULL.
michael@0:      * @param errorCode Standard ICU error code. Its input value must
michael@0:      *                  pass the U_SUCCESS() test, or else the function returns
michael@0:      *                  immediately. Check for U_FAILURE() on output or use with
michael@0:      *                  function chaining. (See User Guide for details.)
michael@0:      * @return *this
michael@0:      * @throws IllegalArgumentException for syntax errors in the pattern string
michael@0:      * @throws IndexOutOfBoundsException if certain limits are exceeded
michael@0:      *         (e.g., argument number too high, argument name too long, etc.)
michael@0:      * @throws NumberFormatException if a number could not be parsed
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     MessagePattern &parseChoiceStyle(const UnicodeString &pattern,
michael@0:                                      UParseError *parseError, UErrorCode &errorCode);
michael@0: 
michael@0:     /**
michael@0:      * Parses a PluralFormat pattern string.
michael@0:      * @param pattern a PluralFormat pattern string
michael@0:      * @param parseError Struct to receive information on the position
michael@0:      *                   of an error within the pattern.
michael@0:      *                   Can be NULL.
michael@0:      * @param errorCode Standard ICU error code. Its input value must
michael@0:      *                  pass the U_SUCCESS() test, or else the function returns
michael@0:      *                  immediately. Check for U_FAILURE() on output or use with
michael@0:      *                  function chaining. (See User Guide for details.)
michael@0:      * @return *this
michael@0:      * @throws IllegalArgumentException for syntax errors in the pattern string
michael@0:      * @throws IndexOutOfBoundsException if certain limits are exceeded
michael@0:      *         (e.g., argument number too high, argument name too long, etc.)
michael@0:      * @throws NumberFormatException if a number could not be parsed
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     MessagePattern &parsePluralStyle(const UnicodeString &pattern,
michael@0:                                      UParseError *parseError, UErrorCode &errorCode);
michael@0: 
michael@0:     /**
michael@0:      * Parses a SelectFormat pattern string.
michael@0:      * @param pattern a SelectFormat pattern string
michael@0:      * @param parseError Struct to receive information on the position
michael@0:      *                   of an error within the pattern.
michael@0:      *                   Can be NULL.
michael@0:      * @param errorCode Standard ICU error code. Its input value must
michael@0:      *                  pass the U_SUCCESS() test, or else the function returns
michael@0:      *                  immediately. Check for U_FAILURE() on output or use with
michael@0:      *                  function chaining. (See User Guide for details.)
michael@0:      * @return *this
michael@0:      * @throws IllegalArgumentException for syntax errors in the pattern string
michael@0:      * @throws IndexOutOfBoundsException if certain limits are exceeded
michael@0:      *         (e.g., argument number too high, argument name too long, etc.)
michael@0:      * @throws NumberFormatException if a number could not be parsed
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     MessagePattern &parseSelectStyle(const UnicodeString &pattern,
michael@0:                                      UParseError *parseError, UErrorCode &errorCode);
michael@0: 
michael@0:     /**
michael@0:      * Clears this MessagePattern.
michael@0:      * countParts() will return 0.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     void clear();
michael@0: 
michael@0:     /**
michael@0:      * Clears this MessagePattern and sets the UMessagePatternApostropheMode.
michael@0:      * countParts() will return 0.
michael@0:      * @param mode The new UMessagePatternApostropheMode.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     void clearPatternAndSetApostropheMode(UMessagePatternApostropheMode mode) {
michael@0:         clear();
michael@0:         aposMode=mode;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * @param other another object to compare with.
michael@0:      * @return TRUE if this object is equivalent to the other one.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UBool operator==(const MessagePattern &other) const;
michael@0: 
michael@0:     /**
michael@0:      * @param other another object to compare with.
michael@0:      * @return FALSE if this object is equivalent to the other one.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     inline UBool operator!=(const MessagePattern &other) const {
michael@0:         return !operator==(other);
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * @return A hash code for this object.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     int32_t hashCode() const;
michael@0: 
michael@0:     /**
michael@0:      * @return this instance's UMessagePatternApostropheMode.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMessagePatternApostropheMode getApostropheMode() const {
michael@0:         return aposMode;
michael@0:     }
michael@0: 
michael@0:     // Java has package-private jdkAposMode() here.
michael@0:     // In C++, this is declared in the MessageImpl class.
michael@0: 
michael@0:     /**
michael@0:      * @return the parsed pattern string (null if none was parsed).
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     const UnicodeString &getPatternString() const {
michael@0:         return msg;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Does the parsed pattern have named arguments like {first_name}?
michael@0:      * @return TRUE if the parsed pattern has at least one named argument.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UBool hasNamedArguments() const {
michael@0:         return hasArgNames;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Does the parsed pattern have numbered arguments like {2}?
michael@0:      * @return TRUE if the parsed pattern has at least one numbered argument.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UBool hasNumberedArguments() const {
michael@0:         return hasArgNumbers;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Validates and parses an argument name or argument number string.
michael@0:      * An argument name must be a "pattern identifier", that is, it must contain
michael@0:      * no Unicode Pattern_Syntax or Pattern_White_Space characters.
michael@0:      * If it only contains ASCII digits, then it must be a small integer with no leading zero.
michael@0:      * @param name Input string.
michael@0:      * @return &gt;=0 if the name is a valid number,
michael@0:      *         ARG_NAME_NOT_NUMBER (-1) if it is a "pattern identifier" but not all ASCII digits,
michael@0:      *         ARG_NAME_NOT_VALID (-2) if it is neither.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     static int32_t validateArgumentName(const UnicodeString &name);
michael@0: 
michael@0:     /**
michael@0:      * Returns a version of the parsed pattern string where each ASCII apostrophe
michael@0:      * is doubled (escaped) if it is not already, and if it is not interpreted as quoting syntax.
michael@0:      * <p>
michael@0:      * For example, this turns "I don't '{know}' {gender,select,female{h''er}other{h'im}}."
michael@0:      * into "I don''t '{know}' {gender,select,female{h''er}other{h''im}}."
michael@0:      * @return the deep-auto-quoted version of the parsed pattern string.
michael@0:      * @see MessageFormat.autoQuoteApostrophe()
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UnicodeString autoQuoteApostropheDeep() const;
michael@0: 
michael@0:     class Part;
michael@0: 
michael@0:     /**
michael@0:      * Returns the number of "parts" created by parsing the pattern string.
michael@0:      * Returns 0 if no pattern has been parsed or clear() was called.
michael@0:      * @return the number of pattern parts.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     int32_t countParts() const {
michael@0:         return partsLength;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Gets the i-th pattern "part".
michael@0:      * @param i The index of the Part data. (0..countParts()-1)
michael@0:      * @return the i-th pattern "part".
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     const Part &getPart(int32_t i) const {
michael@0:         return parts[i];
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Returns the UMessagePatternPartType of the i-th pattern "part".
michael@0:      * Convenience method for getPart(i).getType().
michael@0:      * @param i The index of the Part data. (0..countParts()-1)
michael@0:      * @return The UMessagePatternPartType of the i-th Part.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UMessagePatternPartType getPartType(int32_t i) const {
michael@0:         return getPart(i).type;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Returns the pattern index of the specified pattern "part".
michael@0:      * Convenience method for getPart(partIndex).getIndex().
michael@0:      * @param partIndex The index of the Part data. (0..countParts()-1)
michael@0:      * @return The pattern index of this Part.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     int32_t getPatternIndex(int32_t partIndex) const {
michael@0:         return getPart(partIndex).index;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Returns the substring of the pattern string indicated by the Part.
michael@0:      * Convenience method for getPatternString().substring(part.getIndex(), part.getLimit()).
michael@0:      * @param part a part of this MessagePattern.
michael@0:      * @return the substring associated with part.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UnicodeString getSubstring(const Part &part) const {
michael@0:         return msg.tempSubString(part.index, part.length);
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Compares the part's substring with the input string s.
michael@0:      * @param part a part of this MessagePattern.
michael@0:      * @param s a string.
michael@0:      * @return TRUE if getSubstring(part).equals(s).
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UBool partSubstringMatches(const Part &part, const UnicodeString &s) const {
michael@0:         return 0==msg.compare(part.index, part.length, s);
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Returns the numeric value associated with an ARG_INT or ARG_DOUBLE.
michael@0:      * @param part a part of this MessagePattern.
michael@0:      * @return the part's numeric value, or UMSGPAT_NO_NUMERIC_VALUE if this is not a numeric part.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     double getNumericValue(const Part &part) const;
michael@0: 
michael@0:     /**
michael@0:      * Returns the "offset:" value of a PluralFormat argument, or 0 if none is specified.
michael@0:      * @param pluralStart the index of the first PluralFormat argument style part. (0..countParts()-1)
michael@0:      * @return the "offset:" value.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     double getPluralOffset(int32_t pluralStart) const;
michael@0: 
michael@0:     /**
michael@0:      * Returns the index of the ARG|MSG_LIMIT part corresponding to the ARG|MSG_START at start.
michael@0:      * @param start The index of some Part data (0..countParts()-1);
michael@0:      *        this Part should be of Type ARG_START or MSG_START.
michael@0:      * @return The first i>start where getPart(i).getType()==ARG|MSG_LIMIT at the same nesting level,
michael@0:      *         or start itself if getPartType(msgStart)!=ARG|MSG_START.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     int32_t getLimitPartIndex(int32_t start) const {
michael@0:         int32_t limit=getPart(start).limitPartIndex;
michael@0:         if(limit<start) {
michael@0:             return start;
michael@0:         }
michael@0:         return limit;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * A message pattern "part", representing a pattern parsing event.
michael@0:      * There is a part for the start and end of a message or argument,
michael@0:      * for quoting and escaping of and with ASCII apostrophes,
michael@0:      * and for syntax elements of "complex" arguments.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     class Part : public UMemory {
michael@0:     public:
michael@0:         /**
michael@0:          * Default constructor, do not use.
michael@0:          * @internal
michael@0:          */
michael@0:         Part() {}
michael@0: 
michael@0:         /**
michael@0:          * Returns the type of this part.
michael@0:          * @return the part type.
michael@0:          * @stable ICU 4.8
michael@0:          */
michael@0:         UMessagePatternPartType getType() const {
michael@0:             return type;
michael@0:         }
michael@0: 
michael@0:         /**
michael@0:          * Returns the pattern string index associated with this Part.
michael@0:          * @return this part's pattern string index.
michael@0:          * @stable ICU 4.8
michael@0:          */
michael@0:         int32_t getIndex() const {
michael@0:             return index;
michael@0:         }
michael@0: 
michael@0:         /**
michael@0:          * Returns the length of the pattern substring associated with this Part.
michael@0:          * This is 0 for some parts.
michael@0:          * @return this part's pattern substring length.
michael@0:          * @stable ICU 4.8
michael@0:          */
michael@0:         int32_t getLength() const {
michael@0:             return length;
michael@0:         }
michael@0: 
michael@0:         /**
michael@0:          * Returns the pattern string limit (exclusive-end) index associated with this Part.
michael@0:          * Convenience method for getIndex()+getLength().
michael@0:          * @return this part's pattern string limit index, same as getIndex()+getLength().
michael@0:          * @stable ICU 4.8
michael@0:          */
michael@0:         int32_t getLimit() const {
michael@0:             return index+length;
michael@0:         }
michael@0: 
michael@0:         /**
michael@0:          * Returns a value associated with this part.
michael@0:          * See the documentation of each part type for details.
michael@0:          * @return the part value.
michael@0:          * @stable ICU 4.8
michael@0:          */
michael@0:         int32_t getValue() const {
michael@0:             return value;
michael@0:         }
michael@0: 
michael@0:         /**
michael@0:          * Returns the argument type if this part is of type ARG_START or ARG_LIMIT,
michael@0:          * otherwise UMSGPAT_ARG_TYPE_NONE.
michael@0:          * @return the argument type for this part.
michael@0:          * @stable ICU 4.8
michael@0:          */
michael@0:         UMessagePatternArgType getArgType() const {
michael@0:             UMessagePatternPartType type=getType();
michael@0:             if(type==UMSGPAT_PART_TYPE_ARG_START || type==UMSGPAT_PART_TYPE_ARG_LIMIT) {
michael@0:                 return (UMessagePatternArgType)value;
michael@0:             } else {
michael@0:                 return UMSGPAT_ARG_TYPE_NONE;
michael@0:             }
michael@0:         }
michael@0: 
michael@0:         /**
michael@0:          * Indicates whether the Part type has a numeric value.
michael@0:          * If so, then that numeric value can be retrieved via MessagePattern.getNumericValue().
michael@0:          * @param type The Part type to be tested.
michael@0:          * @return TRUE if the Part type has a numeric value.
michael@0:          * @stable ICU 4.8
michael@0:          */
michael@0:         static UBool hasNumericValue(UMessagePatternPartType type) {
michael@0:             return type==UMSGPAT_PART_TYPE_ARG_INT || type==UMSGPAT_PART_TYPE_ARG_DOUBLE;
michael@0:         }
michael@0: 
michael@0:         /**
michael@0:          * @param other another object to compare with.
michael@0:          * @return TRUE if this object is equivalent to the other one.
michael@0:          * @stable ICU 4.8
michael@0:          */
michael@0:         UBool operator==(const Part &other) const;
michael@0: 
michael@0:         /**
michael@0:          * @param other another object to compare with.
michael@0:          * @return FALSE if this object is equivalent to the other one.
michael@0:          * @stable ICU 4.8
michael@0:          */
michael@0:         inline UBool operator!=(const Part &other) const {
michael@0:             return !operator==(other);
michael@0:         }
michael@0: 
michael@0:         /**
michael@0:          * @return A hash code for this object.
michael@0:          * @stable ICU 4.8
michael@0:          */
michael@0:         int32_t hashCode() const {
michael@0:             return ((type*37+index)*37+length)*37+value;
michael@0:         }
michael@0: 
michael@0:     private:
michael@0:         friend class MessagePattern;
michael@0: 
michael@0:         static const int32_t MAX_LENGTH=0xffff;
michael@0:         static const int32_t MAX_VALUE=0x7fff;
michael@0: 
michael@0:         // Some fields are not final because they are modified during pattern parsing.
michael@0:         // After pattern parsing, the parts are effectively immutable.
michael@0:         UMessagePatternPartType type;
michael@0:         int32_t index;
michael@0:         uint16_t length;
michael@0:         int16_t value;
michael@0:         int32_t limitPartIndex;
michael@0:     };
michael@0: 
michael@0: private:
michael@0:     void preParse(const UnicodeString &pattern, UParseError *parseError, UErrorCode &errorCode);
michael@0: 
michael@0:     void postParse();
michael@0: 
michael@0:     int32_t parseMessage(int32_t index, int32_t msgStartLength,
michael@0:                          int32_t nestingLevel, UMessagePatternArgType parentType,
michael@0:                          UParseError *parseError, UErrorCode &errorCode);
michael@0: 
michael@0:     int32_t parseArg(int32_t index, int32_t argStartLength, int32_t nestingLevel,
michael@0:                      UParseError *parseError, UErrorCode &errorCode);
michael@0: 
michael@0:     int32_t parseSimpleStyle(int32_t index, UParseError *parseError, UErrorCode &errorCode);
michael@0: 
michael@0:     int32_t parseChoiceStyle(int32_t index, int32_t nestingLevel,
michael@0:                              UParseError *parseError, UErrorCode &errorCode);
michael@0: 
michael@0:     int32_t parsePluralOrSelectStyle(UMessagePatternArgType argType, int32_t index, int32_t nestingLevel,
michael@0:                                      UParseError *parseError, UErrorCode &errorCode);
michael@0: 
michael@0:     /**
michael@0:      * Validates and parses an argument name or argument number string.
michael@0:      * This internal method assumes that the input substring is a "pattern identifier".
michael@0:      * @return &gt;=0 if the name is a valid number,
michael@0:      *         ARG_NAME_NOT_NUMBER (-1) if it is a "pattern identifier" but not all ASCII digits,
michael@0:      *         ARG_NAME_NOT_VALID (-2) if it is neither.
michael@0:      * @see #validateArgumentName(String)
michael@0:      */
michael@0:     static int32_t parseArgNumber(const UnicodeString &s, int32_t start, int32_t limit);
michael@0: 
michael@0:     int32_t parseArgNumber(int32_t start, int32_t limit) {
michael@0:         return parseArgNumber(msg, start, limit);
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Parses a number from the specified message substring.
michael@0:      * @param start start index into the message string
michael@0:      * @param limit limit index into the message string, must be start<limit
michael@0:      * @param allowInfinity TRUE if U+221E is allowed (for ChoiceFormat)
michael@0:      * @param parseError
michael@0:      * @param errorCode
michael@0:      */
michael@0:     void parseDouble(int32_t start, int32_t limit, UBool allowInfinity,
michael@0:                      UParseError *parseError, UErrorCode &errorCode);
michael@0: 
michael@0:     // Java has package-private appendReducedApostrophes() here.
michael@0:     // In C++, this is declared in the MessageImpl class.
michael@0: 
michael@0:     int32_t skipWhiteSpace(int32_t index);
michael@0: 
michael@0:     int32_t skipIdentifier(int32_t index);
michael@0: 
michael@0:     /**
michael@0:      * Skips a sequence of characters that could occur in a double value.
michael@0:      * Does not fully parse or validate the value.
michael@0:      */
michael@0:     int32_t skipDouble(int32_t index);
michael@0: 
michael@0:     static UBool isArgTypeChar(UChar32 c);
michael@0: 
michael@0:     UBool isChoice(int32_t index);
michael@0: 
michael@0:     UBool isPlural(int32_t index);
michael@0: 
michael@0:     UBool isSelect(int32_t index);
michael@0: 
michael@0:     UBool isOrdinal(int32_t index);
michael@0: 
michael@0:     /**
michael@0:      * @return TRUE if we are inside a MessageFormat (sub-)pattern,
michael@0:      *         as opposed to inside a top-level choice/plural/select pattern.
michael@0:      */
michael@0:     UBool inMessageFormatPattern(int32_t nestingLevel);
michael@0: 
michael@0:     /**
michael@0:      * @return TRUE if we are in a MessageFormat sub-pattern
michael@0:      *         of a top-level ChoiceFormat pattern.
michael@0:      */
michael@0:     UBool inTopLevelChoiceMessage(int32_t nestingLevel, UMessagePatternArgType parentType);
michael@0: 
michael@0:     void addPart(UMessagePatternPartType type, int32_t index, int32_t length,
michael@0:                  int32_t value, UErrorCode &errorCode);
michael@0: 
michael@0:     void addLimitPart(int32_t start,
michael@0:                       UMessagePatternPartType type, int32_t index, int32_t length,
michael@0:                       int32_t value, UErrorCode &errorCode);
michael@0: 
michael@0:     void addArgDoublePart(double numericValue, int32_t start, int32_t length, UErrorCode &errorCode);
michael@0: 
michael@0:     void setParseError(UParseError *parseError, int32_t index);
michael@0: 
michael@0:     UBool init(UErrorCode &errorCode);
michael@0:     UBool copyStorage(const MessagePattern &other, UErrorCode &errorCode);
michael@0: 
michael@0:     UMessagePatternApostropheMode aposMode;
michael@0:     UnicodeString msg;
michael@0:     // ArrayList<Part> parts=new ArrayList<Part>();
michael@0:     MessagePatternPartsList *partsList;
michael@0:     Part *parts;
michael@0:     int32_t partsLength;
michael@0:     // ArrayList<Double> numericValues;
michael@0:     MessagePatternDoubleList *numericValuesList;
michael@0:     double *numericValues;
michael@0:     int32_t numericValuesLength;
michael@0:     UBool hasArgNames;
michael@0:     UBool hasArgNumbers;
michael@0:     UBool needsAutoQuoting;
michael@0: };
michael@0: 
michael@0: U_NAMESPACE_END
michael@0: 
michael@0: #endif  // !UCONFIG_NO_FORMATTING
michael@0: 
michael@0: #endif  // __MESSAGEPATTERN_H__