Класс Format

java.lang.Object
- java.text.Format

Все реализованные интерфейсы:: Serializable, Cloneable

Прямые известные подклассы:: DateFormat, MessageFormat, NumberFormat

public abstract class Format
extends Object
implements Serializable, Cloneable

Класс Format является абстрактным базовым классом для форматирования информации, зависящей от локали, такой как даты, сообщения и числа.

Format определяет программно-ориентированный интерфейс для форматирования объектов, зависящих от локали, в String (метод format) и для разбора String обратно в объекты (метод parseObject).

Как правило, метод parseObject формата должен быть способен разобрать любую строку, отформатированную его методом format. Однако могут быть исключительные случаи, когда это невозможно. Например, метод format может создавать два смежных целых числа без разделителя, и в этом случае метод parseObject не сможет определить, какие цифры относятся к какому числу.

Наследование

Платформа Java предоставляет три специализированных подкласса Format — DateFormat, MessageFormat, и NumberFormat — для форматирования дат, сообщений и чисел соответственно.

Конкретные подклассы должны реализовать три метода:

format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
formatToCharacterIterator(Object obj)
parseObject(String source, ParsePosition pos)

Эти общие методы позволяют полиморфный разбор и форматирование объектов и используются, например, MessageFormat. Подклассы часто также предоставляют дополнительные методы format для определенных типов ввода, а также методы parse для определенных типов результатов. Любой метод parse, который не принимает аргумент ParsePosition, должен выбрасывать исключение ParseException, когда в начале входного текста отсутствует текст в требуемом формате.

Большинство подклассов также реализуют следующие методы-фабрики:

getInstance для получения полезного объекта формата, подходящего для текущей локали
getInstance(Locale) для получения полезного объекта формата, подходящего для указанной локали

Кроме того, некоторые подклассы могут также реализовывать другие методы getXxxxInstance для более специализированного управления. Например, класс NumberFormat предоставляет методы getPercentInstance и getCurrencyInstance для получения специализированных форматировщиков чисел.

Подклассы Format, позволяющие программистам создавать объекты для локалей (с помощью getInstance(Locale) , например), также должны реализовать следующий статический метод класса:

public static Locale[] getAvailableLocales()

И, наконец, подклассы могут определить набор констант для идентификации различных полей в отформатированном выводе. Эти константы используются для создания объекта FieldPosition, который идентифицирует информацию, содержащуюся в поле, и его позицию в отформатированном результате. Эти константы должны называться item_FIELD, где item идентифицирует поле. Примеры таких констант см. в ERA_FIELD и его друзьях в DateFormat.

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

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

С тех пор:: 1.1
См. также:: ParsePosition, FieldPosition, NumberFormat, DateFormat, MessageFormat, Форматированный вид

Краткое описание вложенных классов

Модификатор и тип	Класс	Описание
`static class`	`Format.Field`	Определяет константы, используемые в качестве ключей атрибутов в `AttributedCharacterIterator` , возвращаемом `Format.formatToCharacterIterator` и в качестве идентификаторов полей в `FieldPosition`.

Краткое описание конструкторов

Модификатор	Конструктор	Описание
`protected`	`Format()`	Единственный конструктор.

Краткое описание методов

Модификатор и тип	Метод	Описание
`Object`	`clone()`	Создает и возвращает копию этого объекта.
`String`	`format(Object obj)`	Форматирует объект для получения строки.
`abstract StringBuffer`	`format(Object obj, StringBuffer toAppendTo, FieldPosition pos)`	Форматирует объект и добавляет результирующий текст в заданный буфер строк.
`AttributedCharacterIterator`	`formatToCharacterIterator(Object obj)`	Форматирует объект, создавая `AttributedCharacterIterator`.
`Object`	`parseObject(String source)`	Разбирает текст с начала заданной строки для получения объекта.
`abstract Object`	`parseObject(String source, ParsePosition pos)`	Разбирает текст из строки для получения объекта.

Методы, объявленные в классе java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Подробное описание конструкторов

Format

protected Format()

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

Подробное описание методов

format

public final String format(Object obj)

Форматирует объект для получения строки. Это эквивалентно

format(obj, new StringBuffer(), new FieldPosition(0)).toString();

.

Параметры:: obj - Объект для форматирования
Возвращает:: Отформатированная строка.
Исключения:: IllegalArgumentException - если Format не может отформатировать данный объект

format

public abstract StringBuffer format(Object obj,
                                    StringBuffer toAppendTo,
                                    FieldPosition pos)

Форматирует объект и добавляет результирующий текст в заданный буфер строк. Если аргумент pos идентифицирует поле, используемое форматом, то его индексы устанавливаются в начало и конец первого такого поля, встреченного.

Параметры:: obj - Объект для форматирования; toAppendTo - место, куда должен быть добавлен текст; pos - FieldPosition , идентифицирующий поле в отформатированном тексте
Возвращает:: переданный в качестве toAppendTo буфер строк, с добавленным отформатированным текстом
Исключения:: NullPointerException - если toAppendTo или pos равно null; IllegalArgumentException - если Format не может отформатировать данный объект

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object obj)

Форматирует объект, создавая AttributedCharacterIterator. Вы можете использовать возвращенный AttributedCharacterIterator для построения результирующей строки, а также для получения информации о результирующей строке.

Каждый ключ атрибута AttributedCharacterIterator будет типа Field. Реализация каждого Format должна определять допустимые значения для каждого атрибута в AttributedCharacterIterator, но обычно ключ атрибута используется и как значение атрибута.

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

Параметры:: obj - Объект для форматирования
Возвращает:: AttributedCharacterIterator, описывающий отформатированное значение.
Исключения:: NullPointerException - если obj равно null.; IllegalArgumentException - при невозможности форматирования данного объекта.
С тех пор:: 1.4

parseObject

public abstract Object parseObject(String source,
                                   ParsePosition pos)

Разбирает текст из строки для получения объекта.

Метод пытается разобрать текст, начиная с индекса, заданного pos. Если разбор успешен, то индекс pos обновляется до индекса после последнего используемого символа (разбор не обязательно использует все символы до конца строки), и возвращается разобранный объект. Обновленный pos может использоваться для указания начальной точки для следующего вызова этого метода. Если произошла ошибка, то индекс pos не изменяется, индекс ошибки pos устанавливается в индекс символа, где произошла ошибка, и возвращается null.

Параметры:: source - Строка, часть которой должна быть обработана.; pos - Объект ParsePosition с информацией об индексе и индексе ошибки, как описано выше.
Возвращает:: Объект, разобранный из строки. В случае ошибки возвращает null.
Исключения:: NullPointerException - если source или pos равно null.

parseObject

public Object parseObject(String source)
                   throws ParseException

Разбирает текст с начала заданной строки для получения объекта. Метод может не использовать весь текст заданной строки.

Параметры:: source - Строка, начало которой должно быть обработано.
Возвращает:: Объект, разобранный из строки.
Исключения:: ParseException - если начало заданной строки нельзя обработать.; NullPointerException - если source равно null.

clone

public Object clone()

Создает и возвращает копию этого объекта.

Переопределяет:: clone в классе Object
Возвращает:: клонированный экземпляр.
См. также:: Cloneable