Temporal.PlainDate

Объект Temporal.PlainDate представляет календарную дату (дату без времени и часового пояса); например, событие в календаре, которое длится весь день независимо от часового пояса, в котором оно происходит. В основе объекта лежит календарная дата в формате ISO 8601 с полями года, месяца и дня и связанной с ней календарной системой.

Описание

Объект PlainDate — это, по сути, часть даты объекта Temporal.PlainDateTime, из которой удалена информация о времени. Поскольку дата и время практически не взаимодействуют друг с другом, здесь описана общая информация о свойствах даты.

Формат RFC 9557

Объекты PlainDate можно сериализовать и анализировать с помощью формата RFC 9557 — расширения формата ISO 8601 / RFC 3339. Строка имеет следующий вид (пробелы добавлены только для удобства чтения и не должны присутствовать в фактической строке):

YYYY-MM-DD [u-ca=calendar_id]

YYYY

Четырёхзначное число или шестизначное число со знаком + или -.

MM

Двухзначное число от 01 до 12.

DD

Двухзначное число от 01 до 31. Компоненты YYYY, MM и DD могут разделяться символом - или не разделяться вовсе.

[u-ca=calendar_id] Необязательно

Замените calendar_id на используемый календарь. Список наиболее распространённых поддерживаемых типов календарей см. в разделе Intl.supportedValuesOf(). По умолчанию используется [u-ca=iso8601]. Можно добавить критический флаг, поставив перед ключом !: например, [!u-ca=iso8601]. Этот флаг обычно указывает другим системам, что аннотацию нельзя игнорировать, если они её не поддерживают. Анализатор Temporal выдаст ошибку, если аннотации содержат две или более аннотаций календаря и одна из них является критической. Обратите внимание, что YYYY-MM-DD всегда интерпретируется как календарная дата ISO 8601, а затем преобразуется в указанный календарь.

В качестве входных данных можно дополнительно указать время, смещение и идентификатор часового пояса в том же формате, что и PlainDateTime, но они будут проигнорированы. Другие аннотации в формате [key=value] также игнорируются, и для них нельзя указывать критический флаг.

При сериализации можно настроить отображение идентификатора календаря и добавление к нему критического флага.

Ограничение недопустимой даты

Методы Temporal.PlainDate.from(), Temporal.PlainDate.prototype.with(), Temporal.PlainDate.prototype.add(), Temporal.PlainDate.prototype.subtract() и их аналоги в других объектах Temporal позволяют создавать даты с использованием свойств, зависящих от календаря. Компоненты даты могут выходить за допустимые пределы. В календаре ISO это всегда является переполнением, например, если месяц больше 12 или число превышает количество дней в месяце. Для исправления достаточно ограничить значение максимально допустимым. В других календарях недопустимый случай может быть сложнее. При использовании параметра overflow: "constrain" недопустимые даты исправляются следующим образом:

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

Конструктор

Temporal.PlainDate() Экспериментальная функция

Создаёт новый объект Temporal.PlainDate, напрямую задавая исходные данные.

Статические методы

Temporal.PlainDate.compare()

Возвращает число (-1, 0 или 1), указывающее, предшествует ли первая дата второй, совпадает с ней или следует за ней. Эквивалентно сравнению полей года, месяца и дня исходных дат ISO 8601.

Temporal.PlainDate.from()

Создаёт новый объект Temporal.PlainDate из другого объекта Temporal.PlainDate, объекта со свойствами даты или строки RFC 9557.

Свойства экземпляра

Эти свойства определены в Temporal.PlainDate.prototype и доступны всем экземплярам Temporal.PlainDate.

Temporal.PlainDate.prototype.calendarId

Возвращает строку, представляющую календарь, используемый для интерпретации внутренней даты ISO 8601.

Temporal.PlainDate.prototype.constructor

Функция-конструктор, создавшая объект экземпляра. Для экземпляров Temporal.PlainDate исходным значением является конструктор Temporal.PlainDate().

Temporal.PlainDate.prototype.day

