Класс SimpleDateFormat

public class SimpleDateFormat extends DateFormat

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

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

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

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

Определены следующие буквы шаблона (все остальные символы от 'A' до 'Z' и от 'a' до 'z', не указанные в таблице ниже, зарезервированы). При передаче шаблона с не заключённым в кавычки зарезервированным символом методы applyPattern(String), applyLocalizedPattern(String) и SimpleDateFormat constructors выбрасывают IllegalArgumentException.

Таблица букв шаблона, компонентов даты и времени, способов представления и примеров.

Буква	Компонент даты или времени	Представление	Примеры
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	Обозначение до/после полудня	Текст	PM
H	Час дня (0–23)	Число	0
k	Час дня (1–24)	Число	24
K	Час до/после полудня (0–11)	Число	0
h	Час до/после полудня (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

  Двузначное число часов должно быть в диапазоне от 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

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

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