Класс DateFormat

DateFormat — это абстрактный класс для подклассов форматирования дат/времени, который форматирует и анализирует даты или время в независимом от языка формате. Подкласс форматирования дат/времени, такой как SimpleDateFormat, позволяет форматировать (т. е. дата → текст), анализировать (текст → дата) и нормализовать. Дата представлена как Date объект или как миллисекунды с момента 1 января 1970 года, 00:00:00 GMT.

DateFormat предоставляет множество методов класса для получения стандартных форматировщиков дат/времени на основе стандартного или заданного региона и ряда стилей форматирования. Эти стили форматирования включают FULL, LONG, MEDIUM и SHORT. Более подробная информация и примеры использования этих стилей приведены в описаниях методов.

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

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

myString = DateFormat.getDateInstance().format(myDate);

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

DateFormat df = DateFormat.getDateInstance();
for (int i = 0; i < myDate.length; ++i) {
    output.println(df.format(myDate[i]) + "; ");
}

Для форматирования даты для другого региона укажите его в вызове getDateInstance().

DateFormat df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE);

Вы также можете использовать DateFormat для анализа.

myDate = df.parse(myString);

Используйте getDateInstance для получения стандартного формата даты для данной страны. Доступны и другие статические методы-фабрики. Используйте getTimeInstance для получения формата времени для данной страны. Используйте getDateTimeInstance для получения формата даты и времени. Вы можете передавать различные параметры в эти методы-фабрики для управления длиной результата; от SHORT до MEDIUM, до LONG и до FULL. Точный результат зависит от региона, но, как правило:

• SHORT полностью числовой, например 12.13.52 или 3:30pm
• MEDIUM более длинный, например Jan 12, 1952
• LONG более длинный, например January 12, 1952 или 3:30:32pm
• FULL достаточно подробно указан, например Tuesday, April 12, 1952 AD or 3:30:42pm PST.

Вы также можете установить часовой пояс в формате, если хотите. Если вам нужен еще больший контроль над форматом или анализом (или вы хотите предоставить пользователям больше контроля), вы можете попробовать привести полученный из методов-фабрик DateFormat к типу SimpleDateFormat. Это будет работать для большинства стран; просто помните, что нужно поместить его в try блок на случай необычного случая.

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

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

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

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

Поля

calendar

protected Calendar calendar

numberFormat

protected NumberFormat numberFormat

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

ERA_FIELD

public static final int ERA_FIELD

Полезная константа для выравнивания поля ЭРА. Используется в FieldPosition для форматирования даты/времени.

См. также:

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

YEAR_FIELD

public static final int YEAR_FIELD

Полезная константа для выравнивания поля ГОД. Используется в FieldPosition для форматирования даты/времени.

См. также:

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

MONTH_FIELD

public static final int MONTH_FIELD

Полезная константа для выравнивания поля МЕСЯЦ. Используется в FieldPosition для форматирования даты/времени.

См. также:

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

DATE_FIELD

public static final int DATE_FIELD

Полезная константа для выравнивания поля ДАТА. Используется в FieldPosition для форматирования даты/времени.

См. также:

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

HOUR_OF_DAY1_FIELD

public static final int HOUR_OF_DAY1_FIELD

Полезная константа для выравнивания поля HOUR_OF_DAY с основанием 1. Используется в FieldPosition для форматирования даты/времени. HOUR_OF_DAY1_FIELD используется для 24-часовых часов с основанием 1. Например, 23:59 + 01:00 дает результат 24:59.

См. также:

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

HOUR_OF_DAY0_FIELD

public static final int HOUR_OF_DAY0_FIELD

Полезная константа для выравнивания поля HOUR_OF_DAY с основанием 0. Используется в FieldPosition для форматирования даты/времени. HOUR_OF_DAY0_FIELD используется для 24-часовых часов с основанием 0. Например, 23:59 + 01:00 дает результат 00:59.

См. также:

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

MINUTE_FIELD

public static final int MINUTE_FIELD

Полезная константа для выравнивания поля МИНУТА. Используется в FieldPosition для форматирования даты/времени.

См. также:

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

SECOND_FIELD

public static final int SECOND_FIELD

Полезная константа для выравнивания поля СЕКУНДА. Используется в FieldPosition для форматирования даты/времени.

См. также:

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

MILLISECOND_FIELD

public static final int MILLISECOND_FIELD

Полезная константа для выравнивания поля МИЛЛИСЕКУНДА. Используется в FieldPosition для форматирования даты/времени.

См. также:

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

DAY_OF_WEEK_FIELD

public static final int DAY_OF_WEEK_FIELD

Полезная константа для выравнивания поля ДЕНЬ_НЕДЕЛИ. Используется в FieldPosition для форматирования даты/времени.

См. также:

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

DAY_OF_YEAR_FIELD

public static final int DAY_OF_YEAR_FIELD

Полезная константа для выравнивания поля ДЕНЬ_ГОДА. Используется в FieldPosition для форматирования даты/времени.

См. также:

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

DAY_OF_WEEK_IN_MONTH_FIELD

