Date

The date data type in Filtrera represents a calendar date without a time component, formatted as an ISO 8601 date. This reference guide provides a detailed specification of the date data type, its syntax, and usage.

Syntax

The date type is used to define date values without any time or timezone information. The type notation for date is date.

Examples

from 2023-01-01
from 2023-12-25
from 2000-06-15

In these examples:

• 2023-01-01 represents January 1st, 2023.
• 2023-12-25 represents December 25th, 2023.
• 2000-06-15 represents June 15th, 2000.

Note

This is a breaking change from earlier versions of Filtrera, where a date literal like 2023-01-01 would create an instant at UTC midnight. It now creates a date value instead.

Type Notation for date

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

Example

param eventDate: date
let formattedDate = $'The event is scheduled on {eventDate}.'
from formattedDate

In this example, eventDate is defined as a date type, and formattedDate incorporates eventDate.

Default Stringification

The default string representation of a date in Filtrera is the ISO 8601 date format: YYYY-MM-DD.

Example

let eventDate = 2023-01-15

from eventDate

In this example, eventDate will be stringified as 2023-01-15.

Literal Types

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

param myParam: 2023-01-01

Arithmetic with Dates

Dates support addition and subtraction with durations that represent calendar units: days, weeks, months, and years. Sub-day durations (like hours, minutes, etc.) are not supported with dates.

Adding Durations

let start = 2023-01-01
from start + 10 days    // Result: 2023-01-11
from start + 2 weeks    // Result: 2023-01-15
from start + 1 months   // Result: 2023-02-01
from start + 1 years    // Result: 2024-01-01

Subtracting Durations

let start = 2023-06-15
from start - 5 days     // Result: 2023-06-10
from start - 2 weeks    // Result: 2023-06-01
from start - 1 months   // Result: 2023-05-15
from start - 1 years    // Result: 2022-06-15

Subtracting Two Dates

Subtracting two dates results in a duration in days:

let start = 2023-01-01
let end = 2023-01-31

from end - start  // Result: 30 days

For more details on arithmetic operations, refer to the Arithmetic article.

Converting Between Date and Instant

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

Date to Instant

Converting a date to an instant creates an instant at UTC midnight:

from 2023-06-15 :: instant
// Result: 2023-06-15T00:00:00.000+00:00

Instant to Date

Converting an instant to a date extracts the date component:

from 2023-06-15T14:30:00+02:00 :: date
// Result: 2023-06-15

Practical Usage

Example: Calculating a Deadline

let startDate = 2023-03-01
let duration = 90 days
let deadline = startDate + duration

let message = $'The project starts on {startDate} and the deadline is {deadline}.'
from message

In this example, startDate is a date, duration is 90 days, and deadline is calculated by adding duration to startDate.

Example: Days Between Dates

let orderDate = 2023-01-15
let deliveryDate = 2023-01-22

let shippingDays = deliveryDate - orderDate
let message = $'Shipping takes {shippingDays}.'
from message

In this example, the difference between two dates is calculated, resulting in a duration in days.

Summary

The date data type in Filtrera allows you to work with calendar dates without time components. It uses the ISO 8601 date format (YYYY-MM-DD) and supports arithmetic with calendar-unit durations (days, weeks, months, years). Subtracting two dates produces a duration in days. Dates can be converted to and from instants using the :: operator, where date-to-instant creates a value at UTC midnight, and instant-to-date extracts the date component.