Класс SimpleDateFormat

Все реализованные интерфейсы:
Serializable, Cloneable 
public class SimpleDateFormat
extends DateFormat

SimpleDateFormat — это конкретный класс для форматирования и разбора дат с учетом локали. Он позволяет выполнять форматирование (дата → текст), разбор (текст → дата) и нормализацию.

SimpleDateFormat позволяет начать с выбора любых пользовательских шаблонов для форматирования даты и времени. Однако рекомендуется создавать форматировщик даты и времени с использованием getTimeInstance, getDateInstance, или getDateTimeInstance в DateFormat. Каждый из этих методов класса может вернуть форматировщик даты/времени, инициализированный с шаблоном форматирования по умолчанию. Вы можете изменить шаблон форматирования с помощью методов applyPattern по своему усмотрению. Дополнительную информацию об использовании этих методов см. в DateFormat.

Шаблоны дат и времени

Форматы дат и времени определяются строками шаблонов дат и времени. В строках шаблонов дат и времени нецитированные буквы от 'A' до 'Z' и от 'a' до 'z' интерпретируются как символы шаблона, представляющие компоненты строки даты или времени. Текст можно заключить в одинарные кавычки (') для предотвращения интерпретации. "''" представляет одиночную кавычку. Все остальные символы не интерпретируются; они просто копируются в строку вывода при форматировании или сопоставляются со строкой ввода при разборе.

Определены следующие символы шаблона (все остальные символы от 'A' до 'Z' и от 'a' до 'z' зарезервированы):

Символ Компонент даты или времени Представление Примеры
G Обозначения эры Текст AD
y Год Год 1996; 96
Y Год недели Год 2009; 09
M Месяц в году (зависит от контекста) Месяц July; Jul; 07
L Месяц в году (самостоятельная форма) Месяц July; Jul; 07
w Неделя в году Число 27
W Неделя в месяце Число 2
D День в году Число 189
d День в месяце Число 10
F День недели в месяце Число 2
E Имя дня недели Текст Tuesday; Tue
u Номер дня недели (1 = понедельник, ..., 7 = воскресенье) Число 1
a Маркер AM/PM Текст PM
H Час в сутках (0-23) Число 0
k Час в сутках (1-24) Число 24
K Час в формате AM/PM (0-11) Число 0
h Час в формате AM/PM (1-12) Число 12
m Минута в часе Число 30
s Секунда в минуте Число 55
S Миллисекунда Число 978
z Часовой пояс Общий часовой пояс Pacific Standard Time; PST; GMT-08:00
Z Часовой пояс Часовой пояс RFC 822 -0800
X Часовой пояс Часовой пояс ISO 8601 -08; -0800; -08:00
Символы шаблона обычно повторяются, так как их количество определяет точное представление:
  • Текст: Для форматирования, если количество символов шаблона равно 4 или более, используется полная форма; в противном случае используется короткая или сокращенная форма, если она доступна. Для разбора обе формы принимаются независимо от количества символов шаблона.

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

  • Год: Если календарь форматировщика Calendar является григорианским, применяются следующие правила.
    • Для форматирования, если количество символов шаблона равно 2, год усекается до 2 цифр; в противном случае он интерпретируется как число.
    • Для разбора, если количество символов шаблона больше 2, год интерпретируется буквально, независимо от количества цифр. Таким образом, используя шаблон "ДД/ММ/ГГГГ", "01/11/12" разбирается как 11 января 12 года н.э.
    • Для разбора с шаблоном сокращенного года ("y" или "yy"), SimpleDateFormat должен интерпретировать сокращенный год относительно какого-то столетия. Это делается путем корректировки дат, чтобы они находились в пределах 80 лет до и 20 лет после момента создания экземпляра SimpleDateFormat. Например, используя шаблон "ДД/ММ/ГГ" и экземпляр SimpleDateFormat , созданный 1 января 1997 года, строка "01/11/12" будет интерпретироваться как 11 января 2012 года, а строка "05/04/64" — как 4 мая 1964 года. При разборе только строки, состоящие ровно из двух цифр, как определено в Character.isDigit(char), будут преобразованы в столетие по умолчанию. Любая другая числовая строка, такая как строка из одной цифры, строка из трех или более цифр или строка из двух цифр, которая не состоит только из цифр (например, "-1"), интерпретируется буквально. Поэтому "01/02/3" или "01/02/003" разбираются, используя тот же шаблон, как 2 января 3 года н.э. Аналогично, "01/02/-3" разбирается как 2 января 4 года до н.э.
    В противном случае применяются формы, специфичные для календарной системы. Как для форматирования, так и для разбора, если количество символов шаблона равно 4 или более, используется длинная форма, специфичная для календаря long form. В противном случае используется короткая или сокращенная форма, специфичная для календаря short or abbreviated form.

    Если указан номер недели 'Y' , и календарь календарь не поддерживает годы недель, вместо этого используется год календаря ('y'). Поддержка лет недели может быть проверена с помощью вызова getCalendar().isWeekDateSupported().

  • Месяц: Если количество символов шаблона равно 3 или более, месяц интерпретируется как текст; в противном случае он интерпретируется как число.
    • Символ М генерирует контекстно-зависимые названия месяцев, такие как вложенная форма имён. Символ М контекстно-зависим в том смысле, что, когда он используется в отдельном шаблоне, например, "MMMM", он даёт отдельную форму имени месяца, а когда он используется в шаблоне, содержащем другие поля, например, "d MMMM", он даёт форматную форму имени месяца. Например, январь на каталонском языке — "de gener" в формате, а в отдельной форме — "gener". В этом случае "MMMM" даст "gener", а часть месяца в "d MMMM" даст "de gener". Если DateFormatSymbols был задан явно с помощью конструктора SimpleDateFormat(String,DateFormatSymbols) или метода setDateFormatSymbols(DateFormatSymbols), используются имена месяцев, заданные DateFormatSymbols.
    • Символ L генерирует отдельную форму имён месяцев.

  • Общий часовой пояс: Часовые пояса интерпретируются как текст, если они имеют названия. Для часовых поясов, представляющих значение смещения GMT, используется следующий синтаксис: 
    GMTOffsetTimeZone:
             GMT Sign Hours : Minutes
     Sign: one of
             + -
     Hours:
             Digit
             Digit Digit
     Minutes:
             Digit Digit
     Digit: one of
             0 1 2 3 4 5 6 7 8 9
    Часы должны быть от 0 до 23, а Минуты — от 00 до 59. Формат независим от локали, а цифры должны быть взяты из блока Basic Latin стандарта Unicode.

    Для разбора также принимаются часовые пояса RFC 822.

  • Часовой пояс RFC 822: Для форматирования используется формат часового пояса RFC 822 длиной 4 цифры: 
    RFC822TimeZone:
             Sign TwoDigitHours Minutes
     TwoDigitHours:
             Digit Digit
    TwoDigitHours должен быть от 00 до 23. Другие определения такие же, как для общих часовых поясов.

    Для разбора также принимаются общие часовые пояса.

  • Часовой пояс ISO 8601: Количество символов шаблона определяет формат как для форматирования, так и для разбора следующим образом: 
    ISO8601TimeZone:
             OneLetterISO8601TimeZone
             TwoLetterISO8601TimeZone
             ThreeLetterISO8601TimeZone
     OneLetterISO8601TimeZone:
             Sign TwoDigitHours
             Z
     TwoLetterISO8601TimeZone:
             Sign TwoDigitHours Minutes
             Z
     ThreeLetterISO8601TimeZone:
             Sign TwoDigitHours : Minutes
             Z
    Другие определения такие же, как для общих часовых поясов или часовых поясов RFC 822.

    Для форматирования, если значение смещения от GMT равно 0, "Z" выводится. Если количество символов шаблона равно 1, любая дробная часть часа игнорируется. Например, если шаблон — "X" , а часовой пояс — "GMT+05:30", то "+05" выводится.

    Для разбора "Z" разбирается как обозначение часового пояса UTC. Общие часовые пояса не принимаются.

    Если количество символов шаблона равно 4 или более, IllegalArgumentException выбрасывается при построении SimpleDateFormat или применении шаблона применении шаблона.

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

Примеры

Следующие примеры показывают, как шаблоны дат и времени интерпретируются в локали США. Указанная дата и время — 2001-07-04 12:08:56 по местному времени в часовом поясе Тихоокеанское время США.
Шаблон даты и времени Результат
"yyyy.MM.dd G 'at' HH:mm:ss z" 2001.07.04 AD at 12:08:56 PDT
"EEE, MMM d, ''yy" Wed, Jul 4, '01
"h:mm a" 12:08 PM
"hh 'o''clock' a, zzzz" 12 o'clock PM, Pacific Daylight Time
"K:mm a, z" 0:08 PM, PDT
"yyyyy.MMMMM.dd GGG hh:mm aaa" 02001.July.04 AD 12:08 PM
"EEE, d MMM yyyy HH:mm:ss Z" Wed, 4 Jul 2001 12:08:56 -0700
"yyMMddHHmmssZ" 010704120856-0700
"yyyy-MM-dd'T'HH:mm:ss.SSSZ" 2001-07-04T12:08:56.235-0700
"yyyy-MM-dd'T'HH:mm:ss.SSSXXX" 2001-07-04T12:08:56.235-07:00
"YYYY-'W'ww-u" 2001-W27-3

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

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

С момента:
1.1
См. также:
Java Tutorial, Calendar, TimeZone, DateFormat, DateFormatSymbols, Serialized Form

Вложенные классы

Вложенные классы/интерфейсы, объявленные в классе java.text.DateFormat

DateFormat.Field

Поля

Поля, объявленные в классе java.text.DateFormat

AM_PM_FIELD, calendar, DATE_FIELD, DAY_OF_WEEK_FIELD, DAY_OF_WEEK_IN_MONTH_FIELD, DAY_OF_YEAR_FIELD, DEFAULT, ERA_FIELD, FULL, HOUR_OF_DAY0_FIELD, HOUR_OF_DAY1_FIELD, HOUR0_FIELD, HOUR1_FIELD, LONG, MEDIUM, MILLISECOND_FIELD, MINUTE_FIELD, MONTH_FIELD, numberFormat, SECOND_FIELD, SHORT, TIMEZONE_FIELD, WEEK_OF_MONTH_FIELD, WEEK_OF_YEAR_FIELD, YEAR_FIELD

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

Конструктор Описание
SimpleDateFormat()

Создаёт SimpleDateFormat с использованием шаблона по умолчанию и символов формата даты для локали по умолчанию FORMAT.
SimpleDateFormat​(String pattern)

Создаёт SimpleDateFormat с использованием заданного шаблона и символов формата даты по умолчанию для локали по умолчанию FORMAT.
SimpleDateFormat​(String pattern, DateFormatSymbols formatSymbols)

Создаёт SimpleDateFormat с использованием заданного шаблона и символов формата даты.
SimpleDateFormat​(String pattern, Locale locale)

Создаёт SimpleDateFormat с использованием заданного шаблона и символов формата даты по умолчанию для заданной локали.

Методы

Модификатор и тип Метод Описание
void applyLocalizedPattern​(String pattern)

Применяет заданную локализацию шаблона к этому формату даты.
void applyPattern​(String pattern)

Применяет заданный шаблон к этому формату даты.
Object clone()

Создает копию этого SimpleDateFormat.
boolean equals​(Object obj)

Сравнивает заданный объект с этим SimpleDateFormat на равенство.
StringBuffer format​(Date date, StringBuffer toAppendTo, FieldPosition pos)

Форматирует заданный Date в строку даты/времени и добавляет результат к заданному StringBuffer.
AttributedCharacterIterator formatToCharacterIterator​(Object obj)

Форматирует объект, создавая AttributedCharacterIterator.
Date get2DigitYearStart()

Возвращает начальную дату 100-летнего периода, в рамках которого интерпретируются двузначные годы.
DateFormatSymbols getDateFormatSymbols()

Получает копию символов формата даты и времени этого формата даты.
int hashCode()

Возвращает значение хэш-кода для этого объекта SimpleDateFormat.
Date parse​(String text, ParsePosition pos)

Парсит текст из строки для создания Date.
void set2DigitYearStart​(Date startDate)

Устанавливает 100-летний период, в рамках которого будут интерпретироваться двузначные годы, начиная с даты, указанной пользователем.
void setDateFormatSymbols​(DateFormatSymbols newFormatSymbols)

Устанавливает символы формата даты и времени этого формата даты.
String toLocalizedPattern()

Возвращает локальную строку шаблона, описывающую этот формат даты.
String toPattern()

Возвращает строку шаблона, описывающую этот формат даты.

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

format, format, getAvailableLocales, getCalendar, getDateInstance, getDateInstance, getDateInstance, getDateTimeInstance, getDateTimeInstance, getDateTimeInstance, getInstance, getNumberFormat, getTimeInstance, getTimeInstance, getTimeInstance, getTimeZone, isLenient, parse, parseObject, setCalendar, setLenient, setNumberFormat, setTimeZone

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

format, parseObject

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

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

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

SimpleDateFormat

public SimpleDateFormat()

Создаёт SimpleDateFormat с использованием по умолчанию шаблона и символов формата даты для локального FORMAT по умолчанию. Примечание: Этот конструктор может не поддерживать все языковые настройки. Для полной поддержки используйте методы-фабрики в классе DateFormat.

SimpleDateFormat

public SimpleDateFormat(String pattern)

Создаёт SimpleDateFormat с использованием заданного шаблона и символов формата даты по умолчанию для локального FORMAT по умолчанию. Примечание: Этот конструктор может не поддерживать все языковые настройки. Для полной поддержки используйте методы-фабрики в классе DateFormat класс.

Это эквивалентно вызову SimpleDateFormat(pattern, Locale.getDefault(Locale.Category.FORMAT)).

Параметры:
pattern - шаблон, описывающий формат даты и времени
Исключения:
NullPointerException - если заданный шаблон равен null
IllegalArgumentException - если заданный шаблон некорректен
См. также:
Locale.getDefault(java.util.Locale.Category), Locale.Category.FORMAT

SimpleDateFormat

public SimpleDateFormat(String pattern,
                        Locale locale)

Создаёт SimpleDateFormat с использованием заданного шаблона и символов формата даты для заданного региона. Примечание: Этот конструктор может не поддерживать все языковые настройки. Для полной поддержки используйте методы-фабрики в классе DateFormat классе.

Параметры:
pattern - шаблон, описывающий формат даты и времени
locale - регион, символы формата даты которого должны использоваться
Исключения:
NullPointerException - если заданный шаблон или регион равны null
IllegalArgumentException - если заданный шаблон некорректен

SimpleDateFormat

public SimpleDateFormat(String pattern,
                        DateFormatSymbols formatSymbols)

Создаёт SimpleDateFormat с использованием заданного шаблона и символов формата даты.

Параметры:
pattern - шаблон, описывающий формат даты и времени
formatSymbols - символы формата даты, которые должны быть использованы для форматирования
Исключения:
NullPointerException - если заданный шаблон или formatSymbols равны null
IllegalArgumentException - если заданный шаблон некорректен

Методы

set2DigitYearStart

public void set2DigitYearStart(Date startDate)

Устанавливает 100-летний период, в котором двухзначные годы будут интерпретироваться, начиная с указанной даты.

Параметры:
startDate - При разборе двухзначные годы будут помещены в диапазон startDate по startDate + 100 years.
Исключения:
NullPointerException - если startDate равно null.
С тех пор:
1.2
См. также:
get2DigitYearStart()

get2DigitYearStart

public Date get2DigitYearStart()

Возвращает начальную дату 100-летнего периода, в рамках которого интерпретируются двухзначные годы.

Возвращает:
начало 100-летнего периода, в который парсятся двухзначные годы
С тех пор:
1.2
См. также:
set2DigitYearStart(java.util.Date)

format

public StringBuffer format(Date date,
                           StringBuffer toAppendTo,
                           FieldPosition pos)

Форматирует заданное Date в строку даты/времени и добавляет результат к заданному StringBuffer.

Определено в:
format в классе DateFormat
Параметры:
date - значение даты-времени, которое необходимо отформатировать в строку даты-времени.
toAppendTo - место, куда будет добавлен новый текст даты-времени.
pos - отслеживает положение поля в возвращаемой строке. Например, для строки даты-времени "1996.07.10 AD at 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'.
Возвращает:
отформатированная строка даты-времени.
Исключения:
NullPointerException - если любой из параметров имеет значение null.

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object obj)

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

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

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

