Класс NumberFormat

public abstract class NumberFormat
extends Format

NumberFormat является абстрактным базовым классом для всех числовых форматов. Этот класс предоставляет интерфейс для форматирования и разбора чисел. NumberFormat также предоставляет методы для определения, какие языковые локали имеют числовые форматы, и каковы их имена.

NumberFormat помогает вам форматировать и разбирать числа для любой локали. Ваш код может быть полностью независим от соглашений локали для десятичных знаков, разделителей тысяч или даже конкретных десятичных цифр, или от того, является ли числовой формат даже десятичным.

Для форматирования числа для текущей локали используйте один из методов фабричного класса:

myString = NumberFormat.getInstance().format(myNumber);

Если вы форматируете несколько чисел, эффективнее получить формат и использовать его несколько раз, чтобы система не должна была многократно получать информацию о соглашениях языковой и стране локали.

NumberFormat nf = NumberFormat.getInstance();
for (int i = 0; i < myNumber.length; ++i) {
    output.println(nf.format(myNumber[i]) + "; ");
}

Для форматирования числа для другой локали укажите её в вызове getInstance.

NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);

Вы также можете использовать NumberFormat для разбора чисел:

myNumber = nf.parse(myString);

Используйте getInstance или getNumberInstance для получения стандартного числового формата. Используйте getIntegerInstance для получения формата целого числа. Используйте getCurrencyInstance для получения формата валюты. И используйте getPercentInstance для получения формата для отображения процентов. С этим форматом дробь, например, 0,53, отображается как 53%.

Вы также можете управлять отображением чисел с помощью таких методов, как setMinimumFractionDigits. Если вам нужен ещё больший контроль над форматом или разбором, или вы хотите предоставить пользователям больше контроля, вы можете попробовать привести NumberFormat полученное из методов фабрики к DecimalFormat. Это будет работать для подавляющего большинства локалей; просто помните, что следует поместить это в try блок на случай, если вы столкнётесь с необычной.

NumberFormat и DecimalFormat разработаны таким образом, что некоторые элементы управления работают для форматирования, а другие — для разбора. Ниже приведено подробное описание каждого из этих методов управления.

setParseIntegerOnly: влияет только на разбор, например, если true, "3456.78" → 3456 (и оставляет позицию разбора сразу после индекса 6), если false, "3456.78" → 3456.78 (и оставляет позицию разбора сразу после индекса 8). Это независимо от форматирования. Если вы хотите не показывать десятичную точку, когда после неё нет цифр, используйте setDecimalSeparatorAlwaysShown.

setDecimalSeparatorAlwaysShown: влияет только на форматирование, и только в тех случаях, когда после десятичной точки нет цифр, например, с шаблоном типа "#,##0.##", например, если true, 3456.00 → "3456.", если false, 3456.00 → "3456". Это независимо от разбора. Если вы хотите, чтобы разбор прекращался на десятичной точке, используйте setParseIntegerOnly.

Вы также можете использовать формы методов parse и format с ParsePosition и FieldPosition, чтобы:

• поэтапно анализировать части строки
• выравнивать десятичную точку и другие области

Например, вы можете выровнять числа двумя способами:

1. Если вы используете моноширинный шрифт с отступами для выравнивания, вы можете передать FieldPosition в вызов форматирования, при этом field = INTEGER_FIELD. При выводе getEndIndex будет установлено значение смещения между последним символом целой части и десятичной точкой. Добавьте (desiredSpaceCount - getEndIndex) пробелов в начало строки.
2. Если вы используете пропорциональный шрифт, вместо заполнения пробелами измерьте ширину строки в пикселях от начала до getEndIndex. Затем переместите перо на (desiredPixelWidth - widthToAlignmentPoint) до рисования текста. Это также работает, когда десятичной точки нет, но есть дополнительные символы в конце, например, с круглыми скобками в отрицательных числах: "(12)" для -12.

Синхронизация

Форматы чисел, как правило, не синхронизированы. Рекомендуется создавать отдельные экземпляры формата для каждого потока. Если несколько потоков одновременно обращаются к формату, он должен быть синхронизирован внешним образом.

Поля

INTEGER_FIELD

public static final int INTEGER_FIELD

Постоянная поля, используемая для создания объекта FieldPosition. Указывает, что должна быть возвращена позиция целой части форматированного числа.

См. также:

FieldPosition, Значения постоянных полей

FRACTION_FIELD

public static final int FRACTION_FIELD

Постоянная поля, используемая для создания объекта FieldPosition. Указывает, что должна быть возвращена позиция дробной части форматированного числа.

См. также:

FieldPosition, Значения постоянных полей

Конструкторы

NumberFormat

protected NumberFormat()

