Pyret

This document contains the date-time library for Pyret, along with many examples and some longer descriptions of language design choices.
The official Pyret documentation can be found here.

1 Builtins and Libraries

This section contains information on libraries that come with Pyret.

1.1 duration

1.1.1 The Duration Datatype

1.1.2 Duration Methods

1.1.3 Duration Functions

1.2 day-of-week

1.2.1 The DayOfWeek Datatype

1.2.2 DayOfWeek Methods

1.2.3 DayOfWeek Functions

1.3 month-of-year

1.3.1 The MonthOfYear Datatype

1.3.2 MonthOfYear Methods

1.3.3 MonthOfYear Functions

1.4 zone-offset

1.4.1 The ZoneOffset Datatype

1.4.2 ZoneOffset Methods

1.4.3 ZoneOffset Functions

1.5 zone-id

1.5.1 The ZoneId Datatype

1.5.2 ZoneId Methods

1.5.3 ZoneId Functions

1.6 temporal

1.6.1 The Temporal Datatype

1.6.2 Temporal Attribute Types

1.6.3 Temporal Methods

1.6.4 Temporal Functions

1.6.5 naive-date

1.6.5.1 The NaiveDate Datatype

1.6.5.2 NaiveDate Methods

1.6.6 naive-time

1.6.6.1 NaiveTime Methods

1.6.6.2 NaiveTime Functions

1.6.7 utc-date-time

1.6.7.1 The UTCDateTime Type

1.6.7.2 UTCDateTime Methods

1.6.7.3 UTCDateTime Functions

1.6.8 offset-time

1.6.8.1 OffsetTime Methods

1.6.9 offset-date-time

1.6.9.1 The OffsetDateTime Type

1.6.9.2 OffsetDateTime Methods

1.6.9.3 OffsetDateTime Functions

1.1 duration

Usage:

include duration

import duration as ...

1.1.1 The Duration Datatype

data Duration:

| duration(year :: Number, month :: Number, day :: Number, hour :: Number, minute :: Number, second :: Number)

end

The Duration type has several fields, combinations of which allow different ways of representing the amounts of time this library provides.
The functions associated with this type include several constructors that ensure users need not directly access this data type to construct simpler versions of durations (i.e. only years, days, or hour-minute-second triples, etc.).
In conversions and normalization, Duration assumes that a "month" duration is equivalent to 30 days and a "year" duration is equivalent to 365 days. This is done for uniformity, and differences in actual month/year lengths are more accurately reflected in the Temporal types.
There are no variants for Duration, and programs cannot use cases statements with Durations. Instead, they can be created and manipulated with the methods and functions below.

1.1.2 Duration Methods

.get :: (units :: Set<TemporalUnit>) -> Duration

Gets the value of the requested Duration from ’units’ with 0 for the non-requested units (i.e. without normalizing the Duration from ’units’).

Examples:

check:
  duration(1, 11, 6, -4, 2, -4.5).get([set: unit-month]) is duration(0, 11, 0, 0, 0, 0)
  duration(41.3, 0, 11, 0, 23, 0).get([set: unit-day, unit-year, unit-hour]) is duration(41.3, 0, 0, 0, 0, 0)
end

.get-units :: () -> Set<TemporalUnit>

Returns a set of non-0 units uniquely defining the value of this Duration.

Examples:

check:
  duration(1, 1, 1, 1, 1, 1).get-units()
    is [set: unit-year, unit-month, unit-day, unit-hour, unit-minute, unit-second]
  duration(0, 0, 2, -1.1, -5, 0).get-units()
    is [set: unit-day, unit-hour, unit-minute]
  duration(0, 0, 0, 0, 0, 0).get-units() is empty-set
end

.normalize :: (units :: Set<TemporalUnit>) -> Duration

Normalize the duration into seconds and perform greedy division into a new duration for the ’units’ provided.

A normalized Duration is greedily divided such that its year attribute, followed by month attribute, and so on are as large as possible, implying that only the units in the set passed may be non-integer, and only the value of the smallest unit in the duration may be non-integer

Examples:

check:
  duration(1, 2, 3, 4, 5, 6).normalize([set: unit-year])
    is duration(1, 2, 3, 4, 5, 6)
  duration(1, 12, 30, 24, 60, 60).normalize([set: unit-year, unit-month, unit-day, unit-hour, unit-minute, unit-second])
    is duration(2, 0, 26, 1, 1, 0)
  duration(-1, 2, -3, 4, -5, 6).normalize([set: unit-year, unit-hour, unit-minute, unit-second])
    is ...
    duration(10, 20, 30, 40, 50, 60).normalize([set: unit-year, unit-month, unit-year])
    is duration(11, 8, 12817/480, 0, 0, 0)
end

.abs :: () -> Duration

Returns a copy of this Duration with all attributes made positive.

Examples:

check:
  duration(1, -2, 3, -4, 5, -6).abs()
    is duration(1, 2, 3, 4, 5, 6)
end

.scale-f :: (f :: (Number -> Number)) -> Duration

Returns a copy of the Duration scaled by the function ’f’.

Examples:

check:
  duration(0, 1, -1, 11/2, -22/7, 0).scale-f(num-round)
    is duration(0, 1, -1, 6, -3, 0)
end

.scale :: (coeff :: Number) -> Duration

Returns a copy of this Duration scaled by the passed scalar.

Examples:

check:
  duration(2, 4, 6, 8, 10, 12).scale(0.5)
    is duration(1, 2, 3, 4, 5, 6)
  duration(2, 4, 6, 8, 10, 12).scale(0)
    is duration(0, 0, 0, 0, 0, 0)
end

.equals :: (other :: Duration) -> Boolean

Checks if the normalized forms of this Duration and the specified Duration are equal.

Examples:

check:
  duration(1, 20, 39, 2, -1, -90).equals(duration(1, 20, 39, 2, -1, -90))
    is true
  duration(1, 20, 39, 2, -1, -90).equals(duration(2, 9, 4, 1, 57, 30))
    is true
  duration(-1, -2, -3, -4, -5, -6).equals(duration(1, 2, 3, 4, 5, 6))
    is false
