Spec-Zone.ru › OpenJDK 17

Класс SimpleDateFormat

java.lang.Object
java.text.Format
java.text.DateFormat
java.text.SimpleDateFormat
Все реализованные интерфейсы:
Serializable, Cloneable 
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

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

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

Примечание API:
Рассмотрите использование DateTimeFormatter в качестве неизменяемой и потокобезопасной альтернативы.
С:
1.1
См. также:
  • Java Tutorial
  • Calendar
  • TimeZone
  • DateFormat
  • DateFormatSymbols
  • DateTimeFormatter
  • Сериализованная форма

Краткое описание вложенных классов

Вложенные классы/интерфейсы, объявленные в классе java.text.DateFormat

DateFormat.Field

Краткое описание полей

Поля, объявленные в классе java.text.DateFormat

AM_PM_FIELD, calendar, DATE_FIELD, DAY_OF_WEEK_FIELD, DAY_OF_WEEK_IN_MONTH_FIELD, DAY_OF_YEAR_FIELD, DEFAULT, ERA_FIELD, FULL, HOUR_OF_DAY0_FIELD, HOUR_OF_DAY1_FIELD, HOUR0_FIELD, HOUR1_FIELD, LONG, MEDIUM, MILLISECOND_FIELD, MINUTE_FIELD, MONTH_FIELD, numberFormat, SECOND_FIELD, SHORT, TIMEZONE_FIELD, WEEK_OF_MONTH_FIELD, WEEK_OF_YEAR_FIELD, YEAR_FIELD

Краткое описание конструкторов

Конструктор Описание
SimpleDateFormat()
Создаёт SimpleDateFormat с использованием стандартного шаблона и символов формата даты для локали по умолчанию FORMAT.
SimpleDateFormat(String pattern)
Создаёт SimpleDateFormat с использованием заданного шаблона и стандартных символов формата даты для локали по умолчанию FORMAT.
SimpleDateFormat(String pattern, DateFormatSymbols formatSymbols)
Создаёт SimpleDateFormat с использованием заданного шаблона и символов формата даты.
SimpleDateFormat(String pattern, Locale locale)
Создаёт SimpleDateFormat с использованием заданного шаблона и стандартных символов формата даты для заданной локали.

Краткое описание методов

Модификатор и тип Метод Описание
void applyLocalizedPattern(String pattern)
Применяет заданную локализацию шаблона к этому формату даты.
void applyPattern(String pattern)
Применяет заданный шаблон к этому формату даты.
Object clone()
Создаёт копию этого SimpleDateFormat.
boolean equals(Object obj)
Сравнивает данный объект с этим SimpleDateFormat на равенство.
StringBuffer format(Date date, StringBuffer toAppendTo, FieldPosition pos)
Форматирует данное Date в строку даты/времени и добавляет результат к данному StringBuffer.
AttributedCharacterIterator formatToCharacterIterator(Object obj)
Форматирует объект, создавая AttributedCharacterIterator.
Date get2DigitYearStart()
Возвращает начальную дату 100-летнего периода, в рамках которого интерпретируются двузначные годы.
DateFormatSymbols getDateFormatSymbols()
Получает копию символов формата даты и времени этого формата даты.
int hashCode()
Возвращает хэш-код для этого объекта SimpleDateFormat.
Date parse(String text, ParsePosition pos)
Парсит текст из строки, чтобы получить Date.
void set2DigitYearStart(Date startDate)
Устанавливает 100-летний период, в котором будут интерпретироваться двузначные годы, начиная с указанной даты пользователем.
void setDateFormatSymbols(DateFormatSymbols newFormatSymbols)
Устанавливает символы формата даты и времени для этого формата даты.
String toLocalizedPattern()
Возвращает локализацию шаблона, описывающего этот формат даты.
String toPattern()
Возвращает шаблон, описывающий этот формат даты.

Методы, объявленные в классе java.text.DateFormat

format, format, getAvailableLocales, getCalendar, getDateInstance, getDateInstance, getDateInstance, getDateTimeInstance, getDateTimeInstance, getDateTimeInstance, getInstance, getNumberFormat, getTimeInstance, getTimeInstance, getTimeInstance, getTimeZone, isLenient, parse, parseObject, setCalendar, setLenient, setNumberFormat, setTimeZone

Методы, объявленные в классе java.text.Format

format, parseObject

Методы, объявленные в классе java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Подробное описание конструкторов

SimpleDateFormat

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

SimpleDateFormat

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

Это эквивалентно вызову SimpleDateFormat(pattern, Locale.getDefault(Locale.Category.FORMAT)).

Параметры:
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.
Исключения:
NullPointerException - если startDate равно null.
С:
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 - отслеживает позицию поля в возвращаемой строке. Например, для строки даты-времени "1996.07.10 AD at 15:08:56 PDT", если заданное fieldPosition равно DateFormat.YEAR_FIELD, начальный и конечный индексы fieldPosition будут установлены соответственно в 0 и 4. Обратите внимание, что если одно и то же поле даты-времени появляется более одного раза в шаблоне, то fieldPosition будет установлено для первого вхождения этого поля даты-времени. Например, при форматировании Date в строку даты-времени "1 PM PDT (Pacific Daylight Time)" с шаблоном "h a z (zzzz)" и полем выравнивания DateFormat.TIMEZONE_FIELD, начальный и конечный индексы fieldPosition будут установлены соответственно в 5 и 8 для первого вхождения символа шаблона часового пояса 'z'.
Возвращает:
отформатированная строка даты-времени.
Исключения:
NullPointerException - если какой-либо из параметров равен null.

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object obj)
Форматирует объект, создавая AttributedCharacterIterator. Вы можете использовать возвращённый AttributedCharacterIterator для построения результирующей строки, а также для получения информации о результирующей строке.

Каждый ключ атрибута AttributedCharacterIterator будет иметь тип DateFormat.Field, а соответствующее значение атрибута будет таким же, как и ключ атрибута.

Переопределяет:
formatToCharacterIterator в классе Format
Параметры:
obj - объект для форматирования
Возвращает:
AttributedCharacterIterator, описывающий отформатированное значение.
Исключения:
NullPointerException - если obj равен null.
IllegalArgumentException - если Format не может отформатировать заданный объект или если строка шаблона Format некорректна.
С:
1.4

parse

public Date parse(String text, ParsePosition pos)
Парсит текст из строки для получения Date.

Метод пытается пропарсить текст, начиная с индекса, заданного pos. Если парсинг успешен, то индекс pos обновляется до индекса после последнего использованного символа (парсинг не обязательно использует все символы до конца строки), и возвращается пропарсенная дата. Обновлённый pos может быть использован для указания начальной точки для следующего вызова этого метода. Если произошла ошибка, то индекс pos не изменяется, индекс ошибки pos устанавливается в индекс символа, где произошла ошибка, и возвращается null.

Эта операция парсинга использует calendar для получения Date. Все поля даты-времени calendar очищаются перед парсингом, а значения полей даты-времени по умолчанию calendar используются для любой недостающей информации о дате-времени. Например, значение года пропарсенной Date равно 1970 с GregorianCalendar, если значение года не задано результатом операции парсинга. Значение TimeZone может быть перезаписано в зависимости от заданного шаблона и значения часового пояса в text. Любое предварительно заданное значение TimeZone с помощью вызова setTimeZone может потребоваться восстановить для дальнейших операций.

Определено в:
parse в классе DateFormat
Параметры:
text - Строка, часть которой должна быть пропарсена.
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 - если заданные новые символы формата 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

© 1993, 2021, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/text/SimpleDateFormat.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API