File indexing completed on 2024-03-24 15:28:59

0001 /*
0002     This file is part of the kholidays library.
0003 
0004     SPDX-FileCopyrightText: 2012 Allen Winter <winter@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-or-later
0007 */
0008 
0009 #ifndef KHOLIDAYS_SUNRISESET_H
0010 #define KHOLIDAYS_SUNRISESET_H
0011 
0012 #include "kholidays_export.h"
0013 #include <QTime>
0014 
0015 namespace KHolidays
0016 {
0017 /**
0018   @brief
0019   Methods for determining the sunrise and sunset times for a given date and Earth location.
0020 */
0021 
0022 namespace SunRiseSet
0023 {
0024 /**
0025   Compute the sunrise time (UTC) for a date and Earth location.
0026   @param date is any valid QDate.
0027   @param latitude is a floating point representing a valid latitude (-90.0, 90.0)
0028   @param longitude is a floating point representing a valid longitude (-180.0, 180.0)
0029   @return the QTime of the sunrise in UTC.
0030 
0031   @note the latitude and longitude are truncated as needed to fit into their proper range.
0032 
0033 */
0034 KHOLIDAYS_EXPORT QTime utcSunrise(const QDate &date, double latitude, double longitude);
0035 
0036 /**
0037   Compute the sunset time (UTC) for a date and Earth location.
0038   @param date is any valid QDate.
0039   @param latitude is a floating point representing a valid latitude (-90.0, 90.0)
0040   @param longitude is a floating point representing a valid longitude (-180.0, 180.0)
0041   @return the QTime of the sunset in UTC.
0042 
0043   @note the latitude and longitude are truncated as needed to fit into their proper range.
0044 */
0045 KHOLIDAYS_EXPORT QTime utcSunset(const QDate &date, double latitude, double longitude);
0046 
0047 /**
0048   Compute the civil dawn time (UTC) for a date and Earth location.
0049   @param date is any valid QDate.
0050   @param latitude is a floating point representing a valid latitude (-90.0, 90.0)
0051   @param longitude is a floating point representing a valid longitude (-180.0, 180.0)
0052   @see https://en.wikipedia.org/wiki/Twilight
0053   @return the QTime of the sunrise in UTC.
0054 
0055   @note the latitude and longitude are truncated as needed to fit into their proper range.
0056   @since 5.77
0057 */
0058 KHOLIDAYS_EXPORT QTime utcDawn(const QDate &date, double latitude, double longitude);
0059 
0060 /**
0061   Compute the civil dawn time (UTC) for a date and Earth location.
0062   @param date is any valid QDate.
0063   @param latitude is a floating point representing a valid latitude (-90.0, 90.0)
0064   @param longitude is a floating point representing a valid longitude (-180.0, 180.0)
0065   @see https://en.wikipedia.org/wiki/Twilight
0066   @return the QTime of the sunset in UTC.
0067 
0068   @note the latitude and longitude are truncated as needed to fit into their proper range.
0069   @since 5.77
0070 */
0071 KHOLIDAYS_EXPORT QTime utcDusk(const QDate &date, double latitude, double longitude);
0072 
0073 /**
0074   Checks whether it is polar day on day @p date at @p latitude.
0075   That is, the sun stays above -0.83° relative to the horizon at all times.
0076   Both sunrise/sunset and dawn/dusk times will be invalid for such a day.
0077   @param latitude in degree (-90.0, 90.0)
0078   @see isPolarNight(), isPolarTwilight()
0079   @see https://en.wikipedia.org/wiki/Midnight_sun
0080 
0081   @since 5.97
0082 */
0083 KHOLIDAYS_EXPORT bool isPolarDay(const QDate &date, double latitude);
0084 
0085 /**
0086   Checks whether it is polar twilight on day @p date at @p latitude.
0087   That is, the sun rises at least above -6° relative the horizon during the day,
0088   but remains below -0.83° at all times. Sunrise/sunset times will be invalid
0089   for such a day, but dawn/dusk times will be available.
0090   @param latitude in degree (-90.0, 90.0)
0091   @see isPolarDay(), isPolarNight()
0092   @see https://en.wikipedia.org/wiki/Polar_night
0093 
0094   @since 5.97
0095 */
0096 KHOLIDAYS_EXPORT bool isPolarTwilight(const QDate &date, double latitude);
0097 
0098 /**
0099   Checks whether it is polar night on day @p date at @p latitude.
0100   That is, the sun stays below -6° relative to the horizon at all times.
0101   Both sunrise/sunset and dawn/dusk times will be invalid for such a day.
0102   @param latitude in degree (-90.0, 90.0)
0103   @see isPolarDay(), isPolarTwilight()
0104   @see https://en.wikipedia.org/wiki/Polar_night
0105 
0106   @since 5.97
0107 */
0108 KHOLIDAYS_EXPORT bool isPolarNight(const QDate &date, double latitude);
0109 }
0110 
0111 }
0112 
0113 #endif