Единственный конструктор. (Для вызова конструкторами подклассов, обычно неявный.)

Методы

format

public StringBuffer format(Object number,
                           StringBuffer toAppendTo,
                           FieldPosition pos)

Указано:

format в классе Format

Параметры:

number - число для форматирования

toAppendTo - StringBuffer, в который будет добавлен отформатированный текст

pos - При вводе: поле выравнивания, если необходимо. На выходе: смещения поля выравнивания.

Возвращает:

переданное значение в качестве toAppendTo

Выбрасывает:

IllegalArgumentException - если number равно null или не является экземпляром Number.

NullPointerException - если toAppendTo или pos равно null

ArithmeticException - если требуется округление с режимом округления RoundingMode.UNNECESSARY

См. также:

FieldPosition

parseObject

public final Object parseObject(String source,
                                ParsePosition pos)

Указано:

parseObject в классе Format

Параметры:

source - Строка, часть которой должна быть пропаршена.

pos - Объект ParsePosition с информацией об индексе и индексе ошибки, как описано выше.

Возвращает:

Пропаршенное Number из строки. В случае ошибки возвращает null.

Выбрасывает:

NullPointerException - если pos равно null.

format

public final String format(double number)

Специализация format.

Параметры:

number - двойное число для форматирования

Возвращает:

отформатированная строка

Исключения:

ArithmeticException - если необходимо округлить с режимом округления RoundingMode.UNNECESSARY

См. также:

Format.format(java.lang.Object)

format

public final String format(long number)

Специализация форматирования.

Параметры:

number - длинное число для форматирования

Возвращает:

отформатированная строка

Исключения:

ArithmeticException - если необходимо округлить с режимом округления RoundingMode.UNNECESSARY

См. также:

Format.format(java.lang.Object)

format

public abstract StringBuffer format(double number,
                                    StringBuffer toAppendTo,
                                    FieldPosition pos)

Специализация форматирования.

Параметры:

number - двойное число для форматирования

toAppendTo - StringBuffer, в который будет добавлен отформатированный текст

pos - позиция поля

Возвращает:

отформатированный StringBuffer

Исключения:

ArithmeticException - если необходимо округлить с режимом округления RoundingMode.UNNECESSARY

См. также:

Format.format(java.lang.Object)

format

public abstract StringBuffer format(long number,
                                    StringBuffer toAppendTo,
                                    FieldPosition pos)

Специализация форматирования.

Параметры:

number - длинное число для форматирования

toAppendTo - StringBuffer, в который будет добавлен отформатированный текст

pos - позиция поля

Возвращает:

отформатированный StringBuffer

Исключения:

ArithmeticException - если необходимо округлить с режимом округления RoundingMode.UNNECESSARY

См. также:

Format.format(java.lang.Object)

parse

public abstract Number parse(String source,
                             ParsePosition parsePosition)

Возвращает Long, если возможно (например, в диапазоне [Long.MIN_VALUE, Long.MAX_VALUE] и без десятичных знаков), в противном случае Double. Если установлен IntegerOnly, остановится на десятичной точке (или эквиваленте; например, для рациональных чисел "1 2/3", остановится после 1). Не выбрасывает исключения; если ни один объект не может быть распарсен, индекс не изменяется!

Параметры:

source - строка для разбора

parsePosition - позиция разбора

Возвращает:

разбираемое значение

См. также:

isParseIntegerOnly(), Format.parseObject(java.lang.String, java.text.ParsePosition)

parse

public Number parse(String source)
             throws ParseException

Параметры:

source - строка, начало которой необходимо разобрать.

Возвращает:

число, разобранное из строки.

Исключения:

ParseException - если начало указанной строки не может быть разобрано.

isParseIntegerOnly

public boolean isParseIntegerOnly()

Возвращает true, если этот формат будет анализировать числа только как целые. Например, в английском локали, с ParseIntegerOnly равным true, строка "1234." будет разобрана как целое значение 1234, а разбор остановится на символе ".". Конечно, точный формат, принимаемый операцией разбора, зависит от локали и определяется подклассами NumberFormat.

Возвращает:

true если числа должны анализироваться только как целые; false в противном случае

setParseIntegerOnly

public void setParseIntegerOnly(boolean value)

Устанавливает, должны ли числа анализироваться только как целые.

Параметры:

value - true если числа должны анализироваться только как целые; false в противном случае

См. также:

isParseIntegerOnly()

getInstance

public static final NumberFormat getInstance()

Возвращает числовой формат общего назначения для текущего стандартного локали FORMAT. Это то же самое, что вызов getNumberInstance().

Возвращает:

экземпляр NumberFormat для форматирования чисел общего назначения

getInstance

public static NumberFormat getInstance(Locale inLocale)

