NAME

Time::UTC::Segment - segments of UTC definition

SYNOPSIS

        use Time::UTC::Segment;

        $seg = Time::UTC::Segment->start;

        $tai = $seg->start_tai_instant;
        $tai = $seg->end_tai_instant;
        $len = $seg->length_in_tai_seconds;

        $day = $seg->start_utc_day;
        $day = $seg->last_utc_day;
        $day = $seg->end_utc_day;

        $len = $seg->utc_second_length;
        $secs = $seg->leap_utc_seconds;

        $secs = $seg->last_day_utc_seconds;
        $secs = $seg->length_in_utc_seconds;

        $seg = $seg->prev;
        $seg = $seg->next;

        if($seg->complete_p) { ...
        $seg->when_complete(\&do_stuff);

DESCRIPTION

An object of this class represents a segment of the definition of UTC in terms of TAI. Each segment is a period of time over which the relation between UTC and TAI is stable. Each point where the relation changes is a boundary between segments.

Each segment consists of an integral number of consecutive UTC days. Within each segment, the length of the UTC second is fixed relative to the TAI second. Also, every UTC day in the segment except for the last one contains exactly 86400 UTC seconds. The last day of a segment commonly has some other length.

Because UTC is only defined a few months ahead, the description of UTC that is available at any particular time is necessarily incomplete. Nevertheless, this API gives the superficial appearance of completeness. The information-querying methods will die if asked for information that is not yet available. There are additional methods to probe the availability of information.

CONSTRUCTOR

Objects of this class are not created by users, but are generated internally. New segments appear when updated UTC data is downloaded; this is done automatically as required. Segments are accessed from each other by means of the next and prev methods.

Time::UTC::Segment->start

Returns the first segment of the UTC description.

METHODS

Information querying

Most methods merely query the segment data. The data are strictly read-only.

The methods will die if information is requested that is not available. This happens when looking further ahead than UTC has been defined. UTC is defined only a few months in advance.

All numeric values are returned as Math::BigRat objects.

$seg->start_tai_instant

The instant at which this segment starts, in TAI form: a Math::BigRat giving the number of TAI seconds since the TAI epoch.

$seg->end_tai_instant

The instant at which this segment ends, in TAI form: a Math::BigRat giving the number of TAI seconds since the TAI epoch.

$seg->length_in_tai_seconds

The duration of this segment, measured in TAI seconds, as a Math::BigRat.

$seg->start_utc_day

The first UTC day of this segment: a Math::BigInt giving the number of days since the TAI epoch.

$seg->last_utc_day

The last UTC day of this segment: a Math::BigInt giving the number of days since the TAI epoch.

$seg->end_utc_day

The first UTC day after the end of this segment: a Math::BigInt giving the number of days since the TAI epoch.

$seg->utc_second_length

The length of the UTC second in this segment, measured in TAI seconds, as a Math::BigRat.

$seg->leap_utc_seconds

The number of extra UTC seconds inserted at the end of the last day of this segment, as a Math::BigRat. May be negative.

$seg->last_day_utc_seconds

The number of UTC seconds in the last day of this segment, as a Math::BigRat.

$seg->length_in_utc_seconds

The duration of this segment, measured in UTC seconds, as a Math::BigRat.

$seg->prev

The immediately preceding segment. undef if there is no preceding segment, because this segment covers the start of UTC service at the beginning of 1961.

$seg->next

The immediately following segment. In the event that UTC ever becomes fully defined, either by being defined for the entire future or by being withdrawn altogether, there will be a final segment for which this will be undef.

Completeness

Segments can be classified as "complete" and "incomplete". For complete segments, all information-querying methods give answers. For incomplete segments, only a few data are available: the methods start_tai_instant, start_utc_day, utc_second_length, and prev will give correct answers, but other methods will die.

An incomplete segment can become complete, as new information becomes available, when updated UTC data is (automatically) downloaded. When this happens, the resulting complete segment cannot be distinguished from any other complete segment.

Only one incomplete segment exists at a time.

$seg->complete_p

Returns a boolean indicating whether the segment is currently complete.

$seg->when_complete(WHAT)

WHAT must be a reference to a function which takes no arguments. When the segment is complete, the function will be called. If the segment is already complete then the function is called immediately; otherwise the function is noted and will be called when the segment becomes complete due to the availability of new information.

This is a one-shot operation. To do something similar for all segments, see foreach_utc_segment_when_complete in Time::UTC.

INVARIANTS

The following relations hold for all segments:

        $seg->length_in_tai_seconds ==
                $seg->end_tai_instant - $seg->start_tai_instant

        $seg->last_utc_day + 1 == $seg->end_utc_day

        $seg->last_day_utc_seconds == 86400 + $seg->leap_utc_seconds

        $seg->length_in_utc_seconds ==
                86400 * ($seg->last_utc_day - $seg->start_utc_day) +
                        $seg->last_day_utc_seconds

        $seg->length_in_tai_seconds ==
                $seg->length_in_utc_seconds * $seg->utc_second_length

        $seg->next->prev == $seg

        $seg->end_tai_instant == $seg->next->start_tai_instant

        $seg->end_utc_day == $seg->next->start_utc_day

SEE ALSO

Time::UTC

AUTHOR

Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

Copyright (C) 2005, 2006, 2007 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Time::UTC

perl -MCPAN -e shell
install Time::UTC