anytime 0.2.0

Ergonomic astronomical timescales in rust
Documentation
//! Astronomical time scales and conversions with nanosecond resolution.
//!
//! [`Time`] stores an instant with a type-level [`Scale`]. The scale marker
//! prevents accidental mixing of values while the conversion implementations
//! make changes of scale explicit:
//!
//! ```
//! use anytime::{Time, scales::{TAI, UTC}};
//!
//! let utc = Time::<UTC>::from_jd(2_451_545.0);
//! let tai: Time<TAI> = utc.into();
//! # assert_eq!(tai.utc().jd(), 2_451_545.0);
//! ```
//!
//! Values can also be compared and differenced directly, even when they use
//! different scales. Subtraction returns a `chrono::TimeDelta`, while
//! comparisons use standard ordering operators:
//!
//! ```
//! use anytime::{Time, scales::{TAI, UTC}};
//! use chrono::TimeDelta;
//!
//! let earlier = Time::<UTC>::from_jd(2_451_545.0);
//! let later: Time<TAI> = Time::<UTC>::from_jd(2_451_546.0).into();
//! let is_ordered = earlier < later;
//! let difference = later - earlier;
//! # assert!(is_ordered);
//! # assert_eq!(difference, TimeDelta::seconds(86_400));
//! ```
//!
//! A value can be formatted as a Gregorian date string, including sub-second
//! precision, through [`Time::gregorian`]:
//!
//! ```
//! use anytime::{Time, scales::UTC};
//! use chrono::NaiveDate;
//!
//! let date = NaiveDate::from_ymd_opt(2000, 1, 1)
//!     .unwrap()
//!     .and_hms_nano_opt(12, 0, 0, 123_456_789)
//!     .unwrap();
//! let date_string = Time::<UTC>::from_gregorian(date)
//!     .gregorian()
//!     .to_string();
//! # assert_eq!(date_string, "2000-01-01 12:00:00.123456789");
//! ```
//!
//! When the scale is selected at runtime, use [`AnyTime`]'s constructors with
//! [`TimeScale`]:
//!
//! ```
//! use anytime::{AnyTime, TimeScale};
//!
//! let utc = AnyTime::from_isot_str("2000-01-01T12:00:00", TimeScale::UTC).unwrap();
//! # assert_eq!(utc, AnyTime::from_jd(2_451_545.0, TimeScale::UTC));
//! ```
//!
//! When the scale for a whole collection is selected at runtime, use
//! [`AnyTimeSeries`]. It stores the scale once while retaining a homogeneous
//! typed series internally:
//!
//! ```
//! use anytime::{AnyTimeSeries, Time, TimeSeries, scales::{TAI, UTC}};
//!
//! let tai = TimeSeries::new(vec![Time::<TAI>::from_jd(2_451_545.0)]);
//! let series: AnyTimeSeries = tai.into();
//! let utc: TimeSeries<UTC> = series.into();
//!
//! assert_eq!(utc.len(), 1);
//! ```
//!
//! Convert a runtime-selected value to another runtime-selected scale with
//! [`AnyTime::convert`]:
//!
//! ```
//! use anytime::{AnyTime, TimeScale};
//!
//! let utc = AnyTime::from_jd(2_451_545.0, TimeScale::UTC);
//! let tai = utc.convert(TimeScale::TAI);
//! # assert_eq!(tai.scale(), TimeScale::TAI);
//! ```
//!
//! Typed values also support the same parsing constructors. [`std::str::FromStr`]
//! assumes an ISO 8601 `T`-separated date and time without an offset, interpreted
//! in the type's scale:
//!
//! ```
//! use anytime::{Time, scales::UTC};
//!
//! let utc: Time<UTC> = "2000-01-01T12:00:00".parse().unwrap();
//! # assert_eq!(utc, Time::<UTC>::from_jd(2_451_545.0));
//! ```
//!
//! The crate supports UTC, TAI, TT, TCG, TCB, TDB, and UT1. Its GNSS scales are
//! BDT, GLONASST, GPST, GST, and QZZST. UTC conversions use leap-second data built
//! into the crate. UT1 conversions additionally use Earth-orientation data loaded
//! with [`load_finals2000a`].
//!
//! # Feature overview
//!
//! - Use [`Time::from_jd`], [`Time::from_mjd`], [`Time::from_split_jd`], or
//!   [`Time::from_gregorian`] to construct a typed value, or [`AnyTime`]'s
//!   runtime-scale constructors when the scale is chosen dynamically.
//! - Use [`Time::jd`], [`Time::mjd`], [`Time::split_jd`], or
//!   [`Time::gregorian`] to inspect a value.
//! - Use the `From`/`Into` implementations or [`Time::utc`], [`Time::tai`], and
//!   the other scale methods to convert values.
//! - Use [`TimeSeries`] for stored collections or [`TimeSeries::range_iter`]
//!   for lazy ranges. Use [`AnyTimeSeries`] when the common series scale is
//!   selected at runtime.
//! - Use [`AnyTime`] when a collection may contain values from multiple scales.
//! - Enable the `serde` feature to serialize and deserialize [`Time`],
//!   [`AnyTime`], [`TimeSeries`], [`AnyTimeSeries`], and [`TimeScale`] values.
//!
// Astronomical time-scale names intentionally retain their standard acronyms.
#![allow(clippy::upper_case_acronyms)]
#![deny(missing_docs)]

mod any_series;
mod anytime;
mod constants;
mod eop;
mod macros;
#[cfg(test)]
mod references;
pub mod scales;
mod series;
mod time;

pub use any_series::{AnyTimeSeries, AnyTimeSeriesIntoIter, AnyTimeSeriesIter};
pub use anytime::AnyTime;
pub use eop::{load_finals2000a, FinalsLoadError};
pub use scales::{
    TimeScale, TimeScaleParseError, BDT, GLONASST, GPS, GPST, GST, QZZST, TAI, TCB, TCG, TDB, TDT,
    TT, UT, UT1, UTC,
};
pub use series::{TimeSeries, TimeSeriesRange};
pub use time::{Scale, Time};