NAME

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

VERSION

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

PREFACE

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.

DESCRIPTION

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 used to bootstrap the 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.

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.MM.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.

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.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.Duration

        sys.std.Core.Type.Int

            sys.std.Core.Type.UInt

                sys.std.Core.Type.PInt

                    # These are all finite positive integer types.

                    sys.std.Temporal.Type.PInt(12|31)

                # These are all finite unsigned integer types.

                sys.std.Temporal.Type.UInt(23|59)

        sys.std.Rational.Type.Rat
            sys.std.Rational.Type.URat

                # These are all infinite unsigned rational types.

                sys.std.Temporal.Type.URatLT62

This documentation is pending.

SYSTEM-DEFINED TEMPORAL-CONCERNING DATA TYPES

These non-core data types are all ordered scalar types.

sys.std.Temporal.Type.PInt(12|31)

A 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.UInt(23|59)

A UInt(23|59) is a proper subtype of UInt 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 an unsigned integer not greater than 23|59.

sys.std.Temporal.Type.URatLT62

A URatLT62 is a proper subtype of URat 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 an unsigned rational less than 62. The cardinality of this type is infinity; to define a most-generalized finite URatLT62 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.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. 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.UInt23), minute (a maybe_of.UInt59), second (a maybe_of.URatLT62). 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 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 (a Int), month (a PInt12), day (a PInt31), hour (a UInt23), minute (a UInt59), second (a URatLT62). 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 (a 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 UInt23), minute (a UInt59), second (a URatLT62). 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 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

A FloatDateTime is to UTCDateTime as FloatInstant is to UTCInstant.

sys.std.Temporal.Type.FloatDate

A FloatDate is to UTCDate as FloatInstant is to UTCInstant.

sys.std.Temporal.Type.FloatTime

A FloatTime is to UTCTime as FloatInstant is to UTCInstant.

sys.std.Temporal.Type.Duration

A Duration 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 Duration 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 Duration 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 Duration 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 Duration 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 Duration 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 FOR TEMPORAL MATH

These functions implement commonly used temporal math operations.

UTCInstant

function sys.std.Temporal.UTCInstant.difference result Duration params { minuend(UTCInstant), subtrahend(UTCInstant) }: 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.
function sys.std.Temporal.UTCInstant.abs_difference result Duration params { topic(Duration), other(Duration) }: This 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.UTCInstant.later result UTCInstant params { instant(Instant), duration(Duration) }: 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.UTCInstant.earlier result UTCInstant params { instant(Instant), duration(Duration) }: This function results in the instant that is earlier than its instant argument by the amount of time in the duration argument.

FloatInstant

function sys.std.Temporal.FloatInstant.difference result Duration params { minuend(FloatInstant), subtrahend(FloatInstant) }: 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.
function sys.std.Temporal.FloatInstant.abs_difference result Duration params { topic(Duration), other(Duration) }: This 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.FloatInstant.later result FloatInstant params { instant(Instant), duration(Duration) }: 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.FloatInstant.earlier result FloatInstant params { instant(Instant), duration(Duration) }: This function results in the instant that is earlier than its instant argument by the amount of time in the duration argument.

Duration

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.Duration.abs result Duration params { topic(Duration) }: This function results in the absolute value of its argument.
function sys.std.Temporal.Duration.sum result Duration params { addends(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 addends has zero values, then sum results in the duration zero, which is the identity value for addition.
function sys.std.Temporal.Duration.difference result Duration params { minuend(Duration), subtrahend(Duration) }: This function results in the difference when its subtrahend argument is subtracted from its minuend argument.

SYSTEM SERVICES FOR CURRENT DATES AND TIMES

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

system_service sys.std.Temporal.UTCInstant.fetch_current_datetime update { target(UTCDateTime) } read {}: 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_current_date update { target(UTCDate) } read {}: This system service routine is the same as sys.std.Temporal.UTCInstant.fetch_current_date except that it only produces an instant value with the date (YMD) attributes set.
system_service sys.std.Temporal.UTCInstant.fetch_current_time update { target(UTCTime) } read {}: This system service routine is the same as sys.std.Temporal.UTCInstant.fetch_current_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_current_datetime update { target(FloatDateTime) } read {}: 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_current_date update { target(FloatDate) } read {}: This system service routine is the same as sys.std.Temporal.FloatInstant.fetch_current_date except that it only produces an instant value with the date (YMD) attributes set.
system_service sys.std.Temporal.FloatInstant.fetch_current_time update { target(FloatTime) } read {}: This system service routine is the same as sys.std.Temporal.FloatInstant.fetch_current_date except that it only produces an instant value with the time (HIS) attributes set; it still retains the full precision.

AUTHOR

Darren Duncan (perl@DarrenDuncan.net)

LICENSE AND COPYRIGHT

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

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

TRADEMARK POLICY

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

ACKNOWLEDGEMENTS

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)