cal_to_jd()

PHP cal_to_jd(): Преобразование даты календаря в юлианский номер дня

Функция cal_to_jd() преобразует дату из поддерживаемого календаря (григорианского, юлианского, еврейского или французского республиканского) в юлианский номер дня — единственное целое число, однозначно идентифицирующее день. Поскольку результат — просто число, оно является удобным общим знаменателем для сравнения дат, вычисления количества дней между двумя датами или конвертации между календарными системами.

На этой странице описаны сигнатура функции, рабочий пример, поддерживаемые календари, наиболее распространённые ошибки и дальнейшие шаги.

Примечание: cal_to_jd() является частью расширения Calendar PHP. Расширение поставляется в комплекте с PHP, но должно быть включено (по умолчанию оно компилируется в большинстве сборок). Если функция не определена, включите ext-calendar.

Что такое юлианский номер дня?

Юлианский номер дня (Julian Day Count, также называемый Julian Day Number, JDN) — это непрерывный счёт дней, начиная с 1 января 4713 г. до н. э. по пролептическому юлианскому календарю, который считается днём 0. Каждая последующая дата соответствует большему положительному целому числу, а более ранние даты имели бы отрицательные значения.

Этот счёт не зависит от конкретного календаря: он не привязан к месяцам, високосным годам или той или иной календарной системе. Это делает его стандартным «опорным» представлением в астрономии, научных вычислениях и любом коде, который должен взаимодействовать с разными календарями.

Не следует путать юлианский номер дня (номер дня) с юлианским календарём (до-григорианским календарём). Несмотря на похожие названия, они не связаны между собой.

Синтаксис

cal_to_jd(int $calendar, int $month, int $day, int $year): int

Возвращаемое значение: юлианский номер дня в виде int, или 0, если дата недействительна для выбранного календаря.

Базовый пример

Преобразование 2 марта 2023 года (григорианский) в юлианский номер дня:

Обратите внимание на порядок аргументов: это month, day, year, а не day-month-year или year-month-day. Путаница с этим — наиболее распространённая ошибка при использовании cal_to_jd().

Выбор константы календаря

Первый аргумент определяет, к какому календарю относятся значения month/day/year:

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

<?php
// October 15, 1582 — the day the Gregorian calendar began.
echo cal_to_jd(CAL_GREGORIAN, 10, 15, 1582), "\n"; // 2299161
echo cal_to_jd(CAL_JULIAN,    10, 5,  1582), "\n";  // 2299161
?>

Оба выводят одинаковый юлианский номер дня, потому что при григорианской реформе было пропущено 10 дней: григорианское 15 октября и юлианское 5 октября — это один и тот же физический день.

Типичные ошибки

• Недействительные даты возвращают 0, а не false. Передача несуществующей даты, например 30 февраля, даёт 0. Проверяйте пользовательский ввод с помощью checkdate() перед преобразованием, если нужно обнаружить некорректные даты.
• Порядок аргументов — month, day, year. См. примечание выше.
• Расширение должно быть включено. Вызов зависит от ext-calendar; ошибка «undefined function» означает, что оно не загружено.

Обратное преобразование с cal_from_jd()

У cal_to_jd() есть обратная функция: cal_from_jd() преобразует юлианский номер дня обратно в дату календаря. Вместе они позволяют конвертировать даты между календарными системами, используя юлианский номер дня как нейтральный промежуточный формат:

<?php
$jd = cal_to_jd(CAL_GREGORIAN, 3, 2, 2023);

$date = cal_from_jd($jd, CAL_GREGORIAN);
echo $date['date']; // 3/2/2023
?>

Связанные функции

• cal_from_jd() — обратная функция: юлианский номер дня в дату календаря.
• cal_info() — метаданные (названия месяцев и др.) о календаре.
• cal_days_in_month() — количество дней в заданном месяце.
• gregoriantojd(), juliantojd(), jewishtojd(), frenchtojd() — специализированные сокращения для того же преобразования для каждого календаря.
• Полный обзор функций Calendar в PHP.

Заключение

cal_to_jd() сводит любую поддерживаемую дату календаря к единственному целому числу — юлианскому номеру дня — обеспечивая нейтральный к календарю способ сравнения дат, измерения интервалов и конвертации между календарями. Помните порядок аргументов month, day, year, выбирайте константу календаря, соответствующую входным данным, и используйте cal_from_jd() для обратного преобразования.

Практика