[icu-design] ICU API proposal: ShortNumberFormat

[Mark D. ☕ <ma...@ma...>]

Dear ICU team & users,

I would like to propose the following API for: *ICU 49*
Please provide feedback by: *next Friday, 2011-08-26*
Designated API reviewer: *Markus*
Ticket: http://bugs.icu-project.org/trac/ticket/8460

------------------------------

public class *ShortNumberFormat*extends com.ibm.icu.text.DecimalFormat

The ShortNumberFormat produces abbreviated numbers, suitable for display in
environments will limited real estate. For example, 'Hits: 1.2B' instead of
'Hits: 1,200,000,000'. The format will be appropriate for the given
language, such as "1,2 Mrd." for German.

For numbers under 1000 trillion (under 10^15, such as 123,456,789,012,345),
the result will be short for supported languages. However, the result may
sometimes exceed 7 characters, such as when there are combining marks or
thin characters. In such cases, the visual width in fonts should still be
short.

By default, there are 2 significant digits. After creation, if more than
three significant digits are set (with setMaximumSignificantDigits), or if a
fixed number of digits are set (with setMaximumIntegerDigits or
setMaximumFractionDigits), then result may be wider.

At this time, negative numbers and parsing are not supported, and will
produce an UnsupportedOperationException.

*Open Issues:*

   - Should we rename to ShortDecimalFormat?
   - Should we add a getInstance method to NumberFormat?

------------------------------
ShortNumberFormat

public *ShortNumberFormat*(com.ibm.icu.util.ULocale locale)

Create a ShortNumberFormat appropriate for a locale.

*Parameters:*locale -
------------------------------
ShortNumberFormat

public *ShortNumberFormat*(java.util.Locale locale)

Create a ShortNumberFormat appropriate for a locale.

*Parameters:*locale -
------------------------------
ShortNumberFormat

public *ShortNumberFormat*(java.lang.String pattern,
                         com.ibm.icu.text.DecimalFormatSymbols formatSymbols,
                         java.lang.String[] prefix,
                         java.lang.String[] suffix,
                         long[] divisor,
                         java.util.Collection<java.lang.String>
debugCreationErrors)

Create a short number "from scratch". Intended for internal use. The prefix,
suffix, and divisor arrays are parallel, and provide the information for
each power of 10. When formatting a value, the correct power of 10 is found,
then the value is divided by the divisor, and the prefix and suffix are set
(using setPositivePrefix/Suffix).

*Parameters:*pattern - A number format pattern. Note that the prefix and
suffix are discarded, and the decimals are overridden by default.
formatSymbols - Decimal format symbols, typically from a locale.prefix - An
array of prefix values, one for each power of 10 from 0 to 14suffix - An
array of prefix values, one for each power of 10 from 0 to 14divisor - An
array of prefix values, one for each power of 10 from 0 to 14
debugCreationErrors - A collection of strings for debugging. If null on
input, then any errors found will be added to that collection instead of
throwing exceptions.