Documentation for libsunwait
This is a port to a C++ library of the sunwait executable (licencsed under
the GPLv3) written by Dan Risacher based on codes by Paul Schlyter and
with contributions of others mentioned in the original code
( https://github.com/risacher/sunwait )
It provide a class with functions to wait for sunrise and set, poll whether
it is day or night, list sunrise and set times. Instead of sunrise or set
corresponding twilight times can be considered, as well as times offset
by a fixed amount from any of these.
API of libsunwait
SunWait
-
class SunWait
Main class.
Calculate sunrise and sunset times for the current or targetted day. The times can be adjusted either for twilight or fixed durations.
The geographical coordinates should be set (e.g. via the constructor) and optionally the twilight angle and fixed offset can be specified.
There are functions for waiting for sunrise or sunset (wait) listing such event times (list and print_list) reporting the day length and twilight times (report) and reporting whether it is day or night (poll)
Public Functions
-
SunWait() = default
Construct a new SunWait object with default geographical coordinates and twilight angle.
-
inline SunWait(double lat, double lon)
Construct a new SunWait object with the requested geographical coordinates and the default twilight angle.
- Parameters
lat – Geographical latitude in decimal degrees (N positive, S negative)
lon – Geographical longitude in decimal degrees (E positive, W negative)
-
inline SunWait(const char *lat, const char *lon)
Construct a new SunWait object with the requested geographical coordinates and the default twilight angle.
With thise versions a char* is used and the library attempts to parse the information.
- Parameters
lat – Geographical latitude
lon – Geographical longitude
-
inline SunWait(double lat, double lon, double angle)
Construct a new SunWait object with the requested geographical coordinates and twilight angle.
- Parameters
lat – Geographical latitude in decimal degrees (N positive, S negative)
lon – Geographical longitude in decimal degrees (E positive, W negative)
angle – Twilight angle (in decimal degrees, negative for the Sun below horizon)
-
inline SunWait(const char *lat, const char *lon, double angle)
Construct a new SunWait object with the requested geographical coordinates and twilight angle.
With thise versions a char* is used and the library attempts to parse the information.
- Parameters
lat – Geographical latitude
lon – Geographical longitude
angle – Twilight angle (in decimal degrees, negative for the Sun below horizon)
-
void setCoordinates(double lat, double lon)
Update the geographical coordinates.
- Parameters
lat – Geographical latitude in decimal degrees (N positive, S negative)
lon – Geographical longitude in decimal degrees (E positive, S negative)
-
bool setCoordinates(const char *lat, const char *lon)
Update the geographical coordinates.
With thise versions a char* is used and the library attempts to parse the information.
- Parameters
lat – Geographical latitude
lon – Geographical longitude
- Returns
Return true when successful.
-
int poll(const time_t ttime = NOT_SET)
Poll whether it is day or night for a given time.
- Parameters
ttime – Time for the request (optional). By default the current time is used.
- Returns
Returns one if the return codes EXIT_DAY or EXIT_NIGHT
-
int wait(bool reportSunrise = true, bool reportSunset = true, unsigned long *waitptr = nullptr)
Sleep until specified event occurs (sun rise or sun set or either)
With a twilight angle and offset set, the corresponding event(s) will be queried.
- Parameters
reportSunrise – When true sun rises are considered
reportSunset – When true sun sets are considered
waitptr – When provided the wait time in seconds is written to the variable which is pointed to instead of waiting
- Returns
Returns EXIT_OK or EXIT_ERROR
-
void generate_report(int year = NOT_SET, int mon = NOT_SET, int mday = NOT_SET)
This replicates the generate report of the original sunwait command line executable.
A report contatining the day length and twilight timings for a given date (today by default) are printed to the standard output. Optionally the starting date can be given (year, month, day).
- Parameters
year – Specify the year
mon – Specify the month
mday – Specify the day
-
void print_list(const int days, int year = NOT_SET, int mon = NOT_SET, int mday = NOT_SET)
This replicates the list command of the original sunwait executable.
Prints the time (GMT or local) the event occurs for a given date (and a number of following days) to the standard output. Optionally the starting date can be given (year, month, day).
- Parameters
days – Number of days to report
year – Specify the year
mon – Specify the month
mday – Specify the day
-
std::pair<std::vector<time_t>, std::vector<time_t>> list(const int days, const int year, const int month, int day)
This will return a pair of vectors with the times (time_t) of requested events.
This is similar to the print_list function, but the returned times can easily be processed by the main program. If for any given day polar day or night apply, both event times are set to POLAR_DAY or POLAR_NIGHT, respectively. Optionally the starting date can be given (year, month, day).
- Parameters
days – Number of days to report
year – Specify the year
mon – Specify the month
mday – Specify the day
- Returns
std::pair<std::vector<time_t>, std::vector<time_t>>
Public Members
-
double offsetHour = NO_OFFSET
Adjust sunrise or sunset by this amount, in hours, towards midday. This allows to report time / wait until / etc that correspond to a given time before/after any event (such as 15 before sun rise).
-
double twilightAngle = TWILIGHT_ANGLE_DAYLIGHT
Twilight angle requested by user in degrees. Negative values are below the horizon. The default value is used for calculating sun rise and set taking into account standard refraction and the upper limb instead of the center of the sun.
-
bool utc = false
Printed output is in GMT/UTC (true) or localtime (false).
-
bool debug = false
When true, debug information is printed to the standard output.
-
SunWait() = default
Preprocessor defines
- group TwilightAngles
Defines for twilight angles.
long description
- group ReturnCodes
Defines for return codes.
long description
- group PolarDayNight
Defines for polar day and night in the list function.
long description