Menu
▾
▴
[icu-design] ICU 61 API Proposal: Add grouping strategies to NumberFormatter
|
From: Shane C. <sf...@go...> - 2018-02-03 06:30:39
|
*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* |
