jpayne@69: // © 2016 and later: Unicode, Inc. and others. jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html jpayne@69: /******************************************************************** jpayne@69: * COPYRIGHT: jpayne@69: * Copyright (c) 1997-2011, International Business Machines Corporation and jpayne@69: * others. All Rights Reserved. jpayne@69: * Copyright (C) 2010 , Yahoo! Inc. jpayne@69: ******************************************************************** jpayne@69: * jpayne@69: * File SELFMT.H jpayne@69: * jpayne@69: * Modification History: jpayne@69: * jpayne@69: * Date Name Description jpayne@69: * 11/11/09 kirtig Finished first cut of implementation. jpayne@69: ********************************************************************/ jpayne@69: jpayne@69: #ifndef SELFMT jpayne@69: #define SELFMT jpayne@69: jpayne@69: #include "unicode/utypes.h" jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: jpayne@69: #include "unicode/messagepattern.h" jpayne@69: #include "unicode/numfmt.h" jpayne@69: jpayne@69: /** jpayne@69: * \file jpayne@69: * \brief C++ API: SelectFormat object jpayne@69: */ jpayne@69: jpayne@69: #if !UCONFIG_NO_FORMATTING jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: class MessageFormat; jpayne@69: jpayne@69: /** jpayne@69: *

SelectFormat supports the creation of internationalized jpayne@69: * messages by selecting phrases based on keywords. The pattern specifies jpayne@69: * how to map keywords to phrases and provides a default phrase. The jpayne@69: * object provided to the format method is a string that's matched jpayne@69: * against the keywords. If there is a match, the corresponding phrase jpayne@69: * is selected; otherwise, the default phrase is used.

jpayne@69: * jpayne@69: *

Using SelectFormat for Gender Agreement

jpayne@69: * jpayne@69: *

Note: Typically, select formatting is done via MessageFormat jpayne@69: * with a select argument type, jpayne@69: * rather than using a stand-alone SelectFormat.

jpayne@69: * jpayne@69: *

The main use case for the select format is gender based inflection. jpayne@69: * When names or nouns are inserted into sentences, their gender can affect pronouns, jpayne@69: * verb forms, articles, and adjectives. Special care needs to be jpayne@69: * taken for the case where the gender cannot be determined. jpayne@69: * The impact varies between languages:

jpayne@69: * \htmlonly jpayne@69: * jpayne@69: * \endhtmlonly jpayne@69: *

Some other languages have noun classes that are not related to gender, jpayne@69: * but similar in grammatical use. jpayne@69: * Some African languages have around 20 noun classes.

jpayne@69: * jpayne@69: *

Note:For the gender of a person in a given sentence, jpayne@69: * we usually need to distinguish only between female, male and other/unknown.

jpayne@69: * jpayne@69: *

To enable localizers to create sentence patterns that take their jpayne@69: * language's gender dependencies into consideration, software has to provide jpayne@69: * information about the gender associated with a noun or name to jpayne@69: * MessageFormat. jpayne@69: * Two main cases can be distinguished:

jpayne@69: * jpayne@69: * jpayne@69: * jpayne@69: *

The resulting keyword is provided to MessageFormat as a jpayne@69: * parameter separate from the name or noun it's associated with. For example, jpayne@69: * to generate a message such as "Jean went to Paris", three separate arguments jpayne@69: * would be provided: The name of the person as argument 0, the gender of jpayne@69: * the person as argument 1, and the name of the city as argument 2. jpayne@69: * The sentence pattern for English, where the gender of the person has jpayne@69: * no impact on this simple sentence, would not refer to argument 1 at all:

jpayne@69: * jpayne@69: * 
{0} went to {2}.
jpayne@69: * jpayne@69: *

Note: The entire sentence should be included (and partially repeated) jpayne@69: * inside each phrase. Otherwise translators would have to be trained on how to jpayne@69: * move bits of the sentence in and out of the select argument of a message. jpayne@69: * (The examples below do not follow this recommendation!)

jpayne@69: * jpayne@69: *

The sentence pattern for French, where the gender of the person affects jpayne@69: * the form of the participle, uses a select format based on argument 1:

jpayne@69: * jpayne@69: * \htmlonly
{0} est {1, select, female {allée} other {allé}} à {2}.
\endhtmlonly jpayne@69: * jpayne@69: *

Patterns can be nested, so that it's possible to handle interactions of jpayne@69: * number and gender where necessary. For example, if the above sentence should jpayne@69: * allow for the names of several people to be inserted, the following sentence jpayne@69: * pattern can be used (with argument 0 the list of people's names, jpayne@69: * argument 1 the number of people, argument 2 their combined gender, and jpayne@69: * argument 3 the city name):

