/ 
Time-Keeper-Sun-0.02
/ Time::Keeper::Sun::Day

NAME

Time::Keeper::Sun::Day - the sun's events on one civil day at a place

VERSION

Version 0.02

SYNOPSIS

my $day = $sun->on(year => 2026, month => 10, day => 15);

$day->sunrise;  $day->sunset;                  # Time::Keeper values, or undef
$day->dawn;  $day->dusk(kind => 'nautical');   # civil unless told
$day->solar_noon;  $day->solar_midnight;
$day->day_length;                              # a Time::Keeper::Duration, or undef
$day->is_polar_day;  $day->is_polar_night;
$day->sunrises;  $day->sunsets;                # all of them
$day->events;                                  # ([name, value], ...) in order

DESCRIPTION

What "on" in Time::Keeper::Sun gives: the moments the sun rose, set, reached its height and passed through the twilights on one civil day in the place's zone. A day runs from the midnight the zone had to the next; it is 23, 24 or 25 hours long where the clocks change, and it holds whatever crossings fall in it, which can be none or two of a kind. See "THE DAY" in Time::Keeper::Sun.

Every value is in the place's zone and locale and is rounded to the whole second.

METHODS

date

The day, as a Time::Keeper::Date.

place

The Time::Keeper::Sun place the day was computed for.

zone_name

The zone's name.

start

end

The window's edges as values: the local midnight the day began at, and the one it ends before.

sunrise

sunset

The first sunrise or sunset in the day, or undef when there is none: the sun's upper limb at the horizon seen from the place's elevation.

solar_noon

solar_midnight

The sun's upper and lower transits in the day, or undef.

dawn

dusk

$day->dawn;                          # civil: the sun six degrees down
$day->dusk(kind => 'nautical');      # twelve
$day->dawn(kind => 'astronomical');  # eighteen

The beginning and the end of a twilight, or undef.

sunrises

sunsets

solar_noons

solar_midnights

dawns

dusks

Every event of the kind in the day, in order, as a list: empty, one, or two.

events

Every event of the day in order of time, each a reference to a two-element array of the event's name and its value. The names are sunrise, sunset, civil_dawn, civil_dusk, nautical_dawn, nautical_dusk, astronomical_dawn, astronomical_dusk, solar_noon and solar_midnight.

day_length

The day's first sunrise to the sunset that follows it, wherever that falls, as a Time::Keeper::Duration; the whole window when the sun is up all day; undef when there is no sunrise, or no sunset after it.

is_polar_day

is_polar_night

True when the sun neither rose nor set in the window and was above the horizon all through it, or below it. They speak of the sun's horizon only: a polar night can still have a civil dawn and dusk.

AUTHOR

LNATION, <email at lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)