end

.is-negative :: () -> Boolean

Checks if this Duration is negative in its normalized form.

Examples:

check:
  duration(1, 2, 3, 4.09, 5, 6).is-negative()
    is false
  duration(-1, 2, -3, 4.09, -5, 6).is-negative()
    is true
  duration(-1, 20, -3, 4.09, -5, 6).is-negative()
    is false
    duration(0, 0, 0, 0, 0, 0).is-negative()
    is false
end

.is-zero :: () -> Boolean

Checks if this Duration is 0 in its normalized form.

Examples:

check:
  duration(0, 0, 1, -24, 1, -60).is-zero()
    is true
  duration(0, 0, 0, 0, 0, 0).is-zero()
    is true
  duration(1, 2, 3, 4.09, 5, 6).is-zero()
    is false
end

.set-unit :: (unit :: TemporalUnit, n :: Number) -> Duration

Returns a copy of this Duration with the specified unit modified to ’n’.

Examples:

check:
  duration(-1, -2, -3, -4, -5, -6).change-unit(unit-day, 3) end)
    is duration(-1, -2, 3, -4, -5, -6)
end

.plus :: (other :: Duration) -> Duration

Returns a copy of this Duration with the specified Duration added.

Examples:

check:
  duration(1, 2, 3, 4, 5, 6).plus(duration(0, 1, -3, 5, 6, -99))
    is duration(1, 3, 0, 9, 11, -93)
end

.minus :: (other :: Duration) -> Duration

Returns a copy of this Duration with the specified Duration subtracted.

Examples:

check:
  duration(1, 2, 3, 4, 5, 6).minus(duration(0, 1, 3, 5, 6, 99))
    is duration(1, 1, 0, -1, -1, -93)
end

.times :: (other :: Duration) -> Duration

Returns a copy of this Duration with the specified Duration multiplied.

Examples:

check:
  duration(1, 2, 3, 4, 5, 6).times(duration(0, 1, 3, 5, 6, 99))
    is ...
end

.divide :: (other :: Duration) -> Duration

Returns a copy of this Duration with the specified Duration divided.

Examples:

check:
  duration(1, 2, 3, 4, 5, 6).divide(duration(0, 1, 3, 5, 6, 99))
    is ...
    duration(1, 2, 3, 4, 5, 6).divide(duration(0, 0, 0, 0, 0, 0))
    raises "division by zero"
end

.to-string :: () -> String

A string representation of this Duration using ISO-8601 seconds based representation in normalized form, such as "PT8H6M12.345S".

Examples:

check:
  duration(1, 2, 3, 4, 5, 6).to-string()
    is "P1Y2M3DT4H5M6S"
  duration(1, 0, 0, 8, 6, 12.345).to-string()
    is "P1YT8H6M12.345S"
end

1.1.3 Duration Functions

These functions require the Duration module to be imported, as indicated in the examples.

The input is not normalized, and is instead stored as is to account for computational use cases.

ymd-to-duration :: (
years :: Number,
months :: Number,
days :: Number
)
-> Duration

Obtains a duration representing an amount from the values of the years, months, and days.

Examples:

check:
  ymd-to-duration(-4, -10, -21)
    is duration(-4, -10, -21, 0, 0, 0)
end

hms-to-duration :: (
hours :: Number,
minutes :: Number,
seconds :: Number
)
-> Duration

Obtains a duration representing an amount from the values of the hours, minutes, and seconds.

Examples:

check:
  hms-to-duration(-5, -3, -11)
    is duration(0, 0, 0, -5, -3, -11)
end

years-to-duration :: (years :: Number) -> Duration

Obtains a Duration representing a number of years.

Examples:

check:
  years-to-duration(1)
    is duration(1, 0, 0, 0, 0, 0)
end

months-to-duration :: (months :: Number) -> Duration

Obtains a Duration representing a number of months.

Examples:

check:
  months-to-duration(1)
    is duration(0, 1, 0, 0, 0, 0)
end

days-to-duration :: (days :: Number) -> Duration

Obtains a Duration representing a number of days.

Examples:

check:
  days-to-duration(1)
    is duration(0, 0, 1, 0, 0, 0)
end

hours-to-duration :: (hour :: Number) -> Duration

Obtains a Duration representing a number of hours.

Examples:

check:
  hours-to-duration(1)
    is duration(0, 0, 0, 1, 0, 0)
end

minutes-to-duration :: (years :: Number) -> Duration

Obtains a Duration representing a number of minutes.

Examples:

check:
  minutes-to-duration(1)
    is duration(0, 0, 0, 0, 1, 0)
end

seconds-to-duration :: (seconds :: Number) -> Duration

Obtains a Duration representing a number of seconds.

Examples:

check:
  seconds-to-duration(1)
    is duration(0, 0, 0, 0, 0, 1)
end

1.2 day-of-week

Usage:

include day-of-week

import day-of-week as ...

1.2.1 The DayOfWeek Datatype

data DayOfWeek:

| d1
| d2
| d3
| d4
| d5
| d6
| d7

end

The DayOfWeek represents the possible days of the standard business week.
The e-nums 1 through 7 happen to coincide with the trade convention for weeks in the Gragorian Calendar, where 1 represents Monday, 2 represents Tuesday, and so on.
These seven variables for DayOfWeek may be created and manipulated with the methods and functions below.

1.2.2 DayOfWeek Methods

.get-display-name :: () -> String

Gets the textual representation following the trade representation of the week such as ’Monday’ or ’Friday’.

Examples:

check:
  d5.get-display-name() is "Friday"
end

.get-num :: () -> Number

Gets the day-of-week Number value following the trade week representation.

Examples:

check:
  d3.get-value() is 3
end

.arithmetic-f :: (f :: (Number -> Number)) -> DayOfWeek

