Muldis::D::Manual::TemporalExtras - Legacy temporal data types, operators, and syntax removed from Muldis D
This document is Muldis::D::Manual::TemporalExtras version 0.9.0.
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.
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.
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.
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
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. The TAIInstant type explicitly composes the Instant mixin type.
TAIInstant
Instant
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.
tai_instant
Rat
seconds
Ordered
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 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.
TAIDuration
Duration
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. 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 Just 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
Just
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 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 Just 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 Just / 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 Just / 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 Just / 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 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.
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. 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 Just 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 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 Just 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.
function 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.
order-determination
function 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.
function 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.
function 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.
function 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.
function 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.
subtrahend
minuend
function 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.
function 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.
function 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.
function diff (UTCDuration <-- minuend : UTCInstant, subtrahend : UTCInstant) implements sys.std.Temporal.Instant.diff {...}
function abs_diff (UTCDuration <-- topic : UTCInstant, other : UTCInstant) implements sys.std.Temporal.Instant.abs_diff {...}
function later (UTCInstant <-- instant : UTCInstant, duration : UTCDuration) implements sys.std.Temporal.Instant.later {...}
function earlier (UTCInstant <-- instant : UTCInstant, duration : UTCDuration) implements sys.std.Temporal.Instant.earlier {...}>>
function diff (UTCDuration <-- minuend : FloatInstant, subtrahend : FloatInstant) implements sys.std.Temporal.Instant.diff {...}>>
function abs_diff (UTCDuration <-- topic : FloatInstant, other : FloatInstant) implements sys.std.Temporal.Instant.abs_diff {...}
function later (FloatInstant <-- instant : FloatInstant, duration : UTCDuration) implements sys.std.Temporal.Instant.later {...}
function earlier (FloatInstant <-- instant : FloatInstant, duration : UTCDuration) implements sys.std.Temporal.Instant.earlier {...}>>
function abs (TAIDuration <-- topic : TAIDuration) implements sys.std.Temporal.Duration.abs {...}
This function results in the absolute value of its argument.
function 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.
topic
sum
function 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.
function 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.
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 abs (UTCDuration <-- topic : UTCDuration) implements sys.std.Temporal.Duration.abs {...}
function sum (UTCDuration <-- topic? : bag_of.UTCDuration) implements sys.std.Temporal.Duration.sum {...}
function diff (UTCDuration <-- minuend : UTCDuration, subtrahend : UTCDuration) implements sys.std.Temporal.Duration.diff {...}>>
function abs_diff (UTCDuration <-- topic : UTCDuration, other : UTCDuration) implements sys.std.Temporal.Duration.abs_diff {...}
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 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 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 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.
target
system-service 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.
system-service 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_date
system-service 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.
system-service 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.
system-service 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_date
system-service 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.
The standard_syntax_extensions pragma declares which optional portions of the Muldis D grammar a programmer may employ with their Muldis D code.
standard_syntax_extensions
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>
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>
<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.
sys.std.Temporal.Type.TAIInstant
TAIInstant_payload
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.
sys.std.Temporal.Type.TAIDuration
TAIDuration_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:
sys.std.Temporal.Type.UTCInstant
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 Just 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.
UTCInstant_payload
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.
value_kind
value
type_name
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].
sys.std.Temporal.Type.FloatInstant
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:
sys.std.Temporal.Type.UTCDuration
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 Just 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.
UTCDuration_payload
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.
sys.std.Core.Type.Cat.OVLScaValExprNodeSet
value__sse_temporal
depot
Examples:
TAIInstant:1235556432.0 TAIInstant:854309115.0 TAIDuration:3600.0 TAIDuration:-50.0 TAIDuration:3.14159 TAIDuration:b;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]
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.
UTC[Instant|DateTime|Date|Time]
Float[Instant|DateTime|Date|Time]
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.
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 Just 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.
Seq|Array
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 Just 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.
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(0b1011101101 * 0b10 ** -0b11011) 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]
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.
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 the Nothing or a Just 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.
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 or Rat 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.
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 the Nothing or a Just 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.
[ 'TAIInstant', 1235556432.0 ] [ 'TAIInstant', 854309115.0 ] [ 'TAIDuration', 3600.0 ] [ 'TAIDuration', -50.0 ] [ 'TAIDuration', 3.14159 ] [ 'TAIDuration', { b => ['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] ]
Go to Muldis::D::Manual for the majority of distribution-internal references.
Darren Duncan (darren@DarrenDuncan.net)
darren@DarrenDuncan.net
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.
The TRADEMARK POLICY in Muldis::D::Manual applies to this file too.
The ACKNOWLEDGEMENTS in Muldis::D::Manual apply to this file too.
6 POD Errors
The following errors were encountered while parsing the POD:
Unterminated C< ... > sequence
To install Muldis::D::Manual, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Muldis::D::Manual
CPAN shell
perl -MCPAN -e shell install Muldis::D::Manual
For more information on module installation, please visit the detailed CPAN module installation guide.