Dates Utility
Dates value operations. No hidden external Service communication.
Contract Dates · 1.0.0-draft.1
Functions
now
Current datetime.
No Arguments
Returns: core.datetime
today
Current calendar date in the named timezone.
| Argument | Type | Required | Default |
|---|---|---|---|
| timezone | core.string | Yes | — |
Returns: core.date
date
Parse yyyy-MM-dd strictly.
| Argument | Type | Required | Default |
|---|---|---|---|
| text | core.string | Yes | — |
Returns: core.date
datetime
Parse an ISO datetime containing an explicit offset or Z.
| Argument | Type | Required | Default |
|---|---|---|---|
| text | core.string | Yes | — |
Returns: core.datetime
parse
Parse date/datetime using an explicit pattern and policies.
| Argument | Type | Required | Default |
|---|---|---|---|
| text | core.string | Yes | — |
| kind | core.string | Yes | — |
| pattern | core.string | Yes | — |
| timezone | core.string? | No | null |
| policy | Dates.ParsePolicy? | No | null |
Returns: core.date | core.datetime
add
Add an integer amount with the rules in this contract.
| Argument | Type | Required | Default |
|---|---|---|---|
| value | core.date | core.datetime | Yes | — |
| amount | core.integer | Yes | — |
| unit | core.string | Yes | — |
| options | Dates.AddOptions? | No | null |
Returns: core.date | core.datetime
startOfDay
Earliest valid instant on that local date; a wholly skipped date fails.
| Argument | Type | Required | Default |
|---|---|---|---|
| date | core.date | Yes | — |
| timezone | core.string | Yes | — |
Returns: core.datetime
before
Same-type comparison.
| Argument | Type | Required | Default |
|---|---|---|---|
| left | core.date | core.datetime | Yes | — |
| right | core.date | core.datetime | Yes | — |
Returns: core.boolean
after
Same-type comparison.
| Argument | Type | Required | Default |
|---|---|---|---|
| left | core.date | core.datetime | Yes | — |
| right | core.date | core.datetime | Yes | — |
Returns: core.boolean
between
Decimal elapsed datetime difference in milliseconds/seconds/minutes/hours.
| Argument | Type | Required | Default |
|---|---|---|---|
| start | core.datetime | Yes | — |
| end | core.datetime | Yes | — |
| unit | core.string | Yes | — |
Returns: core.decimal
format
String; datetime formatting requires explicit timezone, date formatting does not.
| Argument | Type | Required | Default |
|---|---|---|---|
| value | core.date | core.datetime | Yes | — |
| pattern | core.string | Yes | — |
| timezone | core.string? | No | null |
Returns: core.string
Behavior
- Dates are calendar values; datetimes are instants. Parsing is strict and never chooses an implicit machine timezone.
- Calendar date addition accepts days, weeks, months and years. Datetime elapsed addition accepts milliseconds, seconds, minutes and hours. Datetime calendar addition requires options.timezone and preserves local clock time.
- Month/year addition defaults to the last valid destination day; monthEnd reject requests failure. Daylight-saving gaps/overlaps fail unless gap forward or overlap earlier/later explicitly resolves them.
- Pattern fields are yyyy, MM, dd, HH, mm, ss, SSS and XXX with quoted literal text. kind is date or datetime. Invalid type/unit combinations, zones and dates fail.
- startOfDay is the earliest valid instant of the local date; wholly skipped dates fail. Datetime format requires an explicit timezone. Adding a calendar day is not adding 24 elapsed hours.