Возвращает числовой формат общего назначения для указанной локали. Это то же самое, что вызов getNumberInstance(inLocale).

Параметры:

inLocale - требуемый регион

Возвращает:

экземпляр NumberFormat для форматирования чисел общего назначения

getNumberInstance

public static final NumberFormat getNumberInstance()

Возвращает:

экземпляр NumberFormat для форматирования чисел общего назначения

См. также:

Locale.getDefault(java.util.Locale.Category), Locale.Category.FORMAT

getNumberInstance

public static NumberFormat getNumberInstance(Locale inLocale)

Возвращает числовой формат общего назначения для указанного региона.

Параметры:

inLocale - требуемый регион

Возвращает:

экземпляр NumberFormat для форматирования чисел общего назначения

getIntegerInstance

public static final NumberFormat getIntegerInstance()

Возвращает:

числовой формат для целых значений

С:

1.4

См. также:

getRoundingMode(), Locale.getDefault(java.util.Locale.Category), Locale.Category.FORMAT

getIntegerInstance

public static NumberFormat getIntegerInstance(Locale inLocale)

Возвращает числовой формат для целых чисел для указанного региона. Возвращаемый числовой формат настроен на округление чисел с плавающей запятой до ближайшего целого числа с использованием округления по правилу половина к четному (см. RoundingMode.HALF_EVEN) для форматирования и для анализа только целой части входной строки (см. isParseIntegerOnly).

Параметры:

inLocale - требуемый язык

Возвращает:

формат числа для целых значений

С:

1.4

См. также:

getRoundingMode()

getCurrencyInstance

public static final NumberFormat getCurrencyInstance()

Возвращает:

экземпляр NumberFormat для форматирования валюты

См. также:

Locale.getDefault(java.util.Locale.Category), Locale.Category.FORMAT

getCurrencyInstance

public static NumberFormat getCurrencyInstance(Locale inLocale)

Возвращает формат валюты для указанного языка.

Параметры:

inLocale - требуемый язык

Возвращает:

экземпляр NumberFormat для форматирования валюты

getPercentInstance

public static final NumberFormat getPercentInstance()

Возвращает:

экземпляр NumberFormat для форматирования процентов

См. также:

Locale.getDefault(java.util.Locale.Category), Locale.Category.FORMAT

getPercentInstance

public static NumberFormat getPercentInstance(Locale inLocale)

Возвращает формат процентов для указанного языка.

Параметры:

inLocale - требуемый язык

Возвращает:

экземпляр NumberFormat для форматирования процентов

getAvailableLocales

public static Locale[] getAvailableLocales()

Возвращает массив всех языков, для которых методы get*Instance этого класса могут возвращать локализованные экземпляры. Возвращаемый массив представляет собой объединение языков, поддерживаемых Java-средой выполнения и установленным NumberFormatProvider реализациями. Он должен содержать по крайней мере экземпляр Locale равный Locale.US.

Возвращает:

Массив языков, для которых доступны локализованные NumberFormat экземпляры.

hashCode

public int hashCode()

Переопределяет hashCode.

Переопределяет:

hashCode в классе Object

Возвращает:

значение хэш-кода для этого объекта.

См. также:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

equals

public boolean equals(Object obj)

Переопределяет equals.

Переопределяет:

equals в классе Object

Параметры:

obj - объект-ссылка для сравнения.

Возвращает:

true если этот объект такой же, как аргумент obj; false в противном случае.

См. также:

Object.hashCode(), HashMap

clone

public Object clone()

Переопределяет Cloneable.

Переопределяет:

clone в классе Format

Возвращает:

клонированный экземпляр.

См. также:

Cloneable

isGroupingUsed

public boolean isGroupingUsed()

Возвращает true, если группировка используется в этом формате. Например, в английском локали с включенной группировкой число 1234567 может быть отформатировано как "1 234 567". Разделитель группировки, а также размер каждой группы зависят от локали и определяются подклассами NumberFormat.

Возвращает:

true если используется группировка; false в противном случае

См. также:

setGroupingUsed(boolean)

setGroupingUsed

public void setGroupingUsed(boolean newValue)

Устанавливает, будет ли использоваться группировка в этом формате.

Параметры:

newValue - true если группировка используется; false в противном случае

См. также:

isGroupingUsed()

getMaximumIntegerDigits

public int getMaximumIntegerDigits()

Возвращает максимальное количество цифр, разрешённых в целой части числа.

Возвращает:

максимальное количество цифр

См. также:

setMaximumIntegerDigits(int)

setMaximumIntegerDigits

public void setMaximumIntegerDigits(int newValue)

