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.

Date.elapsed

Return floating-point seconds since the moment.

Date.elapsed(moment)

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

emit -limit 1 | put hours_wasted_today = Date.elapsed(:today:) / 3600;

Date.endOf

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

Date.endOf(moment, timeunit)

information_source 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

emit -limit 1 | put eom = Date.endOf(time, "month")

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

bulb 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

emit -from :0: -limit 1
| put pacific = Date.format(:2015-01-01T00:00:00:,null,"PDT")
| put mountain = Date.format(:2015-01-01T00:00:00:,"HH-z")
| put central = Date.format(:2015-01-01T00:00:00:,"HH Z","CDT")
| put eastern = Date.format(:2015-01-01T00:00:00:,null,"Eastern")

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

bulb 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

emit -from :0: -limit 1
| put pacific = Date.formatTz(:2015-01-01T00:00:00:,"PDT")
| put mountain = Date.formatTz(:2015-01-01T00:00:00:,"MST")
| put central = Date.formatTz(:2015-01-01T00:00:00:,"CDT")
| put eastern = Date.formatTz(:2015-01-01T00:00:00:,"Eastern")

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

emit -limit 1 | put month_num = Date.get(time, "month")

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

emit
  | remove time
  | put fromunix = Date.new(1411426250)
  | put fromunixstr = Date.new("1411426250")
  | put infinity = Date.new(Infinity)
  | put negInfinity = Date.new(-Infinity)
  | put fromday =  Date.new("2014-09-22")
  | put fromISO =  Date.new("2014-09-22T11:39:17.993")
  | put ISOwithTZ =  Date.new("2014-09-22T11:39:17.993-08:00")
  | split

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

emit
| put date_in = "Thu Oct 29 2015 16:46:35 -0700",
      date_format = "ddd MMM DD YYYY HH:mm:ss Z",
      date_out = Date.parse(date_in, date_format);
emit
| put date_in = "Thu Oct 29 2015 16:46:35-0700",
      date_format = "ddd MMM DD YYYY HH:mm:ssZ",
      date_out = Date.parse(date_in, date_format);
emit
| put date_in = "Thu Oct 29 2015 16:46:35 +07:00",
      date_format = "ddd MMM DD YYYY HH:mm:ss Z",
      date_out = Date.parse(date_in, date_format);
emit
| put date_in = "10/29/15 16:46:35.000Z",
      date_format = "MM/DD/YY HH:mm:ss.SSSZ",
      date_out = Date.parse(date_in, date_format);
emit
| put date_in = "2015-10-29 16-0700",
      date_format = "YYYY-MM-DD HHZ",
      date_out = Date.parse(date_in, date_format);
emit
| put date_in = "2015-10-29 16:46:35-0700",
      date_format = "//default: ISO8601",
      date_out = Date.parse(date_in);
emit
| put date_in = "2015-10-29T16:46:35.000Z",
      date_format = "//default: ISO8601",
      date_out = Date.parse(date_in);
emit
| put date_in = "2014-09-22Z+08:00",
      date_format = "//default: Date fallback with timezone",
      date_out = Date.parse(date_in);
emit
| put date_in = "Wed Dec 2 18:56:48 2015 UTC",
      date_format = "//default: acceptable non-ISO8601",
      date_out = Date.parse(date_in);

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

emit -limit 1 
| put oh_pluto = Date.new("2006-09-13")
| put that_month = Date.quantize(oh_pluto, :M:), that_year = Date.quantize(oh_pluto, :y:) 
| keep oh_pluto, that_month, that_year

Date.startOf

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

Date.startOf(moment, timeunit)

information_source 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

emit -limit 1 | put today = Date.startOf(time, "day")

Date.time

Return the current moment, at millisecond resolution.

Date.time()

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

const start = Date.time();
emit -from start
| put elapsed = time - start, clock = Date.time(), skew = clock - time 
| view table

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

emit
| put now_moment = :now:, now_string = Date.toString(:now:)
| put time_string = "Current time: " + now_string

Date.unix

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

Date.unix(moment)

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

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

const sixty = Date.unix(Date.new("2014-09-22T00:01:00")) - Date.unix(Date.new("2014-09-22"));
emit -limit 1 | put seconds_in_minute = sixty

Date.unixms

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

Date.unixms(moment)

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

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

const sixtyaught = Date.unixms(Date.new("2014-09-22T00:01:00")) - Date.unixms(Date.new("2014-09-22"));
emit -limit 1 | put ms_in_minute = sixtyaught