Skip to content
Filtrera

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 time and timezone components. The type notation for instant is instant.

Basic Syntax

An instant can be defined with or without time and timezone information. When the time component is omitted, it defaults to midnight (00:00:00.000).

Examples

from 2023-01-01
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-01 represents a date with the time defaulting to midnight (00:00:00.000).
  • 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.

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

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.

Example: Defaulting to Midnight

let dateOnly = 2023-01-01


let message = $'The date is {dateOnly}, which defaults to midnight.'
from message

In this example, dateOnly is an instant representing 2023-01-01 at midnight (00:00:00.000). The message explains the default time.

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 time and timezone components, you can accurately represent and manipulate instants in time. When the time component is omitted, it defaults to midnight, making it convenient to work with dates. The default stringification of an instant is always a fully specified ISO 8601 format, ensuring consistency. Leveraging these features enables you to create reliable and robust Filtrera programs that handle date and time values with precision.