Устанавливает максимальное количество цифр, разрешенных в целой части числа. maximumIntegerDigits должно быть ≥ minimumIntegerDigits. Если новое значение для maximumIntegerDigits меньше текущего значения minimumIntegerDigits, то minimumIntegerDigits также будет установлено в новое значение.

Параметры:

newValue - максимальное количество цифр целой части, которые должны быть показаны; если меньше нуля, то используется ноль. Конкретный подкласс может установить верхнюю границу этого значения, соответствующую типу числовых данных, которые форматируются.

См. также:

getMaximumIntegerDigits()

getMinimumIntegerDigits

public int getMinimumIntegerDigits()

Возвращает минимальное количество цифр, разрешенных в целой части числа.

Возвращает:

минимальное количество цифр

См. также:

setMinimumIntegerDigits(int)

setMinimumIntegerDigits

public void setMinimumIntegerDigits(int newValue)

Устанавливает минимальное количество цифр, разрешенных в целой части числа. minimumIntegerDigits должно быть ≤ maximumIntegerDigits. Если новое значение для minimumIntegerDigits превышает текущее значение maximumIntegerDigits, то maximumIntegerDigits также будет установлено в новое значение.

Параметры:

newValue - минимальное количество цифр целой части, которые должны быть показаны; если меньше нуля, то используется ноль. Конкретный подкласс может установить верхнюю границу этого значения, соответствующую типу числовых данных, которые форматируются.

См. также:

getMinimumIntegerDigits()

getMaximumFractionDigits

public int getMaximumFractionDigits()

Возвращает максимальное количество цифр, разрешенных в дробной части числа.

Возвращает:

максимальное количество цифр.

См. также:

setMaximumFractionDigits(int)

setMaximumFractionDigits

public void setMaximumFractionDigits(int newValue)

Устанавливает максимальное количество цифр, разрешенных в дробной части числа. maximumFractionDigits должно быть ≥ minimumFractionDigits. Если новое значение для maximumFractionDigits меньше текущего значения minimumFractionDigits, то minimumFractionDigits также будет установлено в новое значение.

Параметры:

newValue - максимальное количество цифр дробной части, которые должны быть показаны; если меньше нуля, то используется ноль. Конкретный подкласс может установить верхнюю границу этого значения, соответствующую типу числовых данных, которые форматируются.

См. также:

getMaximumFractionDigits()

getMinimumFractionDigits

public int getMinimumFractionDigits()

Возвращает минимальное количество цифр, разрешенных в дробной части числа.

Возвращает:

минимальное количество цифр

См. также:

setMinimumFractionDigits(int)

setMinimumFractionDigits

public void setMinimumFractionDigits(int newValue)

Устанавливает минимальное количество цифр, разрешенных в дробной части числа. minimumFractionDigits должен быть ≤ maximumFractionDigits. Если новое значение minimumFractionDigits превышает текущее значение maximumFractionDigits, то maximumIntegerDigits также будет установлено в новое значение.

Параметры:

newValue - минимальное количество цифр дробной части, которое должно быть показано; если меньше нуля, то используется ноль. Конкретный подкласс может применять верхний предел к этому значению, соответствующий типу числовых данных, которые форматируются.

См. также:

getMinimumFractionDigits()

getCurrency

public Currency getCurrency()

Возвращает:

валюту, используемую этим форматом числа, или null

ИИсключения:

UnsupportedOperationException - если класс формата числа не реализует форматирование валюты

С момента:

1.4

setCurrency

public void setCurrency(Currency currency)

Параметры:

currency - новая валюта, которая должна использоваться этим форматом числа

ИИсключения:

UnsupportedOperationException - если класс формата числа не реализует форматирование валюты

NullPointerException - если currency равно null

С момента:

1.4

getRoundingMode

public RoundingMode getRoundingMode()

Получает RoundingMode, используемый в этом NumberFormat. Реализация по умолчанию этого метода в NumberFormat всегда выбрасывает UnsupportedOperationException. Подклассы, обрабатывающие различные режимы округления, должны переопределять этот метод.

Возвращает:

RoundingMode используемый для этого NumberFormat.

Исключения:

UnsupportedOperationException - Встроенная реализация всегда выбрасывает это исключение

С:

1.6

См. также:

setRoundingMode(RoundingMode)

setRoundingMode

public void setRoundingMode(RoundingMode roundingMode)

Устанавливает RoundingMode, используемый в этом NumberFormat. Встроенная реализация этого метода в NumberFormat всегда выбрасывает UnsupportedOperationException. Подклассы, обрабатывающие различные режимы округления, должны переопределить этот метод.

Параметры:

roundingMode - Используемый RoundingMode

Исключения:

UnsupportedOperationException - Встроенная реализация всегда выбрасывает это исключение

NullPointerException - если roundingMode имеет значение null

С:

1.6

См. также:

getRoundingMode()