Muldis::D::Ext::Temporal - Muldis D extension for temporal data types and operators
This document is Muldis::D::Ext::Temporal version 0.115.0.
This document is part of the Muldis D language specification, whose root document is Muldis::D; you should read that root document before you read this one, which provides subservient details.
TODO: PARTIALLY REWRITE THIS DOCUMENT; REFACTOR THE TEMPORAL TYPES!
Muldis D has a mandatory core set of system-defined (eternally available) entities, which is referred to as the Muldis D core or the core; they are the minimal entities that all Muldis D implementations need to provide; they are mutually self-describing and are either used to bootstrap the language or they constitute a reasonable minimum level of functionality for a practically useable industrial-strength (and fully TTM-conforming) programming language; any entities outside the core, called 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 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.
Temporal
TAI
UTC
Float
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.
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 Muldis::D::Core.
This documentation is pending.
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
These non-core data types are all ordered scalar types.
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.
PInt[12|31]
PInt
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.
NNInt[23|59]
NNInt
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).
NNRatLT62
NNRat
ratio
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. Put another way, the TAIInstant type is intended to have exactly the same meaning as the same-named type of Perl 6 (see http://perlcabal.org/syn/S02.html for details). Or at least that used to be true; TODO: update this.
TAIInstant
A TAIInstant has 1 system-defined possrep named tai_instant which consists of 1 Rat-typed attribute named seconds. 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.
tai_instant
Rat
seconds
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.
UTCInstant
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 is intended to have exactly the same meaning as the same-named type of Perl 6, as per TAIInstant. A TAIDuration has 1 system-defined possrep named tai_duration which consists of 1 Rat-typed attribute named seconds. 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.
TAIDuration
tai_duration
UTCDuration
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. 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.
instant
year
maybe_of.Int
month
maybe_of.PInt12
day
maybe_of.PInt31
hour
maybe_of.NNInt23
minute
maybe_of.NNInt59
second
maybe_of.NNRatLT62
Single
Nothing
1
12
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 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.
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.
UTCDateTime
datetime
Int
PInt12
PInt31
NNInt23
NNInt59
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).
UTCDate
date
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).
UTCTime
time
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 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.
FloatInstant
FloatDateTime is to UTCDateTime as FloatInstant is to UTCInstant.
FloatDateTime
FloatDate is to UTCDate as FloatInstant is to UTCInstant.
FloatDate
FloatTime is to UTCTime as FloatInstant is to UTCInstant.
FloatTime
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.
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.
duration
years
months
days
hours
minutes
maybe_of.Rat
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 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.
These functions implement commonly used temporal math operations.
function sys.std.Temporal.TAIInstant.diff (TAIDuration <-- $minuend : TAIInstant, $subtrahend : TAIInstant)
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.
subtrahend
minuend
function sys.std.Temporal.TAIInstant.abs_diff (TAIDuration <-- $topic : TAIInstant, $other : TAIInstant)
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.
function sys.std.Temporal.TAIInstant.later (TAIInstant <-- $instant : TAIInstant, $duration : TAIDuration)
This function results in the instant that is later than its instant argument by the amount of time in the duration argument.
function sys.std.Temporal.TAIInstant.earlier (TAIInstant <-- $instant : TAIInstant, $duration : TAIDuration)
This function results in the instant that is earlier than its instant argument by the amount of time in the duration argument.
function sys.std.Temporal.TAIDuration.abs (TAIDuration <-- $topic : TAIDuration)
This function results in the absolute value of its argument.
function sys.std.Temporal.TAIDuration.sum (TAIDuration <-- $topic? : bag_of.TAIDuration)
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.
topic
sum
function sys.std.Temporal.TAIDuration.diff (TAIDuration <-- $minuend : TAIDuration, $subtrahend : TAIDuration)
This function results in the difference when its subtrahend argument is subtracted from its minuend argument.
function sys.std.Temporal.UTCInstant.diff (UTCDuration <-- $minuend : UTCInstant, $subtrahend : UTCInstant)
function sys.std.Temporal.UTCInstant.abs_diff (UTCDuration <-- $topic : UTCInstant, $other : UTCInstant)
function sys.std.Temporal.UTCInstant.later (UTCInstant <-- $instant : UTCInstant, $duration : UTCDuration)
function sys.std.Temporal.UTCInstant.earlier (UTCInstant <-- $instant : UTCInstant, $duration : UTCDuration)
function sys.std.Temporal.FloatInstant.diff (UTCDuration <-- $minuend : FloatInstant, $subtrahend : FloatInstant)
function sys.std.Temporal.FloatInstant.abs_diff (UTCDuration <-- $topic : FloatInstant, $other : FloatInstant)
function sys.std.Temporal.FloatInstant.later (FloatInstant <-- $instant : FloatInstant, $duration : UTCDuration)
function sys.std.Temporal.FloatInstant.earlier (FloatInstant <-- $instant : FloatInstant, $duration : 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.
function sys.std.Temporal.UTCDuration.abs (UTCDuration <-- $topic : UTCDuration)
function sys.std.Temporal.UTCDuration.sum (UTCDuration <-- $topic? : bag_of.UTCDuration)
function sys.std.Temporal.UTCDuration.diff (UTCDuration <-- $minuend : UTCDuration, $subtrahend : UTCDuration)
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.
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.
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.
These system-service routines provide ways to get the current date or time from the system.
system-service sys.std.Temporal.TAIInstant.fetch_curr_instant (&$target : TAIInstant)
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.
target
system-service sys.std.Temporal.UTCInstant.fetch_curr_datetime (&$target : UTCDateTime)
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.
system-service sys.std.Temporal.UTCInstant.fetch_curr_date (&$target : UTCDate)
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_date
system-service sys.std.Temporal.UTCInstant.fetch_curr_time (&$target : UTCTime)
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.
system-service sys.std.Temporal.FloatInstant.fetch_curr_datetime (&$target : FloatDateTime)
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.
system-service sys.std.Temporal.FloatInstant.fetch_curr_date (&$target : FloatDate)
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_date
system-service sys.std.Temporal.FloatInstant.fetch_curr_time (&$target : FloatTime)
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.
Go to Muldis::D for the majority of distribution-internal references, and Muldis::D::SeeAlso for the majority of distribution-external references.
Darren Duncan (darren@DarrenDuncan.net)
darren@DarrenDuncan.net
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 Muldis::D for details.
The TRADEMARK POLICY in Muldis::D applies to this file too.
The ACKNOWLEDGEMENTS in Muldis::D apply to this file too.
To install Muldis::D, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Muldis::D
CPAN shell
perl -MCPAN -e shell install Muldis::D
For more information on module installation, please visit the detailed CPAN module installation guide.