This article covers these topics:

• Introduction to date and time functions
• Timestamp parameters
• Piping
• Date/time specific functions
• Examples

Introduction to date and time functions

This set of functions allows you to trigger other parts of a survey based on dates and times. For example, you can define a route through the survey based on the current date or time. You can also create reminders based on respondent behaviour using this functionality.

Timestamp parameters

For those functions that take in a timestamp (millisecond value), they also accept formatted dates in the following formats:

Format String

yyyy-MM-dd

yyyy-MM-dd HH:mm

yyyy-MM-dd HH:mm:ss

HH:mm

HH:mm:ss

The format of the string will be automatically detected and converted to its equivalent timestamp value and parsed where it was used, without the need of any formatting function. For more information on date formats, see date formats)

Piping

You are able to pipe values from and to date/time questions using the following functions:

Function	Description
answer(qref)	If the question referenced by qref is a date/time question, this function returns the default format string: "yyyy-MM-dd HH:mm" if it's a date and time input, "yyyy-MM-dd" if it's a date only input and  "HH:mm" if it's a time only input. This can be used in question texts and in conditions.
answerms(qref)	Returns the millisecond timestamp value of a date question referenced to by qref (date question specific addition).
setans(qref,your_value)	If the question referenced to by qref is a date/time question, the your_value parameter is interpreted as a timestamp parameter, and the date/time answer is set accordingly.

Date/time specific functions

The following table lists all the date/time function. For more info on each function please see below.

Function	Description	Example
tomillis(datestr,[format])	Parses a date text string to the millisecond representation, specify any of the format Strings mentioned above, or else it uses the device default. For more information, see tomillis below.	refer to Date and Time Functions Example
formatmillis(millis,[format])	Formats a millisecond value to a text string format (any of the format Strings mentioned above). For more information, see formatmillis below.	formatmillis(1696331330000,yyyy-MM-dd HH:mm)
currentmillis()	Returns the current date and time millisecond timestamp value. For more information, see currentmillis below.	refer to Date and Time Functions Example
currentdate()	Returns the current date in format "yyyy-MM-dd". Shorthand function for mstostring(currentms(),'yyyy-MM-dd')	refer to Date and Time Functions Example
currenttime()	Returns the current time in format "HH:mm". Shorthand function for mstostring(currentms(),"HH:mm").	refer to Date and Time Functions Example
currentts()	Returns the current time in format "yyyy-MM-dd HH:mm". Shorthand function for mstostring(currentms(),'yyyy-MM-dd HH:mm').	refer to Date and Time Functions Example
lastentryms()	Returns the millisecond timestamp representing the start time of the latest entry to this survey by the respondent.	refer to Date and Time Functions Example
reminderms()	Returns the millisecond timestamp of a scheduled reminder/alert.	refer to Advanced alerts (reminders)
addyears(timestamp,years_to_add)	Adds years to a timestamp value. Maintaining month, day and time by using the native calendar functions.	refer to Date and Time Functions Example
addmonths(timestamp,months_to_add)	Adds months to a timestamp value. Maintaining day of month and time by using the native calendar functions.	refer to Date and Time Functions Example
adddays(timestamp,days_to_add)	Adds days to a timestamp value. This function takes into consideration DST by using the native calendar functions for adding days. For more information, see adddays below.	refer to Date and Time Functions Example
addhours(timestamp,hours_to_add)	Adds hours to a timestamp. For more information, see addhours below.	refer to Date and Time Functions Example
addminutes(timestamp,minutes_to_add)	Adds minutes to a timestamp. For more information, see addminutes below.	refer to Date and Time Functions Example
addms(timestamp,millis_to_add)	Adds milliseconds to a timestamp.	refer to Date and Time Functions Example
datecompare(ms1,ms2)	Compares the date part of two timestamp values. For more information, see datecompare below.	refer to Date and Time Functions Example To compare text string formatted timestamps, use tomillis() function to format to ms first.
timecompare(ms1,ms2)	Compares the time part of two timestamp values. For more information, see timecompare below.	refer to Date and Time Functions Example To compare text string formatted timestamps, use tomillis() function to format to ms first.
tscompare(ms1,ms2)	Compares two timestamps with each other.	refer to Date and Time Functions Example To compare text string formatted timestamps, use tomillis() function to format to ms first.

 

