Skip to content

Latest commit

 

History

History
321 lines (214 loc) · 7.65 KB

date.md

File metadata and controls

321 lines (214 loc) · 7.65 KB
Raw
title
Date Module | Juttle Language Reference

Date

Dates are represented in a Juttle flowgraph as Juttle moments. The Date module enables conversion between Unix timestamps, string representation of date/time, and moments.

[TOC]

Date.elapsed

Return floating-point seconds since the moment.

Date.elapsed(moment)

ℹ️ Note: This is equivalent to Duration.seconds(Date.now() - moment).

{!docs/examples/modules/date_elapsed.juttle!}

Date.endOf

Return a new moment, equal to the supplied moment set to the end of its current time unit.

Date.endOf(moment, timeunit)

ℹ️ Note: The new moment is the end of the unit in the time zone in which moment was recorded, not the time zone in which it is displayed.

Example: Find the last day of this month

{!docs/examples/modules/date_endof.juttle!}

Date.format

Format a moment as a string in the specified format, optionally adding a time zone. The input is assumed to be in UTC.

Date.format(moment)
Date.format(moment, format_string, timezone)
Parameter Description Required?
moment The moment to reformat Yes
format_string The format configuration, as documented in momentjs's format() function No; if not specified, the function returns the ISO-8601-formatted date.
timezone A time zone to include in the formatted string, as documented in momentjs's moment-timezone package

At the link above, you'll find a map you can hover over to get valid values for specific locations. We've also supplemented the built-in values, see list below.		 No

💡 Adjustments for Daylight Savings Time/Standard Time are always applied automatically, so for example you'll still get an accurate result if you specify 'PST' for a date that falls within PDT, or 'PDT' for a date that falls within PST.

Additional timezone values we support:

  • arizona:"US/Arizona"
  • az:"US/Arizona"
  • central:"US/Central"
  • cdt:"US/Central"
  • cst:"US/Central"
  • eastern:"US/Eastern"
  • edt:"US/Eastern"
  • est:"US/Eastern"
  • mountain:"US/Mountain"
  • mdt:"US/Mountain"
  • mst:"US/Mountain"
  • pacific:"US/Pacific"
  • pst:"US/Pacific"
  • pdt:"US/Pacific"

Example

{!docs/examples/modules/date_format.juttle!}

Date.formatTz

Add a time zone to a UTC moment.

Date.formatTz(moment, timezone)
Parameter Description Required?
moment The moment to reformat Yes
timezone A time zone to include in the formatted string, as documented in momentjs's moment-timezone package

At the link above, you'll find a map you can hover over to get valid values for specific locations. We've also supplemented the built-in values, see list below.		 No

💡 Adjustments for Daylight Savings Time/Standard Time are always applied automatically, so for example you'll still get an accurate result if you specify 'PST' for a date that falls within PDT, or 'PDT' for a date that falls within PST.

Additional timezone values we support:

  • arizona:"US/Arizona"
  • az:"US/Arizona"
  • central:"US/Central"
  • cdt:"US/Central"
  • cst:"US/Central"
  • eastern:"US/Eastern"
  • edt:"US/Eastern"
  • est:"US/Eastern"
  • mountain:"US/Mountain"
  • mdt:"US/Mountain"
  • mst:"US/Mountain"
  • pacific:"US/Pacific"
  • pst:"US/Pacific"
  • pdt:"US/Pacific"

Example

{!docs/examples/modules/date_format_tz.juttle!}

Date.get

Return the numeric value of the time unit for a moment as an integer.

Date.get(moment, timeunit)

Example: get the number of current month

{!docs/examples/modules/date_get.juttle!}

Date.new

Return a moment.

Date.new("YYYY-MM-DDTHH:MM:SS.msec+TZ"|seconds)

There are two ways to specify a moment:

Value Description
"YYYY-MM-DDTHH:MM:SS.msec+TZ" An ISO-8601 string. The time zone (TZ) is a numeric offset from UTC0. UTC0 is the default.
seconds Seconds since the UNIX epoch

Example: Some valid dates

{!docs/examples/modules/date_new.juttle!}

Date.parse

Parse a moment from a string using the specified format.

Date.parse(moment_string, format_string)
Parameter Description Required?
moment_string The string to convert to a moment Yes
format_string The format configuration, as documented in momentjs's String+Format constructor No; if not specified, the function expects ISO-8601-formatted date as input.

Example: Parse a JavaScript-formatted date

{!docs/examples/modules/date_parse.juttle!}

Format

Whitespace in the format string should match whitespace in the incoming string.

Different separators such as - vs / for date components, . vs , before milliseconds, are supported. However, if the timestamp in your data is enclosed in brackets, such as [2015/10/29 16:46:35], Date.parse will only handle the enclosed string and not the brackets.

When Date.parse is called with a single parameter of input string, without a custom format specification, it will parse several variants of ISO-8601 dates.

Timezone support

Juttle follows momentjs format for timezone specification, namely, as offset from UTC +HH:mm or -HH:mm, +HHmm or -HHmm, or the literal Z to stand for UTC (GMT) time zone.

Date.parse does not handle acronyms such as "PDT", or longform such as "GMT-0700 (PDT)".

Date.quantize

Return a new moment, equal to the supplied moment rounded down to an even number of durations since the epoch.

Date.quantize(moment, duration)

Example: get year and month when Pluto lost planet status

{!docs/examples/modules/date_quantize.juttle!}

Date.startOf

Return a new moment, equal to the supplied moment set to the start of its current time unit.

Date.startOf(moment, timeunit)

ℹ️ Note: The new moment is the start of the unit in the time zone in which moment was recorded, not the time zone in which it is displayed.

Example: beginning of a given day

{!docs/examples/modules/date_startof.juttle!}

Date.time

Return the current moment, at millisecond resolution.

Date.time()

Example: Show the difference between a time stamp and real time

{!docs/examples/modules/date_time.juttle!}

Date.toString()

Convert a value of type Date to type String. This is necessary to perform string operations such as concatenation.

Date.toString(date)

The returned String is in ISO-8601 format:

YYYY-MM-DDTHH:mm:ss.SSSZ

Example: print current time

{!docs/examples/modules/date_to_string.juttle!}

Date.unix

Return the UNIX time stamp for this moment, as seconds since the epoch.

Date.unix(moment)

ℹ️ Note: This is equivalent to Duration.seconds(moment - Date.new(0)).

Example: Compute the number of seconds in a minute, the hard way

{!docs/examples/modules/date_unix.juttle!}

Date.unixms

Return the UNIX time stamp for this moment, as milliseconds since the epoch.

Date.unixms(moment)

ℹ️ Note: This is equivalent to Duration.milliseconds(moment - Date.new(0)).

Example: Compute the number of milliseconds in a minute, the hard way

{!docs/examples/modules/date_unix_ms.juttle!}