// © 2016 and later: Unicode, Inc. and others. // License & terms of use: http://www.unicode.org/copyright.html /* ******************************************************************************* * Copyright (C) 2007-2014, International Business Machines Corporation and * others. All Rights Reserved. ******************************************************************************* * * File PLURFMT.H ******************************************************************************** */ #ifndef PLURFMT #define PLURFMT #include "unicode/utypes.h" #if U_SHOW_CPLUSPLUS_API /** * \file * \brief C++ API: PluralFormat object */ #if !UCONFIG_NO_FORMATTING #include "unicode/messagepattern.h" #include "unicode/numfmt.h" #include "unicode/plurrule.h" U_NAMESPACE_BEGIN class Hashtable; class NFRule; /** * <p> * <code>PluralFormat</code> supports the creation of internationalized * messages with plural inflection. It is based on <i>plural * selection</i>, i.e. the caller specifies messages for each * plural case that can appear in the user's language and the * <code>PluralFormat</code> selects the appropriate message based on * the number. * </p> * <h4>The Problem of Plural Forms in Internationalized Messages</h4> * <p> * Different languages have different ways to inflect * plurals. Creating internationalized messages that include plural * forms is only feasible when the framework is able to handle plural * forms of <i>all</i> languages correctly. <code>ChoiceFormat</code> * doesn't handle this well, because it attaches a number interval to * each message and selects the message whose interval contains a * given number. This can only handle a finite number of * intervals. But in some languages, like Polish, one plural case * applies to infinitely many intervals (e.g., the plural case applies to * numbers ending with 2, 3, or 4 except those ending with 12, 13, or * 14). Thus <code>ChoiceFormat</code> is not adequate. * </p><p> * <code>PluralFormat</code> deals with this by breaking the problem * into two parts: * <ul> * <li>It uses <code>PluralRules</code> that can define more complex * conditions for a plural case than just a single interval. These plural * rules define both what plural cases exist in a language, and to * which numbers these cases apply. * <li>It provides predefined plural rules for many languages. Thus, the programmer * need not worry about the plural cases of a language and * does not have to define the plural cases; they can simply * use the predefined keywords. The whole plural formatting of messages can * be done using localized patterns from resource bundles. For predefined plural * rules, see the CLDR <i>Language Plural Rules</i> page at * https://unicode-org.github.io/cldr-staging/charts/latest/supplemental/language_plural_rules.html * </ul> * </p> * <h4>Usage of <code>PluralFormat</code></h4> * <p>Note: Typically, plural formatting is done via <code>MessageFormat</code> * with a <code>plural</code> argument type, * rather than using a stand-alone <code>PluralFormat</code>. * </p><p> * This discussion assumes that you use <code>PluralFormat</code> with * a predefined set of plural rules. You can create one using one of * the constructors that takes a <code>locale</code> object. To * specify the message pattern, you can either pass it to the * constructor or set it explicitly using the * <code>applyPattern()</code> method. The <code>format()</code> * method takes a number object and selects the message of the * matching plural case. This message will be returned. * </p> * <h5>Patterns and Their Interpretation</h5> * <p> * The pattern text defines the message output for each plural case of the * specified locale. Syntax: * <pre> * pluralStyle = [offsetValue] (selector '{' message '}')+ * offsetValue = "offset:" number * selector = explicitValue | keyword * explicitValue = '=' number // adjacent, no white space in between * keyword = [^[[:Pattern_Syntax:][:Pattern_White_Space:]]]+ * message: see {@link MessageFormat} * </pre> * Pattern_White_Space between syntax elements is ignored, except * between the {curly braces} and their sub-message, * and between the '=' and the number of an explicitValue. * * </p><p> * There are 6 predefined casekeyword in CLDR/ICU - 'zero', 'one', 'two', 'few', 'many' and * 'other'. You always have to define a message text for the default plural case * <code>other</code> which is contained in every rule set. * If you do not specify a message text for a particular plural case, the * message text of the plural case <code>other</code> gets assigned to this * plural case. * </p><p> * When formatting, the input number is first matched against the explicitValue clauses. * If there is no exact-number match, then a keyword is selected by calling * the <code>PluralRules</code> with the input number <em>minus the offset</em>. * (The offset defaults to 0 if it is omitted from the pattern string.) * If there is no clause with that keyword, then the "other" clauses is returned. * </p><p> * An unquoted pound sign (<code>#</code>) in the selected sub-message * itself (i.e., outside of arguments nested in the sub-message) * is replaced by the input number minus the offset. * The number-minus-offset value is formatted using a * <code>NumberFormat</code> for the <code>PluralFormat</code>'s locale. If you * need special number formatting, you have to use a <code>MessageFormat</code> * and explicitly specify a <code>NumberFormat</code> argument. * <strong>Note:</strong> That argument is formatting without subtracting the offset! * If you need a custom format and have a non-zero offset, then you need to pass the * number-minus-offset value as a separate parameter. * </p> * For a usage example, see the {@link MessageFormat} class documentation. * * <h4>Defining Custom Plural Rules</h4> * <p>If you need to use <code>PluralFormat</code> with custom rules, you can * create a <code>PluralRules</code> object and pass it to * <code>PluralFormat</code>'s constructor. If you also specify a locale in this * constructor, this locale will be used to format the number in the message * texts. * </p><p> * For more information about <code>PluralRules</code>, see * {@link PluralRules}. * </p> * * ported from Java * @stable ICU 4.0 */ class U_I18N_API PluralFormat : public Format { … }; U_NAMESPACE_END #endif /* #if !UCONFIG_NO_FORMATTING */ #endif /* U_SHOW_CPLUSPLUS_API */ #endif // _PLURFMT //eof