use crate::{
astronomical_calculator,
complex_zmanim_calendar::cache::ZmanCache,
util::geolocation::GeoLocation,
zmanim_calculator::{
self,
ZmanOffset::{self, Degrees, Minutes, MinutesZmaniyos},
},
};
use jiff::{SignedDuration, Zoned, civil::Date};
/// Struct to store a 4-dimensional location and settings, to simplify getting
/// many *zmanim* for the same location. Has premade methods for many common
/// (and uncommon) *zmanim*. (see `impl` block)
///
/// Construct with [`ComplexZmanimCalendar::new`]. The underlying solar events
/// are computed lazily and cached per instance, so calculating many *zmanim*
/// for the same date and location is cheap. The cache makes this type
/// `!Sync`; to share a calendar across threads, clone it.
#[derive(Debug, Clone)]
pub struct ComplexZmanimCalendar {
geo_location: GeoLocation,
date: Date,
use_elevation: UseElevation,
cache: ZmanCache,
}
/// Cached solar events are ignored; two calendars are equal when their
/// location, date, and elevation setting are equal.
impl PartialEq for ComplexZmanimCalendar {
fn eq(&self, other: &Self) -> bool {
self.geo_location == other.geo_location
&& self.date == other.date
&& self.use_elevation == other.use_elevation
}
}
/// Where unspecified, when sunrise and sunset are mentioned in the calculation
/// of other *zmanim*, they will be sea-level or elevation-based depending on
/// the value of `use_elevation`
///
/// **Elevation-based *zmanim* (even sunrise and sunset) should not be used
/// *lekula* without the guidance of a *posek***. See the [root
/// documentation](crate) for more details.
///
/// Many of the methods return `None` if the sun does not reach the specified
/// position below the horizon at this location and date (common in polar
/// regions).
impl ComplexZmanimCalendar {
/// Returns a new `ComplexZmanimCalendar` for the given location, day, and
/// elevation setting
#[must_use]
pub fn new(geo_location: GeoLocation, date: Date, use_elevation: UseElevation) -> Self {
Self {
geo_location,
date,
use_elevation,
cache: ZmanCache::default(),
}
}
/// Location at which to calculate *zmanim*
#[must_use]
pub fn geo_location(&self) -> &GeoLocation {
&self.geo_location
}
/// Day for which to calculate *zmanim*
#[must_use]
pub fn date(&self) -> Date {
self.date
}
/// When to account for elevation. See [`UseElevation`]
#[must_use]
pub fn use_elevation(&self) -> UseElevation {
self.use_elevation
}
/// Sets the day for which to calculate *zmanim*, clearing the cached solar
/// events
pub fn set_date(&mut self, date: Date) {
self.date = date;
self.cache = ZmanCache::default();
}
/// Sets the location at which to calculate *zmanim*, clearing the cached
/// solar events
pub fn set_geo_location(&mut self, geo_location: GeoLocation) {
self.geo_location = geo_location;
self.cache = ZmanCache::default();
}
/// Sets when to account for elevation. Cached solar events are kept, as
/// they are stored per physical event, not per elevation setting
pub fn set_use_elevation(&mut self, use_elevation: UseElevation) {
self.use_elevation = use_elevation;
}
// Cached solar events. All zmanim methods reach the astronomical layer
// through one of these, so each underlying event is computed only once per
// calendar instance.
fn cached_sunrise(&self, use_elevation: bool) -> Option<Zoned> {
let cell = if use_elevation {
&self.cache.elevation_sunrise
} else {
&self.cache.sea_level_sunrise
};
cell.get_or_init(|| zmanim_calculator::hanetz(self.date, &self.geo_location, use_elevation))
.clone()
}
fn cached_sunset(&self, use_elevation: bool) -> Option<Zoned> {
let cell = if use_elevation {
&self.cache.elevation_sunset
} else {
&self.cache.sea_level_sunset
};
cell.get_or_init(|| zmanim_calculator::shkia(self.date, &self.geo_location, use_elevation))
.clone()
}
fn cached_solar_noon(&self) -> Option<Zoned> {
self.cache
.solar_noon
.get_or_init(|| zmanim_calculator::chatzos_hayom(self.date, &self.geo_location))
.clone()
}
fn cached_solar_midnight(&self) -> Option<Zoned> {
self.cache
.solar_midnight
.get_or_init(|| zmanim_calculator::chatzos_halayla(self.date, &self.geo_location))
.clone()
}
fn cached_sunrise_offset_by_degrees(&self, degrees: f64) -> Option<Zoned> {
let key = degrees.to_bits();
if let Some((_, cached)) = self
.cache
.sunrise_by_degrees
.borrow()
.iter()
.find(|(k, _)| *k == key)
{
return cached.clone();
}
let result = astronomical_calculator::sunrise_offset_by_degrees(
self.date,
&self.geo_location,
astronomical_calculator::GEOMETRIC_ZENITH + degrees,
);
self.cache
.sunrise_by_degrees
.borrow_mut()
.push((key, result.clone()));
result
}
fn cached_sunset_offset_by_degrees(&self, degrees: f64) -> Option<Zoned> {
let key = degrees.to_bits();
if let Some((_, cached)) = self
.cache
.sunset_by_degrees
.borrow()
.iter()
.find(|(k, _)| *k == key)
{
return cached.clone();
}
let result = astronomical_calculator::sunset_offset_by_degrees(
self.date,
&self.geo_location,
astronomical_calculator::GEOMETRIC_ZENITH + degrees,
);
self.cache
.sunset_by_degrees
.borrow_mut()
.push((key, result.clone()));
result
}
// Basics
/// Returns *alos hashachar* (dawn) based on either declination of the sun
/// below the horizon, a fixed time offset, or a minutes *zmaniyos*
/// (temporal minutes) offset before sunrise
#[must_use]
pub fn alos(&self, offset: &ZmanOffset) -> Option<Zoned> {
match offset {
Degrees(deg) => self.cached_sunrise_offset_by_degrees(*deg),
_ => Some(zmanim_calculator::offset_before_event(
&self.cached_sunrise(self.use_elevation.to_bool(false))?,
offset,
)),
}
}
/// Returns sea level sunrise
#[must_use]
pub fn sea_level_sunrise(&self) -> Option<Zoned> {
self.cached_sunrise(false)
}
/// Returns sea level sunset
#[must_use]
pub fn sea_level_sunset(&self) -> Option<Zoned> {
self.cached_sunset(false)
}
/// Returns elevation-adjusted sunrise
#[must_use]
pub fn elevation_sunrise(&self) -> Option<Zoned> {
self.cached_sunrise(true)
}
/// Returns elevation-adjusted sunset
#[must_use]
pub fn elevation_sunset(&self) -> Option<Zoned> {
self.cached_sunset(true)
}
/// Returns *hanetz*, or sunrise. Will be elevation-adjusted or not
/// depending on `use_elevation`
#[must_use]
pub fn hanetz(&self) -> Option<Zoned> {
self.cached_sunrise(self.use_elevation.to_bool(true))
}
/// Returns *shkia*, or sunset. Will be elevation-adjusted or not depending
/// on `use_elevation`
#[must_use]
pub fn shkia(&self) -> Option<Zoned> {
self.cached_sunset(self.use_elevation.to_bool(true))
}
/// Returns sunrise, for use internally. Will be elevation-adjusted only if
/// `use_elevation == All`
#[must_use]
fn zmanim_sunrise(&self) -> Option<Zoned> {
self.cached_sunrise(self.use_elevation.to_bool(false))
}
/// Returns sunset, for use internally. Will be elevation-adjusted only if
/// `use_elevation == All`
#[must_use]
fn zmanim_sunset(&self) -> Option<Zoned> {
self.cached_sunset(self.use_elevation.to_bool(false))
}
/// Returns the latest *zman krias shema* (time to recite *Shema* in the
/// morning) according to the opinion of the *Magen Avraham* (MGA) based on
/// *alos* and *tzeis* being given offset from sunrise and sunset,
/// respectively.
#[must_use]
pub fn sof_zman_shema_mga(&self, offset: &ZmanOffset) -> Option<Zoned> {
Some(zmanim_calculator::sof_zman_shema(
&self.alos(offset)?,
&self.tzeis(offset)?,
))
}
/// Returns the latest *zman tefila* (time to recite *shacharis* in the
/// morning) according to the opinion of the *Magen Avraham* (MGA) based on
/// *alos* and *tzeis* being the given offset from sunrise and sunset,
/// respectively.
#[must_use]
pub fn sof_zman_tefila_mga(&self, offset: &ZmanOffset) -> Option<Zoned> {
Some(zmanim_calculator::sof_zman_tefila(
&self.alos(offset)?,
&self.tzeis(offset)?,
))
}
/// Returns the latest *zman biur chametz* (the latest time for burning
/// *chametz* on *Erev Pesach*) according to the opinion of the *Magen
/// Avraham* (MGA) based on *alos* and *tzeis* being the given offset
/// from sunrise and sunset, respectively.
#[must_use]
pub fn sof_zman_biur_chametz_mga(&self, offset: &ZmanOffset) -> Option<Zoned> {
Some(zmanim_calculator::sof_zman_biur_chametz(
&self.alos(offset)?,
&self.tzeis(offset)?,
))
}
/// Returns Astronomical *chatzos* (noon)
#[must_use]
pub fn chatzos_hayom(&self) -> Option<Zoned> {
self.cached_solar_noon()
}
/// Returns *chatzos hayom* calculated as halfway between [sea level
/// sunrise](ComplexZmanimCalendar::sea_level_sunrise) and [sea level
/// sunset](ComplexZmanimCalendar::sea_level_sunset). Many are of the
/// opinion that *chatzos* is calculated as the midpoint between sunrise and
/// sunset, despite it not being the most accurate way to calculate it. A
/// day starting at *alos* and ending at *tzeis* using the same time or
/// degree offset would also return the same time. In reality due to
/// lengthening or shortening of day, this is not necessarily [the exact
/// midpoint](ComplexZmanimCalendar::chatzos_hayom) of the day, but it is
/// very close. See [The Definition of
/// *Chatzos*](https://kosherjava.com/2020/07/02/definition-of-chatzos/)
/// for a detailed explanation of the ways to calculate *Chatzos*.
#[must_use]
pub fn chatzos_hayom_as_half_day(&self) -> Option<Zoned> {
Some(zmanim_calculator::chatzos_hayom_as_half_day(
&self.sea_level_sunrise()?,
&self.sea_level_sunset()?,
))
}
/// Returns Astronomical *chatzos halayla* **at the end of the day** (the
/// last zman of the day returned by the calendar, that may actually be
/// after midnight of the day it is being calculated for).
///
/// For example, if calculating it for the date of *Erev Pesach*, the
/// calculation will be for *Leil Pesach* to allow you to use the *zman* as
/// *sof zman achilas matza*.
#[must_use]
pub fn chatzos_halayla(&self) -> Option<Zoned> {
self.cached_solar_midnight()
}
/// Returns *mincha gedola* according to the opinion of the *Magen Avraham*
/// (MGA) based on *alos* and *tzeis* being the given offset from sunrise
/// and sunset, respectively.
#[must_use]
pub fn mincha_gedola_mga(&self, offset: &ZmanOffset) -> Option<Zoned> {
Some(zmanim_calculator::mincha_gedola(
&self.alos(offset)?,
&self.tzeis(offset)?,
))
}
/// Returns *samuch lemincha ketana* according to the opinion of the *Magen
/// Avraham* (MGA) based on *alos* and *tzeis* being the given offset
/// from sunrise and sunset, respectively.
#[must_use]
pub fn samuch_lemincha_ketana_mga(&self, offset: &ZmanOffset) -> Option<Zoned> {
Some(zmanim_calculator::samuch_lemincha_ketana(
&self.alos(offset)?,
&self.tzeis(offset)?,
))
}
/// Returns *mincha ketana* according to the opinion of the *Magen Avraham*
/// (MGA) based on *alos* and *tzeis* being the given offset from sunrise
/// and sunset, respectively.
#[must_use]
pub fn mincha_ketana_mga(&self, offset: &ZmanOffset) -> Option<Zoned> {
Some(zmanim_calculator::mincha_ketana(
&self.alos(offset)?,
&self.tzeis(offset)?,
))
}
/// Returns *plag hamincha* according to the opinion of the *Magen Avraham*
/// (MGA) based on *alos* and *tzeis* being the given offset from sunrise
/// and sunset, respectively.
#[must_use]
pub fn plag_mga(&self, offset: &ZmanOffset) -> Option<Zoned> {
Some(zmanim_calculator::plag_hamincha(
&self.alos(offset)?,
&self.tzeis(offset)?,
))
}
/// Returns *mincha gedola* calculated as 30 minutes after *chatzos* and not
/// 1/2 of a *shaah zmanis* after *chatzos* as calculated by
/// [`zmanim_calculator::mincha_gedola`]. See
/// [`zmanim_calculator::mincha_gedola_30_minutes`] for more details
#[must_use]
pub fn mincha_gedola_30_minutes(&self) -> Option<Zoned> {
Some(self.cached_solar_noon()? + SignedDuration::from_mins(30))
}
/// Returns *tzeis* (nightfall) based on either declination of the sun below
/// the horizon, a fixed time offset, or a minutes *zmaniyos* (temporal
/// minutes) offset after sunset
#[must_use]
pub fn tzeis(&self, offset: &ZmanOffset) -> Option<Zoned> {
match offset {
Degrees(deg) => self.cached_sunset_offset_by_degrees(*deg),
_ => Some(zmanim_calculator::offset_after_event(
&self.cached_sunset(self.use_elevation.to_bool(false))?,
offset,
)),
}
}
/// Returns *shaah zmanis* (temporal hour) according to the opinion of the
/// *Magen Avraham* (MGA) based on *alos* and *tzeis* being the given
/// offset from sunrise and sunset, respectively.
#[must_use]
pub fn shaah_zmanis_mga(&self, offset: &ZmanOffset) -> Option<SignedDuration> {
Some(zmanim_calculator::shaah_zmanis(
&self.alos(offset)?,
&self.tzeis(offset)?,
))
}
// GRA
/// Returns the latest *Zman Shema* (time to recite *Shema* in the morning)
/// that is 3 *shaos zmaniyos* (solar hours) after
/// sunrise according the GRA. The day is
/// calculated from sunrise to sunset.
#[must_use]
pub fn sof_zman_shema_gra(&self) -> Option<Zoned> {
Some(zmanim_calculator::sof_zman_shema(
&self.zmanim_sunrise()?,
&self.zmanim_sunset()?,
))
}
/// Returns the latest *zman tefila* (time to recite *shacharis* in the
/// morning) that is 4 *shaos zmaniyos* (solar hours) after
/// sunrise according GRA.
/// The day is calculated from sunrise to sunset
#[must_use]
pub fn sof_zman_tefila_gra(&self) -> Option<Zoned> {
Some(zmanim_calculator::sof_zman_tefila(
&self.zmanim_sunrise()?,
&self.zmanim_sunset()?,
))
}
/// Returns the latest time for burning *chametz* on *Erev
/// Pesach* according to the opinion of the GRA. This time is 5 hours into
/// the day based on the opinion of the GRA that the day is calculated from
/// sunrise to sunset. Since this library does not implement a calendar,
/// this method will return the *zman* any day of the year.
#[must_use]
pub fn sof_zman_biur_chametz_gra(&self) -> Option<Zoned> {
Some(self.zmanim_sunrise()? + (self.shaah_zmanis_gra()? * 5))
}
/// Returns *mincha gedola* calculated as 6.5 *shaos zmaniyos* (solar hours)
/// after sunrise, according to the GRA.
#[must_use]
pub fn mincha_gedola_gra(&self) -> Option<Zoned> {
Some(zmanim_calculator::mincha_gedola(
&self.zmanim_sunrise()?,
&self.zmanim_sunset()?,
))
}
/// Returns the later of
/// [`mincha_gedola_gra`](ComplexZmanimCalendar::mincha_gedola_gra)
/// and
/// [`mincha_gedola_30_minutes`](ComplexZmanimCalendar::mincha_gedola_30_minutes)
/// . In the winter when 1/2 of a
/// [GRA *shaah zmanis*](ComplexZmanimCalendar::shaah_zmanis_gra)
/// is less than 30 minutes
/// [`mincha_gedola_30_minutes`](ComplexZmanimCalendar::mincha_gedola_30_minutes)
/// will be returned, otherwise
/// [`mincha_gedola_gra`](ComplexZmanimCalendar::mincha_gedola_gra)
/// will be returned
#[must_use]
pub fn mincha_gedola_gra_greater_than_30_minutes(&self) -> Option<Zoned> {
let mg_30 = self.mincha_gedola_30_minutes()?;
let mg_gra = self.mincha_gedola_gra()?;
Some(mg_30.max(mg_gra))
}
/// Returns *samuch lemincha ketana* (near *mincha
/// ketana*), that is half an hour before [*mincha
/// ketana*](ComplexZmanimCalendar::mincha_ketana_gra) or is 9 *shaos
/// zmaniyos* (solar hours) after sunrise, calculated according to the GRA
/// using a day starting at sunrise and ending at sunset. This is the
/// time that eating or other activity can't begin prior to praying
/// *mincha*. See the *Mechaber* and *Mishna Berurah* 232 and 249:2.
#[must_use]
pub fn samuch_lemincha_ketana_gra(&self) -> Option<Zoned> {
Some(self.zmanim_sunrise()? + (self.shaah_zmanis_gra()? * 9))
}
/// Returns *mincha ketana* calculated as 9.5 *shaos zmaniyos* (solar hours)
/// after sunrise, according to the GRA.
#[must_use]
pub fn mincha_ketana_gra(&self) -> Option<Zoned> {
Some(zmanim_calculator::mincha_ketana(
&self.zmanim_sunrise()?,
&self.zmanim_sunset()?,
))
}
/// Returns *plag hamincha* calculated as 10.75 *shaos zmaniyos* (solar
/// hours) after sunrise, according to the GRA.
#[must_use]
pub fn plag_gra(&self) -> Option<Zoned> {
Some(zmanim_calculator::plag_hamincha(
&self.zmanim_sunrise()?,
&self.zmanim_sunset()?,
))
}
/// Returns a *shaah zmanis* according to the opinion of the GRA.
/// This calculation divides the day based on the opinion of the *GRA* that
/// the day runs from sunrise to sunset. The day is split into 12 equal
/// parts with each one being a *shaah zmanis*
#[must_use]
pub fn shaah_zmanis_gra(&self) -> Option<SignedDuration> {
Some(zmanim_calculator::shaah_zmanis(
&self.zmanim_sunrise()?,
&self.zmanim_sunset()?,
))
}
// Baal HaTanya
/// Returns the *Baal Hatanya*'s *alos* (dawn) calculated as the time when
/// the sun is 16.9° below the eastern geometric horizon before sunrise.
/// It is based on the calculation that the time between dawn and
/// [*hanetz amiti*](ComplexZmanimCalendar::hanetz_amiti_baal_hatanya)
/// (sunrise) is 72 minutes, the time that is takes to walk 4 *mil* at
/// 18 minutes a *mil* (*Rambam* and others). The sun's position at 72
/// minutes before *hanetz amiti* (sunrise) in Jerusalem around the
/// equinox / equilux is 16.9° below geometric zenith.
#[must_use]
pub fn alos_baal_hatanya(&self) -> Option<Zoned> {
self.alos(&Degrees(16.9))
}
/// **Note: *hanetz amiti* is used only for
/// calculating certain other *zmanim*. For practical purposes, daytime
/// *mitzvos* like *shofar* and *lulav* should not be done until after the
/// normal time for [*hanetz*](ComplexZmanimCalendar::hanetz).**
///
/// Returns the *Baal Hatanya*'s *hanetz amiti* (sunrise). This forms the
/// base for the *Baal Hatanya*'s dawn-based
/// calculations that are calculated as a dip below the horizon before
/// sunrise. According to the *Baal Hatanya*, *hanetz amiti*, or true
/// (halachic) sunrise, is when the top of the sun's disk is visible at an
/// elevation similar to the mountains of *Eretz Yisrael*. The time is
/// calculated as the point at which the center of the sun's disk is
/// 1.583° below the horizon. This degree-based calculation can be found
/// in Rabbi Shalom Dov Ber Levine's commentary on The *Baal Hatanya*'s
/// *Seder Hachnasas Shabbos*. From an elevation of 546 meters, the top of
/// *Har Hacarmel*, the sun disappears when it is 1° 35' or 1.583°
/// below the sea level horizon. This in turn is based on the *Gemara
/// Shabbos* 35a. There are other opinions brought down by Rabbi Levine,
/// including Rabbi Yosef Yitzchok Feigelstock who calculates it as the
/// degrees below the horizon 4 minutes after sunset in *Yerushalayim* (on
/// the equinox). That is brought down as 1.583°. This is identical to
/// the 1° 35' *zman* and is probably a typo and should be 1.683°.
/// These calculations are used by most *Chabad* calendars that use the
/// *Baal Hatanya*'s *zmanim*.
#[must_use]
pub fn hanetz_amiti_baal_hatanya(&self) -> Option<Zoned> {
self.alos(&Degrees(1.583))
}
/// **Note: *shkiah amiti* is used only for calculating certain other
/// *zmanim*. For practical purposes, all daytime *mitzvos* should be
/// completed before the normal time for
/// [*shkiah*](ComplexZmanimCalendar::shkia).**
///
/// Returns the *Baal Hatanya*'s *shkiah amiti* (sunset). This forms the
/// base for the *Baal Hatanya*'s dusk-based
/// calculations that are calculated as a dip below the horizon after
/// sunset. According to the *Baal Hatanya*, *shkiah amiti*, true (halachic)
/// sunset, is when the top of the sun's disk disappears from view at an
/// elevation similar to the mountains of *Eretz Yisrael*. This time is
/// calculated as the point at which the center of the sun's disk is 1.583
/// degrees below the horizon.
#[must_use]
pub fn shkia_amiti_baal_hatanya(&self) -> Option<Zoned> {
self.tzeis(&Degrees(1.583))
}
/// Returns the *Baal Hatanya*'s *shaah zmanis* (temporal hour). This
/// forms the base for the *Baal Hatanya*'s day based calculations that are
/// calculated as a 1.583° dip below the horizon after sunset. According
/// to the *Baal Hatanya*, *shkiah amiti*, true (halachic) sunset, is when
/// the top of the sun's disk disappears from view at an elevation similar
/// to the mountains of *Eretz Yisrael*. This time is calculated as the
/// point at which the center of the sun's disk is 1.583 degrees below the
/// horizon. The calculations are based on a day from [*hanetz
/// amiti*](ComplexZmanimCalendar::hanetz_amiti_baal_hatanya) to
/// [*shkiah amiti*](ComplexZmanimCalendar::shkia_amiti_baal_hatanya). The
/// day is split into 12 equal parts with each one being a *shaah
/// zmanis*.
#[must_use]
pub fn shaah_zmanis_baal_hatanya(&self) -> Option<SignedDuration> {
self.shaah_zmanis_mga(&Degrees(1.583))
}
/// Returns the *Baal Hatanya*'s *sof zman krias shema*
/// (latest time to recite *Shema* in the morning). This time is 3
/// of the [*Baal Hatanya*'s temporal
/// hours](ComplexZmanimCalendar::shaah_zmanis_baal_hatanya) after [*hanetz
/// amiti*](ComplexZmanimCalendar::hanetz_amiti_baal_hatanya) (sunrise)
/// based on the opinion of the *Baal Hatanya* that the day is
/// calculated from sunrise to sunset.
#[must_use]
pub fn sof_zman_shema_baal_hatanya(&self) -> Option<Zoned> {
self.sof_zman_shema_mga(&Degrees(1.583))
}
/// Returns the *Baal Hatanya*'s *sof zman tefila* (latest
/// time to recite the morning prayers). This time is 4 of the [*Baal
/// Hatanya*'s temporal
/// hours](ComplexZmanimCalendar::shaah_zmanis_baal_hatanya) after [*hanetz
/// amiti*](ComplexZmanimCalendar::hanetz_amiti_baal_hatanya) (sunrise)
/// based on the opinion of the *Baal Hatanya* that the day is
/// calculated from sunrise to sunset.
#[must_use]
pub fn sof_zman_tefila_baal_hatanya(&self) -> Option<Zoned> {
self.sof_zman_tefila_mga(&Degrees(1.583))
}
/// Returns the latest time for burning *chametz* on *Erev
/// Pesach* according to the opinion of the Baal Hatanya. This time is 5
/// of the [*Baal Hatanya*'s temporal
/// hours](ComplexZmanimCalendar::shaah_zmanis_baal_hatanya) after [*hanetz
/// amiti*](ComplexZmanimCalendar::hanetz_amiti_baal_hatanya) (sunrise)
/// based on the opinion of the *Baal Hatanya* that the day is
/// calculated from sunrise to sunset. Since this library does not
/// implement a calendar, this method will return the *zman* any day of
/// the year.
#[must_use]
pub fn sof_zman_biur_chametz_baal_hatanya(&self) -> Option<Zoned> {
self.sof_zman_biur_chametz_mga(&Degrees(1.583))
}
/// Returns the *Baal Hatanya*'s *mincha gedola*. *Mincha
/// gedola* is the earliest time one can pray *mincha*. The *Rambam* is
/// of the opinion that it is better to delay *mincha* until *mincha
/// ketana* while the *Rash*, *Tur*, GRA and others are of the opinion
/// that *mincha* can be prayed *lechatchila* starting at *mincha
/// gedola*. This is calculated as 6.5 of the [*Baal Hatanya*'s temporal
/// hours](ComplexZmanimCalendar::shaah_zmanis_baal_hatanya) after [*hanetz
/// amiti*](ComplexZmanimCalendar::hanetz_amiti_baal_hatanya) (sunrise).
/// This calculation is based on the opinion of the *Baal Hatanya* that
/// the day is calculated from sunrise to sunset.
#[must_use]
pub fn mincha_gedola_baal_hatanya(&self) -> Option<Zoned> {
self.mincha_gedola_mga(&Degrees(1.583))
}
/// Returns the later of
/// [`mincha_gedola_baal_hatanya`](ComplexZmanimCalendar::mincha_gedola_baal_hatanya)
/// and
/// [`mincha_gedola_30_minutes`](ComplexZmanimCalendar::mincha_gedola_30_minutes)
/// . In the winter when 1/2 of a
/// [*Baal Hatanya shaah
/// zmanis*](ComplexZmanimCalendar::shaah_zmanis_baal_hatanya)
/// is less than 30 minutes
/// [`mincha_gedola_30_minutes`](ComplexZmanimCalendar::mincha_gedola_30_minutes)
/// will be returned, otherwise
/// [`mincha_gedola_baal_hatanya`](ComplexZmanimCalendar::mincha_gedola_baal_hatanya)
/// will be returned
#[must_use]
pub fn mincha_gedola_baal_hatanya_greater_than_30_minutes(&self) -> Option<Zoned> {
let mg_30 = self.mincha_gedola_30_minutes()?;
let mg_bht = self.mincha_gedola_baal_hatanya()?;
Some(mg_30.max(mg_bht))
}
/// Returns the *Baal Hatanya*'s *mincha ketana*. This is the
/// preferred earliest time to pray *mincha* in the opinion of the *Rambam*
/// and others. For more information on this see the documentation on
/// *mincha gedola*. This is calculated as 9.5 of the [*Baal Hatanya*'s
/// temporal hours](ComplexZmanimCalendar::shaah_zmanis_baal_hatanya) after
/// [*hanetz amiti*](ComplexZmanimCalendar::hanetz_amiti_baal_hatanya)
/// (sunrise). This calculation is calculated based on the opinion of
/// the *Baal Hatanya* that the day is calculated from sunrise to
/// sunset.
#[must_use]
pub fn mincha_ketana_baal_hatanya(&self) -> Option<Zoned> {
self.mincha_ketana_mga(&Degrees(1.583))
}
/// Returns the *Baal Hatanya*'s *plag hamincha*. This is
/// calculated as 10.75 of the [*Baal Hatanya*'s temporal
/// hours](ComplexZmanimCalendar::shaah_zmanis_baal_hatanya) after *hanetz
/// amiti* (sunrise). This calculation is calculated based on the
/// opinion of the *Baal Hatanya* that the day is calculated from
/// sunrise to sunset.
#[must_use]
pub fn plag_baal_hatanya(&self) -> Option<Zoned> {
self.plag_mga(&Degrees(1.583))
}
/// Returns *tzeis* (nightfall) when the sun is 6° below
/// the western geometric horizon (90°) after sunset. This calculation
/// is based on the position of the sun 24 minutes after sunset in Jerusalem
/// around the equinox / equilux, which is 6° below geometric zenith.
#[must_use]
pub fn tzeis_baal_hatanya(&self) -> Option<Zoned> {
self.tzeis(&Degrees(6.0))
}
// Rav Moshe Feinstein
/// Returns fixed local *chatzos*. See
/// [`crate::zmanim_calculator::fixed_local_chatzos_hayom`] for more
/// details.
#[must_use]
pub fn fixed_local_chatzos_hayom(&self) -> Option<Zoned> {
zmanim_calculator::fixed_local_chatzos_hayom(self.date, &self.geo_location)
}
/// Returns Rav Moshe Feinstein's opinion of the calculation of
/// *sof zman krias shema* (latest time to recite *Shema* in the morning)
/// according to the opinion of the *Magen Avraham* (MGA) that the day is
/// calculated from dawn to nightfall, but calculated using the first half
/// of the day only. The half a day starts at *alos* defined as 18° and
/// ends at fixed local *chatzos*. *Sof Zman Shema* is 3 *shaos
/// zmaniyos* (solar hours) after *alos* or half of this half-day.
#[must_use]
pub fn sof_zman_shema_mga_alos_18_to_fixed_local_chatzos(&self) -> Option<Zoned> {
let alos = self.alos_18_degrees()?;
let chatzos = self.fixed_local_chatzos_hayom()?;
Some(zmanim_calculator::half_day_based_zman(&alos, &chatzos, 3.0))
}
/// Returns Rav Moshe Feinstein's opinion of the calculation of
/// *sof zman krias shema* (latest time to recite *Shema* in the morning)
/// according to the opinion of the *Magen Avraham* (MGA) that the day is
/// calculated from dawn to nightfall, but calculated using the first half
/// of the day only. The half a day starts at *alos* defined as 16.1°
/// and ends at fixed local *chatzos*. *Sof Zman Shema* is 3 *shaos
/// zmaniyos* (solar hours) after this *alos* or half of this half-day.
#[must_use]
pub fn sof_zman_shema_mga_alos_16_1_to_fixed_local_chatzos(&self) -> Option<Zoned> {
let alos = self.alos_16_1_degrees()?;
let chatzos = self.fixed_local_chatzos_hayom()?;
Some(zmanim_calculator::half_day_based_zman(&alos, &chatzos, 3.0))
}
/// Returns Rav Moshe Feinstein's opinion of the calculation of
/// *sof zman krias shema* (latest time to recite *Shema* in the morning)
/// according to the opinion of the *Magen Avraham* (MGA) that the day is
/// calculated from dawn to nightfall, but calculated using the first half
/// of the day only. The half a day starts at *alos* defined as 90 minutes
/// before sunrise and ends at fixed local *chatzos*. *Sof Zman Shema* is 3
/// *shaos zmaniyos* (solar hours) after this *alos* or half of this
/// half-day.
#[must_use]
pub fn sof_zman_shema_mga_90_minutes_to_fixed_local_chatzos(&self) -> Option<Zoned> {
let alos = self.alos_90_minutes()?;
let chatzos = self.fixed_local_chatzos_hayom()?;
Some(zmanim_calculator::half_day_based_zman(&alos, &chatzos, 3.0))
}
/// Returns Rav Moshe Feinstein's opinion of the calculation of
/// *sof zman krias shema* (latest time to recite *Shema* in the morning)
/// according to the opinion of the *Magen Avraham* (MGA) that the day is
/// calculated from dawn to nightfall, but calculated using the first half
/// of the day only. The half a day starts at *alos* defined as 72 minutes
/// before sunrise and ends at fixed local *chatzos*. *Sof Zman Shema* is 3
/// *shaos zmaniyos* (solar hours) after this *alos* or half of this
/// half-day.
#[must_use]
pub fn sof_zman_shema_mga_72_minutes_to_fixed_local_chatzos(&self) -> Option<Zoned> {
let alos = self.alos_72_minutes()?;
let chatzos = self.fixed_local_chatzos_hayom()?;
Some(zmanim_calculator::half_day_based_zman(&alos, &chatzos, 3.0))
}
/// Returns Rav Moshe Feinstein's opinion of the calculation of
/// *sof zman krias shema* (latest time to recite *Shema* in the morning)
/// according to the opinion of the GRA that the day is calculated from
/// sunrise to sunset, but calculated using the first half of the day only.
/// The half a day starts at sunrise and ends at fixed local *chatzos*. *Sof
/// Zman Shema* is 3 *shaos zmaniyos* (solar hours) after sunrise or half of
/// this half-day.
#[must_use]
pub fn sof_zman_shema_gra_sunrise_to_fixed_local_chatzos(&self) -> Option<Zoned> {
let alos = self.zmanim_sunrise()?;
let chatzos = self.fixed_local_chatzos_hayom()?;
Some(zmanim_calculator::half_day_based_zman(&alos, &chatzos, 3.0))
}
/// Returns Rav Moshe Feinstein's opinion of the calculation of
/// *sof zman tefila* (the latest time to recite the morning
/// prayers) according to the opinion of the GRA that the day is calculated
/// from sunrise to sunset, but calculated using the first half of the day
/// only. The half a day starts at sunrise and ends at fixed local
/// *chatzos*. *Sof zman tefila* is 4 *shaos zmaniyos* (solar hours) after
/// sunrise or 2/3 of this half-day.
#[must_use]
pub fn sof_zman_tefila_gra_sunrise_to_fixed_local_chatzos(&self) -> Option<Zoned> {
let alos = self.zmanim_sunrise()?;
let chatzos = self.fixed_local_chatzos_hayom()?;
Some(zmanim_calculator::half_day_based_zman(&alos, &chatzos, 4.0))
}
/// Returns Rav Moshe Feinstein's opinion of the calculation of
/// mincha gedola, the earliest time one can pray mincha that is 30 minutes
/// after fixed local *chatzos*.
#[must_use]
pub fn mincha_gedola_gra_fixed_local_chatzos_30_minutes(&self) -> Option<Zoned> {
self.fixed_local_chatzos_hayom()?
.checked_add(SignedDuration::from_mins(30))
.ok()
}
/// Returns Rav Moshe Feinstein's opinion of the calculation of
/// mincha ketana (the preferred time to recite the mincha prayers according
/// to the opinion of the Rambam and others) calculated according to the GRA
/// that is 3.5 *shaos zmaniyos* (solar hours) after fixed local *chatzos*.
#[must_use]
pub fn mincha_ketana_gra_fixed_local_chatzos_to_sunset(&self) -> Option<Zoned> {
let chatzos = self.fixed_local_chatzos_hayom()?;
let sunset = self.zmanim_sunset()?;
chatzos
.checked_add(sunset.duration_since(&chatzos) / 12 * 7)
.ok()
}
/// Returns Rav Moshe Feinstein's opinion of the calculation of
/// plag hamincha. This method returns plag hamincha calculated according to
/// the GRA that the day ends at sunset and is 4.75 *shaos zmaniyos* (solar
/// hours) after fixed local *chatzos*.
#[must_use]
pub fn plag_gra_fixed_local_chatzos_to_sunset(&self) -> Option<Zoned> {
let chatzos = self.fixed_local_chatzos_hayom()?;
let sunset = self.zmanim_sunset()?;
chatzos
.checked_add(sunset.duration_since(&chatzos) / 24 * 19)
.ok()
}
/// Method to return *tzeis* (dusk) calculated as 50 minutes after
/// sunset. This method returns
/// *tzeis* (nightfall) based on the opinion of Rabbi Moshe Feinstein
/// for the New York area. This time should not be used for latitudes
/// other than ones similar to the latitude of the NY area.
#[must_use]
pub fn tzeis_50_minutes(&self) -> Option<Zoned> {
self.tzeis(&Minutes(50.0))
}
// Ahavat Shalom
/// Returns the time of *mincha gedola* based on the opinion of
/// Rabbi Yaakov Moshe Hillel as published in the luach of the Beis Horaah
/// of Yeshivat Chevrat Ahavat Shalom that *mincha gedola* is calculated as
/// half a *shaah zmanis* after *chatzos* with *shaos zmaniyos* calculated
/// based on a day starting 72 minutes before sunrise (alos 16.1°) and
/// ending 13.5 minutes after sunset (*tzeis* 3.7°). *Mincha gedola* is
/// the earliest time to pray *mincha*. The later of this time or 30
/// clock minutes after *chatzos* is returned. See
/// [`mincha_gedola_gra_greater_than_30_minutes`](ComplexZmanimCalendar::mincha_gedola_gra_greater_than_30_minutes)
/// (though that calculation is based on *mincha gedola* GRA). For more
/// information about *mincha gedola* see the documentation on [*mincha
/// gedola*](crate::zmanim_calculator::mincha_gedola).
#[must_use]
pub fn mincha_gedola_ahavat_shalom(&self) -> Option<Zoned> {
let chatzos = self.chatzos_hayom()?;
let alos_16_1 = self.alos_16_1_degrees()?;
let tzeis_3_7 = self.tzeis_geonim_3_7_degrees()?;
let mg_as = chatzos
.checked_add(tzeis_3_7.duration_since(&alos_16_1) / 24)
.ok()?;
let mg_30 = self.mincha_gedola_30_minutes()?;
Some(mg_30.max(mg_as))
}
/// Returns the time of *mincha ketana* based on the opinion of
/// Rabbi Yaakov Moshe Hillel as published in the luach of the Beis Horaah
/// of Yeshivat Chevrat Ahavat Shalom that *mincha ketana* is calculated as
/// 2.5 *shaos zmaniyos* before *tzeis* 3.8° with *shaos zmaniyos*
/// calculated based on a day starting at *alos* 16.1° and ending at
/// *tzeis* 3.8°. *Mincha ketana* is the preferred earliest time to
/// pray *mincha* according to the opinion of the *Rambam* and others.
/// For more information on this see the documentation on [*mincha
/// ketana*](crate::zmanim_calculator::mincha_ketana).
#[must_use]
pub fn mincha_ketana_ahavat_shalom(&self) -> Option<Zoned> {
Some(zmanim_calculator::mincha_ketana(
&self.alos_16_1_degrees()?,
&self.tzeis_geonim_3_8_degrees()?,
))
}
/// Returns the time of *plag hamincha* based on the opinion of
/// Rabbi Yaakov Moshe Hillel as published in the luach of the Beis Horaah
/// of Yeshivat Chevrat Ahavat Shalom that *plag hamincha* is
/// calculated as 1.25 *shaos zmaniyos* before *tzeis* 3.8° with *shaos
/// zmaniyos* calculated based on a day starting at *alos* 16.1° and
/// ending at *tzeis* 3.8°.
#[must_use]
pub fn plag_ahavat_shalom(&self) -> Option<Zoned> {
Some(zmanim_calculator::plag_hamincha(
&self.alos_16_1_degrees()?,
&self.tzeis_geonim_3_8_degrees()?,
))
}
/// Returns a *shaah zmanis* (temporal hour) used by some *zmanim*
/// according to the opinion of Rabbi Yaakov Moshe Hillel as published in
/// the luach of the Beis Horaah of Yeshivat Chevrat Ahavat Shalom that is
/// based on a day starting 72 minutes before sunrise in degrees (*alos*
/// 16.1°) and ending 14 minutes after sunset in degrees (*tzeis*
/// 3.8°). This day is split into 12 equal parts with each part
/// being a *shaah zmanis*. Note that with this system, *chatzos*
/// (midday) will not be the point that the sun is halfway across the
/// sky. These *shaos zmaniyos* are used for *Mincha Ketana* and *Plag
/// Hamincha*. The 14 minutes are based on 3/4 of an 18 minute *mil*,
/// with half a minute added for Rav Yosi.
#[must_use]
pub fn shaah_zmanis_alos_16_1_to_tzeis_3_8(&self) -> Option<SignedDuration> {
Some(zmanim_calculator::shaah_zmanis(
&self.alos_16_1_degrees()?,
&self.tzeis_geonim_3_8_degrees()?,
))
}
/// Returns a *shaah zmanis* (temporal hour) used by some *zmanim*
/// according to the opinion of Rabbi Yaakov Moshe Hillel as published in
/// the luach of the Beis Horaah of Yeshivat Chevrat Ahavat Shalom that is
/// based on a day starting 72 minutes before sunrise in degrees (*alos*
/// 16.1°) and ending 13.5 minutes after sunset in degrees (*tzeis*
/// 3.7°). This day is split into 12 equal parts with each part
/// being a *shaah zmanis*. Note that with this system, *chatzos*
/// (midday) will not be the point that the sun is halfway across the
/// sky. These *shaos zmaniyos* are used for *mincha gedola* calculation.
#[must_use]
pub fn shaah_zmanis_alos_16_1_to_tzeis_3_7(&self) -> Option<SignedDuration> {
Some(zmanim_calculator::shaah_zmanis(
&self.alos_16_1_degrees()?,
&self.tzeis_geonim_3_7_degrees()?,
))
}
// Ateret Torah
/// Returns the latest *zman krias shema* (time to recite
/// *Shema* in the morning) based on the calculation of *Chacham* Yosef
/// Harari-Raful of Yeshivat Ateret Torah, that the day starts 1/10th of the
/// day before sunrise and is usually calculated as ending 40 minutes after
/// sunset. *Shaos zmaniyos* are calculated based on this day and added to
/// *alos* to reach this time. This time is 3 *shaos zmaniyos* (temporal
/// hours) after *alos*72 zmaniyos. Note: Based on this calculation
/// *chatzos* will not be at midday.
#[must_use]
pub fn sof_zman_shema_ateret_torah(&self) -> Option<Zoned> {
Some(zmanim_calculator::sof_zman_shema(
&self.alos_72_minutes_zmanis()?,
&self.tzeis_ateret_torah()?,
))
}
/// Returns the latest *zman tefila* (time to recite the morning
/// prayers) based on the calculation of *Chacham* Yosef Harari-Raful of
/// Yeshivat Ateret Torah, that the day starts 1/10th of the day before
/// sunrise and is usually calculated as ending 40 minutes after sunset.
/// *Shaos zmaniyos* are calculated based on this day and added to *alos* to
/// reach this time. This time is 4 *shaos zmaniyos* (temporal hours)
/// after *alos*72 *zmaniyos*. Note: Based on this calculation *chatzos*
/// will not be at midday.
#[must_use]
pub fn sof_zman_tefila_ateret_torah(&self) -> Option<Zoned> {
Some(zmanim_calculator::sof_zman_tefila(
&self.alos_72_minutes_zmanis()?,
&self.tzeis_ateret_torah()?,
))
}
/// Returns the time of *mincha gedola* based on the calculation of
/// *Chacham* Yosef Harari-Raful of Yeshivat Ateret Torah, that the day
/// starts 1/10th of the day before sunrise and is usually calculated as
/// ending 40 minutes after sunset. The *Rambam* is of the opinion that it
/// is better to delay *mincha* until *mincha ketana* while the *Rash*,
/// *Tur*, GRA and others are of the opinion that *mincha* can be prayed
/// *lechatchila* starting at *mincha gedola*. For more information on
/// this see the documentation on [*mincha
/// gedola*](crate::zmanim_calculator::mincha_gedola).
/// This is calculated as 6.5 solar hours after *alos*. The calculation used
/// is `6.5 *` [`ComplexZmanimCalendar::shaah_zmanis_ateret_torah`] after
/// *alos*.
#[must_use]
pub fn mincha_gedola_ateret_torah(&self) -> Option<Zoned> {
Some(zmanim_calculator::mincha_gedola(
&self.alos_72_minutes_zmanis()?,
&self.tzeis_ateret_torah()?,
))
}
/// Returns the time of *mincha ketana* based on the calculation of
/// *Chacham* Yosef Harari-Raful of Yeshivat Ateret Torah, that the day
/// starts 1/10th of the day before sunrise and is usually calculated as
/// ending 40 minutes after sunset. This is the preferred earliest time to
/// pray *mincha* according to the opinion of the *Rambam* and others. For
/// more information on this see the documentation on [*mincha
/// ketana*](crate::zmanim_calculator::mincha_ketana). This is calculated as
/// 9.5 solar hours after *alos*. The calculation used is 9.5 *
/// [`ComplexZmanimCalendar::shaah_zmanis_ateret_torah`] after *alos*.
#[must_use]
pub fn mincha_ketana_ateret_torah(&self) -> Option<Zoned> {
Some(zmanim_calculator::mincha_ketana(
&self.alos_72_minutes_zmanis()?,
&self.tzeis_ateret_torah()?,
))
}
/// Returns the time of *plag hamincha* based on the calculation
/// of *Chacham* Yosef Harari-Raful of Yeshivat Ateret Torah, that the day
/// starts 1/10th of the day before sunrise and is usually calculated as
/// ending 40 minutes after sunset. *Shaos zmaniyos* are calculated based on
/// this day and added to *alos* to reach this time. This time is 10.75
/// *shaos zmaniyos* (temporal hours) after dawn.
#[must_use]
pub fn plag_ateret_torah(&self) -> Option<Zoned> {
Some(zmanim_calculator::plag_hamincha(
&self.alos_72_minutes_zmanis()?,
&self.tzeis_ateret_torah()?,
))
}
/// Returns *tzeis* calculated as 40 minutes after sunset. Please note that
/// *Chacham* Yosef Harari-Raful of Yeshivat Ateret Torah who uses this
/// time, does so only for calculating various other zmanei hayom such as
/// *Sof Zman Krias Shema* and *Plag Hamincha*. His calendars do not publish
/// a *zman* for *tzeis*. It should also be noted that *Chacham*
/// Harari-Raful provided a 25 minute *zman* for Israel. This API uses
/// 40 minutes year round in any place on the globe.
#[must_use]
pub fn tzeis_ateret_torah(&self) -> Option<Zoned> {
self.tzeis(&Minutes(40.0))
}
/// Returns a shaah zmanis (temporal hour) according to the opinion
/// of the *Chacham* Yosef Harari-Raful of Yeshivat Ateret Torah calculated
/// with *alos* being 1/10th of sunrise to sunset day, or 72 minutes
/// *zmaniyos* of such a day before sunrise, and *tzeis* is usually
/// calculated as 40 minutes after sunset. This day is split into 12
/// equal parts with each part being a shaah zmanis. Note that with this
/// system, *chatzos* (midday) will not be the point that the sun is
/// halfway across the sky.
#[must_use]
pub fn shaah_zmanis_ateret_torah(&self) -> Option<SignedDuration> {
Some(zmanim_calculator::shaah_zmanis(
&self.alos_72_minutes_zmanis()?,
&self.tzeis_ateret_torah()?,
))
}
// Ben Ish Chai
/// Returns sunrise calculated as the time when the sun is directly due east
/// (azimuth 90°) in Polar regions on days that there is no
/// [*hanetz*](ComplexZmanimCalendar::hanetz). If there is *hanetz* that
/// day, `None` is returned.
///
/// In Polar regions (the Arctic or Antarctic circles), there are days of no
/// sunrise or sunset, and there are halachic opinions that during these
/// periods, sunrise is reached when the sun is directly due east (azimuth
/// 90°). The day-night boundary (sunset) in these opinions is when the sun
/// is directly due west (azimuth 270°) returned by
/// [`polar_sunset_ben_ish_chai`](ComplexZmanimCalendar::polar_sunset_ben_ish_chai).
/// This is the opinion of Rabbi Yehosef Schwarz in his דברי יוסף – דרך מבוא
/// השמש and דברי יוסף – תשובות, שאלה ח׳. This is brought down *lehalacha*
/// by The *Ben Ish Chai* in the רב פעלים – חלק ב׳, סוד ישרים ס׳ ד׳.
/// This time is close to six hours before astronomical chatzos hayom, but
/// depending on the time of year and location in the Arctic / Antarctic, it
/// can be up to 46 minutes before or after this time.
#[must_use]
pub fn polar_sunrise_ben_ish_chai(&self) -> Option<Zoned> {
if self.hanetz().is_none() {
astronomical_calculator::time_at_azimuth(
self.date,
&self.geo_location,
astronomical_calculator::Azimuth::East,
)
} else {
None
}
}
/// Returns *Plag Hamincha* in Polar regions on days that there are no
/// [*hanetz*](ComplexZmanimCalendar::hanetz) and [*shkia*
/// ](ComplexZmanimCalendar::shkia), calculated 10.75 *shaaos zmaniyos* of a
/// day calculated starting at
/// [`polar_sunrise_ben_ish_chai`](ComplexZmanimCalendar::polar_sunrise_ben_ish_chai)
/// and ending at
/// [`polar_sunset_ben_ish_chai`](ComplexZmanimCalendar::polar_sunset_ben_ish_chai).
///
/// This is the opinion of Rabbi Yehosef Schwarz in his דברי יוסף – דרך מבוא
/// השמש and דברי יוסף – תשובות, שאלה ח׳. This is brought down *lehalacha*
/// by The *Ben Ish Chai* in the רב פעלים – חלק ב׳, סוד ישרים ס׳ ד׳. If
/// there is sunrise or sunset on the set day, `None` will be returned.
#[must_use]
pub fn polar_plag_ben_ish_chai(&self) -> Option<Zoned> {
Some(zmanim_calculator::plag_hamincha(
&self.polar_sunrise_ben_ish_chai()?,
&self.polar_sunset_ben_ish_chai()?,
))
}
/// Returns sunset calculated as the time when the sun is directly due west
/// (azimuth 270°) in Polar
/// regions on days
/// that there is no [*shkia*](ComplexZmanimCalendar::shkia). If there is
/// *shkia* that day, `None` is returned.
///
/// In Polar regions (the Arctic or Antarctic circles), there are days of no
/// sunrise or sunset, and there are halachic opinions that during these
/// periods, sunset (the day-night boundary) is reached when the sun is
/// directly due west (azimuth 270°). Sunrise in this opinion is when the
/// sun is directly due east (azimuth 90°) returned by
/// [`polar_sunrise_ben_ish_chai`](ComplexZmanimCalendar::polar_sunrise_ben_ish_chai).
/// This is the opinion of Rabbi Yehosef Schwarz in his דברי יוסף – דרך מבוא
/// השמש and דברי יוסף – תשובות, שאלה ח׳. This is brought down
/// *lehalacha* by The *Ben Ish Chai* in the רב פעלים – חלק ב׳, סוד
/// ישרים ס׳ ד׳. This time is close to six hours after astronomical chatzos
/// hayom, but depending on the time of year and location in the Arctic /
/// Antarctic, it can be up to 46 minutes before or after this time.
#[must_use]
pub fn polar_sunset_ben_ish_chai(&self) -> Option<Zoned> {
if self.shkia().is_none() {
astronomical_calculator::time_at_azimuth(
self.date,
&self.geo_location,
astronomical_calculator::Azimuth::West,
)
} else {
None
}
}
// Shach
/// Returns the latest *zman krias shema* (time to recite *Shema* in the
/// morning) calculated as 3 hours (regular clock hours and not *shaos
/// zmaniyos*) before *chatzos*. Generally known as part of the "Komarno"
/// *zmanim* after Rav Yitzchak Eizik of Komarno, a proponent of this
/// calculation, it actually predates him a lot. It is the opinion of the
/// *Shach* in the *Nekudas Hakesef* (*Yoreh Deah* 184), Rav Moshe Lifshitz
/// in his commentary *Lechem Mishneh* on *Brachos* 1:2. It is next brought
/// down about 100 years later by the *Yaavetz* (in his *siddur*, *Mor
/// Uktziah Orach Chaim* 1, *Lechem Shamayim*, *Brachos* 1:2 and *She'elos
/// Yaavetz* vol. 1 no. 40), Rav Yitzchak Eizik of Komarno in the *Ma'aseh
/// Oreg* on *Mishnayos Brachos* 11:2, *Shevus Yaakov*, *Chasan Sofer* and
/// others. See *Yisrael Vehazmanim* vol. 1 7:3, page 55 - 62
#[must_use]
pub fn sof_zman_shema_3_hrs_before_chatzos(&self) -> Option<Zoned> {
self.chatzos_hayom()?
.checked_sub(SignedDuration::from_hours(3))
.ok()
}
/// Returns the latest *zman* tefila (time to recite the morning prayers)
/// calculated as 2 hours before *chatzos*. This is based on the opinions
/// that calculate sof *zman* krias shema as [3 hours before
/// *chatzos*](ComplexZmanimCalendar::sof_zman_shema_3_hrs_before_chatzos).
#[must_use]
pub fn sof_zman_tefila_2_hrs_before_chatzos(&self) -> Option<Zoned> {
self.chatzos_hayom()?
.checked_sub(SignedDuration::from_hours(2))
.ok()
}
zmanim_for_offset!(
|_| Some(Degrees(16.1)),
[
alos_16_1_degrees => alos, alos_degrees_basedon_doc!(16.1, 72),
tzeis_16_1_degrees => tzeis, tzeis_degrees_basedon_doc!(16.1, 72),
shaah_zmanis_mga_16_1_degrees => shaah_zmanis_mga, shaah_mga_degrees_basedon_doc!(16.1, 72),
sof_zman_shema_mga_16_1_degrees => sof_zman_shema_mga, szks_mga_degrees_doc!(16.1),
sof_zman_tefila_mga_16_1_degrees => sof_zman_tefila_mga, szt_mga_degrees_doc!(16.1),
sof_zman_biur_chametz_mga_16_1_degrees => sof_zman_biur_chametz_mga, sz_biur_chametz_mga_degrees_doc!(16.1),
mincha_gedola_mga_16_1_degrees => mincha_gedola_mga, mg_mga_degrees_doc!(16.1),
samuch_lemincha_ketana_mga_16_1_degrees => samuch_lemincha_ketana_mga, slmk_mga_degrees_doc!(16.1),
mincha_ketana_mga_16_1_degrees => mincha_ketana_mga, mk_mga_degrees_doc!(16.1),
plag_mga_16_1_degrees => plag_mga, plag_mga_degrees_lechumra_doc!(16.1),
]
);
// *alos* 16.1 degrees to sunset
/// Returns the latest *zman krias shema* (time to recite
/// *Shema* in the morning) based on the opinion that the day starts at
/// *alos* 16.1° and ends at sunset. This is the opinion of the
/// *Chidushei UKlalos HaRazah* and the *Menora Hatehora* as mentioned
/// by *Yisrael Vehazmanim* vol 1, sec. 7, ch. 3 no. 16. Three *shaos
/// zmaniyos* are calculated based on this day and added to *alos* to
/// reach this time. This time is 3 *shaos zmaniyos* (solar hours) after
/// dawn based on the opinion that the day is calculated from a *alos*
/// 16.1° to sunset.
#[must_use]
pub fn sof_zman_shema_alos_16_1_to_sunset(&self) -> Option<Zoned> {
Some(zmanim_calculator::sof_zman_shema(
&self.alos_16_1_degrees()?,
&self.zmanim_sunset()?,
))
}
/// This method should be used *lechumra* only and returns the time of *plag
/// hamincha* based on the opinion that the day starts at *alos* 16.1°
/// and ends at sunset.
///
/// 10.75 *shaos zmaniyos* are calculated based on
/// this day and added to *alos* to reach this time. This time is 10.75
/// *shaos zmaniyos* (temporal hours) after dawn based on the opinion
/// that the day is calculated from a dawn of 16.1 degrees before
/// sunrise to sunset. This returns the time of 10.75 * the calculated
/// *shaah zmanis* after dawn. Since plag by this calculation can occur
/// after sunset, it should only be used *lechumra*.
#[must_use]
pub fn plag_alos_16_1_to_sunset(&self) -> Option<Zoned> {
Some(zmanim_calculator::plag_hamincha(
&self.alos_16_1_degrees()?,
&self.zmanim_sunset()?,
))
}
// 16.1 degrees to *tzeis* geonim 7.083 degrees
/// Returns the latest *zman krias shema* (time to recite
/// *Shema* in the morning) based on the opinion that the day starts at
/// *alos* 16.1° and ends at *tzeis* 7.083°. 3 *shaos zmaniyos*
/// are calculated based on this day and added to *alos* to reach this
/// time. This time is 3 *shaos zmaniyos* (temporal hours) after alos
/// 16.1° based on the opinion that the day is calculated from a
/// *alos* 16.1° to *tzeis* 7.083°.
#[must_use]
pub fn sof_zman_shema_alos_16_1_to_tzeis_7_083(&self) -> Option<Zoned> {
Some(zmanim_calculator::sof_zman_shema(
&self.alos_16_1_degrees()?,
&self.tzeis_geonim_7_083_degrees()?,
))
}
/// Returns the time of *plag hamincha* based on the opinion
/// that the day starts at *alos* 16.1° and ends at *tzeis*
/// 7.083°. 10.75 *shaos zmaniyos* are calculated based on this day
/// and added to *alos* to reach this time. This time is 10.75 *shaos
/// zmaniyos* (temporal hours) after dawn based on the opinion that the
/// day is calculated from a dawn of 16.1 degrees before sunrise to
/// *tzeis* 7.083°. This returns the time of 10.75 * the calculated
/// *shaah zmanis* after dawn.
#[must_use]
pub fn plag_alos_16_1_to_tzeis_7_083(&self) -> Option<Zoned> {
Some(zmanim_calculator::plag_hamincha(
&self.alos_16_1_degrees()?,
&self.tzeis_geonim_7_083_degrees()?,
))
}
/// Returns a *shaah zmanis* (temporal hour) used by some *zmanim* according
/// to some opinions that is based on a day starting at alos 16.1°
/// and ending tzais 7.083°. This day is split into 12 equal parts
/// with each part being a *shaah zmanis*. Note that with this system,
/// *chatzos* (midday) will not be the point that the sun is halfway
/// across the sky.
#[must_use]
pub fn shaah_zmanis_alos_16_1_to_tzeis_7_083(&self) -> Option<SignedDuration> {
Some(zmanim_calculator::shaah_zmanis(
&self.alos_16_1_degrees()?,
&self.tzeis_geonim_7_083_degrees()?,
))
}
zmanim_for_offset!(
|_| Some(Degrees(18.0)),
[
alos_18_degrees => alos, alos_degrees_doc!(18),
tzeis_18_degrees => tzeis, tzeis_degrees_doc!(18),
shaah_zmanis_mga_18_degrees => shaah_zmanis_mga, shaah_mga_degrees_doc!(18),
sof_zman_shema_mga_18_degrees => sof_zman_shema_mga, szks_mga_degrees_doc!(18),
sof_zman_tefila_mga_18_degrees => sof_zman_tefila_mga, szt_mga_degrees_doc!(18),
plag_mga_18_degrees => plag_mga, plag_mga_degrees_lechumra_doc!(18),
]
);
// 19 degrees
/// Returns *alos* (dawn) calculated when the sun is 19°
/// below the eastern geometric horizon before sunrise. This is the
/// *Rambam*'s *alos* according to Rabbi Moshe Kosower's *Maaglei Tzedek*,
/// page 88, *Ayeles Hashachar* Vol. I, page 12, *Yom Valayla Shel Torah*,
/// Ch. 34, p. 222 and Rabbi Yaakov Shakow's *Luach Ikvei Hayom*.
#[must_use]
pub fn alos_19_degrees(&self) -> Option<Zoned> {
self.alos(&Degrees(19.0))
}
zmanim_for_offset!(
|_| Some(Degrees(19.8)),
[
alos_19_8_degrees => alos, alos_degrees_basedon_doc!(19.8, 90),
tzeis_19_8_degrees => tzeis, tzeis_degrees_basedon_doc!(19.8, 90),
shaah_zmanis_mga_19_8_degrees => shaah_zmanis_mga, shaah_mga_degrees_basedon_doc!(19.8, 90),
sof_zman_shema_mga_19_8_degrees => sof_zman_shema_mga, szks_mga_degrees_doc!(19.8),
sof_zman_tefila_mga_19_8_degrees => sof_zman_tefila_mga, szt_mga_degrees_doc!(19.8),
plag_mga_19_8_degrees => plag_mga, plag_mga_degrees_lechumra_doc!(19.8),
]
);
zmanim_for_offset!(
|_| Some(Degrees(26.0)),
[
alos_26_degrees => alos, alos_degrees_basedon_lechumra_doc!(26, 120),
tzeis_26_degrees => tzeis, tzeis_degrees_basedon_doc!(26, 120),
shaah_zmanis_mga_26_degrees => shaah_zmanis_mga, shaah_mga_degrees_lechumra_basedon_doc!(26, 120),
plag_mga_26_degrees => plag_mga, plag_mga_degrees_lechumra_doc!(26),
]
);
zmanim_for_offset!(
|_| Some(Minutes(60.0)),
[
alos_60_minutes => alos, "Returns *alos* (dawn) calculated as 60 minutes before sunrise. This is the time to walk the distance of 4 *mil* at 15 minutes a *mil*. This seems to be the opinion of the *Chavas Yair* in the *Mekor Chaim, Orach Chaim* Ch. 90, though the *Mekor Chaim* in Ch. 58 and in the *Chut Hashani* Ch. 97 states that a person walks 3 and a 1/3 *mil* in an hour, or an 18-minute *mil*. Also see the *Divrei Malkiel* Vol. 4, Ch. 20, page 34) who mentions the 15 minute *mil lechumra* by baking *matzos*. Also see the *Maharik* Ch. 173 where the questioner quoting the *Ra'avan* is of the opinion that the time to walk a *mil* is 15 minutes (5 *mil* in a little over an hour). There are many who believe that there is a *ta'us sofer* (scribal error) in the *Ra'avan*, and it should be 4 *mil* in a little over an hour, or an 18-minute *mil*. Time based offset calculations are based on the opinion of the *Rishonim* who stated that the time of the *neshef* (time between dawn and sunrise) does not vary by the time of year or location but purely depends on the time it takes to walk the distance of 4 *mil*.",
tzeis_60_minutes => tzeis, "Returns *tzeis hakochavim* (nightfall) based on the opinion of the *Chavas Yair* and *Divrei Malkiel* that the time to walk the distance of a mil is 15 minutes, for a total of 60 minutes for 4 *mil* after sunset. See detailed documentation explaining the 60 minute concept at [alos_60_minutes](ComplexZmanimCalendar::alos_60_minutes).",
shaah_zmanis_mga_60_minutes => shaah_zmanis_mga, shaah_mga_minutes_doc!(60),
plag_mga_60_minutes => plag_mga, plag_mga_minutes_doc!(60),
]
);
zmanim_for_offset!(
|_| Some(Minutes(72.0)),
[
alos_72_minutes => alos, alos_minutes_basedon_doc!(72, 18),
tzeis_72_minutes => tzeis, "Returns *tzeis hakochavim* (nightfall) based on the opinion of *Rabbeinu Tam* that *tzeis hakochavim* is calculated as 72 minutes after sunset, the time it takes to walk 4 *mil* at 18 minutes a mil. According to the *Machtzis Hashekel* in *Orach Chaim* 235:3, the *Pri Megadim* in *Orach Chaim* 261:2 (see the *Biur Halacha*) and others (see *Hazmanim Bahalacha* 17:3 and 17:5) the 72 minutes are standard clock minutes any time of the year in any location.",
shaah_zmanis_mga_72_minutes => shaah_zmanis_mga, shaah_mga_minutes_doc!(72),
sof_zman_shema_mga_72_minutes => sof_zman_shema_mga, szks_mga_minutes_doc!(72),
sof_zman_tefila_mga_72_minutes => sof_zman_tefila_mga, szt_mga_minutes_doc!(72),
sof_zman_biur_chametz_mga_72_minutes => sof_zman_biur_chametz_mga, sz_biur_chametz_mga_minutes_doc!(72),
mincha_gedola_mga_72_minutes => mincha_gedola_mga, mg_mga_minutes_doc!(72),
samuch_lemincha_ketana_mga_72_minutes => samuch_lemincha_ketana_mga, slmk_mga_minutes_doc!(72),
mincha_ketana_mga_72_minutes => mincha_ketana_mga, mk_mga_minutes_doc!(72),
plag_mga_72_minutes => plag_mga, plag_mga_minutes_lechumra_doc!(72),
]
);
zmanim_for_offset!(
|this: &ComplexZmanimCalendar| {
Some(MinutesZmaniyos {
minutes_zmaniyos: 72.0,
shaah_zmanis: this.shaah_zmanis_gra()?,
})
},
[
alos_72_minutes_zmanis => alos, concat!(
alos_minutes_zmanis_basedon_doc!(72, 18, "1/10th"),
"\nThis calculation is used in the calendars published by the Hisachdus Harabanim D'Artzos Habris Ve'Canada."
),
tzeis_72_minutes_zmanis => tzeis, "Returns *tzeis hakochavim* (nightfall) calculated as 72 minutes *zmaniyos*, or 1/10th of the day after sunset. This is the way that the *Minchas Cohen* in *Ma'amar* 2:4 calculates *Rebbeinu Tam*'s time of *tzeis*. It should be noted that this calculation results in the shortest time from sunset to *tzeis* being during the winter solstice, the longest at the summer solstice and 72 clock minutes at the equinox. This does not match reality, since there is no direct relationship between the length of the day and twilight. The shortest twilight is during the equinox, the longest is during the summer solstice, and in the winter with the shortest daylight, the twilight period is longer than during the equinoxes.",
shaah_zmanis_mga_72_minutes_zmanis => shaah_zmanis_mga, shaah_mga_minutes_zmanis_doc!(72, "1/10th"),
sof_zman_shema_mga_72_minutes_zmanis => sof_zman_shema_mga, szks_mga_minutes_zmanis_doc!(72, "1/10th"),
sof_zman_tefila_mga_72_minutes_zmanis => sof_zman_tefila_mga, szt_mga_minutes_zmanis_doc!(72, "1/10th"),
sof_zman_biur_chametz_mga_72_minutes_zmanis => sof_zman_biur_chametz_mga, sz_biur_chametz_mga_minutes_zmanis_doc!(72, "1/10th"),
plag_mga_72_minutes_zmanis => plag_mga, plag_mga_minutes_zmanis_lechumra_doc!(72, "1/10th"),
]
);
zmanim_for_offset!(
|_| Some(Minutes(90.0)),
[
alos_90_minutes => alos, alos_minutes_basedon_doc!(90, 22.5),
tzeis_90_minutes => tzeis, "Returns *tzeis hakochavim* (dusk) calculated as 90 minutes after sunset. This method returns *tzeis* based on the opinion of the *Magen Avraham* that the time to walk the distance of a *mil* according to the *Rambam*'s opinion is 18 minutes, for a total of 90 minutes based on the opinion of Ula who calculated *tzeis* as 5 *mil* after *shkiah* (sunset). A similar calculation [tzeis_19_8_degrees](ComplexZmanimCalendar::tzeis_19_8_degrees) uses solar position calculations based on this time.",
shaah_zmanis_mga_90_minutes => shaah_zmanis_mga, shaah_mga_minutes_doc!(90),
sof_zman_shema_mga_90_minutes => sof_zman_shema_mga, szks_mga_minutes_doc!(90),
sof_zman_tefila_mga_90_minutes => sof_zman_tefila_mga, szt_mga_minutes_doc!(90),
plag_mga_90_minutes => plag_mga, plag_mga_minutes_lechumra_doc!(90),
]
);
zmanim_for_offset!(
|this: &ComplexZmanimCalendar| {
Some(MinutesZmaniyos {
minutes_zmaniyos: 90.0,
shaah_zmanis: this.shaah_zmanis_gra()?,
})
},
[
alos_90_minutes_zmanis => alos, alos_minutes_zmanis_basedon_doc!(90, 22.5, "1/8th"),
tzeis_90_minutes_zmanis => tzeis, concat!(
tzeis_minutes_zmanis_basedon_doc!(90, 22.5, "1/8th"),
" This time is known in Yiddish as the *achtel* (an eighth) *zman*."
),
shaah_zmanis_mga_90_minutes_zmanis => shaah_zmanis_mga, shaah_mga_minutes_zmanis_doc!(90, "1/8th"),
sof_zman_shema_mga_90_minutes_zmanis => sof_zman_shema_mga, szks_mga_minutes_zmanis_doc!(90, "1/8th"),
sof_zman_tefila_mga_90_minutes_zmanis => sof_zman_tefila_mga, szt_mga_minutes_zmanis_doc!(90, "1/8th"),
plag_mga_90_minutes_zmanis => plag_mga, plag_mga_minutes_zmanis_lechumra_doc!(90, "1/8th"),
]
);
zmanim_for_offset!(
|_| Some(Minutes(96.0)),
[
alos_96_minutes => alos, alos_minutes_basedon_doc!(96, 24),
tzeis_96_minutes => tzeis, tzeis_minutes_basedon_doc!(96, 24),
shaah_zmanis_mga_96_minutes => shaah_zmanis_mga, shaah_mga_minutes_doc!(96),
sof_zman_shema_mga_96_minutes => sof_zman_shema_mga, szks_mga_minutes_doc!(96),
sof_zman_tefila_mga_96_minutes => sof_zman_tefila_mga, szt_mga_minutes_doc!(96),
plag_mga_96_minutes => plag_mga, plag_mga_minutes_lechumra_doc!(96),
]
);
zmanim_for_offset!(
|this: &ComplexZmanimCalendar| {
Some(MinutesZmaniyos {
minutes_zmaniyos: 96.0,
shaah_zmanis: this.shaah_zmanis_gra()?,
})
},
[
alos_96_minutes_zmanis => alos, alos_minutes_zmanis_basedon_doc!(96, 22.5, "1/7.5th"),
tzeis_96_minutes_zmanis => tzeis, tzeis_minutes_zmanis_basedon_doc!(96, 22.5, "1/7.5th"),
shaah_zmanis_mga_96_minutes_zmanis => shaah_zmanis_mga, shaah_mga_minutes_zmanis_doc!(96, "1/7.5th"),
sof_zman_shema_mga_96_minutes_zmanis => sof_zman_shema_mga, szks_mga_minutes_zmanis_doc!(96, "1/7.5th"),
sof_zman_tefila_mga_96_minutes_zmanis => sof_zman_tefila_mga, szt_mga_minutes_zmanis_doc!(96, "1/7.5th"),
plag_mga_96_minutes_zmanis => plag_mga, plag_mga_minutes_zmanis_lechumra_doc!(96, "1/7.5th"),
]
);
zmanim_for_offset!(
|_| Some(Minutes(120.0)),
[
alos_120_minutes => alos, "This method should be used *lechumra* only and returns *alos* (dawn) calculated using 120 minutes before sunrise. This is based on the time to walk the distance of 5 *mil* (Ula) at 24 minutes a *mil*. Time based offset calculations for *alos* are based on the opinion of the *Rishonim* who stated that the time of the *neshef* (time between dawn and sunrise) does not vary by the time of year or location but purely depends on the time it takes to walk the distance of 5 *mil* (Ula). Since this time is extremely early, it should only be used *lechumra*, such as not eating after this time on a fast day, and **not** as the start time for *mitzvos* that can only be performed during the day.",
tzeis_120_minutes => tzeis, "Returns *tzeis hakochavim* (dusk) calculated as 120 minutes after sunset. For information on how this is calculated see the documentation on [alos_120_minutes](ComplexZmanimCalendar::alos_120_minutes).",
shaah_zmanis_mga_120_minutes => shaah_zmanis_mga, shaah_mga_minutes_doc!(120),
sof_zman_shema_mga_120_minutes => sof_zman_shema_mga, szks_mga_minutes_doc!(120),
sof_zman_tefila_mga_120_minutes => sof_zman_tefila_mga, szt_mga_minutes_doc!(120),
plag_mga_120_minutes => plag_mga, plag_mga_minutes_lechumra_doc!(120),
]
);
zmanim_for_offset!(
|this: &ComplexZmanimCalendar| {
Some(MinutesZmaniyos {
minutes_zmaniyos: 120.0,
shaah_zmanis: this.shaah_zmanis_gra()?,
})
},
[
alos_120_minutes_zmanis => alos, "This method should be used *lechumra* only and returns *alos* (dawn) calculated using 120 minutes *zmaniyos* or 1/6th of the day before sunrise. This is based on a 24-minute *mil* so the time for 5 *mil* is 120 minutes, which is 1/6th of a day `(12 * 60) / 6 = 120`. The day is calculated from sunrise to sunset. Since this time is extremely early, it should only be used *lechumra*, such as not eating after this time on a fast day, and **not** as the start time for *mitzvos* that can only be performed during the day.",
tzeis_120_minutes_zmanis => tzeis, "This method should be used *lechumra* only and returns *tzeis* (dusk) calculated using 120 minutes *zmaniyos* after sunset. Since the *zman* is extremely late and at a time when the sun is well below the 18° point (scientifically the darkest point) in most places on the globe, it should only be used *lechumra*, such as delaying the start of nighttime mitzvos.",
shaah_zmanis_mga_120_minutes_zmanis => shaah_zmanis_mga, "Returns a *shaah zmanis* (temporal hour) calculated using a dip of 120 minutes. This calculation divides the day based on the opinion of the *Magen Avraham* (MGA) that the day runs from dawn to dusk. Dawn for this calculation is 120 minutes before sunrise and dusk is 120 minutes after sunset. This day is split into 12 equal parts with each part being a *shaah zmanis*. This is identical to 1/6th of the day from sunrise to sunset. Since *zmanim* that use this method are extremely late or early and at a point when the sky is a long time past the 18° point where the darkest point is reached, *zmanim* that use this should only be used *lechumra* only, such as delaying the start of nighttime *mitzvos*.",
plag_mga_120_minutes_zmanis => plag_mga, plag_mga_minutes_zmanis_lechumra_doc!(120, "1/6th"),
]
);
// Other Misheyakir
/// Returns *misheyakir* based on the position of the sun 12.85° below
/// geometric zenith (90°). This is based on the position of the sun
/// slightly later than 57 minutes before sunrise in Jerusalem around the
/// equinox / equilux. This *zman* is mentioned for use ***bish'as
/// hadchak*** in the Birur Halacha Tinyana and Tlisa'ah in Orach Chaim
/// siman 18 as 12.85°. Actual calculations show it to be slightly more
/// than 12.9°, but the Birur Halacha indicates that 12.85° is a
/// slight *chumra* (on a *bedieved* time) VS the 12.9° that 57 minutes
/// calculates as (a difference of about 14 seconds at the equinox/equilux
/// in Jerusalem). The *zman* of 12.9° is also mentioned in the Piskei
/// Tshuvos siman 18, page 190 (where a typo indicates that this is the
/// degree equivalent to 60 minutes before sunrise, when in fact at that
/// point the sun is about 13.5° below the horizon). The 57 minute based
/// time is mentioned by the Minchas Yitzchak vol. 9, siman 9 as 15 minutes
/// before *alos hashachar* (though he is not clear what location he refers
/// to, and does not mention a degree-based conversion). The Kaf Hachaim
/// vol.1 siman 18, no. 18 states that in Yerushalayim 60 fixed minutes are
/// used year round. Calculations show that 60 fixed minutes in Yerushalayim
/// ranges from 13.5° at the spring equinox to 11.5° at the summer
/// solstice. 57 minutes range from 12.9° at the winter equinox to
/// 11° at the summer solstice. Analysis of the difference between
/// 12.85° and 12.9°, shows that the maximum difference occurs at
/// the summer solstice. In Lakewood, NJ at a latitude of 40.096°, the
/// maximum difference throughout the year is 23 seconds. In the winter
/// where there is the greatest need for very early *misheyakir* times, the
/// difference is in the 16 second range. Going north to Montreal at
/// latitude 45.5°, the maximum is 29 seconds and is about 18 seconds in
/// the winter. Moving farther north to the elevation of Vilnius at a
/// latitude of 54.68°, things change. Firstly, around the summer
/// solstice it will not reach that far below the horizon. On the dates that
/// both can be calculated, the maximum difference can be pretty high on one
/// or two days of the year (around Jul 8), with about a week having over a
/// two minute difference between the two. Even at the latitude of Vilna,
/// from Dec - March, the difference is about 22 seconds.
#[must_use]
pub fn misheyakir_12_85_degrees(&self) -> Option<Zoned> {
self.alos(&Degrees(12.85))
}
/// Returns *misheyakir* based on the position of the sun when
/// it is 11.5° below geometric zenith (90°). This calculation is
/// used for calculating *misheyakir* according to some opinions. This
/// calculation is based on the position of the sun 52 minutes before
/// sunrise in Jerusalem around the equinox / equilux, which calculates
/// to 11.5° below geometric zenith.
#[must_use]
pub fn misheyakir_11_5_degrees(&self) -> Option<Zoned> {
self.alos(&Degrees(11.5))
}
/// Returns *misheyakir* based on the position of the sun when
/// it is 11° below geometric zenith (90°). This calculation is used
/// for calculating *misheyakir* according to some opinions. This
/// calculation is based on the position of the sun 48 minutes before
/// sunrise in Jerusalem around the equinox / equilux, which calculates
/// to 11° below geometric zenith.
#[must_use]
pub fn misheyakir_11_degrees(&self) -> Option<Zoned> {
self.alos(&Degrees(11.0))
}
/// Returns *misheyakir* based on the position of the sun when
/// it is 10.2° below geometric zenith (90°). This calculation is
/// used for calculating *misheyakir* according to some opinions. This
/// calculation is based on the position of the sun 45 minutes before
/// sunrise in Jerusalem around the equinox which calculates to 10.2°
/// below geometric zenith.
#[must_use]
pub fn misheyakir_10_2_degrees(&self) -> Option<Zoned> {
self.alos(&Degrees(10.2))
}
/// Returns *misheyakir* based on the position of the sun when
/// it is 9.5° below geometric zenith (90°). This calculation is
/// based on Rabbi Dovid Kronglass's Calculation of 45 minutes in
/// Baltimore as mentioned in *Divrei Chachamim* No. 24 brought down by
/// the *Birur Halacha*, *Tinyana*, Ch. 18. This calculates to 9.5°.
/// Also see Rabbi Yaakov Yitzchok Neiman in *Kovetz Eitz Chaim* Vol. 9,
/// p. 202 that the *Vya'an Yosef* did not want to rely on times earlier
/// than 45 minutes in New York. This *zman* is also used in the
/// calendars published by Rabbi Hershel Edelstein. As mentioned in
/// Yisroel Vehazmanim, Rabbi Edelstein who was given the 45 minute
/// *zman* by Rabbi Bick. The calendars published by the *Edot
/// Hamizrach* communities also use this *zman*. This also follows the
/// opinion of Rabbi Shmuel Kamenetsky who provided the time of 36 and
/// 45 minutes, but did not provide a degree-based time. Since this
/// *zman* depends on the level of light, Rabbi Yaakov Shakow presented
/// these degree-based times to Rabbi Shmuel Kamenetsky who agreed to
/// them.
#[must_use]
pub fn misheyakir_9_5_degrees(&self) -> Option<Zoned> {
self.alos(&Degrees(9.5))
}
/// Returns *misheyakir* based on the position of the sun when
/// it is 7.65° below geometric zenith (90°). The degrees are based
/// on a 35/36 minute *zman* around the equinox / equilux, when the
/// *neshef* (twilight) is the shortest. This time is based on Rabbi
/// Moshe Feinstein who writes in *Ohr Hachaim* Vol. 4, Ch. 6 that
/// *misheyakir* in New York is 35-40 minutes before sunrise, something
/// that is a drop less than 8°. Rabbi Yisroel Taplin in *Zmanei
/// Yisrael* (page 117) notes that Rabbi Yaakov Kamenetsky stated that
/// it is not less than 36 minutes before sunrise (maybe it is
/// 40 minutes). *Sefer Yisrael Vehazmanim* (p. 7) quotes the *Tamar
/// Yifrach* in the name of the Satmar Rov that one should be stringent
/// not consider *misheyakir* before 36 minutes. This is also the
/// accepted *minhag* in Lakewood that is used in the Yeshiva. This
/// follows the opinion of Rabbi Shmuel Kamenetsky who provided the time
/// of 35/36 minutes, but did not provide a degree-based time. Since
/// this *zman* depends on the level of light, Rabbi Yaakov Shakow
/// presented this degree-based calculations to Rabbi Shmuel Kamenetsky
/// who agreed to them.
#[must_use]
pub fn misheyakir_7_65_degrees(&self) -> Option<Zoned> {
self.alos(&Degrees(7.65))
}
// Bein Hashmashos Yereim
/// Returns the beginning of *bein hashmashos* (twilight)
/// according to the Yereim (Rabbi Eliezer of Metz) calculated as 18 minutes
/// or 3/4 of a 24-minute mil before sunset. According to the Yereim, bein
/// hashmashos starts 3/4 of a mil before sunset and *tzeis* or nightfall
/// starts at sunset.
#[must_use]
pub fn bein_hashmashos_yereim_18_minutes(&self) -> Option<Zoned> {
self.tzeis(&Minutes(-18.0))
}
/// Returns the beginning of *bein hashmashos* (twilight)
/// according to the Yereim (Rabbi Eliezer of Metz) calculated as the sun's
/// position 3.05° above the horizon around the equinox / equilux, its
/// position 18 minutes or 3/4 of an 24-minute mil before sunset. According
/// to the Yereim, *bein hashmashos* starts 3/4 of a mil before sunset and
/// *tzeis* or nightfall starts at sunset. Note that lechumra (of about 14
/// seconds) a refraction value of 0.5166° as opposed to the traditional
/// 0.566° is used. This is more inline with the actual refraction in
/// Eretz Yisrael and is brought down by Rabbi Yedidya Manet in his
/// Zmanei Halacha Lema'aseh (p. 11). That is the first source that I am
/// aware of that calculates degree-based Yereim zmanim. The 0.5166°
/// refraction is also used by the Luach Itim Lebinah. Calculating the
/// Yereim's *bein hashmashos* using 18-minute based degrees is also
/// suggested in the upcoming 8th edition of the zmanim Kehilchasam. For
/// more details, see the article The Yereim's Bein Hashmashos.
#[must_use]
pub fn bein_hashmashos_yereim_3_05_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(-3.05))
}
/// Returns the beginning of *bein hashmashos* (twilight)
/// according to the Yereim (Rabbi Eliezer of Metz) calculated as 16.875
/// minutes or 3/4 of a 22.5-minute mil before sunset. According to the
/// Yereim, *bein hashmashos* starts 3/4 of a mil before sunset and *tzeis*
/// or nightfall starts at sunset.
#[must_use]
pub fn bein_hashmashos_yereim_16_875_minutes(&self) -> Option<Zoned> {
self.tzeis(&Minutes(-16.875))
}
/// Returns the beginning of *bein hashmashos* (twilight)
/// according to the Yereim (Rabbi Eliezer of Metz) calculated as the sun's
/// position 2.8° above the horizon around the equinox / equilux, its
/// position 16.875 minutes or 3/4 of an 18-minute mil before sunset.
/// According to the Yereim, *bein hashmashos* starts 3/4 of a mil before
/// sunset and *tzeis* or nightfall starts at sunset. Details, including how
/// the degrees were calculated can be seen in the documentation of
/// [`bein_hashmashos_yereim_3_05_degrees`](ComplexZmanimCalendar::bein_hashmashos_yereim_3_05_degrees).
#[must_use]
pub fn bein_hashmashos_yereim_2_8_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(-2.8))
}
/// Returns the beginning of *bein hashmashos* (twilight)
/// according to the Yereim (Rabbi Eliezer of Metz) calculated as 13.5
/// minutes or 3/4 of an 18-minute mil before sunset. According to the
/// Yereim, *bein hashmashos* starts 3/4 of a mil before sunset and *tzeis*
/// or nightfall starts at sunset.
#[must_use]
pub fn bein_hashmashos_yereim_13_5_minutes(&self) -> Option<Zoned> {
self.tzeis(&Minutes(-13.5))
}
/// Returns the beginning of *bein hashmashos* according to the
/// Yereim (Rabbi Eliezer of Metz) calculated as the sun's position 2.1°
/// above the horizon around the equinox / equilux in Yerushalayim, its
/// position 13.5 minutes or 3/4 of an 18-minute mil before sunset.
/// According to the Yereim, *bein hashmashos* starts 3/4 of a mil before
/// sunset and *tzeis* or nightfall starts at sunset. Details, including how
/// the degrees were calculated can be seen in the documentation of
/// [`bein_hashmashos_yereim_3_05_degrees`](ComplexZmanimCalendar::bein_hashmashos_yereim_3_05_degrees).
#[must_use]
pub fn bein_hashmashos_yereim_2_1_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(-2.1))
}
// Bein Hashmashos Rabeinu Tam
/// Method to return the beginning of *bein hashmashos* of Rabbeinu Tam
/// calculated when the sun is 13.24° below the western geometric
/// horizon (90°) after sunset. This calculation is based on the
/// same calculation of [*bein hashmashos* Rabbeinu Tam
/// 58.5](ComplexZmanimCalendar::bein_hashmashos_rt_58_5_minutes) minutes
/// but uses a degree-based calculation instead of 58.5 exact minutes.
/// This calculation is based on the position of the sun 58.5 minutes
/// after sunset in Jerusalem around the equinox / equilux, which
/// calculates to 13.24° below geometric zenith. NOTE: As per
/// Yisrael Vehazmanim Vol. III page 1028, No. 50, a dip of slightly
/// less than 13° should be used. Calculations show that the proper
/// dip to be 13.2456° (truncated to 13.24 that provides about 1.5
/// second earlier (*lechumra*) time) below the horizon at that time. This
/// makes a difference of 1 minute and 10 seconds in Jerusalem during the
/// Equinox, and 1 minute 29 seconds during the solstice as compared to the
/// proper 13.24° versus 13°. For NY during the solstice, the
/// difference is 1 minute 56 seconds.
#[must_use]
pub fn bein_hashmashos_rt_13_24_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(13.24))
}
/// Returns the beginning of *bein hashmashos* of Rabbeinu Tam
/// calculated as a 58.5-minute offset after sunset. *bein hashmashos* is
/// 3/4 of a mil before *tzeis* or 3 1/4 mil after sunset. With a mil
/// calculated as 18 minutes, 3.25 * 18 = 58.5 minutes.
#[must_use]
pub fn bein_hashmashos_rt_58_5_minutes(&self) -> Option<Zoned> {
self.tzeis(&Minutes(58.5))
}
/// Returns the beginning of *bein hashmashos* based on the
/// calculation of 13.5 minutes (3/4 of an 18-minute mil) before *shkiah*
/// calculated as 7.083°.
#[must_use]
pub fn bein_hashmashos_rt_13_5_minutes_before_7_083_degrees(&self) -> Option<Zoned> {
self.tzeis_geonim_7_083_degrees()?
.checked_sub(SignedDuration::from_secs(810))
.ok()
}
/// Returns the beginning of *bein hashmashos* of Rabbeinu Tam
/// calculated according to the opinion of the Divrei Yosef (see Yisrael
/// Vehazmanim) calculated 5/18th (27.77%) of the time between alos
/// (calculated as 19.8° before sunrise) and sunrise. This is added to
/// sunset to arrive at the time for *bein hashmashos* of Rabbeinu Tam.
#[must_use]
pub fn bein_hashmashos_rt_2_stars(&self) -> Option<Zoned> {
let sunrise = self.zmanim_sunrise()?;
let alos = self.alos_19_8_degrees()?;
self.zmanim_sunset()?
.checked_add(sunrise.duration_since(&alos) * 5 / 18)
.ok()
}
// Other tzeis
/// Returns the *tzeis hakochavim* (nightfall) based on the
/// opinion of the *Geonim* calculated at the sun's position at 3.7°
/// below the western horizon. This is a very early *zman* and should not be
/// relied on without Rabbinical guidance.
#[must_use]
pub fn tzeis_geonim_3_7_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(3.7))
}
/// Returns the *tzeis hakochavim* (nightfall) based on the
/// opinion of the *Geonim* calculated at the sun's position at 3.8°
/// below the western horizon. This is a very early *zman* and should not be
/// relied on without Rabbinical guidance.
#[must_use]
pub fn tzeis_geonim_3_8_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(3.8))
}
/// Returns the *tzeis hakochavim* (nightfall) based on the
/// opinion of the *Geonim* calculated as 3/4 of a *mil*, based on a
/// 22.5-minute *mil*, or 16 7/8 minutes. It is the sun's position at
/// 4.42° below the western horizon. This is a very early *zman* and
/// should not be relied on without Rabbinical guidance.
#[must_use]
pub fn tzeis_geonim_4_42_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(4.42))
}
/// Returns the *tzeis hakochavim* (nightfall) based on the
/// opinion of the *Geonim* calculated as 3/4 of a *mil* based on a
/// 24-minute *mil*, or 18 minutes. It is the sun's position at 4.66°
/// below the western horizon. This is a very early *zman* and should
/// not be relied on without Rabbinical guidance.
#[must_use]
pub fn tzeis_geonim_4_66_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(4.66))
}
/// Returns the *tzeis* (nightfall) based on the opinion of the
/// *Geonim* calculated as 3/4 of a *mil* based on the sun's position at
/// 4.8° below the western horizon. This is based on Rabbi Leo Levi's
/// calculations. This is a very early *zman* and should not be relied on
/// without Rabbinical guidance.
#[must_use]
pub fn tzeis_geonim_4_8_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(4.8))
}
/// Returns the *tzeis* (nightfall) based on the opinion of the
/// *Geonim* calculated at the sun's position at 5.95° below below
/// geometric zenith (90°), calculated as the position of the sun 24
/// minutes after sunset in Jerusalem around the equinox / equilux. The
/// 24 minutes is based on the *Baal Hatanya*'s calculation of 18
/// minutes (3/4 of a 24 minute *mil*) + 4 minutes for [*shkia
/// amiti*](ComplexZmanimCalendar::shkia_amiti_baal_hatanya) + 2 minutes for
/// *bein hashmashos* of Rav Yosi. See *Hazmanim Bahalacha* vol II, ch.
/// 50, no. 5, p. 512-513, ch. 47, and *Yisrael Vehazmanim* Vol III, ch.
/// 13, no. 53, p. 1026. Among sources he mentions for this zman is
/// Rabbi Yehuda (Leo) Levi's calculations in *Jewish Chrononomy* and
/// other sources. Calculations show that the time is closer to
/// 5.93° and was seemingly rounded to 5.95°. Chabad calendars
/// usually use the 6°-based
/// [`tzeis_baal_hatanya`](ComplexZmanimCalendar::tzeis_baal_hatanya)
/// that is built on this same calculation. It should be noted that Rabbi
/// Yedidya Manet in his *Zmanei HaHalacha Lema'aseh* (4th edition part 2,
/// pages and 22 and 24) lists 5.88° that appears to be a drop too
/// early.
#[must_use]
pub fn tzeis_geonim_5_95_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(5.95))
}
/// Returns the *tzeis* (nightfall) based on the opinion of the
/// *Geonim* as calculated by Rabbi Yechiel Michel Tucazinsky. It is based
/// on the position of the sun no later than 31 minutes after sunset
/// in Jerusalem at the height of the summer solstice and is 28 minutes
/// after *shkiah* around the equinox / equilux. This computes to 6.45°
/// below the western horizon.
#[must_use]
pub fn tzeis_geonim_6_45_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(6.45))
}
/// Returns the *tzeis hakochavim* (nightfall) based on the
/// opinion of the *Geonim* calculated when the sun's position 7.083°
/// (or 7° 5′) below the western horizon. This is often referred to
/// as 7°5' or 7° and 5 minutes. This calculation is based on
/// the observation of 3 medium-sized stars by Dr. Baruch (Berthold)
/// Cohn in his luach Tabellen enthaltend die Zeitangaben für den Beginn
/// der Nacht und des Tages für die Breitengrade + 66 bis -38 published
/// in Strasbourg, France in 1899. This calendar was very popular in
/// Europe, and many other calendars based their time on it. Rav Dovid
/// Tzvi Hoffman in his *Sh"Ut Melamed Leho'il* in an exchange of
/// letters with Baruch Cohn in *Orach Chaim* 30 agreed to this *zman*
/// (page 36), as did the *Sh"Ut Bnei Tziyon* and the *Tenuvas
/// Sadeh*. It is very close to the time of the *Mekor Chesed* of the *Sefer
/// chasidim*. It is close to the position of the sun 30 minutes after
/// sunset in Jerusalem around the equinox / equilux, but not Exactly. The
/// actual position of the sun 30 minutes after sunset in Jerusalem at the
/// equilux is 7.205° and 7.199° at the equinox. See *Hazmanim
/// Bahalacha* vol 2, pages 520-521 for more details.
#[must_use]
pub fn tzeis_geonim_7_083_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(7.0 + (5.0 / 60.0)))
}
/// Returns *tzeis* (nightfall) based on the opinion of the
/// Geonim calculated as 45 minutes after sunset during the summer solstice
/// in New York, when the *neshef* (twilight) is the longest. The sun's
/// position at this time computes to 7.75° below the western horizon.
/// See Igros Moshe Even Haezer 4, Ch. 4 (regarding *tzeis* for *krias
/// Shema*). It is also mentioned in Rabbi Heber's *Shaarei Zmanim* on in
/// chapter 10 (page 87) and chapter 12 (page 108). Also see the time of 45
/// minutes in Rabbi Simcha Bunim Cohen's The radiance of Shabbos as the
/// earliest *zman* for New York. This *zman* is also listed in the *Divrei
/// Shalom* Vol. III, chapter 75, and *Beis Av"i* Vol. III, chapter 117.
/// This *zman* is also listed in the *Divrei Shalom* etc. chapter 177.
/// Since this *zman* depends on the level of light, Rabbi Yaakov Shakow
/// presented this degree-based calculation to Rabbi Rabbi Shmuel
/// Kamenetsky who agreed to it.
#[must_use]
pub fn tzeis_geonim_7_67_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(7.67))
}
/// Returns *tzeis* (nightfall) when the sun is 8.5° below the geometric
/// horizon (90°) after sunset, a time that Rabbi Meir Posen in his the
/// *Ohr Meir* calculated that 3 small stars are visible, which is later
/// than the required 3 medium stars. This calculation is based on the sun's
/// position below the horizon 36 minutes after sunset in Jerusalem around
/// the equinox / equilux.
#[must_use]
pub fn tzeis_geonim_8_5_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(8.5))
}
/// Returns the *tzeis* (nightfall) based on the calculations
/// used in the *Luach Itim Lebinah* as the stringent time for *tzeis*. It
/// is calculated at the sun's position at 9.3° below the western
/// horizon.
#[must_use]
pub fn tzeis_geonim_9_3_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(9.3))
}
/// Returns the *tzeis* (nightfall) based on the opinion of the
/// *Geonim* calculated as 60 minutes after sunset around the equinox /
/// equilux, the day that a solar hour is 60 minutes in New York. The sun's
/// position at this time computes to 9.75° below the western horizon.
/// This is the opinion of Rabbi Eliyahu Henkin. This also follows the
/// opinion of Rabbi Shmuel Kamenetsky. Rabbi Yaakov Shakow presented
/// these degree-based times to Rabbi Shmuel Kamenetsky who agreed to
/// them.
#[must_use]
pub fn tzeis_geonim_9_75_degrees(&self) -> Option<Zoned> {
self.tzeis(&Degrees(9.75))
}
// Solar position / Polar regions
/// Returns the solar azimuth (in degrees, measured clockwise from due
/// north) of the sun at the given datetime for this location.
#[must_use]
pub fn solar_azimuth(&self, instant: &Zoned) -> f64 {
astronomical_calculator::solar_azimuth(instant, &self.geo_location)
}
/// Returns the solar elevation (in degrees) of the sun at the given
/// datetime for this location. The value is negative when the sun is below
/// the horizon, and is based on sea level (not adjusted for altitude).
#[must_use]
pub fn solar_elevation(&self, instant: &Zoned) -> f64 {
astronomical_calculator::solar_elevation(instant, &self.geo_location)
}
/// Returns the percentage of a *shaah zmanis* after sunset (when `sunset`
/// is `true`) or before sunrise (when `sunset` is `false`) for a given
/// `degrees` offset below the horizon.
///
/// For the equilux where there is a 720-minute day, passing 16.1° for
/// the location of Jerusalem will return about 1.2. This will work for any
/// location or date, but will typically only be of interest at the
/// equinox/equilux to calculate the percentage of a *shaah zmanis* for
/// those who want to use the *Minchas Cohen* in *Ma'amar* 2:4 and the *Pri
/// Chadash* who calculate *tzeis* as a percentage of the day after sunset.
/// While the *Minchas Cohen* only applies this to 72 minutes or a 1/10 of
/// the day around the world (based on the equinox / equilux in Israel),
/// this method allows calculations for any degree level for any location.
#[must_use]
pub fn percent_of_shaah_zmanis_from_degrees(&self, degrees: f64, sunset: bool) -> Option<f64> {
let sea_level_sunrise = self.sea_level_sunrise()?;
let sea_level_sunset = self.sea_level_sunset()?;
let twilight = if sunset {
self.tzeis(&Degrees(degrees))?
} else {
self.alos(&Degrees(degrees))?
};
let shaah_zmanis = sea_level_sunset
.duration_since(&sea_level_sunrise)
.as_secs_f64()
/ 12.0;
let rise_set_to_twilight = if sunset {
twilight.duration_since(&sea_level_sunset).as_secs_f64()
} else {
sea_level_sunrise.duration_since(&twilight).as_secs_f64()
};
Some(rise_set_to_twilight / shaah_zmanis)
}
}
/// When to use elevation for *zmanim* calculations. See
/// [`crate`] for details.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum UseElevation {
/// Never use elevation
No,
/// Only use elevation directly for *hanetz* and *shkia*
HanetzShkia,
/// Always use elevation
All,
}
impl UseElevation {
/// Convert the `UseElevation` into a `bool` for
/// [`zmanim_calculator`](crate::zmanim_calculator) functions. The param
/// `hanetz_or_shkia` should be `true` if the calling function is
/// calculating *hanetz* or *shkia*, and `false` otherwise
#[must_use]
pub const fn to_bool(self, hanetz_or_shkia: bool) -> bool {
match self {
Self::No => false,
Self::HanetzShkia => hanetz_or_shkia,
Self::All => true,
}
}
}