parse

public Date parse(String text,
                  ParsePosition pos)

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

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

Данная операция разбора использует calendar для получения Date . Все поля даты и времени calendar обнуляются перед разбором, и значения по умолчанию полей даты и времени calendar используются для любой отсутствующей информации даты и времени. Например, значение года разобранного Date равно 1970 с GregorianCalendar если значение года не указано в операции разбора. Значение TimeZone может быть перезаписано, в зависимости от заданного шаблона и значения часового пояса в text. Любое значение TimeZone , которое было установлено ранее вызовом setTimeZone , может потребоваться восстановить для дальнейших операций.

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

toPattern

public String toPattern()

Возвращает строку шаблона, описывающую этот формат даты.

Возвращает:
строку шаблона, описывающую этот формат даты.

toLocalizedPattern

public String toLocalizedPattern()

Возвращает локализованную строку шаблона, описывающую этот формат даты.

Возвращает:
локализованную строку шаблона, описывающую этот формат даты.

applyPattern

public void applyPattern(String pattern)

Применяет заданную строку шаблона к этому формату даты.

Параметры:
pattern - новый шаблон даты и времени для этого формата даты
Исключения:
NullPointerException - если заданный шаблон равен null
IllegalArgumentException - если заданный шаблон некорректен

applyLocalizedPattern

