Класс SimpleDateFormat

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, год интерпретируется буквально, независимо от количества цифр. Поэтому, используя шаблон "MM/dd/yyyy", "01/11/12" парсится как 11 января 12 года н.э.
  • При парсинге с использованием сокращенного шаблона года ("y" или "yy"), SimpleDateFormat должен интерпретировать сокращенный год относительно какого-то столетия. Он делает это, корректируя даты, чтобы они находились в пределах 80 лет до и 20 лет после момента создания экземпляра SimpleDateFormat. Например, используя шаблон "MM/dd/yy" и экземпляр 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 или больше, используется специфичная для календаря полная форма. В противном случае используется специфичная для календаря короткая или сокращенная форма.
  
  Если указан год недели 'Y', и календарь календарь не поддерживает какие-либо годы недели, используется год календаря ('y') вместо него. Поддержка годов недели может быть проверена вызовом getCalendar().isWeekDateSupported().
  
  
• Месяц: Если количество символов шаблона равно 3 или больше, месяц интерпретируется как текст; в противном случае он интерпретируется как число.
  
  • Символ M создает контекстно-зависимые имена месяцев, такие как встроенные формы имён. Символ M является контекстно-зависимым в том смысле, что когда он используется в отдельном шаблоне, например, "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 или более, при создании SimpleDateFormat или применении шаблона выбрасывается исключение IllegalArgumentException.

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

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

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