Skip to content

Improve sunrise/set method names #254

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
KosherJava merged 6 commits into from
Mar 16, 2026
Merged

Improve sunrise/set method names #254

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
dba0923
Migrate AstronomicalCalendar to use LocalDate - Fix Timezone Bug - Us…
dickermoshe Mar 16, 2026
0375dfe
Fix Javadocs
dickermoshe Mar 16, 2026
0f99d98
Rename getSunrise to getSunriseWithElevation.
dickermoshe Mar 16, 2026
9ccc41b
Merge branch '3-0-modernization' into 3-0-modernization
dickermoshe Mar 16, 2026
baaaba5
Rename getElevationAdjustedSunset/rise to avoid further confusion.
dickermoshe Mar 16, 2026
897072e
Merge branch '3-0-modernization' of http://github.com/dickermoshe/zma…
dickermoshe Mar 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 70 additions & 27 deletions src/main/java/com/kosherjava/zmanim/AstronomicalCalendar.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,15 +23,13 @@
import java.time.LocalTime;
import java.time.ZoneOffset;
import java.time.ZonedDateTime;
import java.time.temporal.ChronoUnit;
import java.util.TimeZone;

import com.kosherjava.zmanim.util.AstronomicalCalculator;
import com.kosherjava.zmanim.util.GeoLocation;
import com.kosherjava.zmanim.util.ZmanimFormatter;

