rust_zmanim/
lib.rs

1// This library is free software; you can redistribute it and/or
2// modify it under the terms of the GNU Lesser General Public
3// License as published by the Free Software Foundation; either
4// version 2.1 of the License, or (at your option) any later version.
5//
6// This library is distributed in the hope that it will be useful,
7// but WITHOUT ANY WARRANTY; without even the implied warranty of
8// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
9// Lesser General Public License for more details.
10//
11// You should have received a copy of the GNU Lesser General Public
12// License along with this library; if not, see:
13// <https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html>
14
15//! # rust-zmanim
16//! Calculate different astronomical times including sunrise and sunset and
17//! Jewish *zmanim* or religious times for prayers and other Jewish religious
18//! duties.
19//!
20//! The [`astronomical_calculator`] provides non-religious astronomical / solar
21//! calculations such as sunrise, sunset and twilight.
22//!
23//! The [`zmanim_calculator`] contains the basics for *zmanim* calculations.
24//!
25//! The [`complex_zmanim_calendar`] provides a stateful struct with many premade
26//! *zmanim* calculations, both built on the [`zmanim_calculator`] API.
27//!
28//! This project is a port from pinnymz's [python-zmanim project](https://github.com/pinnymz/python-zmanim) and Eliyahu Hershfeld's [KosherJava project](https://github.com/KosherJava/zmanim). Much of the code is ported directly from `python-zmanim` and `KosherJava`, and almost all of the documentation is from `KosherJava`
29//!
30//! See the [KosherJava site](https://kosherjava.com) for additional information on the original Java project and *zmanim* in general.
31//!
32//! **Note:** It is important to read the technical notes on top of the
33//! [`astronomical_calculator`] documentation.
34//!
35//! ### Disclaimer
36//! I did my best to get accurate results using standardized astronomical
37//! calculations. Please use care when using the library for *halacha lemaaseh*
38//! applications. **Also**, despite the great *precision* of the returned
39//! values, the *accuracy* is nowhere near that. To quote the NOAA, whose
40//! algorithm this crate uses, "due to variations in atmospheric composition,
41//! temperature, pressure and conditions, observed values may vary from
42//! calculations"
43//!
44//! ## Example (more examples in /examples)
45//! ```rust
46//! use chrono::TimeDelta;
47//! use rust_zmanim::prelude::*;
48//!
49//! // the time in the DateTime will be ignored in zmanim calculations
50//! let dt = chrono_tz::Asia::Jerusalem
51//!     .with_ymd_and_hms(2025, 7, 29, 10, 30, 26)
52//!     .unwrap();
53//!
54//! // your location here
55//! let beit_meir = GeoLocation {
56//!     latitude: 31.7975,
57//!     longitude: 35.0345,
58//!     elevation: 526.0,
59//!     timezone: chrono_tz::Asia::Jerusalem,
60//! };
61//!
62//! // the `zmanim_calculator` lets you make any custom tzais, alos, etc
63//! if let Some(tzais_pi_degrees) = zmanim_calculator::tzais(
64//!     &dt,
65//!     &beit_meir,
66//!     false,
67//!     &ZmanOffset::Degrees(std::f64::consts::PI),
68//! ) {
69//!     assert_eq!(
70//!         tzais_pi_degrees.to_string(),
71//!         "2025-07-29 19:50:30.090272127 IDT"
72//!     );
73//! }
74//!
75//! // there is also a `ComplexZmanimCalendar` struct which stores the date and
76//! // location, convenient for getting many zmanim for the same point in 4D space.
77//! // It also has many common zmanim pre-made
78//! let czc = ComplexZmanimCalendar {
79//!     geo_location: beit_meir,
80//!     date: dt,
81//!     use_elevation: UseElevation::No,
82//! };
83//!
84//! if let Some(alos120) = czc.alos_120_minutes() {
85//!     assert_eq!(alos120.to_string(), "2025-07-29 03:53:39.574572512 IDT");
86//! };
87//!
88//! if let Some(sz18) = czc.shaah_zmanis_mga_18_degrees() {
89//!     // 01:24:14.106060472
90//!     assert_eq!(sz18, TimeDelta::nanoseconds(5054106060472));
91//! }
92//!
93//! // the calculations will return `None` if the specified solar event will not
94//! // occur
95//! let north_pole = GeoLocation {
96//!     latitude: 90.0,
97//!     longitude: 0.0,
98//!     elevation: 0.0,
99//!     timezone: chrono_tz::UTC,
100//! };
101//! let polar_sunset = zmanim_calculator::shkia(&dt, &north_pole, false);
102//! assert!(polar_sunset.is_none());
103//! ```
104
105pub mod astronomical_calculator;
106pub mod complex_zmanim_calendar;
107pub mod util;
108pub mod zmanim_calculator;
109
110/// A convenience module for glob imports. `use rust_zmanim::prelude::*;`
111pub mod prelude {
112    pub use chrono::TimeZone; // So `Tz.with_ymd_and_hms()` will work
113
114    pub use crate::astronomical_calculator;
115    pub use crate::zmanim_calculator;
116
117    pub use crate::complex_zmanim_calendar::*;
118    pub use crate::util::geolocation::GeoLocation;
119    pub use zmanim_calculator::ZmanOffset;
120}
rust_zmanim/lib.rs

rust_zmanim/
lib.rs
