SelectFormat supports the creation of internationalized
* messages by selecting phrases based on keywords. The pattern specifies
* how to map keywords to phrases and provides a default phrase. The
* object provided to the format method is a string that's matched
* against the keywords. If there is a match, the corresponding phrase
* is selected; otherwise, the default phrase is used.
SelectFormat for Gender AgreementThe main use case for the select format is gender based inflection. * When names or nouns are inserted into sentences, their gender can affect pronouns, * verb forms, articles, and adjectives. Special care needs to be * taken for the case where the gender cannot be determined. * The impact varies between languages:
* *Some other languages have noun classes that are not related to gender, * but similar in grammatical use. * Some African languages have around 20 noun classes.
* *To enable localizers to create sentence patterns that take their
* language's gender dependencies into consideration, software has to provide
* information about the gender associated with a noun or name to
* MessageFormat.
* Two main cases can be distinguished:
The resulting keyword is provided to MessageFormat as a
* parameter separate from the name or noun it's associated with. For example,
* to generate a message such as "Jean went to Paris", three separate arguments
* would be provided: The name of the person as argument 0, the gender of
* the person as argument 1, and the name of the city as argument 2.
* The sentence pattern for English, where the gender of the person has
* no impact on this simple sentence, would not refer to argument 1 at all:
{0} went to {2}.
*
* The sentence pattern for French, where the gender of the person affects * the form of the participle, uses a select format based on argument 1:
* *{0} est {1, select, female {all&#u00E9;e} other {all&#u00E9;}} &#u00E0; {2}.
*
* Patterns can be nested, so that it's possible to handle interactions of * number and gender where necessary. For example, if the above sentence should * allow for the names of several people to be inserted, the following sentence * pattern can be used (with argument 0 the list of people's names, * argument 1 the number of people, argument 2 their combined gender, and * argument 3 the city name):
* *{0} {1, plural,
* one {est {2, select, female {all&#u00E9;e} other {all&#u00E9;}}}
* other {sont {2, select, female {all&#u00E9;es} other {all&#u00E9;s}}}
* }&#u00E0; {3}.
*
* The SelectFormat pattern text defines the phrase output
* for each user-defined keyword.
* The pattern is a sequence of keyword{phrase}
* clauses.
* Each clause assigns the phrase phrase
* to the user-defined keyword.
Keywords must match the pattern [a-zA-Z][a-zA-Z0-9_-]*; keywords
* that don't match this pattern result in the error code
* U_ILLEGAL_CHARACTER.
* You always have to define a phrase for the default keyword
* other; this phrase is returned when the keyword
* provided to
* the format method matches no other keyword.
* If a pattern does not provide a phrase for other, the method
* it's provided to returns the error U_DEFAULT_KEYWORD_MISSING.
* If a pattern provides more than one phrase for the same keyword, the
* error U_DUPLICATE_KEYWORD is returned.
*
* Spaces between keyword and
* {phrase} will be ignored; spaces within
* {phrase} will be preserved.
* *
The phrase for a particular select case may contain other message
* format patterns. SelectFormat preserves these so that you
* can use the strings produced by SelectFormat with other
* formatters. If you are using SelectFormat inside a
* MessageFormat pattern, MessageFormat will
* automatically evaluate the resulting format pattern.
* Thus, curly braces ({, }) are only allowed
* in phrases to define a nested format pattern.
Example: *
*
* UErrorCode status = U_ZERO_ERROR;
* MessageFormat *msgFmt = new MessageFormat(UnicodeString("{0} est {1, select, female {all&#u00E9;e} other {all&#u00E9;}} &#u00E0; Paris."), Locale("fr"), status);
* if (U_FAILURE(status)) {
* return;
* }
* FieldPosition ignore(FieldPosition::DONT_CARE);
* UnicodeString result;
*
* char* str1= "Kirti,female";
* Formattable args1[] = {"Kirti","female"};
* msgFmt->format(args1, 2, result, ignore, status);
* cout << "Input is " << str1 << " and result is: " << result << endl;
* delete msgFmt;
*
*
* Produces the output:Input is Kirti,female and result is: Kirti est all&#u00E9;e &#u00E0; Paris.
*
* @draft ICU 4.4
*/
class U_I18N_API SelectFormat : public Format {
public:
/**
* Creates a new SelectFormat .
* @param status output param set to success/failure code on exit, which
* must not indicate a failure before the function call.
* @draft ICU 4.4
*/
SelectFormat(UErrorCode& status);
/**
* Creates a new SelectFormat for a given pattern string.
* @param pattern the pattern for this SelectFormat.
* errors are returned to status if the pattern is invalid.
* @param status output param set to success/failure code on exit, which
* must not indicate a failure before the function call.
* @draft ICU 4.4
*/
SelectFormat(const UnicodeString& pattern, UErrorCode& status);
/**
* copy constructor.
* @draft ICU 4.4
*/
SelectFormat(const SelectFormat& other);
/**
* Destructor.
* @draft ICU 4.4
*/
virtual ~SelectFormat();
/**
* Sets the pattern used by this select format.
* for the keyword rules.
* Patterns and their interpretation are specified in the class description.
*
* @param pattern the pattern for this select format
* errors are returned to status if the pattern is invalid.
* @param status output param set to success/failure code on exit, which
* must not indicate a failure before the function call.
* @draft ICU 4.4
*/
void applyPattern(const UnicodeString& pattern, UErrorCode& status);
/**
* Selects the phrase for the given keyword
*
* @param keyword The keyword that is used to select an alternative.
* @param appendTo output parameter to receive result.
* result is appended to existing contents.
* @param pos On input: an alignment field, if desired.
* On output: the offsets of the alignment field.
* @param status output param set to success/failure code on exit, which
* must not indicate a failure before the function call.
* @return Reference to 'appendTo' parameter.
* @draft ICU 4.4
*/
UnicodeString& format(const UnicodeString& keyword,
UnicodeString& appendTo,
FieldPosition& pos,
UErrorCode& status) const;
/**
* Assignment operator
*
* @param other the SelectFormat object to copy from.
* @draft ICU 4.4
*/
SelectFormat& operator=(const SelectFormat& other);
/**
* Return true if another object is semantically equal to this one.
*
* @param other the SelectFormat object to be compared with.
* @return true if other is semantically equal to this.
* @draft ICU 4.4
*/
virtual UBool operator==(const Format& other) const;
/**
* Return true if another object is semantically unequal to this one.
*
* @param other the SelectFormat object to be compared with.
* @return true if other is semantically unequal to this.
* @draft ICU 4.4
*/
virtual UBool operator!=(const Format& other) const;
/**
* Clones this Format object polymorphically. The caller owns the
* result and should delete it when done.
* @draft ICU 4.4
*/
virtual Format* clone(void) const;
/**
* Format an object to produce a string.
* This method handles keyword strings.
* If the Formattable object is not a UnicodeString,
* then it returns a failing UErrorCode.
*
* @param obj A keyword string that is used to select an alternative.
* @param appendTo output parameter to receive result.
* Result is appended to existing contents.
* @param pos On input: an alignment field, if desired.
* On output: the offsets of the alignment field.
* @param status output param filled with success/failure status.
* @return Reference to 'appendTo' parameter.
* @draft ICU 4.4
*/
UnicodeString& format(const Formattable& obj,
UnicodeString& appendTo,
FieldPosition& pos,
UErrorCode& status) const;
/**
* Returns the pattern from applyPattern() or constructor.
*
* @param appendTo output parameter to receive result.
* Result is appended to existing contents.
* @return the UnicodeString with inserted pattern.
* @draft ICU 4.4
*/
UnicodeString& toPattern(UnicodeString& appendTo);
/**
* This method is not yet supported by SelectFormat.
*
* Before calling, set parse_pos.index to the offset you want to start
* parsing at in the source. After calling, parse_pos.index is the end of
* the text you parsed. If error occurs, index is unchanged.
*
* When parsing, leading whitespace is discarded (with a successful parse),
* while trailing whitespace is left as is.
*
* See Format::parseObject() for more.
*
* @param source The string to be parsed into an object.
* @param result Formattable to be set to the parse result.
* If parse fails, return contents are undefined.
* @param parse_pos The position to start parsing at. Upon return
* this param is set to the position after the
* last character successfully parsed. If the
* source is not parsed successfully, this param
* will remain unchanged.
* @draft ICU 4.4
*/
virtual void parseObject(const UnicodeString& source,
Formattable& result,
ParsePosition& parse_pos) const;
/**
* ICU "poor man's RTTI", returns a UClassID for this class.
*/
static UClassID U_EXPORT2 getStaticClassID(void);
/**
* ICU "poor man's RTTI", returns a UClassID for the actual class.
* @draft ICU 4.4
*/
virtual UClassID getDynamicClassID() const;
private:
typedef enum characterClass{
tStartKeyword,
tContinueKeyword,
tLeftBrace,
tRightBrace,
tSpace,
tOther
}characterClass;
UnicodeString pattern;
//Hash to store the keyword, phrase pairs
Hashtable *parsedValuesHash;
SelectFormat(); // default constructor not implemented
void init(UErrorCode& status);
//For the applyPattern , classifies char.s in one of the characterClass
void classifyCharacter(UChar ch, characterClass& type) const;
//Checks if the "other" keyword is present in pattern
UBool checkSufficientDefinition();
//Checks if the keyword passed is valid
UBool checkValidKeyword(const UnicodeString& argKeyword) const;
void parsingFailure();
void copyHashtable(Hashtable *other, UErrorCode& status);
};
U_NAMESPACE_END
#endif /* #if !UCONFIG_NO_FORMATTING */
#endif // _SELFMT
//eof