Returns the DayOfWeek after modifying the given DayOfWeek through ’f’.

Examples:

check:
  d6.change(lam(x): x * -3 end) is d3
end

.subtract :: (days :: Number) -> DayOfWeek

Returns the DayOfWeek that is the specified number of days before this one.

Examples:

check:
  d1.subtract(10) is d5
end

.between :: (other :: DayOfWeek) -> Number

Returns the number of days between the two given Days.

Examples:

check:
  d1.between(d3) is 2
  d3.between(d1) is 2
end

.add :: (days :: Number) -> DayOfWeek

Returns the DayOfWeek that is the specified number of days after this one.

Examples:

check:
  d1.add(10) is d4
end

1.2.3 DayOfWeek Functions

num-to-day :: (n :: Number) -> DayOfWeek

Obtains an instance of DayOfWeek from a Number value.

Examples:

check:
  num-to-day(3) is d3
  num-to-day(-12) is d2
  num-to-day(22/7)
    raises "Can only create DayOfWeek from Natural Numbers"
end

string-to-day :: (text :: String) -> DayOfWeek

Returns the DayOfWeek from the specified name in trade week respresentation.

Examples:

check:
  string-to-day("THUrsDaY") is d4
  string-to-day("mon")
    raises "Please enter the day in full trade form eg 'Monday'"
end

1.3 month-of-year

Usage:

include month-of-year

import month-of-year as ...

1.3.1 The MonthOfYear Datatype

data MonthOfYear:

| m1
| m2
| m3
| m4
| m5
| m6
| m7
| m8
| m9
| m10
| m11
| m12

end

The MonthOfYear represents the possible months of the standard Gregorian calendar.
The e-nums 1 through 12 happen to coincide with the conventional order of months in the Gregorian Calendar, where 1 represents January, 2 represents February, and so on.
These twelve variables for MonthOfYear may be created and manipulated with the methods and functions below.

1.3.2 MonthOfYear Methods

.get-display-name :: () -> String

Gets the textual representation in the Gregorian Calendar, such as ’January’ or ’December’.

Examples:

check:
  m8.get-display-name() is "August"
end

.get-num :: () -> Number

Gets the MonthOfYear Number value following the Gregorian Calendar Convention

Examples:

check:
  m2.get-num() is 2
end

.length :: (is-leap-year :: Boolean) -> Number

Gets the length of this month in days.

Examples:

check:
  m5.length(true) is 31
  m5.length(false) is 31
  m2.length(true) is 29
  m2.length(false) is 28
end

.arithmetic-f :: (f :: (Number -> Number)) -> MonthOfYear

Returns the MonthOfYear after modifying the given MonthOfYear through ’f’.

Examples:

check:
  m7.arithmetic-f(lam(x): x * -5 end) is m1
end

.subtract :: (months :: MonthOfYear) -> Number

Returns the MonthOfYear that is the specified number of months before this one.

Examples:

check:
   m1.minus(20) is m5
end

.between :: (other :: Number) -> MonthOfYear

Returns the number of months between the specified months

Examples:

check:
   m1.between(m5) is 4
   m5.between(m1) is 4
end

.add :: (months :: Number) -> MonthOfYear

Returns the MonthOfYear that is the specified number of months after this one.

Examples:

check:
  m1.plus(20) is m9
end

1.3.3 MonthOfYear Functions

These functions require the MonthOfYear module to be imported, as indicated in the examples.

num-to-month :: (n :: Number) -> MonthOfYear

Obtains an instance of MonthOfYear from a Number value.

Examples:

check:
  num-to-month(3) is m3
  num-to-month(-39) is m9
  num-to-month(22/7)
    raises "Can only create MonthOfYear from Natural Numbers"
end

string-to-month :: (text :: String) -> MonthOfYear

Returns the MonthOfYear from the specified name in trade week respresentation.

Examples:

check:
  string-to-month("junE") is m6
  string-to-month("JAN")
    raises "Please enter the month in full Gregorian form eg January"
end

1.4 zone-offset

Usage:

include zone-offset

import zone-offset as ...

1.4.1 The ZoneOffset Datatype

data ZoneOffset:

| zone-offset(hours :: Number, minutes :: Number)

end

The ZoneOffset stores the interval between two durations in the form of a time-zone offset.
In effect, a ZoneOffset of (0, 0) represents UTC or GMT, (-5, 0) represents EST, ()and so on.

1.4.2 ZoneOffset Methods

.difference :: (other :: ZoneOffset) -> Duration

Finds the difference between two ZoneOffsets as a Duration.

Examples:

check:
  zone-offset(10, 30).difference(zone-offset(8, 0))
    is duration(0, 0, 0, 2, 30, 0)
  zone-offset(10, 30).difference(zone-offset(13, 15))
    is duration(0, 0, 0, -23, -45, 0)
end

.to-second :: () -> Number

Gets the total ZoneOffset in seconds.

Examples:

check:
  zone-offset(10, 45).to-second()
    is (((10 * 60) + 45) * 60)
end

.to-string :: () -> String

Outputs this ZoneOffset as a String, using an ’+18:00’ format.

Examples:

check:
  zone-offset(-8, -30).to-string() is "-08:30"
  zone-offset(5, 0).to-string() is "+05:00"
end

1.4.3 ZoneOffset Functions

string-to-zone-offset :: (n :: Number) -> ZoneOffset

Obtains an instance of ZoneOffset using a string representation.

Examples:

check:
  offset-to-zone-offset("-1:59") is zone-offset(-1, -59)
  offset-to-zone-offset("+-8:-60") is ...
  offset-to-zone-offset("811")
    raises "ZoneOffset text did not have a sign"
  offset-to-zone-offset("8:11")
    raises "ZoneOffset text did not have a sign"
  offset-to-zone-offset("+811")
    raises "ZoneOffset text input must be in the form '+18:00'"
  offset-to-zone-offset("+a:b")
    raises "ZoneOffset text must have a number for hours"
  offset-to-zone-offset("+0:b")
    raises "ZoneOffset text must have a number for minutes"
