=pod

=encoding utf8

=head1 NAME

Muldis::D::Core::Temporal -
Muldis D operators for TAI temporal data types

=head1 VERSION

This document is Muldis::D::Core::Temporal version 0.106.0.

=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.  Moreover, you
should read the L<Muldis::D::Core> document before this current
document, as that forms its own tree beneath a root document branch.

=head1 DESCRIPTION

This document describes essentially all of the core Muldis D operators that
are specific to the core data types C<Instant> and C<Duration>, which
represent TAI temporal artifacts.

I<This documentation is pending.>

=head1 FUNCTIONS FOR TEMPORAL MATH

These functions implement commonly used temporal math operations.

=head1 Instant

=head2 sys.std.Core.Temporal.Instant.diff

C<< function sys.std.Core.Temporal.Instant.diff (Duration <--
$minuend : Instant, $subtrahend : Instant) >>

This function results in the duration-typed difference when its
instant-typed C<subtrahend> argument is subtracted from its instant-typed
C<minuend> argument.  The result is the amount of time between the 2
arguments, which may be positive or negative depending on which argument
was earlier.

=head2 sys.std.Core.Temporal.Instant.abs_diff

C<< function sys.std.Core.Temporal.Instant.abs_diff (Duration <--
$topic : Instant, $other : Instant) >>

This symmetric function results in the absolute difference between its 2
arguments.  The result is the amount of time between the 2 arguments, which
is always non-negative.

=head2 sys.std.Core.Temporal.Instant.later

C<< function sys.std.Core.Temporal.Instant.later (Instant <--
$instant : Instant, $duration : Duration) >>

This function results in the instant that is later than its C<instant>
argument by the amount of time in the C<duration> argument.

=head2 sys.std.Core.Temporal.Instant.earlier

C<< function sys.std.Core.Temporal.Instant.earlier (Instant <--
$instant : Instant, $duration : Duration) >>

This function results in the instant that is earlier than its C<instant>
argument by the amount of time in the C<duration> argument.

=head1 Duration

=head2 sys.std.Core.Temporal.Duration.abs

C<< function sys.std.Core.Temporal.Duration.abs (Duration <--
$topic : Duration) >>

This function results in the absolute value of its argument.

=head2 sys.std.Core.Temporal.Duration.sum

C<< function sys.std.Core.Temporal.Duration.sum (Duration <--
$topic? : bag_of.Duration) >>

This function results in the sum of the N element values of its argument;
it is a reduction operator that recursively takes each pair of input values
and adds (which is both commutative and associative) them together until
just one is left, which is the result.  If C<topic> has zero values, then
C<sum> results in the duration zero, which is the identity value for
addition.

=head2 sys.std.Core.Temporal.Duration.diff

C<< function sys.std.Core.Temporal.Duration.diff (Duration <--
$minuend : Duration, $subtrahend : Duration) >>

This function results in the difference when its C<subtrahend> argument is
subtracted from its C<minuend> argument.

=head1 SYSTEM-SERVICES FOR CURRENT DATES AND TIMES

These system-service routines provide ways to get the current date or time
from the system.

=head2 sys.std.Core.Temporal.Instant.fetch_curr_instant

C<system-service sys.std.Core.Temporal.Instant.fetch_curr_instant
(&$target : Instant)>

This system-service routine will update the variable supplied as its
C<target> argument so that it holds the value of the current TAI instant as
taken with the full precision that the implementation's system clock or
used time server supports.

=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<darren@DarrenDuncan.net>)

=head1 LICENSE AND COPYRIGHT

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

Muldis D is Copyright © 2002-2010, Muldis Data Systems, Inc.

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
