Класс 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

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

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