public static final int DAY_OF_WEEK_IN_MONTH_FIELD

Полезная константа для выравнивания поля ДЕНЬ_НЕДЕЛИ_В_МЕСЯЦЕ. Используется в FieldPosition для форматирования даты/времени.

См. также:

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

WEEK_OF_YEAR_FIELD

public static final int WEEK_OF_YEAR_FIELD

Полезная константа для выравнивания поля НЕДЕЛЯ_ГОДА. Используется в FieldPosition для форматирования даты/времени.

См. также:

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

WEEK_OF_MONTH_FIELD

public static final int WEEK_OF_MONTH_FIELD

Полезная константа для выравнивания поля НЕДЕЛЯ_МЕСЯЦА. Используется в FieldPosition для форматирования даты/времени.

См. также:

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

AM_PM_FIELD

public static final int AM_PM_FIELD

Полезная константа для выравнивания поля AM_PM. Используется в FieldPosition для форматирования даты/времени.

См. также:

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

HOUR1_FIELD

public static final int HOUR1_FIELD

Полезная константа для выравнивания поля HOUR с основанием 1. Используется в FieldPosition для форматирования даты/времени. HOUR1_FIELD используется для 12-часовых часов с основанием 1. Например, 11:30 PM + 1 час дает результат 12:30 AM.

См. также:

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

HOUR0_FIELD

public static final int HOUR0_FIELD

Полезная константа для выравнивания поля HOUR с основанием 0. Используется в FieldPosition для форматирования даты/времени. HOUR0_FIELD используется для 12-часовых часов с основанием 0. Например, 11:30 PM + 1 час дает результат 00:30 AM.

См. также:

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

TIMEZONE_FIELD

public static final int TIMEZONE_FIELD

Полезная константа для выравнивания поля TIMEZONE. Используется в FieldPosition для форматирования даты/времени.

См. также:

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

FULL

public static final int FULL

Константа для шаблона полного стиля.

См. также:

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

LONG

public static final int LONG

Константа для шаблона длинного стиля.

См. также:

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

MEDIUM

public static final int MEDIUM

Константа для шаблона среднего стиля.

См. также:

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

SHORT

public static final int SHORT

Константа для шаблона короткого стиля.

См. также:

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

DEFAULT

public static final int DEFAULT

Константа для шаблона стиля по умолчанию. Его значение равно MEDIUM.

См. также:

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

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

DateFormat

protected DateFormat()

Создает новый формат даты.

Методы

format

public final StringBuffer format(Object obj,
                                 StringBuffer toAppendTo,
                                 FieldPosition fieldPosition)

Переопределяет Format. Форматирует объект времени в строку времени. Примеры объектов времени — значение времени, выраженное в миллисекундах, и объект Date.

Указано в:

format в классе Format

Параметры:

obj — должен быть числом или объектом Date.

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

fieldPosition — отслеживает позицию поля в возвращаемой строке. На входе: поле выравнивания, если требуется. На выходе: смещения поля выравнивания. Например, для текстового представления времени «1996.07.10 AD в 15:08:56 PDT», если заданное поле FieldPosition — DateFormat.YEAR_FIELD, начальный и конечный индексы FieldPosition будут установлены соответственно в 0 и 4. Обратите внимание, что если одно и то же поле времени встречается более одного раза в шаблоне, FieldPosition будет установлено для первого вхождения этого поля времени. Например, форматирование объекта Date в строку времени «1 PM PDT (Pacific Daylight Time)» с шаблоном «h a z (zzzz)» и полем выравнивания DateFormat.TIMEZONE_FIELD приведет к установке начального и конечного индексов FieldPosition соответственно в 5 и 8 для первого вхождения символа шаблона времени 'z'.

Возвращает:

переданный в качестве toAppendTo буфер строк с добавленным отформатированным текстом.

См. также:

Format

format

public abstract StringBuffer format(Date date,
                                    StringBuffer toAppendTo,
                                    FieldPosition fieldPosition)

Форматирует Date в строку даты и времени.

Параметры:

date — объект Date для форматирования в строку даты и времени.

toAppendTo — буфер строк для возвращаемой строки даты и времени.

fieldPosition — отслеживает позицию поля в возвращаемой строке. На входе: поле выравнивания, если требуется. На выходе: смещения поля выравнивания. Например, для текстового представления времени «1996.07.10 AD в 15:08:56 PDT», если заданное поле FieldPosition — DateFormat.YEAR_FIELD, начальный и конечный индексы FieldPosition будут установлены соответственно в 0 и 4. Обратите внимание, что если одно и то же поле времени встречается более одного раза в шаблоне, FieldPosition будет установлено для первого вхождения этого поля времени. Например, форматирование объекта Date в строку времени «1 PM PDT (Pacific Daylight Time)» с шаблоном «h a z (zzzz)» и полем выравнивания DateFormat.TIMEZONE_FIELD приведет к установке начального и конечного индексов FieldPosition соответственно в 5 и 8 для первого вхождения символа шаблона времени 'z'.

Возвращает:

переданный в качестве toAppendTo буфер строк с добавленным отформатированным текстом.

