Date and Time CIP 2015-08-06 Temporal instant types

● DateTime ○ with timezone (logical zone or absolute offset from UTC) ● LocalDateTime ○ without timezone ● Date ○ without timezone ● Time ○ with absolute offset from UTC (logical zones needs date to map to offset) ● LocalTime ○ without timezone Duration type

● Represents a number of ○ years ○ months ○ days ○ hours ○ minutes ○ seconds (and fractional seconds) ● years and months (and quarters) convertible ● (days and weeks convertible) ● hours, minutes, and seconds convertible ● No conversion between the three groups above! Syntax

No new syntax is introduced.

All handling of temporal values is done through functions:

● datetime(...) ● localdatetime(...) ● date(...) ● time(...) ● localtime(...) ● {datetime,localdatetime,date,time,localtime}.truncate(...) ● {datetime,localdatetime,date,time,localtime}.{statement,transaction,realtime}(...) ● duration(...) ● duration.between(...), duration.inMonths(...), duration.inDays(...), duration.inSeconds(...) Ways of creating temporal instants

● Parsing from ISO 8601 string ● Creating from components ● Getting the current instant ○ using different clocks: statement, transaction, realtime (one of them being default) ● Adding a Duration to an instant ● Converting from other instants

Ways of creating Duration ● Parsing from ISO 8601 string ● Creating from components ● Compute difference between instants Parsing Temporal Instant from ISO 8601 string

● datetime($string), localdatetime($string), date($string), time($string), localtime($string)

● date: YYYY-MM-DD, or YYYY-Www-D, or YYYY-Qq-DD, or YYYY-DDD (calendar date, week date, quarter date, ordinal date respectively) ○ dashes can be omitted, smaller units can be omitted ○ year with a sign prefix can be arbitrarily long, but then dashes may not be omitted ● time: HH:MM:SS.sss ○ colons can be omitted, smaller units can be omitted ● offset: ±HH:MM or Z ○ colons can be omitted, smaller units can be omitted ● zone: [name] Parsing Temporal Instant from ISO 8601 string

● datetime($string) ○ T ○ either offset, or zone, or both ○ smaller units may be omitted ● localdatetime($string) ○ T ○ smaller units may be omitted ● date($string) ○ ● time($string) ○ ● localtime($string) ○ Creating Temporal Instant from components

● datetime({...}), localdatetime({...}), date({...}), time({...}), localtime({...}) ○ Date based: ■ year ■ quarter ■ month ■ week ■ weekYear ■ day ■ ordinalDay ■ weekDay ○ Time based: ■ hour ■ minute ■ second ■ millisecond ■ microsecond ■ nanosecond ○ Other: ■ timezone - the named timezone or offset if no name (supported by zoned types) ■ offset - as a formatted offset string (supported by zoned types) ■ offsetMinutes (supported by zoned types) ■ epochMillis (only supported by DateTime) ■ epochSeconds (only supported by DateTime) ■ epochNanosOfSecond (only supported by DateTime) Getting the current Temporal Instant

● datetime(), localdatetime(), date(), time(), localtime()

The above uses the (implementation specific) default clock, which is one of the below:

Same point in time every invocation in the query: ● datetime.statement(), localtime.statement(), et.c... ● datetime.statement($timezone), et.c...

Same point in time every invocation in the transaction: ● datetime.transaction(), localtime.transaction(), et.c... ● datetime.transaction($timezone), et.c…

Actual time at invocation: ● datetime.realtime(), localtime.realtime(), et.c... ● datetime.realtime($timezone), et.c... Converting Temporal Instants between types

● datetime({...}), localdatetime({...}), date({...}), time({...}), localtime({...}) ● date - selects the date from a Date, or DateTime, or LocalDateTime ● time - selects the time from a Time, LocalTime, DateTime, LocalDateTime ● datetime - selects both the date and time from a DateTime or LocalDateTime

Examples:

● datetime({datetime:$aDateTimeOrLocalDateTime, timezone:"..."}) ● datetime({date:$aDateOrDateTimeOrLocalDateTime, time:$anotherDateOrDateTimeOrLocalDateTime}) ● datetime({datetime:...}), datetime({date:..., time:...}) datetime({datetime:..., timezone:...}), datetime({date:..., time:..., timezone:...}) ● localdatetime({datetime:...}), localdatetime({date:..., time:...}) ● time({time:...}), time({time:..., timezone:...}) ● date({date:...}) ● localtime({time:...}) Parsing Duration from ISO 8601 string

● duration($string) ● unit based format: PnYnQnMnWnDTnHnMnS ○ zero valued component can be omitted ○ T must precede time-based section (Hours and smaller) ○ Smallest component may be fractional ○ Examples: P15M, P1DT3H, PT48H, P1.5W ● date-and-time based format: PT ○ smaller units may be omitted Creating Duration from Components