end

id-to-zone-offset :: (n :: Number) -> ZoneOffset

Obtains an instance of ZoneOffset using the ZoneId.

Examples:

check:
  id-to-zone-offset(GMT)
    is zone-offset("+", 0, 0)
  id-to-zone-offset(IST)
    is zone-offset("+", 5, 30)
end

hours-to-zone-offset :: (n :: Number) -> ZoneOffset

Obtains an instance of ZoneOffset using hours.

Examples:

check:
  hours-to-zone-offset(-7)
    is zone-offset("-", 7, 0)
end

1.5 zone-id

Usage:

include zone-id

import zone-id as ...

1.5.1 The ZoneId Datatype

data ZoneId:

| A
| ACDT
| ACST
| ACT
| ACT
| ACWST
| ADT
| ADT
| AEDT
| AEST
| AET
| AFT
| AKDT
| AKST
| ALMT
| AMST
| AMST
| AMT
| AMT
| ANAST
| ANAT
| AQTT
| ART
| AST
| AST
| AT
| AWDT
| AWST
| AZOST
| AZOT
| AZST
| AoE
| B
| BNT
| BOT
| BRST
| BRT
| BST
| BST
| BST
| BTT
| C
| CAST
| CAT
| CCT
| CDT
| CDT
| CEST
| CET
| CHADT
| CHAST
| CHOST
| CHOT
| CHUT
| CIDST
| CIST
| CKT
| CLST
| CLT
| COT
| CST
| CST
| CST
| CT
| CVT
| CXT
| ChST
| D
| DAVT
| DDUT
| E
| EASST
| EAST
| EAT
| ECT
| EDT
| EEST
| EET
| EGST
| EGT
| EST
| ET
| F
| FET
| FJST
| FJT
| FKST
| FKT
| FNT
| G
| GALT
| GAMT
| GET
| GFT
| GILT
| GMT
| GST
| GST
| GYT
| H
| HDT
| HKT
| HOVST
| HOVT
| HST
| I
| ICT
| IDT
| IOT
| IRDT
| IRKST
| IRKT
| IRST
| IST
| IST
| IST
| JST
| K
| KGT
| KOST
| KRAST
| KRAT
| KST
| KUYT
| L
| LHDT
| LHST
| LINT
| M
| MAGST
| MAGT
| MART
| MAWT
| MDT
| MHT
| MMT
| MSD
| MSK
| MST
| MT
| MUT
| MVT
| MYT
| N
| NCT
| NDT
| NFDT
| NFT
| NOVST
| NOVT
| NPT
| NRT
| NST
| NUT
| NZDT
| NZST
| O
| OMSST
| OMST
| P
| PDT
| PET
| PETST
| PETT
| PGT
| PHOT
| PHT
| PKT
| PMDT
| PMST
| PONT
| PST
| PST
| PT
| PWT
| PYST
| PYT
| PYT
| Q
| QYZT
| R
| RET
| ROTT
| S
| SAKT
| SAMT
| SAST
| SBT
| SCT
| SGT
| SRET
| SRT
| SST
| SYOT
| T
| TAHT
| TFT
| TJT
| TKT
| TLT
| TMT
| TOST
| TOT
| TRT
| TVT
| U
| ULAST
| ULAT
| UTC
| UYST
| UYT
| UZT
| V
| VET
| VLAST
| VLAT
| VOST
| VUT
| W
| WAKT
| WARST
| WAST
| WAT
| WEST
| WET
| WFT
| WGST
| WGT
| WIB
| WIT
| WITA
| WST
| WT
| X
| Y
| YAKST
| YAKT
| YAPT
| YEKST
| YEKT
| Z

end

The ZoneId stores the Time-Zone codes of all ZoneOffsets around the world.
Each code is mapped to a specific offset in a key-value pair dictionary to allow conversion between ZoneId and ZoneOffset, thereby within Temporal objects.

1.5.2 ZoneId Methods

.get-zone-offset :: () -> ZoneOffset

Gets the ZoneOffset of the ZoneId.

Examples:

check:
  IST.get-zone-offset()
    is zone-offset(5, 30)
  UTC.get-zone-offset()
    is zone-offset(0, 0)
end

.to-string :: () -> String

Outputs this ZoneId as a String.

Examples:

check:
  IST.to-string() is "IST"
  EST.to-string() is "EST"
end

1.5.3 ZoneId Functions

These functions require the ZoneId module to be imported, as indicated in the examples.

string-to-zone-id :: (text :: Number) -> ZoneId

Obtains an instance of ZoneId from a String ensuring that the ZoneId is supported.

Examples:

check:
  string-to-zone-id("IST") is IST
  string-to-zone-id("EST") is EST
end

system-default-zone-id :: () -> ZoneId

Gets the system default ZoneId.

Examples:

check:
  nothing is nothing
end

1.6 temporal

Usage:

include temporal

import temporal as ...

1.6.1 The Temporal Datatype

data Temporal:

| naive-date(year :: DateTimeYear, month :: DateTimeMonth, day :: DateTimeDay)
| naive-time(hour :: DateTimeHour, minute :: DateTimeMinute, second :: DateTimeSecond)
| naive-date-time(year :: DateTimeYear, month :: DateTimeMonth, day :: DateTimeDay, hour :: DateTimeHour, minute :: DateTimeMinute, second :: DateTimeSecond)
| offset-time(hour :: DateTimeHour, minute :: DateTimeMinute, second :: DateTimeSecond, offset :: ZoneOffset)
| utc-date-time(year :: DateTimeYear, month :: DateTimeMonth, day :: DateTimeDay, hour :: DateTimeHour, minute :: DateTimeMinute, second :: DateTimeSecond)
| offset-date-time(year :: DateTimeYear, month :: DateTimeMonth, day :: DateTimeDay, hour :: DateTimeHour, minute :: DateTimeMinute, second :: DateTimeSecond, offset :: ZoneOffset)
| zoned-date-time(year :: DateTimeYear, month :: DateTimeMonth, day :: DateTimeDay, hour :: DateTimeHour, minute :: DateTimeMinute, second :: DateTimeSecond, zone-id :: ZoneID)