форматировать

public final String format(Date date)

Форматирует дату в строку даты/времени.

Параметры:

date - значение времени, которое необходимо отформатировать в строку времени.

Возвращает:

отформатированную строку времени.

разбирать

public Date parse(String source)
           throws ParseException

Параметры:

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

Возвращает:

Дата, разобранная из строки.

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

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

разбирать

public abstract Date parse(String source,
                           ParsePosition pos)

Параметры:

source - Строка даты/времени для разбора

pos - При вводе позиция, с которой следует начать разбор; при выводе позиция, на которой завершился разбор, или начальная позиция, если разбор не удался.

Возвращает:

Дата, или null, если входной текст не смог быть обработан

parseObject

public Object parseObject(String source,
                          ParsePosition pos)

Установлено:

parseObject в классе Format

Параметры:

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

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

Возвращает:

Дата, разобранная из строки. В случае ошибки возвращает null.

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

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

getTimeInstance

public static final DateFormat getTimeInstance()

Возвращает:

Форматировщик времени.

См. также:

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

getTimeInstance

public static final DateFormat getTimeInstance(int style)

Параметры:

style - заданный стиль форматирования. Например, SHORT для "чч:мм а" в локали США.

Возвращает:

Форматировщик времени.

См. также:

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

getTimeInstance

public static final DateFormat getTimeInstance(int style,
                                               Locale aLocale)

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

Параметры:

style - заданный стиль форматирования. Например, SHORT для "чч:мм а" в локали США.

aLocale - заданная локаль.

Возвращает:

Форматировщик времени.

getDateInstance

public static final DateFormat getDateInstance()

Возвращает:

Форматировщик даты.

См. также:

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

getDateInstance

public static final DateFormat getDateInstance(int style)

Параметры:

style - заданный стиль форматирования. Например, SHORT для "дд/мм/гг" в локали США.

Возвращает:

Форматировщик даты.

См. также:

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

getDateInstance

public static final DateFormat getDateInstance(int style,
                                               Locale aLocale)

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

Параметры:

style - заданный стиль форматирования. Например, SHORT для "дд/мм/гг" в локали США.

aLocale - заданная локаль.

Возвращает:

Форматировщик даты.

getDateTimeInstance

public static final DateFormat getDateTimeInstance()

Возвращает:

Форматировщик даты и времени.

См. также:

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

getDateTimeInstance

public static final DateFormat getDateTimeInstance(int dateStyle,
                                                   int timeStyle)

Параметры:

dateStyle - заданный стиль форматирования даты. Например, SHORT для "дд/мм/гг" в локали США.

timeStyle - заданный стиль форматирования времени. Например, SHORT для "чч:мм а" в локали США.

Возвращает:

Форматировщик даты и времени.

См. также:

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

getDateTimeInstance

public static final DateFormat getDateTimeInstance(int dateStyle,
                                                   int timeStyle,
                                                   Locale aLocale)

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

Параметры:

dateStyle - заданный стиль форматирования даты.

timeStyle - заданный стиль форматирования времени.

aLocale - заданная локаль.

Возвращает:

Форматировщик даты и времени.

getInstance

public static final DateFormat getInstance()

Возвращает форматировщик даты и времени по умолчанию, использующий стиль SHORT для даты и времени.

Возвращает:

Форматировщик даты и времени

getAvailableLocales

public static Locale[] getAvailableLocales()

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

Возвращает:

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

setCalendar

public void setCalendar(Calendar newCalendar)

Параметры:

newCalendar - новый календарь, который будет использоваться форматом даты

getCalendar

public Calendar getCalendar()

Возвращает календарь, связанный с этим форматировщиком даты/времени.

Возвращает:

Календарь, связанный с этим форматировщиком даты/времени.

setNumberFormat

public void setNumberFormat(NumberFormat newNumberFormat)

Позволяет установить форматировщик чисел.

Параметры:

newNumberFormat - заданный новый NumberFormat.

getNumberFormat

public NumberFormat getNumberFormat()

Получает форматер чисел, который используется этим форматером даты/времени для форматирования и анализа времени.

Возвращает:

форматер чисел, используемый этим форматером даты/времени.

setTimeZone

public void setTimeZone(TimeZone zone)

getCalendar().setTimeZone(zone)

Параметры:

zone - заданный новый часовой пояс.

getTimeZone

public TimeZone getTimeZone()

Получает часовой пояс. Этот метод эквивалентен следующему вызову.

getCalendar().getTimeZone()

Возвращает:

часовой пояс, связанный с календарем DateFormat.

setLenient

public void setLenient(boolean lenient)

getCalendar().setLenient(lenient)

Параметры:

lenient - при true, анализ является нестрогим

См. также:

Calendar.setLenient(boolean)

isLenient

public boolean isLenient()

Узнать, разрешен ли нестрогий анализ даты/времени. Этот метод эквивалентен следующему вызову.

getCalendar().isLenient()

Возвращает:

true , если calendar нестрогий; false в противном случае.

См. также:

Calendar.isLenient()

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