public void applyLocalizedPattern(String pattern)

Применяет заданную локализованную строку шаблона к этому формату даты.

Параметры:
pattern - строка, которая будет сопоставлена с новым шаблоном даты и времени для этого формата
Исключения:
NullPointerException - если заданный шаблон равен null
IllegalArgumentException - если заданный шаблон некорректен

getDateFormatSymbols

public DateFormatSymbols getDateFormatSymbols()

Получает копию символов формата даты и времени этого формата даты.

Возвращает:
символы формата даты и времени этого формата даты
См. также:
setDateFormatSymbols(java.text.DateFormatSymbols)

setDateFormatSymbols

public void setDateFormatSymbols(DateFormatSymbols newFormatSymbols)

Устанавливает символы формата даты и времени этого формата даты.

Параметры:
newFormatSymbols - новые символы формата даты и времени
Исключения:
NullPointerException - если заданный новыйFormatSymbols равен null
См. также:
getDateFormatSymbols()

clone

public Object clone()

Создает копию этого SimpleDateFormat. Также клонирует символы формата даты этого формата.

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

hashCode

public int hashCode()

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

Переопределяет:
hashCode в классе DateFormat
Возвращает:
значение хэш-кода для этого объекта SimpleDateFormat.
См. также:
Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

equals

public boolean equals(Object obj)

Сравнивает заданный объект с этим объектом SimpleDateFormat на равенство.

Переопределяет:
equals в классе DateFormat
Параметры:
obj - объект-ссылка для сравнения.
Возвращает:
true, если заданный объект равен этому объекту SimpleDateFormat
См. также:
Object.hashCode(), HashMap

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/text/SimpleDateFormat.html

Spec-Zone .ru
спецификации, руководства, описания, API