end

DateTimeYear is any Whole Number

DateTimeMonth is any Integer between 1 and 12 inclusive

DateTimeDay is any Integer between 1 and 31 inclusive

Validation of the day falling in the range of the month’s maximum number of days in the year is enforced when using the DateTime in methods and functions

DateTimeHour is any Integer between 1 and 12 inclusive

DateTimeMinute is any Integer between 0 and 59 inclusive

DateTimeSecond is any Rational within [0, 60)

The Temporal type has several branches, each of which represents a different kind of temporal object, i.e. date, time, or date-time. First, there are three timezone-ignorant branches provided for dates and times, and multiple timezone-aware branches as well. Timezone data is represented in three ways: (a) UTC time, (b) different ZoneOffsets, and (c) ZoneIDs, which will map to specific offsets.
DateTimes with different timezone types are distinct and do not mix, but can be converted to and from each other.
Among other features, these types support: - Addition and subtraction of durations from dates, times, and date-times. - Before/after and equality comparisons among timezone-aware and timezone-ignorant types. - Parsing and formatting operations to and from different representations of datetimes (TODO).
Each of these branches is also associated with a type, thereby allowing type annotations within user programs.

1.6.2 Temporal Attribute Types

type NaiveDate = Temporal%(is-naive-date) type NaiveTime = Temporal%(is-naive-time) type NaiveDateTime = Temporal%(is-naive-date-time)

type UTCDateTime = Temporal%(is-utc-date-time) type UTCDateTimeValid = UTCDateTime%(is-date-time-valid)

type OffsetTime = Temporal%(is-offset-time) type OffsetHour = Number%(is-offset-hour) type OffsetDateTime = Temporal%(is-offset-date-time) type OffsetDateTimeValid = UTCDateTime%(is-date-time-valid)

type ZonedDateTime = Temporal%(is-zoned-date-time)

type DateTimeYear = Number%(is-date-time-year) type DateTimeMonth = Number%(is-date-time-month) type DateTimeDay = Number%(is-date-time-day) type DateTimeHour = Number%(is-date-time-hour) type DateTimeMinute = Number%(is-date-time-minute) type DateTimeSecond = Number%(is-date-time-second)

1.6.3 Temporal Methods

TODO

1.6.4 Temporal Functions

These functions require the Temporal module to be imported, as indicated in the examples.

TODO

1.6.5 naive-date

Usage:

include naive-date

import naive-date as ...

1.6.5.1 The NaiveDate Datatype

TODO

1.6.5.2 NaiveDate Methods

.at-start-of-day :: () -> NaiveDateTime

Combines this date with the time of midnight to create a Temporal%(is-naive-date-time) at the start of this date.

Examples:

check:
1 is 1
end

.zoned-start-of-day :: (zone-id :: ZoneId) -> ZonedDateTime

Returns a zoned date-time from this date at the earliest valid time according to the rules in the time-zone.‘

Examples:

check:
1 is 1
end

.at-time-any :: (
hour :: Number,
minute :: Number,
second :: Number
)
-> NaiveDateTime

Combines this date with a time to create a Temporal%(is-naive-date-time).

Examples:

check:
1 is 1
end

.at-naive-time :: (time :: NaiveTime) -> NaiveDateTime

Combines this date with a time to create a Temporal%(is-naive-date-time).

Examples:

check:
1 is 1
end

.at-offset-time :: (time :: OffsetTime) -> OffsetDateTime

Combines this date with an offset time to create an Temporal%(is-offset-date-time).

Examples:

check:
1 is 1
end

.get-day-of-month :: () -> Number

Gets the value of the day unit.

Examples:

check:
1 is 1
end

.get-month-value :: () -> Number

"Gets the value of the month unit from 1 to 12."

Examples:

check:
1 is 1
end

.get-year :: () -> Number

"Gets the value of the year unit."

Examples:

check:
1 is 1
end

.is-leap-year :: () -> Boolean

Checks if the year of this date is a leap year, according to the ISO proleptic calendar system rules.

Examples:

check:
1 is 1
end

.is-before :: (compare-with :: NaiveDate) -> Boolean

Determines whether the current date occurs before the date it is being compared with.

Examples:

check:
1 is 1
end

.is-after :: (compare-with :: NaiveDate) -> Boolean

Determines whether the current date occurs after the date it is being compared with.

Examples:

check:
1 is 1
end

.until :: (other :: NaiveDate) -> Duration

Calculates the amount of time until another date.

Examples:

check:
1 is 1
end

.minus :: (other :: NaiveDate) -> Duration

Calculates the duration of days to add to ’other’ to get the date in question.

Examples:

check:
1 is 1
end

.minus-duration :: (amount :: Duration) -> NaiveDate

Returns a copy of this date with the specified duration subtracted. (month => 30 days, year => 365 days inside a duration)

Examples:

check:
1 is 1
end

.minus-days :: (days :: Number) -> NaiveDate

Returns a copy of this NaiveDate with the specified duration of days subtracted.

Examples:

check:
1 is 1
end

minus-weeks :: (self :: NaiveDate, weeks :: Number) -> NaiveDate

Returns a copy of this NaiveDate with the specified duration of weeks subtracted.

.minus-months :: (months :: Number) -> NaiveDate

Returns a copy of this NaiveDate with the specified duration of months subtracted.

Examples:

check:
1 is 1
end

.minus-years :: (years :: Number) -> NaiveDate

Returns a copy of this NaiveDate with the specified duration of years subtracted.

Examples:

check:
1 is 1
end

.plus-duration :: (amount :: Duration) -> NaiveDate

Returns a copy of this date with the specified duration added. (month => 30 days, year => 365 days inside a duration)

Examples:

check:
1 is 1
end

.plus-days :: (days :: Number) -> NaiveDate

