cal_from_jd()

PHP-функция cal_from_jd()

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

На этой странице объясняется, что такое юлианский счёт дней, как работает cal_from_jd(), что означает каждый ключ возвращаемого array и чем эта функция отличается от других календарных функций PHP. Для работы этих функций необходимо подключить расширение calendar.

Синтаксис

cal_from_jd(int $julian_day, int $calendar): array

• $julian_day — юлианский счёт дней для преобразования. Должен быть целым числом; дробная часть float усекается.
• $calendar — целевой календарь. Используйте одну из констант ниже.

Функция всегда возвращает array — при корректном целочисленном вводе возвращаемого значения об ошибке нет.

Что такое юлианский счёт дней?

Юлианский счёт дней (JDC) — это непрерывный счёт целых дней, начиная с полудня UTC 1 января 4713 г. до н. э. по пролептическому юлианскому календарю. Поскольку это единственное непрерывно растущее целое число без месяцев и правил високосных лет, оно идеально подходит в качестве нейтральной точки пересчёта при конвертации между календарными системами: вы преобразуете любую дату в JDC, а затем конвертируете этот JDC в целевой календарь.

Именно поэтому его используют в астрономии, программировании и исторических исследованиях — арифметика дат с обычным целым числом проста и однозначна.

Не путайте юлианский счёт дней с юлианским календарём. Счёт дней — это просто число; юлианский календарь — это более старый календарь, который Папа Григорий XIII реформировал в октябре 1582 года, создав используемый нами сегодня григорианский календарь.

Array, возвращаемый cal_from_jd()

Для заданного юлианского счёта дней cal_from_jd() возвращает ассоциативный array со следующими ключами:

Простой пример

Преобразование юлианского счёта дней в григорианскую дату и чтение её компонентов:

<?php
$jd = gregoriantojd(3, 22, 2021); // JDC for March 22, 2021

$date = cal_from_jd($jd, CAL_GREGORIAN);

echo "Date string: " . $date['date'] . "\n";
echo "Year:  " . $date['year'] . "\n";
echo "Month: " . $date['monthname'] . "\n";
echo "Day:   " . $date['day'] . "\n";
echo "Weekday: " . $date['dayname'] . "\n";
?>

Вывод:

Date string: 3/22/2021
Year:  2021
Month: March
Day:   22
Weekday: Monday

Просмотр всего array

Если вы не уверены, какие ключи вам нужны, выведите полное возвращаемое значение:

<?php
$jd = gregoriantojd(12, 25, 2021); // Christmas 2021
print_r(cal_from_jd($jd, CAL_GREGORIAN));
?>

Вывод:

Array
(
    [date] => 12/25/2021
    [month] => 12
    [day] => 25
    [year] => 2021
    [dow] => 6
    [abbrevdayname] => Sat
    [dayname] => Saturday
    [abbrevmonth] => Dec
    [monthname] => December
)

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

• Целое число, а не float с .5. В отличие от астрономической юлианской даты, cal_from_jd() ожидает целочисленный счёт дней. Передача float просто усекает дробную часть.
• Расширение calendar должно быть загружено. Если вы получаете ошибку "Call to undefined function cal_from_jd()", включите расширение calendar в своей сборке PHP.
• Выбирайте подходящую константу календаря. Один и тот же JDC даёт разные значения year/month/day для CAL_GREGORIAN и CAL_JULIAN; всегда передавайте именно ту константу, которую имеете в виду.

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

• cal_to_jd() — обратная операция: преобразование даты в юлианский счёт дней.
• gregoriantojd() — получение юлианского счёта дней из григорианской даты.
• jdtogregorian() — преобразование юлианского счёта дней обратно в строку григорианской даты.
• cal_info() — получение названий месяцев/дней и других метаданных для календаря.
• jddayofweek() — получение дня недели для юлианского счёта дней.

Заключение

cal_from_jd() преобразует юлианский счёт дней в подробный array составных частей даты для любого из четырёх поддерживаемых PHP календарей. В сочетании с cal_to_jd() (или gregoriantojd()) эта функция позволяет конвертировать даты между календарными системами, используя единое целое число — юлианский счёт дней — как нейтральный промежуточный формат.

Практика