Date and time functions

Created: - Updated:

This article covers these topics:

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(1368439980000,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

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

timecompare(ms1,ms2)

Compares the time part of two timestamp values. For more information, see timecompare below.

refer to Date and Time Functions Example

tscompare(ms1,ms2)

Compares two timestamps with each other.

refer to Date and Time Functions Example

 

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 2013-03-15 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 current date and time millisecond timestamp value.

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

Q2:

<question type="datetime" mode="datetime" id="2" text="Enter the Date and Time" alias="Q2"/>

 

Q3:

<question type="info" title="pipe" id="3" text="answer Q2 string is: $answer(Q2)" alias="Q3"/

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

From Q7:   

<precondition if="1==1" then="setans(Dummy1,1368439980000)"/>

Displaying Date/Time in a specific format within a text

Q(Format):

<question type="info" title="formatting" id="10" text="Variables: $var(tom1)&#xD;&#xA;$var(tom2)&#xD;&#xA;$var(tom3)&#xD;&#xA;

straight in text:&#xD;&#xA;$formatmillis(1368439980000)&#xD;&#xA;$formatmillis(1368439980000,yyyy-MM-dd HH:mm:ss)&#xD;&#xA;$formatmillis(1368439980000,yyyy-MM-dd HH:mm)&#xD;&#xA;$formatmillis(1368439980000,yyyy-MM-dd)&#xD;&#xA;$formatmillis(1368439980000,HH:mm:ss)&#xD;&#xA;$formatmillis(1368439980000,HH:mm)&#xD;&#xA;" alias="Format">

    <precondition then="setvar(tom1,tomillis(1999-12-12))"/>

    <precondition then="setvar(tom2,formatmillis(1368439980000,HH:mm))"/>

    <precondition then="setvar(tom3,formatmillis(1368439980000,HH:mm:ss))"/>

</question>

 

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

<question type="info" id="2" text="$var(newdate)" alias="Q2">

 <precondition then="setvar(newdate,formatmillis(answerms(Q1),dd.MM.yyyy))"/>

</question>

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

Q(Compare):

<question type="info" title="Compare" id="13" text="datecompare:&#xD;&#xA;$datecompare(1384348393000,1321020854000)&#xD;&#xA;$datecompare(1321020854000,1384348393000)&#xD;&#xA;

$datecompare(1321020854000,1321020854000)&#xD;&#xA;timecompare:&#xD;&#xA;$timecompare(1384348393000,1321020854000)&#xD;&#xA;$timecompare(1321020854000,1384348393000)&#xD;&#xA;

$timecompare(1321020854000,1321020854000)&#xD;&#xA;tscompare:&#xD;&#xA;$tscompare(1384348393000,1321020854000)&#xD;&#xA;$tscompare(1321020854000,1384348393000)&#xD;&#xA;

$tscompare(1321020854000,1321020854000)&#xD;&#xA;&#xD;&#xA;Variables:&#xD;&#xA;$var(compa1)&#xD;&#xA;$var(compa2)&#xD;&#xA;$var(compa3)&#xD;&#xA;$var(compa4)&#xD;&#xA;

$var(compa5)&#xD;&#xA;$var(compa6)&#xD;&#xA;&#xD;&#xA;format:&#xD;&#xA;$formatmillis($var(compa1),yyyy-MM-dd HH:mm:ss)&#xD;&#xA;$formatmillis($var(compa2),yyyy-MM-dd HH:mm:ss)&#xD;&#xA;$formatmillis($var(compa3),yyyy-MM-dd HH:mm:ss)&#xD;&#xA;$formatmillis($var(compa4),yyyy-MM-dd HH:mm:ss)&#xD;&#xA;$formatmillis($var(compa5),yyyy-MM-dd HH:mm:ss)&#xD;&#xA;$formatmillis($var(compa6),yyyy-MM-dd HH:mm:ss)" alias="Compare">

    <precondition then="setvar(compa1,datecompare(1384348393000,1321020854000))"/>

    <precondition then="setvar(compa2,$datecompare(1384348393000,1321020854000))"/>

    <precondition then="setvar(compa3,timecompare(1384348393000,1321020854000))"/>

    <precondition then="setvar(compa4,$timecompare(1384348393000,1321020854000))"/>

    <precondition then="setvar(compa5,tscompare(1384348393000,1321020854000))"/>

    <precondition then="setvar(compa6,$tscompare(1384348393000,1321020854000))"/>

</question>

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

Q(Add):

<question type="info" title="Add" id="12" text="$addyears(946677600000,3)&#xD;&#xA;$addmonths(946677600000,3)&#xD;&#xA;$adddays(946677600000,3)&#xD;&#xA;$addhours(946677600000,3)&#xD;&#xA;

$addminutes(946677600000,3)&#xD;&#xA;$addms(946677600000,86400000)&#xD;&#xA;$var(ay1)&#xD;&#xA;$var(ay2)&#xD;&#xA;$var(ay3)&#xD;&#xA;$var(ay4)&#xD;&#xA;$var(ay5)&#xD;&#xA;$var(ay6)&#xD;&#xA;

$formatmillis($var(ay1))&#xD;&#xA;Add and Format:&#xD;&#xA;$formatmillis(var(ay1))&#xD;&#xA;$formatmillis(var(ay2))&#xD;&#xA;$formatmillis(var(ay3))&#xD;&#xA;$formatmillis(var(ay4))&#xD;&#xA;

$formatmillis(var(ay5))&#xD;&#xA;$formatmillis(var(ay6))&#xD;&#xA;--&#xD;&#xA;$formatmillis(addyears(946677600000,3))&#xD;&#xA;$formatmillis(addmonths(946677600000,3))&#xD;&#xA;

$formatmillis(adddays(946677600000,3))&#xD;&#xA;$formatmillis(addhours(946677600000,3))&#xD;&#xA;$formatmillis(addminutes(946677600000,3))&#xD;&#xA;$formatmillis(addms(946677600000,86400000))" alias="Add">

    <precondition then="setvar(ay1,addyears(946677600000,3))"/>

    <precondition then="setvar(ay2,addmonths(946677600000,3))"/>

    <precondition then="setvar(ay3,adddays(946677600000,3))"/>

    <precondition then="setvar(ay4,addhours(946677600000,3))"/>

    <precondition then="setvar(ay5,addminutes(946677600000,3))"/>

    <precondition then="setvar(ay6,addms(946677600000,86400000))"/>

</question>