Returns a copy of this NaiveDate with the specified duration of days added.

Examples:

check:
1 is 1
end

.plus-weeks :: (weeks :: Number) -> NaiveDate

Returns a copy of this NaiveDate with the specified duration of weeks added.

.plus-months :: (months :: Number) -> NaiveDate

Returns a copy of this NaiveDate with the specified duration of months added.

Examples:

check:
1 is 1
end

.plus-years :: (years :: Number) -> NaiveDate

Returns a copy of this NaiveDate with the specified duration of years added.

Examples:

check:
1 is 1
end

.to-string :: () -> String

Outputs this date as a String, such as 2007-12-03.

Examples:

check:
1 is 1
end

.get-remaining-days-in-year :: () -> Number

Returns the number of days remaining in a year.

Examples:

check:
1 is 1
end

.get-days-in-year-till-date :: () -> Number

Returns the number of days that have occurred in a year so far.

Examples:

check:
1 is 1
end

.with-unit :: (unit :: TemporalUnit, val :: Number) -> NaiveDate

Returns a copy of this date with the specified unit set to a new value.

Examples:

check:
1 is 1
end

.with-day :: (day :: Number) -> NaiveDate

Returns a copy of this NaiveDate with the day-of-month altered.

Examples:

check:
1 is 1
end

.with-month :: (month :: Number) -> NaiveDate

Returns a copy of this NaiveDate with the month value altered.

Examples:

check:
1 is 1
end

.with-year :: (year :: Number) -> NaiveDate

Returns a copy of this NaiveDate with the year value altered.

Examples:

check:
1 is 1
end

.successor :: () -> NaiveDate

Returns a copy of this NaiveDate with the day incremented by 1.

Examples:

check:
1 is 1
end

.predecessor :: () -> NaiveDate

Returns a copy of this NaiveDate with the day decreased by 1.

Examples:

check:
1 is 1
end

1.6.6 naive-time

Usage:

include naive-time

import naive-time as ...

1.6.6.1 NaiveTime Methods

.at-date :: (date :: NaiveDate) -> NaiveDateTime

Combines this time with a date to create a Temporal%(is-naive-date-time).

Examples:

check:
1 is 1
end

.at-offset :: (offset :: ZoneOffset) -> OffsetTime

Combines this time with an offset to create an Temporal%(is-offset-time).

Examples:

check:
1 is 1
end

.get-second :: () -> Number

Gets the value of the seconds unit.

Examples:

check:
1 is 1
end

.get-minute :: () -> Number

Gets the value of the minutes unit.

Examples:

check:
1 is 1
end

.get-hour :: () -> Number

Gets the value of the hours unit.

Examples:

check:
1 is 1
end

.is-after :: (other :: NaiveTime) -> Boolean

Checks if this Temporal%(is-naive-time) is after the specified Temporal%(is-naive-time).

Examples:

check:
1 is 1
end

.is-before :: (other :: NaiveTime) -> Boolean

Checks if this Temporal%(is-naive-time) is before the specified Temporal%(is-naive-time).

Examples:

check:
1 is 1
end

.minus :: (amt :: Duration) -> NaiveTime

Returns a copy of this time with the specified amount subtracted.

Examples:

check:
1 is 1
end

.minus-seconds :: (seconds :: Number) -> NaiveTime

Returns a copy of this time with the specified number of seconds subtracted.

Examples:

check:
1 is 1
end

.minus-minutes :: (minutes :: Number) -> NaiveTime

Returns a copy of this time with the specified number of minutes subtracted.

Examples:

check:
1 is 1
end

.minus-hours :: (hours :: Number) -> NaiveTime

Returns a copy of this time with the specified number of hours subtracted.

Examples:

check:
1 is 1
end

.plus :: (amt :: Duration) -> NaiveTime

Returns a copy of this time with the specified amount added.

Examples:

check:
1 is 1
end

.plus-seconds :: (seconds :: Number) -> NaiveTime

Returns a copy of this time with the specified number of seconds added.

Examples:

check:
1 is 1
end

.plus-minutes :: (minutes :: Number) -> NaiveTime

Returns a copy of this time with the specified number of minutes added.

Examples:

check:
1 is 1
end

.plus-hours :: (hours :: Number) -> NaiveTime

Returns a copy of this time with the specified number of hours added.

Examples:

check:
1 is 1
end

to-string :: (self :: NaiveTime) -> String

Outputs this time as a String, such as 10:15:30

Examples:

check:
1 is 1
end

.to-second-of-day :: () -> Number

Extracts the time as seconds of day, from 0 to 24 * 60 * 60 - 1.

Examples:

check:
1 is 1
end

.until :: (other :: NaiveTime) -> Duration

Calculates the normalized duration of time until another time.

Examples:

check:
1 is 1
end

.with-unit :: (unit :: TemporalUnit, val :: Number) -> NaiveTime

Returns a copy of this time with the specified unit set to a new value.

Examples:

check:
1 is 1
end

.with-second :: (second :: Number) -> NaiveTime

Returns a copy of this temporal with the seconds altered.

Examples:

check:
1 is 1
end

.with-minute :: (minute :: Number) -> NaiveTime

Returns a copy of this temporal with the minutes altered.

Examples:

check:
1 is 1
end

.with-hour :: (hour :: Number) -> NaiveTime

Returns a copy of this temporal with the hours altered.

Examples:

check:
1 is 1
end

1.6.6.2 NaiveTime Functions

These functions require the Temporal module to be imported, as indicated in the examples.

naive-time-of-any :: (
hour :: Number,
month :: Number,
day :: Number
)
-> NaiveTime

Obtains an instance of NaiveTime from a year, month and day.

Examples:

import temporal as T
check:
1 is 1
end

naive-time-now :: () -> NaiveTime

Obtains the current time from the system clock in the default time-zone.

Examples:

import temporal as T
check:
1 is 1
end

naive-time-from-zone-now :: () -> NaiveTime

