frenchtojd()

Введение

Функция PHP frenchtojd() преобразует дату Французского республиканского календаря в Julian Day Count — единое целое число, однозначно идентифицирующее календарный день. На этой странице объясняется, что означают эти два термина, как вызывать функцию, что означают возвращаемые значения и какие граничные случаи чаще всего вызывают проблемы.

Julian Day Count (JDC) — это непрерывный счёт дней с начала юлианского периода: полдень UTC 1 января 4713 года до н. э. Поскольку это обычное целое число, оно используется в PHP как общий «промежуточный» формат для конвертации между календарями — вы преобразуете дату календаря A в юлианский день, а затем этот юлианский день — в дату календаря B. Формат также широко применяется в астрономии и в любой области, где требуется непрерывное, независимое от календаря измерение времени.

Французский республиканский календарь использовался во Франции с 1793 по 1805 год и был введён Французской революцией взамен григорианского. В нём 12 месяцев по 30 дней каждый, разделённых на трёхнедельные десятидневки (décades), плюс 5 или 6 дополнительных «комплементарных дней» в конце года. Годы отсчитываются от основания Республики (Год I, Год II, …), традиционно обозначаемые римскими цифрами.

Использование встроенной функции PHP frenchtojd()

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

Примечание: Эта функция требует включённого расширения calendar. Проверьте с помощью extension_loaded('calendar'); если оно возвращает false, включите расширение в вашем php.ini.

<?php

$jd = frenchtojd($month, $day, $year);

?>

Функция принимает три целочисленных параметра и возвращает int:

• $month: Номер месяца (1–13). Месяцы 1–12 — это обычные 30-дневные месяцы (Vendémiaire … Fructidor); месяц 13 содержит комплементарные дни.
• $day: День месяца (1–30 для месяцев 1–12, 1–6 для месяца 13).
• $year: Год Французской Республики, например 1 для Года I.

Допустимый диапазон приблизительно — от 1 Vendémiaire Года 1 до конца Года 14. Любая дата вне поддерживаемого диапазона — включая frenchtojd(0, 0, 0) — возвращает 0. Всегда проверяйте результат на 0 перед использованием значения.

Пример использования

Передайте месяц, день и год французской даты в качестве параметров:

<?php

$jd = frenchtojd(12, 22, 1);
echo $jd; // Output: 2376191

?>

Здесь мы конвертируем 22 Fructidor, Год I (месяц 12, день 22, год 1) в его Julian Day Count — 2376191. Этот юлианский день соответствует 8 сентября 1793 года по григорианскому календарю.

Конвертация в другие календари

Поскольку результат является юлианским днём, его можно передать в любую функцию jdto*(), чтобы выразить тот же день в другом календаре. Это наиболее частая причина вызова frenchtojd():

<?php

$jd = frenchtojd(12, 22, 1);     // 22 Fructidor, Year I → 2376191

echo jdtogregorian($jd), "\n";   // Output: 9/8/1793
echo jddayofweek($jd, 1), "\n";  // Output: Sunday

?>

Для обратного преобразования используйте jdtofrench() — функцию, обратную frenchtojd().

Распространённые ошибки

• Порядок аргументов: month, day, year — а не порядок день-месяц-год, используемый в повседневных французских датах. Перестановка первых двух аргументов — наиболее частая ошибка.
• Возврат 0 означает «недопустимая дата или вне диапазона», а не «была выброшена ошибка». Функция не генерирует исключение, поэтому проверяйте результат самостоятельно.
• Комплементарные дни находятся в месяце 13, а не добавлены к месяцу 12. Используйте frenchtojd(13, 1, $year) через frenchtojd(13, 6, $year) для работы с ними.
• Расширение calendar включено не всегда, особенно в минималистичных образах Docker. Защищайте код проверкой extension_loaded('calendar') для обеспечения переносимости.

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

• jdtofrench() — обратная функция: Julian Day → дата Французского республиканского календаря.
• gregoriantojd() — преобразование григорианской даты в юлианский день.
• juliantojd() — преобразование даты юлианского (пролептического) календаря в юлианский день.
• jddayofweek() — получение дня недели для юлианского дня.

Заключение

frenchtojd() позволяет преобразовывать даты Французского республиканского календаря в юлианские дни одним вызовом функции. Помните о порядке аргументов month, day, year, считайте возврат 0 признаком «выхода за пределы диапазона» и используйте полученный юлианский день как мост к другим календарям через семейство функций jdto*().

Практика