Класс 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. Формат не зависит от локали, и цифры должны быть взяты из базового латинского блока стандарта Юникод.

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

• RFC 822 часовой пояс: Для форматирования используется 4-значный формат часового пояса RFC 822:

       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

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

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