Возвращает положительное целое число, представляющее порядковый номер дня этой даты в месяце, начиная с 1, то есть тот же номер дня, который отображается в календаре. Зависит от календаря. Обычно отсчёт начинается с 1 и ведётся непрерывно, но не всегда.

Temporal.PlainDate.prototype.dayOfWeek

Возвращает положительное целое число, представляющее порядковый номер дня этой даты в неделе, начиная с 1. Дни недели нумеруются последовательно от 1 до daysInWeek, причём каждому числу соответствует своё название. Зависит от календаря. Обычно 1 соответствует понедельнику в календаре, даже если в локалях, использующих этот календарь, первым днём недели считается другой день (см. Intl.Locale.prototype.getWeekInfo()).

Temporal.PlainDate.prototype.dayOfYear

Возвращает положительное целое число, представляющее порядковый номер дня этой даты в году, начиная с 1. Первый день этого года — 1, а последний — daysInYear. Зависит от календаря.

Temporal.PlainDate.prototype.daysInMonth

Возвращает положительное целое число, представляющее количество дней в месяце этой даты. Зависит от календаря.

Temporal.PlainDate.prototype.daysInWeek

Возвращает положительное целое число, представляющее количество дней в неделе этой даты. Зависит от календаря. В календаре ISO 8601 это значение всегда равно 7, но в других календарных системах оно может меняться от недели к неделе.

Temporal.PlainDate.prototype.daysInYear

Возвращает положительное целое число, представляющее количество дней в году этой даты. Зависит от календаря. В календаре ISO 8601 это значение равно 365, а в високосном году — 366.

Temporal.PlainDate.prototype.era

Возвращает строчную строку, зависящую от календаря и представляющую эру этой даты, или undefined, если в календаре не используются эры (например, в ISO 8601). era и eraYear вместе однозначно определяют год в календаре так же, как year. Зависит от календаря. Для григорианского календаря это либо "ce", либо "bce".

Temporal.PlainDate.prototype.eraYear

Возвращает неотрицательное целое число, представляющее год этой даты в пределах эры, или undefined, если в календаре не используются эры (например, в ISO 8601). Отсчёт лет обычно начинается с 1 (чаще) или с 0, а годы в эре могут уменьшаться со временем (например, в григорианском календаре до нашей эры). era и eraYear вместе однозначно определяют год в календаре так же, как year. Зависит от календаря.

Temporal.PlainDate.prototype.inLeapYear

Возвращает логическое значение, указывающее, приходится ли эта дата на високосный год. В високосном году дней больше, чем в обычном, из-за дополнительного дня или месяца. Зависит от календаря.

Temporal.PlainDate.prototype.month

Возвращает положительное целое число, представляющее порядковый номер месяца этой даты в году, начиная с 1. Первый месяц этого года — 1, а последний — monthsInYear. Зависит от календаря. Обратите внимание: в отличие от Date.prototype.getMonth(), отсчёт индекса начинается с 1. Если в календаре есть високосные месяцы, то у месяца с тем же monthCode значение индекса month может различаться в разные годы.

Temporal.PlainDate.prototype.monthCode

Возвращает строку, зависящую от календаря и представляющую месяц этой даты. Зависит от календаря. Обычно это M и двухзначный номер месяца. Для високосных месяцев используется код предыдущего месяца с добавлением L. Если високосный месяц является первым месяцем года, кодом будет M00L.

Temporal.PlainDate.prototype.monthsInYear

Возвращает положительное целое число, представляющее количество месяцев в году этой даты. Зависит от календаря. В календаре ISO 8601 это значение всегда равно 12, но в других календарных системах оно может отличаться.

Temporal.PlainDate.prototype.weekOfYear

Возвращает положительное целое число, представляющее порядковый номер недели этой даты в году yearOfWeek, начиная с 1, или undefined, если в календаре нет чётко определённой системы недель. Первая неделя года — 1. Зависит от календаря. Обратите внимание: в ISO 8601 первые и последние несколько дней года могут относиться к последней неделе предыдущего года или первой неделе следующего года.

Temporal.PlainDate.prototype.year