jpayne@69: * jpayne@69: * \htmlonly jpayne@69: * 
{0} {1, plural,
jpayne@69:   *                 one {est {2, select, female {allée} other  {allé}}}
jpayne@69:   *                 other {sont {2, select, female {allées} other {allés}}}
jpayne@69:   *          }à {3}.
jpayne@69: * \endhtmlonly jpayne@69: * jpayne@69: *

Patterns and Their Interpretation

jpayne@69: * jpayne@69: *

The SelectFormat pattern string defines the phrase output jpayne@69: * for each user-defined keyword. jpayne@69: * The pattern is a sequence of (keyword, message) pairs. jpayne@69: * A keyword is a "pattern identifier": [^[[:Pattern_Syntax:][:Pattern_White_Space:]]]+

jpayne@69: * jpayne@69: *

Each message is a MessageFormat pattern string enclosed in {curly braces}.

jpayne@69: * jpayne@69: *

You always have to define a phrase for the default keyword jpayne@69: * other; this phrase is returned when the keyword jpayne@69: * provided to jpayne@69: * the format method matches no other keyword. jpayne@69: * If a pattern does not provide a phrase for other, the method jpayne@69: * it's provided to returns the error U_DEFAULT_KEYWORD_MISSING. jpayne@69: *
jpayne@69: * Pattern_White_Space between keywords and messages is ignored. jpayne@69: * Pattern_White_Space within a message is preserved and output.

jpayne@69: * jpayne@69: * 

Example:
jpayne@69:   * \htmlonly
jpayne@69:   *
jpayne@69:   * UErrorCode status = U_ZERO_ERROR;
jpayne@69:   * MessageFormat *msgFmt = new MessageFormat(UnicodeString("{0} est  {1, select, female {allée} other {allé}} à Paris."), Locale("fr"),  status);
jpayne@69:   * if (U_FAILURE(status)) {
jpayne@69:   *       return;
jpayne@69:   * }
jpayne@69:   * FieldPosition ignore(FieldPosition::DONT_CARE);
jpayne@69:   * UnicodeString result;
jpayne@69:   *
jpayne@69:   * char* str1= "Kirti,female";
jpayne@69:   * Formattable args1[] = {"Kirti","female"};
jpayne@69:   * msgFmt->format(args1, 2, result, ignore, status);
jpayne@69:   * cout << "Input is " << str1 << " and result is: " << result << endl;
jpayne@69:   * delete msgFmt;
jpayne@69:   *
jpayne@69:   * \endhtmlonly
jpayne@69:   *
jpayne@69: *