tomillis(datestr,[format])

Parses a date text string to the timestamp millisecond representation. Optionally providing the format string to use.

Attributes

Attribute	Description
datestr	The date text string (for example 2023-10-03 14:00).
format	The format to use for parsing. If the format is not provided it's automatically detected based on the rules for timestamp parameters

Returns

The date & time string in timestamp milliseconds. 0 if the date could not be parsed.

formatmillis(timestamp,[format])

Formats a timestamp to a text string format.

Attributes

Attribute	Description
timestamp	The millisecond value for the date and time.
format	The format to use for formatting. Default is yyyy-MM-dd HH:mm

Returns

The formatted date string for the timestamp value. 0 if the date could not be formatted (error in timestamp or format).

currentmillis()

Returns

The millisecond representation of the current date and time.

adddays(timestamp,days_to_add)

Adds days to a timestamp value. This function takes into consideration DST by using the native calendar functions for adding days.

Attributes

Attribute	Description
timestamp	The timestamp for the date and time (May be millisecond value or one of the autodetected string formats).
days_to_add	The number of days to add to the timestamp. Can be negative.

Returns

The new date with the days added (time information preserved). Format of output is same as input based on the autodetection rules (if milliseconds in milliseconds out, if "yyyy-MM-dd" in then "yyyy-MM-dd" out). Returns millis on error.

addhours(timestamp,hours_to_add)

Adds hours to a timestamp value.

Attributes

Attribute	Description
timestamp	The timestamp representation for the date and time.
hours_to_add	The number of hours to add to the timestamp value. Can be negative.

Returns

The new date with the hours added. Format of output is same as input based on the autodetection rules (if milliseconds in milliseconds out, if "yyyy-MM-dd" in then "yyyy-MM-dd" out). Returns millis on error.

addminutes(timestamp,minutes_to_add)

Adds minutes to a timestamp value.

Attributes

Attribute	Description
timestamp	The timestamp representation for the date and time.
minutes_to_add	The number of minutes to add to the timestamp value. Can be negative.

Returns

The new date with the minutes added. Format of output is same as input based on the autodetection rules (if milliseconds in milliseconds out, if "yyyy-MM-dd" in then "yyyy-MM-dd" out). Returns millis on error.

datecompare(ms1,ms2)

Compares two timestamps with each other, only taking into consideration the date part and not the time.

Attributes

Attribute	Description
ms1	The first timestamp value.
ms2	The second timestamp value.

Returns

Returns a negative value (negative number of days between them) if date part of ms1 is less than the date part of ms2. Returns 0 if the date part of ms1 is equal to date part of ms2. Returns a positive value (number of days between them) if the date part of ms1 is greater than the date part of ms2. Returns 0 on error.

timecompare(ms1,ms2)

Compares two timestamps with each other, only taking into consideration the time part and not the date.

Attributes

Attributes	Description
ms1	The first timestamp value.
ms2	The second timestamp value.

Returns

Returns a negative value (negative number of milliseconds between them) if time part of ms1 is less than the time part of ms2. Returns 0 if the time part of ms1 is equal to time part of ms2 (note; millisecond precision). Returns a positive value (number of milliseconds between them) if the time part of ms1 is greater than the time part of ms2. Returns 0 on error.

Examples

This example demonstrates how Date and Time Functions can be used to achieve the following logic:

Piping Date/Time Input answer to another question

Setting the answer of a Date/Time Input Question to a specific value

Displaying Date/Time in a specific format within a text

For example, to display the date in the format of 'dd.MM.yyyy'

Comparing Date/Time in conditions: this allows you to route the respondent according to the given Date/Time and the returned value is either positive, negative or zero and that's how you decide the route

Adding to Date & Time (check the Advanced Reminders Examples for use case)