Возвращает целое число, представляющее количество лет этой даты относительно начала года эпохи, определяемого календарём. Зависит от календаря. Обычно год 1 — это либо первый год последней эры, либо год 0001 по ISO 8601. Если эпоха начинается в середине года, значение этого года будет одинаковым как до, так и после даты начала эры.

Temporal.PlainDate.prototype.yearOfWeek

Возвращает целое число, представляющее год, соответствующий значению weekOfYear этой даты, или undefined, если в календаре нет чётко определённой системы недель. Зависит от календаря. Обычно это год даты, но в ISO 8601 первые и последние несколько дней года могут относиться к последней неделе предыдущего года или первой неделе следующего года, из-за чего значение yearOfWeek отличается на 1.

Temporal.PlainDate.prototype[Symbol.toStringTag]

Исходное значение свойства [Symbol.toStringTag] — строка "Temporal.PlainDate". Это свойство используется в Object.prototype.toString().

Методы экземпляра

Temporal.PlainDate.prototype.add()

Возвращает новый объект Temporal.PlainDate, представляющий эту дату, сдвинутую вперёд на заданную длительность (в формате, преобразуемом с помощью Temporal.Duration.from()).

Temporal.PlainDate.prototype.equals()

Возвращает true, если значение этой даты эквивалентно значению другой даты (в формате, преобразуемом с помощью Temporal.PlainDate.from()), и false в противном случае. Даты сравниваются как по значениям дат, так и по календарям.

Temporal.PlainDate.prototype.since()

Возвращает новый объект Temporal.Duration, представляющий длительность от другой даты (в формате, преобразуемом с помощью Temporal.PlainDate.from()) до этой даты. Длительность положительна, если другая дата предшествует этой, и отрицательна, если следует за ней.

Temporal.PlainDate.prototype.subtract()

Возвращает новый объект Temporal.PlainDate, представляющий эту дату, сдвинутую назад на заданную длительность (в формате, преобразуемом с помощью Temporal.Duration.from()).

Temporal.PlainDate.prototype.toJSON()

Возвращает строку, представляющую эту дату в том же формате RFC 9557, что и вызов toString(). Предназначен для неявного вызова методом JSON.stringify().

Temporal.PlainDate.prototype.toLocaleString()

Возвращает строку, представляющую эту дату с учётом языковых особенностей.

Temporal.PlainDate.prototype.toPlainDateTime()

Возвращает новый объект Temporal.PlainDateTime, представляющий эту дату и заданное время в той же календарной системе.

Temporal.PlainDate.prototype.toPlainMonthDay()

Возвращает новый объект Temporal.PlainMonthDay, представляющий monthCode и day этой даты в той же календарной системе.

Temporal.PlainDate.prototype.toPlainYearMonth()

Возвращает новый объект Temporal.PlainYearMonth, представляющий year и month этой даты в той же календарной системе.

Temporal.PlainDate.prototype.toString()

Возвращает строку, представляющую эту дату в формате RFC 9557.

Temporal.PlainDate.prototype.toZonedDateTime()

Возвращает новый объект Temporal.ZonedDateTime, представляющий эту дату, заданное время и заданный часовой пояс в той же календарной системе.

Temporal.PlainDate.prototype.until()

Возвращает новый объект Temporal.Duration, представляющий длительность от этой даты до другой даты (в формате, преобразуемом с помощью Temporal.PlainDate.from()). Длительность положительна, если другая дата следует за этой, и отрицательна, если предшествует ей.

Temporal.PlainDate.prototype.valueOf()

Выбрасывает исключение TypeError, не позволяя экземплярам Temporal.PlainDate неявно преобразовываться в примитивы при использовании в арифметических операциях или операциях сравнения.

Temporal.PlainDate.prototype.with()

Возвращает новый объект Temporal.PlainDate, представляющий эту дату с заменой некоторых полей новыми значениями.

Temporal.PlainDate.prototype.withCalendar()

Возвращает новый объект Temporal.PlainDate, представляющий эту дату, интерпретируемую в новой календарной системе.

Спецификации

Совместимость с браузерами

См. также

• Temporal
• Temporal.Duration
• Temporal.PlainDateTime
• Temporal.PlainMonthDay
• Temporal.PlainYearMonth
• Temporal.ZonedDateTime