/**
* A Java calendar that calculates astronomical times such as {@link #getSunrise() sunrise}, {@link #getSunset()
* A Java calendar that calculates astronomical times such as {@link #getSunriseWithElevation() sunrise}, {@link #getSunsetWithElevation()
* sunset} and twilight times. This class contains a {@link #getLocalDate() zonedDateTime} and can therefore use the standard
* Calendar functionality to change dates etc. The calculation engine used to calculate the astronomical times can be
* changed to a different implementation by implementing the abstract {@link AstronomicalCalculator} and setting it with
Expand Down Expand Up @@ -112,7 +110,7 @@ public class AstronomicalCalendar implements Cloneable {
private AstronomicalCalculator astronomicalCalculator;

/**
* The getSunrise method returns a <code>Instant</code> representing the
* The getSunriseWithElevation method returns a <code>Instant</code> representing the
* {@link AstronomicalCalculator#getElevationAdjustment(double) elevation adjusted} sunrise time. The zenith used
* for the calculation uses {@link #GEOMETRIC_ZENITH geometric zenith} of 90&deg; plus
* {@link AstronomicalCalculator#getElevationAdjustment(double)}. This is adjusted by the
Expand All @@ -127,14 +125,36 @@ public class AstronomicalCalendar implements Cloneable {
* @see #getSeaLevelSunrise()
* @see AstronomicalCalendar#getUTCSunrise
*/
public Instant getSunrise() {
public Instant getSunriseWithElevation() {
double sunrise = getUTCSunrise(GEOMETRIC_ZENITH);
if (Double.isNaN(sunrise)) {
return null;
} else {
return getInstantFromTime(sunrise, SolarEvent.SUNRISE);
}
}
/**
* @deprecated Use {@link #getSunriseWithElevation()} instead.
* This method already accounts for the observer's elevation, but the name
* does not clearly indicate this behavior. The replacement method has a
* clearer and more descriptive name.
*
* @return the <code>Instant</code> representing the exact sunrise time. If the calculation can't be computed such as
* in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it
* does not set, a <code>null</code> will be returned. See detailed explanation on top of the page.
* @see AstronomicalCalculator#adjustZenith
* @see #getSeaLevelSunrise()
* @see AstronomicalCalendar#getUTCSunrise
*/
@Deprecated(forRemoval = false)
public Instant getSunrise() {
double sunrise = getUTCSunrise(GEOMETRIC_ZENITH);
if (Double.isNaN(sunrise)) {
return null;
} else {
return getInstantFromTime(sunrise, SolarEvent.SUNRISE);
}
}

/**
* A method that returns the sunrise without {@link AstronomicalCalculator#getElevationAdjustment(double) elevation
Expand All @@ -145,7 +165,7 @@ public Instant getSunrise() {
* @return the <code>Instant</code> representing the exact sea-level sunrise time. If the calculation can't be computed
* such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one
* where it does not set, a <code>null</code> will be returned. See detailed explanation on top of the page.
* @see AstronomicalCalendar#getSunrise
* @see AstronomicalCalendar#getSunriseWithElevation
* @see AstronomicalCalendar#getUTCSeaLevelSunrise
* @see #getSeaLevelSunset()
*/
Expand Down Expand Up @@ -196,25 +216,48 @@ public Instant getBeginAstronomicalTwilight() {
return getSunriseOffsetByDegrees(ASTRONOMICAL_ZENITH);
}

/**
* The getSunsetWithElevation method returns a <code>Instant</code> representing the
* {@link AstronomicalCalculator#getElevationAdjustment(double) elevation adjusted} sunset time. The zenith used for
* the calculation uses {@link #GEOMETRIC_ZENITH geometric zenith} of 90&deg; plus
* {@link AstronomicalCalculator#getElevationAdjustment(double)}. This is adjusted by the
* {@link AstronomicalCalculator} to add approximately 50/60 of a degree to account for 34 archminutes of refraction
* and 16 archminutes for the sun's radius for a total of {@link AstronomicalCalculator#adjustZenith 90.83333&deg;}.
* See documentation for the specific implementation of the {@link AstronomicalCalculator} that you are using. Note:
* In certain cases the calculates sunset will occur before sunrise. This will typically happen when a timezone
* other than the local timezone is used (calculating Los Angeles sunset using a GMT timezone for example). In this
* case the sunset date will be incremented to the following date.
*
* @return the <code>Instant</code> representing the exact sunset time. If the calculation can't be computed such as in
* the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it
* does not set, a <code>null</code> will be returned. See detailed explanation on top of the page.
* @see AstronomicalCalculator#adjustZenith
* @see #getSeaLevelSunset()
* @see AstronomicalCalendar#getUTCSunset
*/
public Instant getSunsetWithElevation() {
double sunset = getUTCSunset(GEOMETRIC_ZENITH);
if (Double.isNaN(sunset)) {
return null;
} else {
return getInstantFromTime(sunset, SolarEvent.SUNSET);
}
}

/**
* The getSunset method returns a <code>Instant</code> representing the
* {@link AstronomicalCalculator#getElevationAdjustment(double) elevation adjusted} sunset time. The zenith used for
* the calculation uses {@link #GEOMETRIC_ZENITH geometric zenith} of 90&deg; plus
* {@link AstronomicalCalculator#getElevationAdjustment(double)}. This is adjusted by the
* {@link AstronomicalCalculator} to add approximately 50/60 of a degree to account for 34 archminutes of refraction
* and 16 archminutes for the sun's radius for a total of {@link AstronomicalCalculator#adjustZenith 90.83333&deg;}.
* See documentation for the specific implementation of the {@link AstronomicalCalculator} that you are using. Note:
* In certain cases the calculates sunset will occur before sunrise. This will typically happen when a timezone
* other than the local timezone is used (calculating Los Angeles sunset using a GMT timezone for example). In this
* case the sunset date will be incremented to the following date.
*
* @deprecated Use {@link #getSunsetWithElevation()} instead.
* This method already accounts for the observer's elevation, but its name
* does not clearly reflect that behavior. The replacement method provides
* a more accurate and descriptive name.
*
* @return the <code>Instant</code> representing the exact sunset time. If the calculation can't be computed such as in
* the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it
* does not set, a <code>null</code> will be returned. See detailed explanation on top of the page.
* @see AstronomicalCalculator#adjustZenith
* @see #getSeaLevelSunset()
* @see AstronomicalCalendar#getUTCSunset
*/
@Deprecated(forRemoval = false)
public Instant getSunset() {
double sunset = getUTCSunset(GEOMETRIC_ZENITH);
if (Double.isNaN(sunset)) {
Expand All @@ -233,9 +276,9 @@ public Instant getSunset() {
* @return the <code>Instant</code> representing the exact sea-level sunset time. If the calculation can't be computed
* such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one
* where it does not set, a <code>null</code> will be returned. See detailed explanation on top of the page.
* @see AstronomicalCalendar#getSunset
* @see AstronomicalCalendar#getSunsetWithElevation
* @see AstronomicalCalendar#getUTCSeaLevelSunset
* @see #getSunset()
* @see #getSunsetWithElevation()
*/
public Instant getSeaLevelSunset() {
double sunset = getUTCSeaLevelSunset(GEOMETRIC_ZENITH);
Expand Down Expand Up @@ -317,15 +360,15 @@ public static Instant getTimeOffset(Instant time, long offsetMillis) {

/**
* A utility method that returns the time of an offset by degrees below or above the horizon of
* {@link #getSunrise() sunrise}. Note that the degree offset is from the vertical, so for a calculation of 14&deg;
* {@link #getSunriseWithElevation() sunrise}. Note that the degree offset is from the vertical, so for a calculation of 14&deg;
* before sunrise, an offset of 14 + {@link #GEOMETRIC_ZENITH} = 104 would have to be passed as a parameter.
*
* @param offsetZenith
* the degrees before {@link #getSunrise()} to use in the calculation. For time after sunrise use
* the degrees before {@link #getSunriseWithElevation()} to use in the calculation. For time after sunrise use
* negative numbers. Note that the degree offset is from the vertical, so for a calculation of 14&deg;
* before sunrise, an offset of 14 + {@link #GEOMETRIC_ZENITH} = 104 would have to be passed as a
* parameter.
* @return The {@link java.time.Instant} of the offset after (or before) {@link #getSunrise()}. If the calculation
* @return The {@link java.time.Instant} of the offset after (or before) {@link #getSunriseWithElevation()}. If the calculation
* can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does
* not rise, and one where it does not set, a <code>null</code> will be returned. See detailed explanation
* on top of the page.
Expand All @@ -337,15 +380,15 @@ public Instant getSunriseOffsetByDegrees(double offsetZenith) {
}

/**
* A utility method that returns the time of an offset by degrees below or above the horizon of {@link #getSunset()
* A utility method that returns the time of an offset by degrees below or above the horizon of {@link #getSunsetWithElevation()
* sunset}. Note that the degree offset is from the vertical, so for a calculation of 14&deg; after sunset, an
* offset of 14 + {@link #GEOMETRIC_ZENITH} = 104 would have to be passed as a parameter.
*
* @param offsetZenith
* the degrees after {@link #getSunset()} to use in the calculation. For time before sunset use negative
* the degrees after {@link #getSunsetWithElevation()} to use in the calculation. For time before sunset use negative
* numbers. Note that the degree offset is from the vertical, so for a calculation of 14&deg; after
* sunset, an offset of 14 + {@link #GEOMETRIC_ZENITH} = 104 would have to be passed as a parameter.
* @return The {@link java.time.Instant} of the offset after (or before) {@link #getSunset()}. If the calculation can't
* @return The {@link java.time.Instant} of the offset after (or before) {@link #getSunsetWithElevation()}. If the calculation can't
* be computed such as in the Arctic Circle where there is at least one day a year where the sun does not
* rise, and one where it does not set, a <code>null</code> will be returned. See detailed explanation on
* top of the page.
Expand Down Expand Up @@ -466,8 +509,8 @@ public long getTemporalHour() {
/**
* A utility method that will allow the calculation of a temporal (solar) hour based on the sunrise and sunset
* passed as parameters to this method. An example of the use of this method would be the calculation of a
* elevation adjusted temporal hour by passing in {@link #getSunrise() sunrise} and
* {@link #getSunset() sunset} as parameters.
* elevation adjusted temporal hour by passing in {@link #getSunriseWithElevation() sunrise} and
* {@link #getSunsetWithElevation() sunset} as parameters.
*
* @param startOfDay
* The start of the day.
Expand Down
Loading
Loading