Time and Date Functions

Studio provides a set of functions for working with time and dates in expressions.
They are documented at the end of this page.

FunctionDescription
parseTimeParses a string into a timestamp
formatTimeFormats a timestamp into a string
getTimezoneGet the user's local time zone
geoToTimezoneLook up the time zone for a location

About Timestamps

Studio internally represents time as timestamps.
Timestamps are integer values representing the number of milliseconds since Jan 1, 1970 (UNIX Epoch).

Timestamps are defined in UTC time (Coordinated Universal Time), meaning that timestamps are independent of time zones, DST (Daylight Savings Time) etc.

Format Codes

Like most time parsing and formatting libraries, Studio uses format codes. Format codes help the user specify:

  • how strings representing dates should be parsed into timestamps (using parseTime())
  • how timestamps should be converted to strings (using formatTime())

Studio time functions support two common format code conventions:

  • 1-4 letter codes (JavaScript-style codes, familiar to users of libraries such as momentjs and dayjs).
  • % + letter codes (Python-style codes, familiar to users of Pandas to_datetime() and Python strptime() and strftime() functions).

Date and Time Format Codes Supported in Studio Expressions
CodeAltExampleDescription
YY%y18Two-digit year, without century, zero-padded
YYYY%Y2018Four-digit year, with century
M%-m1-12Month as number, beginning at 1
MM%m01-12Month as 2-digit zero-padded number
MMM%bJan-DecMonth as locale’s abbreviated name.
MMMM%BJanuary-DecemberMonth as locale’s full name.
D%-d1-31Day of the month as number
DD%d01-31Day of the month as 2-digit zero-padded number
d%w0-6The day of the week, with Sunday as 0
ddSu-SaWeekday as locale’s minimal name.
ddd%aSun-SatWeekday as locale’s abbreviated name.
dddd%ASunday-SaturdayWeekday as locale’s full name.
H%-H0-23Hour (24 hour clock)
HH%H00-23Hour (24 hour clock), 2-digits zero-padded
h%-I1-12The hour, 12-hour clock
hh%I01-12The hour, 12-hour clock, 2-digits
m%-M0-59The minute
mm%M00-59The minute, 2-digits
s%-S0-59The second
ss%S00-59The second, 2-digits
SSS000-999The millisecond, 3-digits
Z+05:00The offset from UTC, ±HH:mm
ZZ%z+0500The offset from UTC, ±HHmm
A%pAM PMLocale’s equivalent of post or ante meridiem, upper-case
aam pmLocale’s equivalent of post or ante meridiem, lower-case
Do1st-31stDay of Month with ordinal
%%%A literal % character

Examples:

Parsing a date string into a timestamp using a format string

parseTime("25/01/2019", "DD/MM/YYYY"); // => 1548403200000
parseTime("25/01/2019", "%d/%m/%Y"); // => 1548403200000

Formatting a timestamp into a date string using a format string

formatTime(1548403200000, "MM/DD/YY"); // => '01/25/19'
formatTime(1548403200000, "%m/%d/%y"); // => '01/25/19'

Time Zones

Time zones affect the conversion of UTC timestamps into local time. The formatTime() and parseTime() functions accept a timezone that lets you

If not specified, the default timezone is used. This timezone is returned by the
getTimezone() function.

It is also possible to calculate the local timezone for a specific location, using the geoToTimezone() function.

Time zones are represented as strings. There are a number of ways to specify timezones. Below is a list of US time zones.

U.S. Time ZoneUTC offsetDST offset
Pacific/Honolulu−10:00−10:00
America/Adak−10:00−09:00
America/Anchorage−09:00−08:00
America/Los_Angeles−08:00−07:00
America/Denver−07:00−06:00
America/Phoenix−07:00−07:00
America/Chicago−06:00−05:00
America/New_York−05:00−04:00
America/Detroit−05:00−04:00

Locales

Strings representing dates and times can contain language specific words (e.g. names of months and weekdays). Accordingly some formatting codes are locale dependent.

Studio currently only supports a default English locale. Please reach out to [email protected] if you need support for additional locales.

parseTime

Parse a string into a timestamp.

parseTime(time: string, format?: string, timezone?: string): timestamp
  • time A string representing a date and/or time.

  • format An optional string describing the format of the date/time strings to be parsed. If no format is provided, the date is assumed to be in ISO 8601 format.

  • timezone An optional string representing the time zone that the times should be interpreted in, if not provided, the current timezone (defined by the user's browser and operating system) will be used.

  • Returns: an integer timestamp.

Example: No format string provided. ISO 8601 formatted dates can be parsed.

parseTime("2018-04-04");
parseTime("2018-04-04T16:00:00.000Z");

formatTime

Format a timestamp into a string.

formatTime(ts: timestamp, format?: string, timezone?: string): string
  • timestamp An integer timestamp
  • format An optional string describing the format of the resulting date/time strings. If no format is provided, the date will be formatted in ISO 8601 format.
  • timezone An optional string representing the time zone that the timestamp should be converted to, if not provided, the current timezone (defined by the user's browser and operating system) will be used.

getTimezone

Returns the users current timezone.

getTimezone(): string
  • Returns a string representing the local time zone that can be used in other functions accepting timezones, including parseTime() and formatTime(). The format would normally be a long string such as America/Los_Angeles.

Note that different users may get different values depending on
their location in the world and settings in their browser and operating system.

geoToTimezone

Looks up the timezone for a specific location.

geoToTimezone(lng: number, lat: number): string
  • lng longitude in degrees

  • lat longitude in degrees

  • Returns an IANA timezone database string (such as America/Los_Angeles) representing the local time zone that can be used in other functions accepting timezones, including parseTime() and formatTime().

Remarks:

  • The timezones returned by this function are approximate: since the official timezone database is so large, lossy compression is necessary for a small footprint and fast lookups. Expect errors near timezone borders far away from populated areas. However, for most use-cases, accuracy should be adequate.

Sign In