NAME
Muldis::D::Manual::TemporalExtras - Legacy temporal data types, operators, and syntax removed from Muldis D
VERSION
This document is Muldis::D::Manual::TemporalExtras version 0.6.1.
PREFACE
This document is part of the Muldis D language and implementations manual, whose root document is Muldis::D::Manual; you should read that root document before you read this one, which provides subservient details.
DESCRIPTION
The Muldis D language specification included a collection of non-mixin types and/or non-virtual operators from its first released version 0.0.0 (on 2007-06-20) through version 0.120.0 (on 2010-04-23), which generally denoted temporal artifacts in terms of Gregorian year-month-day-hour-minute-second units; during that period the collection was rewritten or substantially altered a small number of times. Then, with version 0.121.0 (on 2010-04-24), these were entirely purged from the Muldis D language specification. The primary reason for this action is that details of the Gregorian calendar et al are too complicated and too subject to change to define in a core programming language spec, and are best left to separate modules; and even if not, the existing such types needed a huge refactor anyway.
The remainder of this document contains the bulk of the purged temporal material as they were in the spec version 0.120.0; this document preserves that material in order to provide a resource for any future third-party efforts to provide temporal non-mixin types and/or non-virtual operators for Muldis D, such that these might best be provided as user-defined materials rather than being built-in to the language. Alternately, such a derived effort may appear in the form of one or more official Muldis D language extensions that are not Muldis::D::Ext::Temporal.
The material of the following sections were originally published in these 4 member documents of the Muldis D language specification, which still exist sans said material: Muldis::D::Ext::Temporal, Muldis::D::Dialect::PTMD_STD, Muldis::D::Dialect::HDMD_Perl6_STD, Muldis::D::Dialect::HDMD_Perl5_STD.
LEGACY DESCRIPTION
This current Temporal
document describes the system-defined Muldis D Temporal Extension, which consists of temporal data types and operators, particularly calendar dates and intervals. The bundled data types describe common kinds of temporal artifacts according to modern calendars. They can represent a variety of precisions and epochs so that users can employ them in a way that most accurately represents what they actually know about their data. Any types whose names start with TAI
are TAI temporal artifacts expressed simply as a count of seconds from a TAI epoch, and any whose names start with UTC
or Float
are based on year-month-day-hour-minute-second components in the Gregorian calendar, either the UTC time zone or a "floating" time zone.
The Muldis D Temporal Extension is expressly not meant to be complete by any means, as a solution for working with temporal data. Rather it is meant to be "good enough" for many common uses. Moreover it isn't intended to have a scope much greater than the temporal data handling abilities of the ISO/IEC 9075 (SQL) standard and the Perl DateTime module. In many situations, users may be better off ignoring this extension, and using Muldis D's core facilities for user-defined types and routines, and code an alternate temporal data solution that works best for them, building over Muldis D's basic integer or such types, or alternately using third-party Muldis D temporal extensions. This current extension exists primarily to ease the porting of SQL databases to Muldis D, and save users accustomed to SQL's facilities and the Perl DateTime module's facilities from having to frequently reinvent the wheel. The details of this Muldis D extension are typically just the same as those in ISO/IEC 9075 (SQL) section "4.6 Datetimes and intervals", but with some alterations. As with SQL and DateTime, dates and times are specified as YYYY.MM.DD.HH.II.SS+ in the proleptic Gregorian calendar, specifically the version with a year zero and negative year numbers, either in the UTC time-zone or floating / no-zone. Matters of "local time" or specifications of other time-zones or daylight savings time are not supported for encoding into values, due partly to various logical problems and complexity such as an inability to distinguish between duplicated times of day around a daylight savings adjustment. If you want to work with "local time", you generally will have to convert to UTC on input and from UTC on output with the Muldis D Temporal Extension; UTC is better for storage, local is maybe better for display.
Now the general practice of working with calendar-centric temporal data is an imperfect process and can not be done with perfect mathematical precision. This is partly because our temporal data in general comes from measurements of environmental cycles (such as rotations of the Earth, revolutions of the Earth's moon around it, and revolutions of the Earth around its sun), which not only are rounded approximations, but we also know for a fact that the actual amount of time these events takes slowly varies over time (such as that the rotation of the Earth is gradually slowing as the moon gradually drifts away from it each year). Also our typical calendaring systems change over time, sometimes to deal with our improved ability to measure the environmental cycles or compensate for drift; witness for example a large part of the world's moving from the Julian to the Gregorian calendar. So the best we have to work with in general will involve rounding, and sometimes a conceptually commutative or associative sequence of operations on temporal data may not yield an identical result from identical inputs when the operations are rearranged into a conceptually equivalent but different form; a simple example being adding or subtracting dates. All the issues can be complicated.
TYPE SUMMARY
Following are all the data types described in this document, arranged in a type graph according to their proper sub|supertype relationships:
sys.std.Core.Type.Universal
sys.std.Core.Type.Scalar
sys.std.Core.Type.DHScalar
sys.std.Core.Type.Int
sys.std.Core.Type.NNInt
sys.std.Core.Type.PInt
sys.std.Temporal.Type.PInt[12|31]
sys.std.Temporal.Type.NNInt[23|59]
sys.std.Core.Type.Cat.DHScalarWP
sys.std.Core.Type.Rat
sys.std.Core.Type.NNRat
sys.std.Temporal.Type.NNRatLT62
# The following are all regular ordered scalar types.
sys.std.Temporal.Type.TAIInstant
sys.std.Temporal.Type.TAIDuration
sys.std.Temporal.Type.UTCInstant
sys.std.Temporal.Type.UTCDateTime
sys.std.Temporal.Type.UTCDate
sys.std.Temporal.Type.UTCTime
sys.std.Temporal.Type.FloatInstant
sys.std.Temporal.Type.FloatDateTime
sys.std.Temporal.Type.FloatDate
sys.std.Temporal.Type.FloatTime
sys.std.Temporal.Type.UTCDuration
This graph slice shows all of the temporal types that compose any mixin types, shown grouped under the mixin types that they compose:
sys.std.Core.Type.Universal
sys.std.Core.Type.Ordered
sys.std.Temporal.Type.TAIInstant
sys.std.Temporal.Type.TAIDuration
sys.std.Temporal.Type.UTCInstant
sys.std.Temporal.Type.FloatInstant
sys.std.Temporal.Type.UTCDuration
sys.std.Temporal.Type.Instant
sys.std.Temporal.Type.TAIInstant
sys.std.Temporal.Type.UTCInstant
sys.std.Temporal.Type.FloatInstant
sys.std.Temporal.Type.Duration
sys.std.Temporal.Type.TAIDuration
sys.std.Temporal.Type.UTCDuration
DATA TYPES FOR TEMPORAL ARTIFACTS
These non-core data types are all ordered scalar types.
sys.std.Temporal.Type.PInt[12|31]
PInt[12|31]
is a proper subtype of PInt
where all member values are not greater than 12|31. Its default and minimum value is 1; its maximum value is 12|31. The significance is that in proleptic Gregorian dates, the [month|month-day] portion is a positive integer not greater than 12|31.
sys.std.Temporal.Type.NNInt[23|59]
NNInt[23|59]
is a proper subtype of NNInt
where all member values are not greater than 23|59. Its default and minimum value is 0; its maximum value is 23|59. The significance is that in the time portion of proleptic Gregorian dates, the [hour|minute] portion is a non-negative integer not greater than 23|59.
sys.std.Temporal.Type.NNRatLT62
NNRatLT62
is a proper subtype of NNRat
where all member values are less than 62. Its default and minimum value is 0; its maximum value is conceptually infinitessimally less than 62 and practically impossible. The significance is that in the time portion of proleptic Gregorian dates, the 'second' portion is a non-negative rational less than 62. The cardinality of this type is infinity; to define a most-generalized finite NNRatLT62
subtype, you must specify the greatest magnitude value denominator of its ratio
possrep, that is, its maximum precision (that denominator is 10^9 if we're working to nanosecond precision).
sys.std.Temporal.Type.TAIInstant
A TAIInstant
is a single point in time which is specified with arbitrary precision in terms of atomic seconds with fractions. That is, a TAIInstant
is defined as a point on the canonical continuous timeline of International Atomic Time (TAI; this is a perfectly linear scale with no discontinuities), specified by a scalar number of TAI seconds since the TAI epoch, which is exactly midnight at the start of January 1st of the year 1958 CE. The TAIInstant
type explicitly composes the Instant
mixin type.
A TAIInstant
has 1 system-defined possrep named tai_instant
which consists of 1 Rat
-typed attribute named seconds
. The TAIInstant
type explicitly composes the Ordered
mixin type. A TAIInstant
is a simple wrapper for a Rat
and all of its other details such as default and minimum and maximum values and cardinality and default ordering algorithm all correspond directly. But TAIInstant
is explicitly disjoint from Rat
due to having a different intended interpretation.
The TAIInstant
type is intended more for use with system event time-stamps or sensitive scientific applications and is not necessarily the best choice for common human-specified temporal artifacts according to various calendars, since there is no fixed conversion rate between them in the general case that includes future dates, and also calendar-based artifacts may be very non-specific; see also the UTCInstant
data type, which is defined in terms of calendars.
sys.std.Temporal.Type.TAIDuration
A TAIDuration
is a single amount of time, which is specified with arbitrary precision in terms of the same units as a TAIInstant
is structured with. A TAIDuration
is not fixed to any point in time. A TAIDuration
is the result type of taking the difference between two TAIInstant
values, but it is not defined in terms of said two values. The TAIDuration
type explicitly composes the Duration
mixin type. A TAIDuration
has 1 system-defined possrep named tai_duration
which consists of 1 Rat
-typed attribute named seconds
. The TAIDuration
type explicitly composes the Ordered
mixin type. A TAIDuration
is a simple wrapper for a Rat
in all ways as per TAIInstant
. But TAIDuration
is explicitly disjoint from TAIInstant
due to having a different intended interpretation. The TAIDuration
type is intended more for benchmarking or scientific applications and is not intended for human-specified calendar based artifacts; again see the UTCDuration
data type for alternatives.
sys.std.Temporal.Type.UTCInstant
A UTCInstant
is a single point in time, or a periodic multiplicity of points in time, which is specified with arbitrary precision using a set of unit quantities involving multiple units, where the units do not generally have a fixed conversion rate with each other. The UTCInstant
type explicitly composes the Instant
mixin type. A UTCInstant
is defined against the proleptic Gregorian calendar and uses these 6 units: terrestrial year, month within year, day within month, hour within day, minute within hour, second and possibly fraction of a second within minute; the only fixed conversion rates are: 1 year is 12 months, 1 hour is 60 minutes. A UTCInstant
is defined against the UTC time-zone specifically, so you use it when you do know that the instant you are specifying was experienced in the UTC time-zone with the specified unit values; if you are otherwise working according to your local time-zone, you would be selecting your UTCInstant
values in terms of a time-zone offset (and daylight-savings time offset if applicable) from your local time.
A UTCInstant
has 1 system-defined possrep whose name is instant
, which has 6 attributes: year
(a maybe_of.Int
), month
(a maybe_of.PInt12
), day
(a maybe_of.PInt31
), hour
(a maybe_of.NNInt23
), minute
(a maybe_of.NNInt59
), second
(a maybe_of.NNRatLT62
). For each attribute, that attribute should be a Single
if a quanity in that unit is known, and it should be Nothing
if there is no applicable or known quantity in that unit. The year
values greater than zero are CE, those less than zero are BCE. The month
value 1
corresponds to the month of January, and 12
corresponds to the month of December. The value of day
is further restricted depending on the combined values of year
and month
, such that all 3 together may only represent a valid date of the proleptic Gregorian calendar (taking into account leap-days); so for example you can't select April 31st or February 30th. The value of second
is further restricted as per day
, as leap-seconds are only valid on certain days, and perhaps only when the hour-minute is 23-59. These further restrictions do not apply if any of the attributes needed to calculate whether they apply are Nothing
.
The default value of UTCInstant
is exactly midnight at the start of January 1st of the year 1 CE (which also happens to be the proleptic Gregorian calendar's epoch); its minimum and maximum values are conceptually infinities and practically impossible. The cardinality of this type is infinity; to define a most-generalized finite UTCInstant
subtype, you must specify the earliest and latest dates it includes (minimally, the earliest and latest year
), as well as the granularity of the type as a fraction of a second (minimally, the largest value denominator for second
).
The UTCInstant
type explicitly composes the Ordered
mixin type. The UTCInstant
type has a default ordering algorithm; for 2 distinct UTCInstant
values, the earlier value is ordered before the later value. To make full ordering of UTCInstant
values possible and deterministic (though semi-meaningless) in the face of unknown/inapplicable attributes; the algorithm works like this: 1. ordering is done numerically one attribute at a time, from the largest units to the smallest; 2. for each attribute, the Nothing
value will order before any Single
value.
sys.std.Temporal.Type.UTCDateTime
A UTCDateTime
is a single specific time on a specific date, with precision to arbitrary fractions of a second. A UTCDateTime
is a proper subtype of UTCInstant
where all 6 attributes of its instant
possrep have Single
/ known values. A UTCDateTime
adds 1 system-defined possrep whose name is datetime
, which has 6 attributes: year
(an Int
), month
(a PInt12
), day
(a PInt31
), hour
(a NNInt23
), minute
(a NNInt59
), second
(a NNRatLT62
). The default and minimum and maximum values are the same as for UTCInstant
.
sys.std.Temporal.Type.UTCDate
A UTCDate
is a single specific terrestrial day, at no particular time of day. A UTCDate
is a proper subtype of UTCInstant
where the 3 attributes of its instant
possrep named [year
, month
, day
] have Single
/ known values, and the other 3 instant
possrep attributes each have the Nothing
/ unknown value. A UTCDate
adds 1 system-defined possrep whose name is date
, which has 3 attributes: year
(an Int
), month
(a PInt12
), day
(a PInt31
). The default value of UTCDate
is January 1st of the year 1 CE; its minimum and maximum values are conceptually infinities and practically impossible. The cardinality of this type is infinity; to define a most-generalized finite UTCDate
subtype, you must specify the earliest and latest dates it includes (minimally, the earliest and latest year
).
sys.std.Temporal.Type.UTCTime
A UTCTime
is a single specific time that isn't on any day in particular (or alternately that is repeating on multiple days), with a precision to arbitrary fractions of a second; its allowed range is between zero seconds (inclusive) and 1 terrestrial day (exclusive). A UTCTime
is a proper subtype of UTCInstant
where the 3 attributes of its instant
possrep named [hour
, minute
, second
] have Single
/ known values, and the other 3 instant
possrep attributes each have the Nothing
/ unknown value. A UTCTime
adds 1 system-defined possrep whose name is time
, which has 3 attributes: hour
(a NNInt23
), minute
(a NNInt59
), second
(a NNRatLT62
). The default and minimum value of UTCTime
is exactly midnight at the start of its day (all of its time
possrep attributes are zero-valued); its maximum value is conceptually infinitessimally less than the midnight at the end of its day and practically impossible. The cardinality of this type is infinity; to define a most-generalized finite UTCTime
subtype, you must specify the granularity of the type as a fraction of a second (minimally, the largest value denominator for second
).
sys.std.Temporal.Type.FloatInstant
A FloatInstant
is exactly the same as UTCInstant
, but that it is not defined against any specific time-zone, but rather is floating; you use it when you do not know in what time-zone the specified date+time is supposed to refer to (it was just somewhere), or when that detail is not significant. The FloatInstant
type explicitly composes the Instant
mixin type. The FloatInstant
type explicitly composes the Ordered
mixin type. The FloatInstant
type is disjoint from the UTCInstant
type, but all of its details save its name and one aspect of its interpretation (representation, cardinality, default values, ordering algorithm, etc) are identical.
sys.std.Temporal.Type.FloatDateTime
FloatDateTime
is to UTCDateTime
as FloatInstant
is to UTCInstant
.
sys.std.Temporal.Type.FloatDate
FloatDate
is to UTCDate
as FloatInstant
is to UTCInstant
.
sys.std.Temporal.Type.FloatTime
FloatTime
is to UTCTime
as FloatInstant
is to UTCInstant
.
sys.std.Temporal.Type.UTCDuration
A UTCDuration
is a single amount of time, which is specified with arbitrary precision using 6 quantities in the same units as a UTCInstant
is structured with. It is not fixed to any date or time and is agnostic to the calendar, other than the interpretation of units' size. A UTCDuration
is the result type of taking the difference between two UTCInstant
values or between two FloatInstant
values, but it is not defined in terms of said two values. The UTCDuration
type explicitly composes the Duration
mixin type.
A UTCDuration
has 1 system-defined possrep whose name is duration
, which has 6 attributes: years
, months
, days
, hours
, minutes
, (all 5 each a maybe_of.Int
), seconds
(a maybe_of.Rat
). Each attribute value is Nothing
when it is unknown or not applicable, and a Single
when it is known and applicable, as per a UTCInstant
.
The default value of UTCDuration
is zero; its minimum and maximum values are conceptually infinities and practically impossible. The cardinality of this type is infinity; to define a most-generalized finite UTCDuration
subtype, you must specify the maximum amount of time that its values may be, plus the granularity of the type in fractions of a second; in other words, you specify seconds
as per a Rat
and the other attributes as per Int
.
The UTCDuration
type explicitly composes the Ordered
mixin type. The UTCDuration
type has a default ordering algorithm which is structurally the same as for UTCInstant
: 1. ordering is done numerically one attribute at a time, from the largest units to the smallest; 2. for each attribute, the Nothing
value will order before any Single
value. However, because the unit values are unconstrained, this algorithm will sort [0 months and 40 days] before [1 month and 0 days] even though common sense says the second should be before the first. So for ordering to make sense, either in general leave all attributes Nothing
except one (recommended), or otherwise be careful to just set compatible attribute values.
FUNCTIONS IMPLEMENTING VIRTUAL ORDERED FUNCTIONS
sys.std.Temporal.TAIInstant.order
function sys.std.Temporal.TAIInstant.order (Order <-- $topic : TAIInstant, $other : TAIInstant, $misc_args? : Tuple, $is_reverse_order? : Bool) implements sys.std.Core.Ordered.order {...}
This is a (total) order-determination
function specific to TAIInstant
.
sys.std.Temporal.TAIDuration.order
function sys.std.Temporal.TAIDuration.order (Order <-- $topic : TAIDuration, $other : TAIDuration, $misc_args? : Tuple, $is_reverse_order? : Bool) implements sys.std.Core.Ordered.order {...}
This is a (total) order-determination
function specific to TAIDuration
.
sys.std.Temporal.UTCInstant.order
function sys.std.Temporal.UTCInstant.order (Order <-- $topic : UTCInstant, $other : UTCInstant, $misc_args? : Tuple, $is_reverse_order? : Bool) implements sys.std.Core.Ordered.order {...}
This is a (total) order-determination
function specific to UTCInstant
.
sys.std.Temporal.FloatInstant.order
function sys.std.Temporal.FloatInstant.order (Order <-- $topic : FloatInstant, $other : FloatInstant, $misc_args? : Tuple, $is_reverse_order? : Bool) implements sys.std.Core.Ordered.order {...}
This is a (total) order-determination
function specific to FloatInstant
.
sys.std.Temporal.UTCDuration.order
function sys.std.Temporal.UTCDuration.order (Order <-- $topic : UTCDuration, $other : UTCDuration, $misc_args? : Tuple, $is_reverse_order? : Bool) implements sys.std.Core.Ordered.order {...}
This is a (total) order-determination
function specific to UTCDuration
.
FUNCTIONS IMPLEMENTING VIRTUAL INSTANT FUNCTIONS
TAIInstant
sys.std.Temporal.TAIInstant.diff
function sys.std.Temporal.TAIInstant.diff (TAIDuration <-- $minuend : TAIInstant, $subtrahend : TAIInstant) implements sys.std.Temporal.Instant.diff {...}
This function results in the duration-typed difference when its instant-typed subtrahend
argument is subtracted from its instant-typed 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.
sys.std.Temporal.TAIInstant.abs_diff
function sys.std.Temporal.TAIInstant.abs_diff (TAIDuration <-- $topic : TAIInstant, $other : TAIInstant) implements sys.std.Temporal.Instant.abs_diff {...}
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.
sys.std.Temporal.TAIInstant.later
function sys.std.Temporal.TAIInstant.later (TAIInstant <-- $instant : TAIInstant, $duration : TAIDuration) implements sys.std.Temporal.Instant.later {...}
This function results in the instant that is later than its instant
argument by the amount of time in the duration
argument.
sys.std.Temporal.TAIInstant.earlier
function sys.std.Temporal.TAIInstant.earlier (TAIInstant <-- $instant : TAIInstant, $duration : TAIDuration) implements sys.std.Temporal.Instant.earlier {...}
This function results in the instant that is earlier than its instant
argument by the amount of time in the duration
argument.
UTCInstant
sys.std.Temporal.UTCInstant.diff
function sys.std.Temporal.UTCInstant.diff (UTCDuration <-- $minuend : UTCInstant, $subtrahend : UTCInstant) implements sys.std.Temporal.Instant.diff {...}
This function results in the duration-typed difference when its instant-typed subtrahend
argument is subtracted from its instant-typed 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.
sys.std.Temporal.UTCInstant.abs_diff
function sys.std.Temporal.UTCInstant.abs_diff (UTCDuration <-- $topic : UTCInstant, $other : UTCInstant) implements sys.std.Temporal.Instant.abs_diff {...}
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.
sys.std.Temporal.UTCInstant.later
function sys.std.Temporal.UTCInstant.later (UTCInstant <-- $instant : UTCInstant, $duration : UTCDuration) implements sys.std.Temporal.Instant.later {...}
This function results in the instant that is later than its instant
argument by the amount of time in the duration
argument.
sys.std.Temporal.UTCInstant.earlier
function sys.std.Temporal.UTCInstant.earlier (UTCInstant <-- $instant : UTCInstant, $duration : UTCDuration) implements sys.std.Temporal.Instant.earlier {...}
This function results in the instant that is earlier than its instant
argument by the amount of time in the duration
argument.
FloatInstant
sys.std.Temporal.FloatInstant.diff
function sys.std.Temporal.FloatInstant.diff (UTCDuration <-- $minuend : FloatInstant, $subtrahend : FloatInstant) implements sys.std.Temporal.Instant.diff {...}
This function results in the duration-typed difference when its instant-typed subtrahend
argument is subtracted from its instant-typed 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.
sys.std.Temporal.FloatInstant.abs_diff
function sys.std.Temporal.FloatInstant.abs_diff (UTCDuration <-- $topic : FloatInstant, $other : FloatInstant) implements sys.std.Temporal.Instant.abs_diff {...}
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.
sys.std.Temporal.FloatInstant.later
function sys.std.Temporal.FloatInstant.later (FloatInstant <-- $instant : FloatInstant, $duration : UTCDuration) implements sys.std.Temporal.Instant.later {...}
This function results in the instant that is later than its instant
argument by the amount of time in the duration
argument.
sys.std.Temporal.FloatInstant.earlier
function sys.std.Temporal.FloatInstant.earlier (FloatInstant <-- $instant : FloatInstant, $duration : UTCDuration) implements sys.std.Temporal.Instant.earlier {...}
This function results in the instant that is earlier than its instant
argument by the amount of time in the duration
argument.
FUNCTIONS IMPLEMENTING VIRTUAL DURATION FUNCTIONS
TAIDuration
sys.std.Temporal.TAIDuration.abs
function sys.std.Temporal.TAIDuration.abs (TAIDuration <-- $topic : TAIDuration) implements sys.std.Temporal.Duration.abs {...}
This function results in the absolute value of its argument.
sys.std.Temporal.TAIDuration.sum
function sys.std.Temporal.TAIDuration.sum (TAIDuration <-- $topic? : bag_of.TAIDuration) implements sys.std.Temporal.Duration.sum {...}
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 topic
has zero values, then sum
results in the duration zero, which is the identity value for addition.
sys.std.Temporal.TAIDuration.diff
function sys.std.Temporal.TAIDuration.diff (TAIDuration <-- $minuend : TAIDuration, $subtrahend : TAIDuration) implements sys.std.Temporal.Duration.diff {...}
This function results in the difference when its subtrahend
argument is subtracted from its minuend
argument.
sys.std.Temporal.TAIDuration.abs_diff
function sys.std.Temporal.TAIDuration.abs_diff (TAIDuration <-- $topic : TAIDuration, $other : TAIDuration) implements sys.std.Temporal.Duration.abs_diff {...}
This symmetric function results in the absolute difference between its 2 arguments.
UTCDuration
Note that all inter-duration operators in general will just do the math on each corresponding attribute individually and not normalize between attributes. This is subject to be revised in the future.
sys.std.Temporal.UTCDuration.abs
function sys.std.Temporal.UTCDuration.abs (UTCDuration <-- $topic : UTCDuration) implements sys.std.Temporal.Duration.abs {...}
This function results in the absolute value of its argument.
sys.std.Temporal.UTCDuration.sum
function sys.std.Temporal.UTCDuration.sum (UTCDuration <-- $topic? : bag_of.UTCDuration) implements sys.std.Temporal.Duration.sum {...}
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 topic
has zero values, then sum
results in the duration zero, which is the identity value for addition.
sys.std.Temporal.UTCDuration.diff
function sys.std.Temporal.UTCDuration.diff (UTCDuration <-- $minuend : UTCDuration, $subtrahend : UTCDuration) implements sys.std.Temporal.Duration.diff {...}
This function results in the difference when its subtrahend
argument is subtracted from its minuend
argument.
sys.std.Temporal.UTCDuration.abs_diff
function sys.std.Temporal.UTCDuration.abs_diff (UTCDuration <-- $topic : UTCDuration, $other : UTCDuration) implements sys.std.Temporal.Duration.abs_diff {...}
This symmetric function results in the absolute difference between its 2 arguments.
FUNCTIONS FOR CONVERSION BETWEEN UTC AND TAI
These functions convert between UTCDateTime
values and equal or nearly equal TAIInstant
values. WARNING: These functions may not produce consistent results over time when dealing with future dates because it is unknown in advance when leap seconds will be added to the UTC time scale, and TAI has no leap seconds.
sys.std.Temporal.UTCInstant.UTC_from_TAI
function sys.std.Temporal.UTCInstant.UTC_from_TAI (UTCDateTime <-- $tai : TAIInstant) {...}
This selector function results in the UTCDateTime
value that is conceptually equal to its TAIInstant
argument, insofar as relevant leap seconds are known.
sys.std.Temporal.UTCInstant.TAI_from_UTC
function sys.std.Temporal.UTCInstant.TAI_from_UTC (TAIInstant <-- $utc : UTCDateTime) {...}
This selector function results in the TAIInstant
value that is conceptually equal to its UTCDateTime
argument, insofar as relevant leap seconds are known.
SYSTEM-SERVICES IMPLEMENTING VIRTUALS FOR CURRENT DATES AND TIMES
These system-service routines provide ways to get the current date or time from the system.
sys.std.Temporal.TAIInstant.fetch_curr_instant
system-service sys.std.Temporal.TAIInstant.fetch_curr_instant (&$target : TAIInstant) implements sys.std.Temporal.Instant.fetch_curr_instant {...}
This system-service routine will update the variable supplied as its 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.
sys.std.Temporal.UTCInstant.fetch_curr_datetime
system-service sys.std.Temporal.UTCInstant.fetch_curr_datetime (&$target : UTCDateTime) implements sys.std.Temporal.Instant.fetch_curr_instant {...}
This system-service routine will update the variable supplied as its target
argument so that it holds the value of the current UTC date and time (YMDHIS) as taken with the full precision that the implementation's system clock or used time server supports.
sys.std.Temporal.UTCInstant.fetch_curr_date
system-service sys.std.Temporal.UTCInstant.fetch_curr_date (&$target : UTCDate) implements sys.std.Temporal.Instant.fetch_curr_instant {...}
This system-service routine is the same as sys.std.Temporal.UTCInstant.fetch_curr_date
except that it only produces an instant value with the date (YMD) attributes set.
sys.std.Temporal.UTCInstant.fetch_curr_time
system-service sys.std.Temporal.UTCInstant.fetch_curr_time (&$target : UTCTime) implements sys.std.Temporal.Instant.fetch_curr_instant {...}
This system-service routine is the same as sys.std.Temporal.UTCInstant.fetch_curr_date
except that it only produces an instant value with the time (HIS) attributes set; it still retains the full precision.
sys.std.Temporal.FloatInstant.fetch_curr_datetime
system-service sys.std.Temporal.FloatInstant.fetch_curr_datetime (&$target : FloatDateTime) implements sys.std.Temporal.Instant.fetch_curr_instant {...}
This system-service routine will update the variable supplied as its target
argument so that it holds the value of the current floating date and time (YMDHIS) as taken with the full precision that the implementation's system clock or used time server supports.
sys.std.Temporal.FloatInstant.fetch_curr_date
system-service sys.std.Temporal.FloatInstant.fetch_curr_date (&$target : FloatDate) implements sys.std.Temporal.Instant.fetch_curr_instant {...}
This system-service routine is the same as sys.std.Temporal.FloatInstant.fetch_curr_date
except that it only produces an instant value with the date (YMD) attributes set.
sys.std.Temporal.FloatInstant.fetch_curr_time
system-service sys.std.Temporal.FloatInstant.fetch_curr_time (&$target : FloatTime) implements sys.std.Temporal.Instant.fetch_curr_instant {...}
This system-service routine is the same as sys.std.Temporal.FloatInstant.fetch_curr_date
except that it only produces an instant value with the time (HIS) attributes set; it still retains the full precision.
FOR ALL 3 STD - STANDARD SYNTAX EXTENSIONS
The standard_syntax_extensions
pragma declares which optional portions of the Muldis D grammar a programmer may employ with their Muldis D code.
There is currently 1 specified standard syntax extension: temporal
. These are all mutually independent and any or all may be used at once.
temporal
The temporal
standard syntax extension is closely related to the Muldis::D::Ext::Temporal language extension, and it constitutes special syntax for its data types; in the future it may improve the type syntax or add syntax for operators.
When the standard_syntax_extensions
pragma includes temporal
in its list, then the following grammar extensions are in effect:
<value__code_as_data> ::=
...
| <value__sse_temporal>
<value_kind> ::=
...
| <value_kind__sse_temporal>
<value_payload> ::=
...
| <value_payload__sse_temporal>
PTMD_STD - TEMPORAL EXTENSION OPAQUE VALUE LITERALS
The temporal
standard syntax extension is closely related to the Muldis::D::Ext::Temporal language extension, and it constitutes special syntax for its data types; in the future it may improve the type syntax or add syntax for operators.
Grammar:
<value__sse_temporal> ::=
...
| <TAIInstant>
| <TAIDuration>
| <UTCInstant>
| <FloatInstant>
| <UTCDuration>
<value_kind__sse_temporal> ::=
...
| TAIInstant
| TAIDuration
| UTC [Instant | DateTime | Date | Time]
| Float [Instant | DateTime | Date | Time]
| UTCDuration
<value_payload__sse_temporal> ::=
...
| <TAIInstant_payload>
| <TAIDuration_payload>
| <UTCInstant_payload>
| <FloatInstant_payload>
| <UTCDuration_payload>
PTMD_STD - Date and Time Literals
Grammar:
<TAIInstant> ::=
TAIInstant ':' <unspace>
[<type_name> ':' <unspace>]?
<TAIInstant_payload>
<TAIInstant_payload> ::=
<Rat_payload>
<TAIDuration> ::=
TAIDuration ':' <unspace>
[<type_name> ':' <unspace>]?
<TAIDuration_payload>
<TAIDuration_payload> ::=
<Rat_payload>
<UTCInstant> ::=
UTC [Instant | DateTime | Date | Time] ':' <unspace>
[<type_name> ':' <unspace>]?
<UTCInstant_payload>
<UTCInstant_payload> ::=
<UTCDuration_payload>
<FloatInstant> ::=
Float [Instant | DateTime | Date | Time] ':' <unspace>
[<type_name> ':' <unspace>]?
<FloatInstant_payload>
<FloatInstant_payload> ::=
<UTCDuration_payload>
<UTCDuration> ::=
UTCDuration ':' <unspace>
[<type_name> ':' <unspace>]?
<UTCDuration_payload>
<UTCDuration_payload> ::=
<num_max_col_val> ';' <unspace> <utc_duration_body>
| <d_utc_duration_body>
<utc_duration_body> ::=
'[' <ws>?
[<int_body>? [<ws>? ',' <ws>?]] ** 5
<ws>? ',' <ws>? <rat_body>?
<ws>? ']'
<d_utc_duration_body> ::=
'[' <ws>?
[<d_int_body>? [<ws>? ',' <ws>?]] ** 5
<ws>? ',' <ws>? <d_rat_body>?
<ws>? ']'
A TAIInstant
node represents a single point in time which is specified in terms of atomic seconds; it is a rational numeric type, that is disjoint from both Rat
and TAIDuration
. This node is interpreted as a Muldis D sys.std.Temporal.Type.TAIInstant
value as follows: A TAIInstant_payload
is formatted and interpreted in the same way as a Rat_payload
.
A TAIDuration
node represents a single amount of time (the difference between two instants) which is specified in terms of atomic seconds; it is a rational numeric type, that is disjoint from both Rat
and TAIInstant
. This node is interpreted as a Muldis D sys.std.Temporal.Type.TAIDuration
value as follows: A TAIDuration_payload
is formatted and interpreted in the same way as a Rat_payload
.
A UTCInstant
node represents an "instant"/"datetime" value that is affiliated with the UTC time-zone. This node is interpreted as a Muldis D sys.std.Temporal.Type.UTCInstant
value whose instant
possrep attribute values are defined as follows:
A UTCInstant_payload
consists mainly of a bracket-delimited sequence of 6 comma-separated elements, where each element is either a valid numeric literal or is completely absent. The 6 elements correspond in order to the 6 attributes: year
, month
, day
, hour
, minute
, second
. For each element that is absent or defined, the corresponding attribute has the Nothing
or a Single
value, respectively. For each of the first 5 elements, when it is defined, it must qualify as a valid body part of an Int
node; for the 6th element, when it is defined, it must qualify as a valid body part of a Rat
node.
Fundamentally each UTCInstant
node element is formatted and interpreted like an Int
or Rat
node, and any similarities won't be repeated here.
A defined year
may be any integer, each of [month
, day
] must be a positive integer, each of [hour
, minute
] must be a non-negative integer, and second
must be a non-negative rational number. If all 6 attributes are defined, then the new UTCInstant
value is also a UTCDateTime
; if just the first 3 or last 3 are defined, then the value is not a UTCDateTime
but rather a UTCDate
or UTCTime
, respectively; if any other combination of attributes are defined, then the value is just a UTCInstant
and not of any of the other 3 subtypes.
If the value_kind
of a value
node is UTCDateTime
or UTCDate
or UTCTime
rather than UTCInstant
, then the value
node is interpreted simply as a UTCInstant
node whose type_name
is UTCDateTime
or UTCDate
or UTCTime
, and the allowed body is appropriately further restricted.
A FloatInstant
node represents an "instant"/"datetime" value that is "floating" / not affiliated with any time-zone. This node is interpreted as a Muldis D sys.std.Temporal.Type.FloatInstant
value in an identical fashion to how a UTCInstant
node is interpreted, whose format it completely shares. Likewise regarding Float[DateTime|Date|Time]
.
A UTCDuration
node represents a duration value, an amount of time, which is not fixed to any instant in time. This node is interpreted as a Muldis D sys.std.Temporal.Type.UTCDuration
value whose duration
possrep attribute values are defined as follows:
A UTCDuration_payload
consists mainly of a bracket-delimited sequence of 6 comma-separated elements, where each element is either a valid numeric literal or is completely absent. The 6 elements correspond in order to the 6 attributes: years
, months
, days
, hours
, minutes
, seconds
. For each element that is absent or defined, the corresponding attribute has the Nothing
or a Single
value, respectively. For each of the first 5 elements, when it is defined, it must qualify as a valid body part of an Int
node; for the 6th element, when it is defined, it must qualify as a valid body part of a Rat
node.
Mostly a UTCDuration
is formatted and interpreted like a UTCInstant
node, and any similarities won't be repeated here.
A defined [years
, months
, days
, hours
, minutes
] may be any integer, and seconds
may be any rational number. Currently, UTCDuration
has no system-defined subtypes, but that may change later.
See also the definition of the catalog data type sys.std.Core.Type.Cat.OVLScaValExprNodeSet
, a tuple of which is what every kind of value__sse_temporal
node distills to when it is beneath the context of a depot
node, as it describes some semantics.
Examples:
TAIInstant:1235556432.0
TAIInstant:854309115.0
TAIDuration:3600.0
TAIDuration:-50.0
TAIDuration:3.14159
TAIDuration:1;1011101101*10^-11011
TAIDuration:1/43
UTCInstant:[1964,10,16,16,12,47.5] # a UTCDateTime #
UTCInstant:[2002,12,6,,,] # a UTCDate #
UTCInstant:[,,,14,2,29.0] # a UTCTime #
FloatInstant:[2003,4,5,2,,] # min,sec unknown or N/A #
FloatInstant:[1407,,,,,] # just know its sometime in 1407 #
UTCDuration:[3,5,1,6,15,45.000012]
HDMD_Perl6_STD - TEMPORAL EXTENSION OPAQUE VALUE LITERALS
The temporal
standard syntax extension is closely related to the Muldis::D::Ext::Temporal language extension, and it constitutes special syntax for its data types; in the future it may improve the type syntax or add syntax for operators.
When this extension is active, there exist 5 additional varieties of value
node: TAIInstant
, TAIDuration
, UTCInstant
, FloatInstant
, UTCDuration
. Also, between these 5 varieties, these 11 additional values are allowed for value
's value_kind
attribute: TAIInstant
, TAIDuration
, UTC[Instant|DateTime|Date|Time]
, Float[Instant|DateTime|Date|Time]
, UTCDuration
. For all of these varieties, the value_kind
may not be omitted.
HDMD_Perl6_STD - Date and Time Literals
A TAIInstant
node represents a single point in time which is specified in terms of atomic seconds. This node is interpreted as a Muldis D sys.std.Temporal.Type.TAIInstant
value as follows: The payload must be a Perl Instant
, which is mapped directly.
A TAIDuration
node represents a single amount of time (the difference between two instants) which is specified in terms of atomic seconds. This node is interpreted as a Muldis D sys.std.Temporal.Type.TAIDuration
value as follows: The payload must be a Perl Duration
, which is mapped directly.
A UTCInstant
node represents an "instant"/"datetime" value that is affiliated with the UTC time-zone. This node is interpreted as a Muldis D sys.std.Temporal.Type.UTCInstant
value whose instant
possrep attribute values are defined as follows:
The payload must be a Perl Seq|Array
with 6 elements, where each element may be either undefined or defined; or if fewer than 6 elements are provided, the Seq|Array
will be implicitly extended to 6, filling with undefs. The 6 payload elements correspond in order, from the lowest to the highest indexed, to the 6 attributes: year
, month
, day
, hour
, minute
, second
. For each payload element that Perl considers undefined or defined, the corresponding attribute has the Nothing
or a Single
value, respectively. For each of the first 5 elements, when it is defined, it must qualify as a valid payload for an Int
node; for the 6th element, when it is defined, it must qualify as a valid payload for a Rat
node.
A defined year
may be any integer, each of [month
, day
] must be a positive integer, each of [hour
, minute
] must be a non-negative integer, and second
must be a non-negative rational number. If all 6 attributes are defined, then the new UTCInstant
value is also a UTCDateTime
; if just the first 3 or last 3 are defined, then the value is not a UTCDateTime
but rather a UTCDate
or UTCTime
, respectively; if any other combination of attributes are defined, then the value is just a UTCInstant
and not of any of the other 3 subtypes.
A FloatInstant
node represents an "instant"/"datetime" value that is "floating" / not affiliated with any time-zone. This node is interpreted as a Muldis D sys.std.Temporal.Type.FloatInstant
value in an identical fashion to how a UTCInstant
node is interpreted, whose format it completely shares. Likewise regarding Float[DateTime|Date|Time]
.
A UTCDuration
node represents a duration value, an amount of time, which is not fixed to any instant in time. This node is interpreted as a Muldis D sys.std.Temporal.Type.UTCDuration
value whose duration
possrep attribute values are defined as follows:
The payload must be a Perl Seq|Array
with 6 elements, where each element may be either undefined or defined; or if fewer than 6 elements are provided, the Seq|Array
will be implicitly extended to 6, filling with undefs. The 6 payload elements correspond in order, from the lowest to the highest indexed, to the 6 attributes: years
, months
, days
, hours
, minutes
, seconds
. For each payload element that Perl considers undefined or defined, the corresponding attribute has the Nothing
or a Single
value, respectively. For each of the first 5 elements, when it is defined, it must qualify as a valid payload for an Int
node; for the 6th element, when it is defined, it must qualify as a valid payload for a Rat
node.
A defined [years
, months
, days
, hours
, minutes
] may be any integer, and seconds
may be any rational number. Currently, UTCDuration
has no system-defined subtypes, but that may change later.
Examples TODO: What is t actual syntax for P6 [Instant|Duration] types?:
:TAIInstant( Instant.new(1235556432.0) )
Instant.new(854309115.0)
:TAIDuration( Duration.new(3600.0) )
Duration.new(-50.0)
Duration.new(3.14159)
Duration.new(:2<1011101101> * :2<10> ** :2<-11011>)
Duration.new(1/43)
:UTCInstant[1964,10,16,16,12,47.5] # a UTCDateTime #
:UTCInstant[2002,12,6] # a UTCDate #
:UTCInstant[undef,undef,undef,14,2,29.0] # a UTCTime #
:FloatInstant[2003,4,5,2] # min,sec unknown or N/A #
:FloatInstant[1407] # just know its sometime in 1407 #
:UTCDuration[3,5,1,6,15,45.000012]
HDMD_Perl5_STD - TEMPORAL EXTENSION OPAQUE VALUE LITERALS
The temporal
standard syntax extension is closely related to the Muldis::D::Ext::Temporal language extension, and it constitutes special syntax for its data types; in the future it may improve the type syntax or add syntax for operators.
When this extension is active, there exist 5 additional varieties of value
node: TAIInstant
, TAIDuration
, UTCInstant
, FloatInstant
, UTCDuration
. Also, between these 5 varieties, these 11 additional values are allowed for value
's value_kind
attribute: TAIInstant
, TAIDuration
, UTC[Instant|DateTime|Date|Time]
, Float[Instant|DateTime|Date|Time]
, UTCDuration
. For all of these varieties, the value_kind
may not be omitted.
HDMD_Perl5_STD - Date and Time Literals
A TAIInstant
node represents a single point in time which is specified in terms of atomic seconds; it is a rational numeric type, that is disjoint from both Rat
and TAIDuration
. This node is interpreted as a Muldis D sys.std.Temporal.Type.TAIInstant
value by directly mapping the payload, which must be as per the payload of a Rat
node.
A TAIDuration
node represents a single amount of time (the difference between two instants) which is specified in terms of atomic seconds; it is a rational numeric type, that is disjoint from both Rat
and TAIInstant
. This node is interpreted as a Muldis D sys.std.Temporal.Type.TAIDuration
value by directly mapping the payload, which must be as per the payload of a Rat
node.
A UTCInstant
node represents an "instant"/"datetime" value that is affiliated with the UTC time-zone. This node is interpreted as a Muldis D sys.std.Temporal.Type.UTCInstant
value whose instant
possrep attribute values are defined as follows:
If the payload is a Perl array ref, then it must have 6 elements, where each element may be either undefined or defined; or if fewer than 6 elements are provided, the array ref will be implicitly extended to 6, filling with undefs. The 6 payload elements correspond in order, from the lowest to the highest indexed, to the 6 attributes:
year
,month
,day
,hour
,minute
,second
. For each payload element that Perl considers undefined or defined, the corresponding attribute has theNothing
or aSingle
value, respectively. For each of the first 5 elements, when it is defined, it must qualify as a valid payload for anInt
node; for the 6th element, when it is defined, it must qualify as a valid payload for aRat
node.A defined
year
may be any integer, each of [month
,day
] must be a positive integer, each of [hour
,minute
] must be a non-negative integer, andsecond
must be a non-negative rational number. If all 6 attributes are defined, then the newUTCInstant
value is also aUTCDateTime
; if just the first 3 or last 3 are defined, then the value is not aUTCDateTime
but rather aUTCDate
orUTCTime
, respectively; if any other combination of attributes are defined, then the value is just aUTCInstant
and not of any of the other 3 subtypes.If the payload is a Perl hash ref, then it must have 1 element, whose key and value are designated, in order, max-col-val and main payload; the max-col-val must be a Perl string and the main payload must be a Perl array ref as per the payload of the previous bullet point but that none of the 6 elements is a Perl hash ref. Each of the 6 main payload elements, when defined, is further interpreted according to the max-col-val, in the same manner as how an
Int
orRat
node's hash ref payload's element's value is interpreted. The interpretation of this payload is the same as for the Perl array ref payload.
A FloatInstant
node represents an "instant"/"datetime" value that is "floating" / not affiliated with any time-zone. This node is interpreted as a Muldis D sys.std.Temporal.Type.FloatInstant
value in an identical fashion to how a UTCInstant
node is interpreted, whose format it completely shares. Likewise regarding Float[DateTime|Date|Time]
.
A UTCDuration
node represents a duration value, an amount of time, which is not fixed to any instant in time. This node is interpreted as a Muldis D sys.std.Temporal.Type.UTCDuration
value whose duration
possrep attribute values are defined as follows:
If the payload is a Perl array ref, then it must have 6 elements, where each element may be either undefined or defined; or if fewer than 6 elements are provided, the array ref will be implicitly extended to 6, filling with undefs. The 6 payload elements correspond in order, from the lowest to the highest indexed, to the 6 attributes:
years
,months
,days
,hours
,minutes
,seconds
. For each payload element that Perl considers undefined or defined, the corresponding attribute has theNothing
or aSingle
value, respectively. For each of the first 5 elements, when it is defined, it must qualify as a valid payload for anInt
node; for the 6th element, when it is defined, it must qualify as a valid payload for aRat
node.A defined [
years
,months
,days
,hours
,minutes
] may be any integer, andseconds
may be any rational number. Currently,UTCDuration
has no system-defined subtypes, but that may change later.If the payload is a Perl hash ref, then it must have 1 element, whose key and value are designated, in order, max-col-val and main payload; the max-col-val must be a Perl string and the main payload must be a Perl array ref as per the payload of the previous bullet point but that none of the 6 elements is a Perl hash ref. Each of the 6 main payload elements, when defined, is further interpreted according to the max-col-val, in the same manner as how an
Int
orRat
node's hash ref payload's element's value is interpreted. The interpretation of this payload is the same as for the Perl array ref payload.
Examples:
[ 'TAIInstant', 1235556432.0 ]
[ 'TAIInstant', 854309115.0 ]
[ 'TAIDuration', 3600.0 ]
[ 'TAIDuration', -50.0 ]
[ 'TAIDuration', 3.14159 ]
[ 'TAIDuration', { 1 => ['1011101101','10','-11011'] } ]
[ 'TAIDuration', [1,43] ]
[ 'UTCInstant', [1964,10,16,16,12,47.5] ] # a UTCDateTime #
[ 'UTCInstant', [2002,12,6] ] # a UTCDate #
[ 'UTCInstant', [undef,undef,undef,14,2,29.0] ] # a UTCTime #
[ 'FloatInstant', [2003,4,5,2] ] # min,sec unknown or N/A #
[ 'FloatInstant', [1407] ] # just know its sometime in 1407 #
[ 'UTCDuration', [3,5,1,6,15,45.000012] ]
SEE ALSO
Go to Muldis::D::Manual for the majority of distribution-internal references.
AUTHOR
Darren Duncan (darren@DarrenDuncan.net
)
LICENSE AND COPYRIGHT
This file is part of the Muldis D language and implementations manual.
Muldis D Manual is Copyright © 2008-2010, Muldis Data Systems, Inc.
See the LICENSE AND COPYRIGHT of Muldis::D::Manual for details.
TRADEMARK POLICY
The TRADEMARK POLICY in Muldis::D::Manual applies to this file too.
ACKNOWLEDGEMENTS
The ACKNOWLEDGEMENTS in Muldis::D::Manual apply to this file too.