● duration({...}) ○ years ○ quarters ○ months ○ weeks ○ days ○ hours ○ minutes ○ seconds ○ milliseconds ○ microseconds ○ nanoseconds Compute Duration as difference between Instants

Computing the duration from instant a to instant b:

● duration.between(a, b) ○ uses natural units ● duration.inSeconds(a, b) ○ uses hours, minutes, seconds ● duration.inDays(a, b) ○ uses days ● duration.inMonths(a, b) ○ uses months and years Adding a Duration to a Temporal Instant

Example: date("1984-10-11") + duration("P33Y5M3D")

Note that this is not associative:

● (date("2011-01-31") + duration("P1M")) + duration("P12M") ○ date({year:2012, month:2, day:28}) ● date("2011-01-31") + (duration("P1M") + duration("P12M")) ○ date({year:2012, month:2, day:29}) Truncating a Temporal Instant datetime.truncate($unit, $instant) localdatetime.truncate($unit, $instant) date.truncate($unit, $instant) time.truncate($unit, $instant) localtime.truncate($unit, $instant)

Supported units: ● millennium ● century ● decade ● year ● weekYear - the first day of the first week of the week year of the specified instant (may be in december of previous year) ● quarter ● month ● week ● day ● hour ● minute ● second ● millisecond ● microsecond Comparing and ORDER BY

● Temporal Instants comparable to other instants of same type ● ORDER BY uses comparison order for Temporal Instants

● ORDER BY groups by type when ordering by field with mixed types

● Duration values are NOT comparable ○ because different months are of different lengths, and not all days are equally long ● ORDER BY for Duration based on average length of days and months Ordering durations - is the order consistent?

● PT672H = P28D ≤ P1M ≤ P31D = PT744H ; P1M ordered as: PT2629746S = PT730,485H (shortest possible: February) ● PT1416H = P59D ≤ P2M ≤ P62D = PT1488H ; P2M ordered as: PT5259492S = PT1460,970H (shortest possible two: Jan-Feb or Feb-Mar, longest possible two: Jul-Aug or Dec-Jan) ● PT2136H = P89D ≤ P3M ≤ P92D = PT2208H ; P3M ordered as: PT7889238S = PT2191,455H (shortest possible three: Feb-Apr, longest possible three: Nov-Jan or Jun-Aug or Jul-Sep) ● PT2880H = P120D ≤ P4M ≤ P123D = PT2952H ; P4M ordered as: PT10518984S = PT2921,940H (shortest possible four: Jan-Apr or Feb-May or Nov-Feb, longest possible four: May-Aug or Jul-Oct or Oct-Jan) ● PT3600H = P150D ≤ P5M ≤ P153D = PT3672H ; P5M ordered as: PT13148730S = PT3652,425H (shortest possible five: Feb-Jun, longest possible five: any range not including Feb) ● PT4344H = P181D ≤ P6M ≤ P184D = PT4416H ; P6M ordered as: PT15778476S = PT4382,910H (shortest possible six: Jan-Jun or Feb-Jul, longest possible six: Jul-Dec or Aug-Jan) ● PT5088H = P212D ≤ P7M ≤ P215D = PT5160H ; P7M ordered as: PT18408222S = PT5113,395H (shortest possible seven: any range including Feb, longest possible seven: Jul-Jan) ● PT5808H = P242D ≤ P8M ≤ P245D = PT5880H ; P8M ordered as: PT21037968S = PT5843,880H (shortest possible eight: Feb-Sep or Sep-Apr or Nov-Jun, longest possible eight: May-Dec or Jun-Jan) ● PT6552H = P273D ≤ P9M ≤ P276D = PT6624H ; P9M ordered as: PT23667714S = PT6574,365H (shortest possible nine: many, longest possible nine: May-Jan) ● PT7272H = P303D ≤ P10M ≤ P306D = PT7344H ; P10M ordered as: PT26297460S = PT7304,850H (shortest possible ten: Feb-Nov or Sep-Jun, longest possible ten: Mar-Dec or Apr-Jan) ● PT8016H = P334D ≤ P11M ≤ P337D = PT8088H ; P11M ordered as: PT28927206S = PT8035,335H (shortest possible eleven: many, longest possible eleven: Mar-Jan) ● PT8760H = P365D ≤ P12M = P1Y ≤ P366D = PT8784H ; P12M, P1Y ordered as: PT31556952S = PT8765,820H (longest possible: leap year) ● PT35040H = P1460D ≤ P4Y ≤ P1461D = PT35064H ; P4Y ordered as: PT126227808S = PT35063,280H (every 100 years, we skip a leap year) ● PT876576H = P36524D ≤ P100Y ≤ P36525D = PT876600H ; P100Y ordered as: PT3155695200S = PT876582,000H (every 400 years, we skip skipping the leap year) ● PT3506328H = P400Y = P146097D = PT3506328H ; P400Y ordered as: PT12622780800S = PT3506328,000H (this it the shortest number of months where we know exactly how many days it is)