=pod

=encoding utf8

=head1 NAME

Muldis::D::Ext::Temporal -
Muldis D extension for temporal data types and operators

=head1 VERSION

This document is Muldis::D::Ext::Temporal version 0.7.1.

=head1 PREFACE

This document is part of the Muldis D language specification, whose root
document is L<Muldis::D>; you should read that root document
before you read this one, which provides subservient details.

=head1 DESCRIPTION

Muldis D has a mandatory core set of system-defined (eternally available)
entities, which is referred to as the I<Muldis D core> or the I<core>; they
are the minimal entities that all Muldis D implementations need to provide;
they are mutually self-describing and are used to bootstrap the language;
any entities outside the core, called I<Muldis D extensions>, are
non-mandatory and are defined in terms of the core or each other, but the
reverse isn't true.

This current C<Temporal> document describes the system-defined I<Muldis D
Temporal Extension>, which consists of temporal data types and operators,
particularly durations and dates or times.

This current document does not describe the polymorphic operators that all
types, or some types including core types, have defined over them; said
operators are defined once for all types in L<Muldis::D::Core>.

I<This documentation is pending.>

=head1 TYPE SUMMARY

Following are all the data types described in this document, arranged in a
type graph according to their proper sub|supertype relationships (but that
the first 3 just reappear from the core set to provide a similar context,
and aren't re-described here):

    sys.std.Core.Type.Universal

        sys.std.Core.Type.Empty

        sys.std.Core.Type.Scalar

            # The following are all regular ordered scalar types.

            sys.std.Temporal.Type.DateTimeWithTZ
            sys.std.Temporal.Type.DateWithTZ
            sys.std.Temporal.Type.TimeWithTZ
            sys.std.Temporal.Type.DurationWithTZ
            sys.std.Temporal.Type.DurationOfDaysWithTZ
            sys.std.Temporal.Type.DateTimeNoTZ
            sys.std.Temporal.Type.DateNoTZ
            sys.std.Temporal.Type.TimeNoTZ
            sys.std.Temporal.Type.DurationNoTZ
            sys.std.Temporal.Type.DurationOfDaysNoTZ

I<This documentation is pending.>

=head1 SYSTEM-DEFINED TEMPORAL SCALAR DATA TYPES

These non-core scalar data types describe common kinds of temporal
artifacts according to modern calendars.  They come in a variety of
precisions and epochs so that users can pick one that most accurately
represents what they actually know about their data.  I<Of course, dealing
with these types in general isn't a perfect science; they stand to be
revised or rewritten.>

=over

=item C<sys.std.Temporal.Type.DateTimeWithTZ>

A C<DateTimeWithTZ> is a single specific time on a specific date, with
precision to arbitrary fractions of a second.  It I<does> incorporate an
explicit terrestrial time-zone offset (relative to UTC), so you use it when
you I<do know> the time-zone and it is significant (which is usually).  It
is conceptually calendar-agnostic.  The default value of
C<DateTimeWithTZ> is the Perl 6 epoch, namely 2000-1-1T0:0:0 in the
Gregorian calendar, with a time-zone offset of zero.  This type's minimum
and maximum values are some kind of infinities.  The cardinality of this
type is infinity; to define a most-generalized finite C<DateTimeWithTZ>
subtype, you must specify the earliest and latest datetimes it includes,
and also its least magnitude fraction of a second.

=item C<sys.std.Temporal.Type.DateWithTZ>

A C<DateWithTZ> is the same as C<DateTimeWithTZ> in all respects but
that its precision is only to the whole terrestrial day.  Its default value
is 2000-1-1 in the Gregorian calendar.  The cardinality of this type is
infinity; to define a most-generalized finite C<DateWithTZ> subtype, you
must specify the earliest and latest dates it includes.

=item C<sys.std.Temporal.Type.TimeWithTZ>

A C<TimeWithTZ> is a single specific time that isn't on any day in
particular, and isn't part of any calendar in particular, with a precision
to arbitrary fractions of a second; its allowed range is between zero
seconds (inclusive) and 1 terrestrial day (exclusive).  It does incorporate
an explicit time-zone offset interval as per C<DateTimeWithTZ>.  Its
default and minimum value is 0:0:0; its maximum value is 1 terrestrial day
in actuality, due to rounding from something slightly less than that.  The
cardinality of this type is infinity; to define a most-generalized finite
C<TimeWithTZ> subtype, you must specify its least magnitude fraction of
a second.

=item C<sys.std.Temporal.Type.DurationWithTZ>

A C<DurationWithTZ> is a single amount of time, with precision to
arbitrary fractions of a second.  It is not fixed to any date or time and
is agnostic to the calendar.  It is the result type of taking the
difference between two C<DateTimeWithTZ> values, and is likewise assumed
to be as unambiguous as when you know the time-zone offsets are known.  Its
default value is zero; its minimum and maximum values are some kind of
infinities.  The cardinality of this type is infinity; to define a
most-generalized finite C<DurationWithTZ> subtype, you must specify the
minimum and maximum amount of time that its values may be, plus the
granularity of the type in fractions of a second.

=item C<sys.std.Temporal.Type.DurationOfDaysWithTZ>

A C<DurationOfDaysWithTZ> is the same as C<DurationWithTZ> in all
respects but that its precision is only to the whole terrestrial day.  The
cardinality of this type is infinity; to define a most-generalized finite
C<DurationOfDaysWithTZ> subtype, you must specify the minimum and
maximum amount of time that its values may be.

=item C<sys.std.Temporal.Type.DateTimeNoTZ>

A C<DateTimeNoTZ> is the same as C<DateTimeWithTZ> in its
precision, but it I<does not> incorporate an explicit terrestrial time-zone
offset interval, and so it is conceptually ambiguous within an interval of
about 25 hours; you use it when you I<do not know> the time-zone or it is
not significant (which is not usually).  Its default value is
2000-1-1T0:0:0 in the Gregorian calendar.  Matters of its cardinality are
the same as for C<DateTimeWithTZ>.

=item C<sys.std.Temporal.Type.DateNoTZ>

A C<DateNoTZ> is the same as C<DateWithTZ> in all respects but
that its differences correspond to the differences between
C<DateTimeWithTZ> and C<DateTimeNoTZ>.  Matters of its
cardinality are the same as for C<DateWithTZ>.

=item C<sys.std.Temporal.Type.TimeNoTZ>

A C<TimeNoTZ> is the same as C<TimeWithTZ> in all respects but
that its differences correspond to the differences between
C<DateTimeWithTZ> and C<DateTimeNoTZ>.  Matters of its
cardinality are the same as for C<TimeWithTZ>.

=item C<sys.std.Temporal.Type.DurationNoTZ>

A C<DurationNoTZ> is the same as C<DurationWithTZ> in all
respects but that it is considered ambiguous within a 50 hour interval, and
it is the result type of taking the difference between two
C<DateTimeNoTZ> values.  Matters of its cardinality are the same
as for C<DurationWithTZ>.

=item C<sys.std.Temporal.Type.DurationOfDaysNoTZ>

A C<DurationOfDaysNoTZ> is to C<DurationOfDaysWithTZ> what
C<DurationNoTZ> is to C<DurationWithTZ>.

=back

=head1 SEE ALSO

Go to L<Muldis::D> for the majority of distribution-internal
references, and L<Muldis::D::SeeAlso> for the majority of
distribution-external references.

=head1 AUTHOR

Darren Duncan (C<perl@DarrenDuncan.net>)

=head1 LICENSE AND COPYRIGHT

This file is part of the formal specification of the Muldis D language.

Muldis D is Copyright © 2002-2008, Darren Duncan.

See the LICENSE AND COPYRIGHT of L<Muldis::D> for details.

=head1 TRADEMARK POLICY

The TRADEMARK POLICY in L<Muldis::D> applies to this file too.

=head1 ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in L<Muldis::D> apply to this file too.

=cut