jwodder / julian-rs

Convert between Julian day numbers and Julian & Gregorian calendars

GitHub | crates.io | Documentation | Issues | Changelog

julian is a Rust library for converting between Julian day numbers and dates in the Gregorian calendar (either proleptic or with the Reformation occurring at a given date) and/or the proleptic Julian calendar. There are also features for querying details about years & months in a "reforming" Gregorian calendar and how they are affected by the calendar reformation date of your choice.

Examples

Before you construct a date, you must first choose a calendar in which to reckon dates. Calendar::GREGORIAN is the proleptic Gregorian calendar, which should be both simple and useful enough for most basic purposes.

To convert a Julian day number to a date in a calendar, use the Calendar::at_jdn() method, like so:

use julian::{Calendar, Month};

let cal = Calendar::GREGORIAN;
let date = cal.at_jdn(2460065);
assert_eq!(date.year(), 2023);
assert_eq!(date.month(), Month::April);
assert_eq!(date.day(), 30);

So JDN 2460065 is April 30, 2023, in the proleptic Gregorian calendar.

To convert a date to a Julian day number, use Calendar::at_ymd() to construct the date, and then call its julian_day_number() method:

use julian::{Calendar, Month};

let cal = Calendar::GREGORIAN;
let date = cal.at_ymd(2023, Month::April, 30).unwrap();
assert_eq!(date.julian_day_number(), 2460065);

See the documentation for more things you can do!

Command

julian also provides a command of the same name for converting between Julian day numbers and dates in Julian-style calendars. To install this command on your system, run:

cargo install julian

Usage

julian [<options>] [<date> ...]

When invoked without arguments, the julian command displays the current date in the proleptic Gregorian calendar & UTC timezone along with the corresponding Julian day number.

When julian is invoked with one or more arguments, any calendar date arguments (in the form "YYYY-MM-DD" or "YYYY-JJJ") are converted to Julian day numbers, and any integer arguments are treated as Julian day numbers and converted to calendar dates. By default, dates are read & written using the proleptic Gregorian calendar, but this can be changed with the --julian or --reformation option.

julian uses astronomical year numbering, where 1 BC (the year immediately before AD 1) is denoted on input & output as year 0 (displayed as "0000"), and the year before that (normally called 2 BC) is denoted -1 (displayed as "-0001"). In addition, the start of the year is always taken as being on January 1, even though not all users of the Julian calendar throughout history have followed this convention.

Options

• -c, --countries — List the country codes recognized by the -r/--reformation option. The output is a table with the following columns:

  • "Code" — the two-letter country code accepted by --reformation
  • "Country" — the country's English name (or a common variation thereof)
  • "Reformation" — the Julian day number of the date on which the country first observed the Gregorian calendar
  • "Last Julian" — the Old Style calendar date of the day before the reformation
  • "First Gregorian" — the New Style calendar date of the day of the reformation

  The database of country reformations dates is drawn from the Debian version of ncal.c as of 2023-04-26, so blame Debian for any historical inaccuracies.

• -h, --help — Display a summary of the command-line options and exit

• -j, --julian — Read & write dates using the proleptic Julian calendar

• -J, --json — Output JSON. See JSON Output below for more information.

• -o, --ordinal — Output calendar dates in the form "YYYY-JJJ", where the part after the hyphen is the day of the year from 001 to 366 (the ordinal date)

• -q, --quiet — Do not print the input value before each output value. Do not print "JDN" before Julian day numbers.

• -r <jdn>, --reformation <jdn> — Read & write dates using a reforming calendar in which the Gregorian calendar is first observed on the date with the given Julian day number

  A two-letter country code (case insensitive) may be given in place of a JDN in order to use the calendar reformation as it was observed in that country. Run julian --countries to get a list of recognized country codes and their corresponding dates.

• -s, --style — Mark dates in reforming calendars as "O.S." (Old Style) or "N.S." (New Style)". Has no effect when -r/--reformation is not given or when -o/--ordinal is given.

• -V, --version — Show the program version and exit

JSON Output

When julian is invoked with the -J/--json option, it outputs a JSON breakdown of the chosen calendar and input & output values. The output structure is an object with two keys, "calendar" and "dates".

• "calendar" — Denotes the type of calendar selected for the julian invocation. This is an object that always contains at least one key, "type", the value of which is "gregorian" (for the default proleptic Gregorian calendar), "julian" (for the proleptic Julian calendar), or "reforming" (for a reforming calendar). When "type" is "reforming", there will be an additional field, "reformation", whose value is the Julian day number of the date on which the calendar first follows the Gregorian calendar.

• "dates" — A list of objects, one per argument (or, if no arguments were given, one object for the current date). Each object contains the following fields describing the date indicated by the argument, regardless of whether the argument was a calendar date or a Julian day number:

  • "julian_day_number" — the date's Julian day number
  • "year" — the date's year
  • "month" — the number (1-12) of the date's month
  • "day" — the date's day-of-month (1-31)
  • "ordinal" — the date's one-based day-of-year ordinal (1-366)
  • "display" — the date in "YYYY-MM-DD" form
  • "ordinal_display" — the date in "YYYY-JJJ" form
  • "old_style" — This field is only present if the calendar in use is a reforming calendar. It is true if the date occurs before the calendar reformation, false otherwise.

julian-rs's Issues

Renovate Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

• [cargo] Autoupdate Cargo.lock

Detected dependencies

cargo

Cargo.toml

• anyhow 1.0.82
• chrono 0.4.38
• csv 1.3.0
• lexopt 0.3.0
• serde 1.0.200
• thiserror 1.0.59
• assert_matches 1.5.0
• indoc 2.0.5
• rstest 0.21.0
• rstest_reuse 0.7.0

github-actions

.github/workflows/test.yml

• actions/checkout v4
• Swatinem/rust-cache v2
• actions/checkout v4
• Swatinem/rust-cache v2
• taiki-e/install-action v2
• actions/checkout v4
• Swatinem/rust-cache v2
• taiki-e/install-action v2
• codecov/codecov-action v4
• actions/checkout v4
• Swatinem/rust-cache v2
• actions/checkout v4
• Swatinem/rust-cache v2
• actions/checkout v4
• Swatinem/rust-cache v2

---

• Check this box to trigger a request for Renovate to run again on this repository

The calender type seems unable to represent some real Julian -> Gregorian calenders in history

Feel free to close this as out of scope if you think it is! I don't have an actual use for it, it is just pedantry I guess as I came across your crate.

I was looking at the API of your Calender type and noticed it only seems to support:

• Fully (forward-dated) Julian calenders
• Fully (back-dated) Gregorian calenders
• Calenders with a single transition from Julian to Gregorian

Unfortunately not all countries had such an easy transition. I thought it was just my own native country (Sweden) that screwed this up (see https://en.wikipedia.org/wiki/Swedish_calendar for some date keeping humour/horror) but apparently there were many more.

If this is out of scope, I am curious if you know of a rust library that can handle this mess (as well as other global calendars, outside of Europe). Especially since I'm pretty sure some dates will be ambiguous without reference to what calendar they are in (and possibly even which country and province).

Julian days tick over at noon

Hi, thanks for this crate. Any plans to handle the half day discrepancy caused by not considering the time of day? The documentation claims that Julian day 0 began at midnight, which is contrary to my understanding (that is, I understand that it began at noon UT on January 1, 4713 BC, proleptic Julian calendar).

I could handle this within my application but it seems better to handle it within this crate. I may be able to help with the implementation but I thought first to ask whether this was a conscious design decision.