Obtains the current time from the system clock in the specified time-zone.

Examples:

import temporal as T
check:
1 is 1
end

parse-naive-time :: (text :: String) -> NaiveTime

Obtains an instance of Temporal%(is-naive-time) from a text string such as 23:59:59

Examples:

import temporal as T
check:
1 is 1
end

1.6.7 utc-date-time

Usage:

include utc-date-time

import utc-date-time as ...

1.6.7.1 The UTCDateTime Type

type UTCDateTime = Temporal%(is-utc-date-time)

UTCDateTime info...
UTCDateTime must always be valid, where a valid UTCDateTime has rational seconds within [0, 60), integer minutes within [0, 60), integer hours within [0, 24), days between 1 (inclusive) and the valid number of days for the appropriate month of the appropriate year, integer months within [0, 12], and whole number year

1.6.7.2 UTCDateTime Methods

.at-offset :: (date :: ZoneOffset) -> OffsetDateTime

Combines this date-time with an offset to create an OffsetDateTime.

Examples:

check:
1 is 1
end

.at-zone :: (offset :: ZoneId) -> UTCDateTime

Combines this date-time with a time-zone to create a ZonedDateTime.

Examples:

check:
1 is 1
end

.get-naive-date :: () -> NaiveDate

Gets the NaiveDate from the date time.

Examples:

check:
1 is 1
end

.get-naive-time :: () -> NaiveTime

Gets the NaiveTime from the date time.

Examples:

check:
1 is 1
end

.compare :: (other :: UTCDateTime) -> Number

Returns 1 if this UTCDateTime is before the other, 0 if both contain the same date-time, -1 if the other is before this UTCDateTime.

Examples:

check:
1 is 1
end

.is-leap-year :: () -> Boolean

Checks if the year is a leap year, according to the ISO proleptic calendar system rules.

Examples:

check:
1 is 1
end

.plus :: (amt :: Duration) -> UTCDateTime

Returns a copy of this UTCDateTime with the specified amount added.

Examples:

check:
1 is 1
end

.plus-weeks :: (weeks :: Number) -> UTCDateTime

Returns a copy of this temporal with the specified number of weeks added."

Examples:

check:
1 is 1
end

.minus :: (amt :: Duration) -> UTCDateTime

Returns a copy of this UTCDateTime with the specified amount subtracted.

Examples:

check:
1 is 1
end

.minus-weeks :: (weeks :: Number) -> UTCDateTime

Returns a copy of this temporal with the specified number of weeks subtracted."

Examples:

check:
1 is 1
end

.until :: (other :: UTCDateTime) -> Duration

Calculates the duration of time until another UTCDateTime.

Examples:

check:
1 is 1
end

to-string :: (self :: UTCDateTime) -> String

Outputs this date-time as a String, such as 2007-12-03T10:15:30.

Examples:

check:
1 is 1
end

.set-unit :: (unit :: TemporalUnit, val :: Number) -> UTCDateTime

Returns a copy of this UTCDateTime with the specified unit set to a new value.

The UTCDateTime is also normalized internally so that even if a negative or ’invalid’ value (such as 31 days in February) is passed, a valid, equivalent UTCDateTime will be returned

Examples:

check:
1 is 1
end

1.6.7.3 UTCDateTime Functions

string-to-utc-date-time :: (text :: String) -> UTCDateTime

Obtains an instance of UTCDateTime from a text string such as ’2007-12-03T10:15:30’.

Examples:

check:
1 is 1
end

1.6.8 offset-time

Usage:

include offset-time

import offset-time as ...

data ZoneOffset:

| zoned-offset(hour :: OffsetHour, minute :: DateTimeMinute)

end

Offset Hour is any Integer that must be between (inclusive) -12 and 14

1.6.8.1 OffsetTime Methods

.at-date :: (date :: NaiveDate) -> OffsetDateTime

Combines this time with a date to create a Temporal%(is-offset-date-time).

Examples:

check:
1 is 1
end

.at-offset :: (offset :: ZoneOffset) -> OffsetTime

Combines this time with an offset to create an Temporal%(is-offset-time).

Examples:

check:
1 is 1
end

.get-second :: () -> Number

Gets the value of the seconds unit.

Examples:

check:
1 is 1
end

.get-minute :: () -> Number

Gets the value of the minutes unit.

Examples:

check:
1 is 1
end

.get-hour :: () -> Number

Gets the value of the hours unit.

Examples:

check:
1 is 1
end

.get-naive-time :: () -> NaiveTime

Gets the NaiveTime component from the OffsetTime in question.

Examples:

check:
1 is 1
end

.to-utc-time :: () -> OffsetTime

Returns an OffsetTime with the time component representing the equivalent time in UTC and the ZoneOffset set to zero.

Examples:

check:
1 is 1
end

.with-offset-same-naive :: () -> OffsetTime

Returns a copy of this OffsetTime with an offset of zero magnitude ensuring that the result has the same naive time.

Examples:

check:
1 is 1
end

.is-after :: (other :: OffsetTime) -> Boolean

Checks if this Temporal%(is-offset-time) is after the specified Temporal%(is-offset-time).

Examples:

check:
1 is 1
end

.is-before :: (other :: OffsetTime) -> Boolean

Checks if this Temporal%(is-offset-time) is before the specified Temporal%(is-offset-time).

Examples:

check:
1 is 1
end

.minus :: (amt :: Duration) -> OffsetTime

Returns a copy of this OffsetTime with the specified amount subtracted.

Examples:

check:
1 is 1
end

.minus-seconds :: (seconds :: Number) -> OffsetTime

Returns a copy of this OffsetTime with the specified number of seconds subtracted.

Examples:

check:
1 is 1
end

.minus-minutes :: (minutes :: Number) -> OffsetTime

Returns a copy of this OffsetTime with the specified number of minutes subtracted.

Examples:

check:
1 is 1
end

.minus-hours :: (hours :: Number) -> OffsetTime

Returns a copy of this OffsetTime with the specified number of hours subtracted.

