Date and Time
Dates and times are central to business operations and planning and are an essential part of Elara and East.
Date-time values and type
East provides a single date-time type for represent timestamps, dates, etc.
It has millisecond precision and does not contain timezone information or other metadata.
The East type for date-times is DateTimeType, and the JavaScript representation is the standard Date object.
| East type | Example value (JavaScript) | East object notation |
|---|---|---|
DateTimeType | new Date("2023-07-01T12:00:00.000Z") | 2023-07-01T12:00:00.000 |
DateTimeType | new Date(0) | 1970-01-01T00:00:00.000 |
Note that East tends to work with the ISO 8601 date-time format.
Since there are not seperate types for dates, times and date-times (timestamps), "dates" are modelled as the start of a particular day. This convention works well for computing durations and offsets, printing, and parsing.
As mentioned, East's date-time values do not include timezone information.
When working with TypeScript/JavaScript be sure to specify your dates in UTC time.
If you use local timestamps (e.g. without the "Z" suffix) with the EDK, the timestamp may be converted from your computer's timezone to UTC before inclusion in the solution template.
This is particularly undesirable because building the the solution template on another computer (or on the same computer in another timezone or after a change daylight-saving time) will produce a different result.
Date and time components
The year, month, day, hour, minute, second etc can be "extracted" from any date-time value. The result is an integer value.
| East function | Description | Example usage | Result |
|---|---|---|---|
Year | Extract the year | Year(new Date("2023-07-01T12:34:56.789Z")) | 2023 |
Month | Extract the month (January = 1) | Month(new Date("2023-07-01T12:34:56.789Z")) | 7 |
DayOfMonth | Extract the day of month | DayOfMonth(new Date("2023-07-01T12:34:56.789Z")) | 1 |
DayOfWeek | Extract the day of week (Monday = 0) | DayOfWeek(new Date("2023-07-01T12:34:56.789Z")) | 5 |
Hour | Extract the hour | Hour(new Date("2023-07-01T12:34:56.789Z")) | 12 |
Minute | Extract the minute | Minute(new Date("2023-07-01T12:34:56.789Z")) | 34 |
Second | Extract the second | Second(new Date("2023-07-01T12:34:56.789Z")) | 56 |
Millisecond | Extract the milliseconds | Millisecond(new Date("2023-07-01T12:34:56.789Z")) | 789 |
Duration calculations
With East you can determine the duration between two date-time values, or add (or subtract) a duration from a date-time value.
You can specify the unit for the duration as "day", "hour", "second", etc.
The duration is returned as float.
| East function | Description | Example usage | Result |
|---|---|---|---|
Duration | Calculate the duration from one date-times to another | Duration(new Date("2023-07-01Z"), new Date("2023-07-22Z"), "day") | 21.0 |
AddDuration | Determine the date-time some duration after a given date-time | AddDuration(new Date("2023-07-01Z"), 21, "day") | 2023-07-22T00:00:00.000 |
SubtractDuration | Determine the date-time some duration before a given date-time | SubtractDuration(new Date("2023-07-22Z"), 21, "day") | 2023-07-01T00:00:00.000 |
Note in Duration the "initial" date-time is the first argument and the "final" date-time is the second argument (which is the opposite order to how Subtract works).
Time zones
Time zone transformations are possible in East using the TimeZoneConvert function.
This will use the tzdata time-zone database to calculate timestamps in different locations and seasons.
Locations can be specified in
"Etc/UTC" or "Australia/Sydney".
| East function | Description | Example usage | Result |
|---|---|---|---|
TimeZoneConvert | Convert a date-time from one time zone to another | TimeZoneConvert(new Date("2023-07-01T00:00:00.000Z"), "Etc/UTC", "Australia/Sydney") | 2023-07-01T10:00:00.000 |
Formatting
When printing or parsing dates with Print and Parse it is possible to provide a format specifier.
This will let you deal with dates and times in a variety of local formats.
| East function | Description | Example usage | Result |
|---|---|---|---|
Print | Print a date in US format | Print(new Date("2023-07-01T00:00:00.000Z"), "M-D-YYYY") | "7-1-2023" |
Parse | Parse a date from US format | Parse(DateTimeType, "7-1-2023", "M-D-YYYY") | 2023-07-01T00:00:00.000 |
Next steps
Continue to the next tutorial to understand how to use and manipulate null and missing data with East and Elara.