Класс 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', используется год календаря ('y'). Поддержку годов недель можно проверить, вызвав getCalendar().isWeekDateSupported().
  
  
• Месяц: Если количество символов шаблона 3 или больше, месяц интерпретируется как текст; в противном случае он интерпретируется как число.
  
  • Символ M производит контекстно-зависимые имена месяцев, такие как встроенная форма имен. Если DateFormatSymbols был явно задан с помощью конструктора SimpleDateFormat(String, DateFormatSymbols) или метода setDateFormatSymbols(DateFormatSymbols), используются имена месяцев, заданные DateFormatSymbols.
  • Символ L производит независимую от контекста форму имен месяцев.
  
  
• Общий часовой пояс: Часовые пояса интерпретируются как текст, если они имеют названия. Для часовых поясов, представляющих значение смещения по Гринвичу, используется следующий синтаксис:

  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

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

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

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

SimpleDateFormat

public SimpleDateFormat()

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

SimpleDateFormat

public SimpleDateFormat(String pattern)

Параметры:

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.

С:

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 - позиция форматирования. На входе: поле выравнивания (при необходимости). На выходе: смещения поля выравнивания.

Возвращает:

отформатированная строка даты-времени.

Исключения:

NullPointerException - если заданная date null.

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object obj)

Переопределяет:

formatToCharacterIterator в классе Format

Параметры:

obj - Формируемый объект

Возвращает:

AttributedCharacterIterator, описывающий отформатированное значение.

Исключения:

NullPointerException - если obj null.

IllegalArgumentException - если Format не может отформатировать данный объект или строка шаблона Format некорректна.

С:

1.4

parse

public Date parse(String text,
                  ParsePosition pos)

Определено в:

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 - если заданный newFormatSymbols 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