Examples:

check:
1 is 1
end

.plus :: (amt :: Duration) -> OffsetTime

Returns a copy of this OffsetTime with the specified amount added.

Examples:

check:
1 is 1
end

.plus-seconds :: (seconds :: Number) -> OffsetTime

Returns a copy of this OffsetTime with the specified number of seconds added.

Examples:

check:
1 is 1
end

.plus-minutes :: (minutes :: Number) -> OffsetTime

Returns a copy of this OffsetTime with the specified number of minutes added.

Examples:

check:
1 is 1
end

.plus-hours :: (hours :: Number) -> OffsetTime

Returns a copy of this OffsetTime with the specified number of hours added.

Examples:

check:
1 is 1
end

to-string :: (self :: OffsetTime) -> String

Outputs this time as a String, such as 10:15:30+00:30.

Examples:

check:
1 is 1
end

.to-second-of-day :: () -> Number

Extracts the time as seconds of day, from 0 to 24 * 60 * 60 - 1.

Examples:

check:
1 is 1
end

.until :: (other :: OffsetTime) -> Duration

Calculates the normalized duration of time until another OffsetTime.

Examples:

check:
1 is 1
end

.with-unit :: (unit :: TemporalUnit, val :: Number) -> OffsetTime

Returns a copy of this time with the specified unit set to a new value.

Examples:

check:
1 is 1
end

.with-second :: (second :: Number) -> OffsetTime

Returns a copy of this OffsetTime with the seconds altered.

Examples:

check:
1 is 1
end

.with-minute :: (minute :: Number) -> OffsetTime

Returns a copy of this OffsetTime with the minutes altered.

Examples:

check:
1 is 1
end

.with-hour :: (hour :: Number) -> OffsetTime

Returns a copy of this OffsetTime with the hours altered.

Examples:

check:
1 is 1
end

1.6.9 offset-date-time

Usage:

include offset-date-time

import offset-date-time as ...

1.6.9.1 The OffsetDateTime Type

type OffsetDateTime = Temporal%(is-offset-date-time)

OffsetDateTime info...
OffsetDateTime must always be valid, where a valid OffsetDateTime has rational seconds within [0, 60), integer minutes within [0, 60), integer hours within [0, 24), days between 1 (inclusive) and the valid number of days for the appropriate month of the appropriate year, integer months within [0, 12], and whole number year
An OffsetDateTime must also have a valid offset following the validity rules described for ZoneOffset in the OffsetTime Section

1.6.9.2 OffsetDateTime Methods

.at-naive :: () -> OffsetDateTime

Extracts the date time and converts into a NaiveDateTime.

Examples:

check:
1 is 1
end

.at-utc :: () -> UTCDateTime

Converts the date time into that at UTC.

Examples:

check:
1 is 1
end

.at-offset-same-utc :: (offset :: ZoneOffset) -> OffsetDateTime

Combines this date-time with an offset to create an OffsetDateTime ensuring that the result has the same UTCDateTime.

Examples:

check:
1 is 1
end

.at-offset-same-naive :: (offset :: ZoneOffset) -> NaiveTime

Combines this date-time with an offset to create an OffsetDateTime trying to keep the same naive date and time.

Examples:

check:
1 is 1
end

.at-zone-same-utc :: (zone :: ZoneId) -> OffsetDateTime

Combines this date-time with a time-zone to create a ZonedDateTime ensuring that the result has the same UTCDateTime.

Examples:

check:
1 is 1
end

.at-zone-same-naive :: (zone :: ZoneId) -> NaiveTime

Combines this date-time with a time-zone to create a ZonedDateTime trying to keep the same naive date and time.

Examples:

check:
1 is 1
end

.get-naive-date :: () -> NaiveDate

Gets the NaiveDate from the date time.

Examples:

check:
1 is 1
end

.get-naive-time :: () -> NaiveTime

Gets the NaiveTime from the date time.

Examples:

check:
1 is 1
end

.compare :: (other :: OffsetDateTime) -> Number

Returns 1 if this OffsetDateTime is before the other, 0 if both contain the same date-time, -1 if the other is before this OffsetDateTime.

Examples:

check:
1 is 1
end

.is-leap-year :: () -> Boolean

Checks if the year is a leap year, according to the ISO proleptic calendar system rules.

Examples:

check:
1 is 1
end

.plus :: (amt :: Duration) -> OffsetDateTime

Returns a copy of this OffsetDateTime with the specified amount added.

Examples:

check:
1 is 1
end

.plus-weeks :: (weeks :: Number) -> OffsetDateTime

Returns a copy of this temporal with the specified number of weeks added."

Examples:

check:
1 is 1
end

.minus :: (amt :: Duration) -> OffsetDateTime

Returns a copy of this OffsetDateTime with the specified amount subtracted.

Examples:

check:
1 is 1
end

.minus-weeks :: (weeks :: Number) -> OffsetDateTime

Returns a copy of this temporal with the specified number of weeks subtracted."

Examples:

check:
1 is 1
end

.until :: (other :: OffsetDateTime) -> Duration

Calculates the duration of time until another OffsetDateTime.

Examples:

check:
1 is 1
end

to-string :: (self :: OffsetDateTime) -> String

Outputs this date-time as a String, such as 2007-12-03T10:15:30.

Examples:

check:
1 is 1
end

.set-unit :: (unit :: TemporalUnit, val :: Number) -> OffsetDateTime

Returns a copy of this OffsetDateTime with the specified unit set to a new value.

The OffsetDateTime is also normalized internally so that even if a negative or ’invalid’ value (such as 31 days in February) is passed, a valid, equivalent OffsetDateTime will be returned

Examples:

check:
1 is 1
end

1.6.9.3 OffsetDateTime Functions

string-to-offset-date-time :: (text :: String) -> OffsetDateTime

Obtains an instance of OffsetDateTime from a text string such as ’2007-12-03T10:15:30+05:00’.

Examples:

check:
1 is 1
end