Instant

The instant data type in Filtrera is used to represent a precise instant in time, formatted according to the ISO 8601 standard. This reference guide provides a detailed specification of the instant data type, its syntax, and usage for users already familiar with the concept.

Syntax

The instant type is used to define date and time values with optional timezone components. The type notation for instant is instant. An instant literal always includes a time component (using the T separator).

Examples

from 2023-01-01T15:14:13
from 2023-01-01T15:14:13.123  // UTC by default
from 2023-01-01T15:14:13.123Z // Explicitly UTC
from 2023-01-01T15:14:13.123+01:00 // UTC+1

In these examples:

• 2023-01-01T15:14:13 includes date and time.
• 2023-01-01T15:14:13.123 includes date, time, and milliseconds (UTC by default).
• 2023-01-01T15:14:13.123Z includes date, time, and milliseconds explicitly in UTC.
• 2023-01-01T15:14:13.123+01:00 includes date, time, milliseconds, and a timezone offset of UTC+1.

Note

In earlier versions of Filtrera, a date-only literal like 2023-01-01 would create an instant at UTC midnight. This now creates a date value instead. To create an instant from a date, use the conversion operator: 2023-01-01 :: instant.

Type Notation for instant

When defining parameters or variables, you can use the type notation instant for the instant data type.

Example

param eventTime: instant
let formattedTime = $'The event is scheduled at {eventTime}.'
from formattedTime

In this example, eventTime is defined as an instant type, and formattedTime incorporates eventTime.

Default Stringification

The default string representation of an instant in Filtrera is always a fully specified ISO 8601 format. Runtimes may provide additional features to format strings based on other formats, but this is not part of the native language.

Example

let eventTime = 2023-01-01T15:14:13.123+01:00

from eventTime

In this example, eventTime will be stringified as 2023-01-01T15:14:13.123+01:00.

Literal Types

As with all other primitive types, instant types can be literal:

param myParam: 2023-01-01T15:14:13.123Z

Converting Between Instant and Date

Instants can be converted to and from dates using the :: conversion operator. See the Conversion article for details.

// Instant to date: extracts the date component
from 2023-06-15T14:30:00+02:00 :: date
// Result: 2023-06-15

// Date to instant: creates an instant at UTC midnight
from 2023-06-15 :: instant
// Result: 2023-06-15T00:00:00.000+00:00

Practical Usage

Example: Storing and Using Instants

let startTime = 2023-01-01T10:00:00
let endTime = 2023-01-01T12:00:00

let duration = $'The event starts at {startTime} and ends at {endTime}.'
from duration

In this example, startTime and endTime are stored as instant values, and duration combines them into a formatted string.

Example: Using Instants with Timezone

let meetingTimeUTC = 2023-01-01T09:00:00Z
let meetingTimeLocal = 2023-01-01T10:00:00+01:00

let message = $'The meeting time is {meetingTimeUTC} UTC, which is {meetingTimeLocal} local time.'
from message

In this example, meetingTimeUTC is an instant in UTC, and meetingTimeLocal is the same instant with a timezone offset of UTC+1. The message incorporates both times.

Summary

The instant data type in Filtrera allows you to work with precise date and time values effectively. By understanding its syntax and usage, including the optional timezone component, you can accurately represent and manipulate instants in time. The default stringification of an instant is always a fully specified ISO 8601 format, ensuring consistency. For date-only values without a time component, see the date data type.