Re: [icu-design] ICU 61 API Proposal: Add grouping strategies to NumberFormatter

[Shane C. <sf...@go...>]

Dear ICU team & users,

Based on feedback, the name of the fifth option in the GroupingStrategy
enum has been changed to "THOUSANDS" instead of "WESTERN".

Please provide feedback by 2018-02-13.

Shane

On Fri, Feb 2, 2018 at 10:30 PM, Shane Carr <sf...@go...> wrote:

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
> *Dear ICU team & users,I would like to propose the following API for: ICU
> 61Please provide feedback by: 2/6/2018Designated API reviewer:
> MarkusTicket: http://bugs.icu-project.org/trac/ticket/13400
> <http://bugs.icu-project.org/trac/ticket/13400>Figuring out the best API
> for grouping separators in number formatting is something that requires
> careful design, so it was not included in the ICU 60 NumberFormatter API.
> We are now ready with a proposal for what the options might look like.
> Like the rest of NumberFormatter, the options proposed for grouping
> separator strategies are designed so that clients use locale data whenever
> possible, and they cover most use cases that we have seen from clients.If
> anyone reading this has a suggestion for better names or another use case
> that isn't covered by the five options, please let me know.For more
> background, please refer back to the "Grouping Setters" section in the main
> NumberFormatter design
> doc:https://docs.google.com/document/d/1RCBg8c2PcdesQJCdw6xZ0UUE49BDkBjxHkgl6cZ_8us/edit#heading=h.lh8nw36mvtgj
> <https://docs.google.com/document/d/1RCBg8c2PcdesQJCdw6xZ0UUE49BDkBjxHkgl6cZ_8us/edit#heading=h.lh8nw36mvtgj>Here
> is the list of options, ICU4C first:/** * An enum declaring the strategy
> for when and how to display grouping separators (i.e., the * separator,
> often a comma or period, after every 2-3 powers of ten). The choices are
> several * pre-built strategies for different use cases that employ locale
> data whenever possible. Example * outputs for 1234 and 1234567 in
> <em>en-IN</em>: * * <ul> * <li>OFF: 1234 and 12345 * <li>MIN2: 1234 and
> 12,34,567 * <li>AUTO: 1,234 and 12,34,567 * <li>ON_ALIGNED: 1,234 and
> 12,34,567 * <li>WESTERN: 1,234 and 1,234,567 * </ul> * * <p> * The default
> is AUTO, which displays grouping separators unless the locale data says
> that grouping * is not customary. To force grouping for all numbers greater
> than 1000 consistently across locales, * use ON_ALIGNED. On the other hand,
> to display grouping less frequently than the default, use MIN2 * or OFF.
> See the docs of each option for details. * * <p> * Note: This enum
> specifies the strategy for grouping sizes. To set which character to use as
> the * grouping separator, use the "symbols" setter. * * @draft ICU 61
> */typedef enum UGroupingStrategy {    /**     * Do not display grouping
> separators in any locale.     *     * @draft ICU 61     */
>    UNUM_GROUPING_OFF,    /**     * Display grouping using locale defaults,
> except do not show grouping on values smaller than     * 10000 (such that
> there is a <em>minimum of two digits</em> before the first separator).
>     *     * <p>     * Note that locales may restrict grouping separators to
> be displayed only on 1 million or     * greater (for example, ee and hu) or
> disable grouping altogether (for example, bg currency).     *     * <p>
>     * Locale data is used to determine whether to separate larger numbers
> into groups of 2     * (customary in South Asia) or groups of 3 (customary
> in Europe and the Americas).     *     * @draft ICU 61     */
>    UNUM_GROUPING_MIN2,    /**     * Display grouping using the default
> strategy for all locales. This is the default behavior.     *     * <p>
>     * Note that locales may restrict grouping separators to be displayed
> only on 1 million or     * greater (for example, ee and hu) or disable
> grouping altogether (for example, bg currency).     *     * <p>     *
> Locale data is used to determine whether to separate larger numbers into
> groups of 2     * (customary in South Asia) or groups of 3 (customary in
> Europe and the Americas).     *     * @draft ICU 61     */
>    UNUM_GROUPING_AUTO,    /**     * Always display the grouping separator
> on values of at least 1000.     *     * <p>     * This option ignores the
> locale data that restricts or disables grouping, described in MIN2 and
>     * AUTO. This option may be useful to normalize the alignment of
> numbers, such as in a     * spreadsheet.     *     * <p>     * Locale data
> is used to determine whether to separate larger numbers into groups of 2
>     * (customary in South Asia) or groups of 3 (customary in Europe and the
> Americas).     *     * @draft ICU 61     */    UNUM_GROUPING_ON_ALIGNED,
>    /**     * Use the Western defaults: groups of 3 and enabled for all
> numbers 1000 or greater. Do not use     * locale data for determining the
> grouping strategy.     *     * @draft ICU 61     */
>    UNUM_GROUPING_WESTERN} UGroupingStrategy;Setter:template<typename
> Derived>class U_I18N_API NumberFormatterSettings {  public:    /**     *
> Specifies the grouping strategy to use when formatting numbers.     *     *
> <ul>     * <li>Default grouping: "12,300" and "1,230"     * <li>Grouping
> with at least 2 digits: "12,300" and "1230"     * <li>No grouping: "12300"
> and "1230"     * </ul>     *     * <p>     * The exact grouping widths will
> be chosen based on the locale.     *     * <p>     * Pass this method an
> element from the {@link UGroupingStrategy} enum. For example:     *     *
> <pre>     * NumberFormatter::with().grouping(UNUM_GROUPING_MIN2)     *
> </pre>     *     * The default is to perform grouping according to locale
> data; most locales, but not all locales,     * enable it by default.     *
>     * @param strategy     *            The grouping strategy to use.     *
> @return The fluent chain.     * @draft ICU 61     */    Derived
> grouping(const UGroupingStrategy &strategy) const;}and in ICU4J:    /**
>     * An enum declaring the strategy for when and how to display grouping
> separators (i.e., the     * separator, often a comma or period, after every
> 2-3 powers of ten). The choices are several     * pre-built strategies for
> different use cases that employ locale data whenever possible. Example
>     * outputs for 1234 and 1234567 in <em>en-IN</em>:     *     * <ul>
>     * <li>OFF: 1234 and 12345     * <li>MIN2: 1234 and 12,34,567     *
> <li>AUTO: 1,234 and 12,34,567     * <li>ON_ALIGNED: 1,234 and 12,34,567
>     * <li>WESTERN: 1,234 and 1,234,567     * </ul>     *     * <p>     *
> The default is AUTO, which displays grouping separators unless the locale
> data says that grouping     * is not customary. To force grouping for all
> numbers greater than 1000 consistently across locales,     * use
> ON_ALIGNED. On the other hand, to display grouping less frequently than the
> default, use MIN2     * or OFF. See the docs of each option for details.
>     *     * <p>     * Note: This enum specifies the strategy for grouping
> sizes. To set which character to use as the     * grouping separator, use
> the "symbols" setter.     *     * @draft ICU 61     * @provisional This API
> might change or be removed in a future release.     * @see NumberFormatter
>     */    public static enum GroupingStrategy {        /**         * Do not
> display grouping separators in any locale.         *         * @draft ICU
> 61         * @provisional This API might change or be removed in a future
> release.         * @see NumberFormatter         */        OFF,        /**
>         * Display grouping using locale defaults, except do not show
> grouping on values smaller than         * 10000 (such that there is a
> <em>minimum of two digits</em> before the first separator).         *
>         * <p>         * Note that locales may restrict grouping separators
> to be displayed only on 1 million or         * greater (for example, ee and
> hu) or disable grouping altogether (for example, bg currency).         *
>         * <p>         * Locale data is used to determine whether to
> separate larger numbers into groups of 2         * (customary in South
> Asia) or groups of 3 (customary in Europe and the Americas).         *
>         * @draft ICU 61         * @provisional This API might change or be
> removed in a future release.         * @see NumberFormatter         */
>        MIN2,        /**         * Display grouping using the default
> strategy for all locales. This is the default behavior.         *         *
> <p>         * Note that locales may restrict grouping separators to be
> displayed only on 1 million or         * greater (for example, ee and hu)
> or disable grouping altogether (for example, bg currency).         *
>         * <p>         * Locale data is used to determine whether to
> separate larger numbers into groups of 2         * (customary in South
> Asia) or groups of 3 (customary in Europe and the Americas).         *
>         * @draft ICU 61         * @provisional This API might change or be
> removed in a future release.         * @see NumberFormatter         */
>        AUTO,        /**         * Always display the grouping separator on
> values of at least 1000.         *         * <p>         * This option
> ignores the locale data that restricts or disables grouping, described in
> MIN2 and         * AUTO. This option may be useful to normalize the
> alignment of numbers, such as in a         * spreadsheet.         *
>         * <p>         * Locale data is used to determine whether to
> separate larger numbers into groups of 2         * (customary in South
> Asia) or groups of 3 (customary in Europe and the Americas).         *
>         * @draft ICU 61         * @provisional This API might change or be
> removed in a future release.         * @see NumberFormatter         */
>        ON_ALIGNED,        /**         * Use the Western defaults: groups of
> 3 and enabled for all numbers 1000 or greater. Do not use         * locale
> data for determining the grouping strategy.         *         * @draft ICU
> 61         * @provisional This API might change or be removed in a future
> release.         * @see NumberFormatter         */        WESTERN
>    }Setter:    /**     * Specifies the grouping strategy to use when
> formatting numbers.     *     * <ul>     * <li>Default grouping: "12,300"
> and "1,230"     * <li>Grouping with at least 2 digits: "12,300" and "1230"
>     * <li>No grouping: "12300" and "1230"     * </ul>     *     * <p>     *
> The exact grouping widths will be chosen based on the locale.     *     *
> <p>     * Pass this method an element from the {@link GroupingStrategy}
> enum. For example:     *     * <pre>     *
> NumberFormatter.with().grouping(GroupingStrategy.MIN2)     * </pre>     *
>     * The default is to perform grouping according to locale data; most
> locales, but not all locales,     * enable it by default.     *     *
> @param strategy     *            The grouping strategy to use.     *
> @return The fluent chain.     * @see GroupingStrategy     * @draft ICU 61
>     * @provisional This API might change or be removed in a future release.
>     */    public T grouping(GroupingStrategy strategy)Sincerely, Shane*
>
>