jpayne@69: * jpayne@69: * Produces the output:
jpayne@69: * \htmlonly jpayne@69: * Kirti est allée à Paris. jpayne@69: * \endhtmlonly jpayne@69: * jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: jpayne@69: class U_I18N_API SelectFormat : public Format { jpayne@69: public: jpayne@69: jpayne@69: /** jpayne@69: * Creates a new SelectFormat for a given pattern string. jpayne@69: * @param pattern the pattern for this SelectFormat. jpayne@69: * errors are returned to status if the pattern is invalid. jpayne@69: * @param status output param set to success/failure code on exit, which jpayne@69: * must not indicate a failure before the function call. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: SelectFormat(const UnicodeString& pattern, UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * copy constructor. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: SelectFormat(const SelectFormat& other); jpayne@69: jpayne@69: /** jpayne@69: * Destructor. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: virtual ~SelectFormat(); jpayne@69: jpayne@69: /** jpayne@69: * Sets the pattern used by this select format. jpayne@69: * for the keyword rules. jpayne@69: * Patterns and their interpretation are specified in the class description. jpayne@69: * jpayne@69: * @param pattern the pattern for this select format jpayne@69: * errors are returned to status if the pattern is invalid. jpayne@69: * @param status output param set to success/failure code on exit, which jpayne@69: * must not indicate a failure before the function call. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: void applyPattern(const UnicodeString& pattern, UErrorCode& status); jpayne@69: jpayne@69: jpayne@69: using Format::format; jpayne@69: jpayne@69: /** jpayne@69: * Selects the phrase for the given keyword jpayne@69: * jpayne@69: * @param keyword The keyword that is used to select an alternative. jpayne@69: * @param appendTo output parameter to receive result. jpayne@69: * result is appended to existing contents. jpayne@69: * @param pos On input: an alignment field, if desired. jpayne@69: * On output: the offsets of the alignment field. jpayne@69: * @param status output param set to success/failure code on exit, which jpayne@69: * must not indicate a failure before the function call. jpayne@69: * @return Reference to 'appendTo' parameter. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: UnicodeString& format(const UnicodeString& keyword, jpayne@69: UnicodeString& appendTo, jpayne@69: FieldPosition& pos, jpayne@69: UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * Assignment operator jpayne@69: * jpayne@69: * @param other the SelectFormat object to copy from. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: SelectFormat& operator=(const SelectFormat& other); jpayne@69: jpayne@69: /** jpayne@69: * Return true if another object is semantically equal to this one. jpayne@69: * jpayne@69: * @param other the SelectFormat object to be compared with. jpayne@69: * @return true if other is semantically equal to this. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: virtual UBool operator==(const Format& other) const; jpayne@69: jpayne@69: /** jpayne@69: * Return true if another object is semantically unequal to this one. jpayne@69: * jpayne@69: * @param other the SelectFormat object to be compared with. jpayne@69: * @return true if other is semantically unequal to this. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: virtual UBool operator!=(const Format& other) const; jpayne@69: jpayne@69: /** jpayne@69: * Clones this Format object polymorphically. The caller owns the jpayne@69: * result and should delete it when done. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: virtual SelectFormat* clone() const; jpayne@69: jpayne@69: /** jpayne@69: * Format an object to produce a string. jpayne@69: * This method handles keyword strings. jpayne@69: * If the Formattable object is not a UnicodeString, jpayne@69: * then it returns a failing UErrorCode. jpayne@69: * jpayne@69: * @param obj A keyword string that is used to select an alternative. jpayne@69: * @param appendTo output parameter to receive result. jpayne@69: * Result is appended to existing contents. jpayne@69: * @param pos On input: an alignment field, if desired. jpayne@69: * On output: the offsets of the alignment field. jpayne@69: * @param status output param filled with success/failure status. jpayne@69: * @return Reference to 'appendTo' parameter. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: UnicodeString& format(const Formattable& obj, jpayne@69: UnicodeString& appendTo, jpayne@69: FieldPosition& pos, jpayne@69: UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * Returns the pattern from applyPattern() or constructor. jpayne@69: * jpayne@69: * @param appendTo output parameter to receive result. jpayne@69: * Result is appended to existing contents. jpayne@69: * @return the UnicodeString with inserted pattern. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: UnicodeString& toPattern(UnicodeString& appendTo); jpayne@69: jpayne@69: /** jpayne@69: * This method is not yet supported by SelectFormat. jpayne@69: *

jpayne@69: * Before calling, set parse_pos.index to the offset you want to start jpayne@69: * parsing at in the source. After calling, parse_pos.index is the end of jpayne@69: * the text you parsed. If error occurs, index is unchanged. jpayne@69: *

jpayne@69: * When parsing, leading whitespace is discarded (with a successful parse), jpayne@69: * while trailing whitespace is left as is. jpayne@69: *

jpayne@69: * See Format::parseObject() for more. jpayne@69: * jpayne@69: * @param source The string to be parsed into an object. jpayne@69: * @param result Formattable to be set to the parse result. jpayne@69: * If parse fails, return contents are undefined. jpayne@69: * @param parse_pos The position to start parsing at. Upon return jpayne@69: * this param is set to the position after the jpayne@69: * last character successfully parsed. If the jpayne@69: * source is not parsed successfully, this param jpayne@69: * will remain unchanged. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: virtual void parseObject(const UnicodeString& source, jpayne@69: Formattable& result, jpayne@69: ParsePosition& parse_pos) const; jpayne@69: jpayne@69: /** jpayne@69: * ICU "poor man's RTTI", returns a UClassID for this class. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: static UClassID U_EXPORT2 getStaticClassID(void); jpayne@69: jpayne@69: /** jpayne@69: * ICU "poor man's RTTI", returns a UClassID for the actual class. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: virtual UClassID getDynamicClassID() const; jpayne@69: jpayne@69: private: jpayne@69: friend class MessageFormat; jpayne@69: jpayne@69: SelectFormat(); // default constructor not implemented. jpayne@69: jpayne@69: /** jpayne@69: * Finds the SelectFormat sub-message for the given keyword, or the "other" sub-message. jpayne@69: * @param pattern A MessagePattern. jpayne@69: * @param partIndex the index of the first SelectFormat argument style part. jpayne@69: * @param keyword a keyword to be matched to one of the SelectFormat argument's keywords. jpayne@69: * @param ec Error code. jpayne@69: * @return the sub-message start part index. jpayne@69: */ jpayne@69: static int32_t findSubMessage(const MessagePattern& pattern, int32_t partIndex, jpayne@69: const UnicodeString& keyword, UErrorCode& ec); jpayne@69: jpayne@69: MessagePattern msgPattern; jpayne@69: }; jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif /* #if !UCONFIG_NO_FORMATTING */ jpayne@69: jpayne@69: #endif /* U_SHOW_CPLUSPLUS_API */ jpayne@69: jpayne@69: #endif // _SELFMT jpayne@69: //eof