Functions

This page provides details of all available functions.

Functions by Type

Data Access Functions

firstStr, firstVal, lastStr, lastVal, submissionStr, submissionVal

Date Functions

new Date, dateAdd, dateFormat, dateFormatDistance, dateSubtract, differenceInDays, differenceInHours, differenceInMinutes, now

Math Functions

min, max, power

Function Reference

Date

The Date function constructs a date object from parts like year, month day, etc:

The Date function must be used with the new keyword (to maintain compatibility with JavaScript).

Syntax

new Date(year, monthIndex)
new Date(year, monthIndex, day)
new Date(year, monthIndex, day, hours)
new Date(year, monthIndex, day, hours, minutes)
new Date(year, monthIndex, day, hours, minutes, seconds)
new Date(year, monthIndex, day, hours, minutes, seconds, milliseconds)

Given at least a year and month, this form of Date() returns a Date object whose component values (year, month, day, hour, minute, second, and millisecond) all come from the following parameters. Any missing fields are given the lowest possible value (1 for day and 0 for every other component). The parameter values are all evaluated against the local time zone, rather than UTC.

If any parameter overflows its defined bounds, it "carries over". For example, if a monthIndex greater than 11 is passed in, those months will cause the year to increment; if a minutes greater than 59 is passed in, hours will increment accordingly, etc. Therefore, new Date(1990, 12, 1) will return January 1st, 1991; new Date(2020, 5, 19, 25, 65) will return 2:05 A.M. June 20th, 2020.

Similarly, if any parameter underflows, it "borrows" from the higher positions. For example, new Date(2020, 5, 0) will return May 31st, 2020.

• year: Integer value representing the year. Values from 0 to 99 map to the years 1900 to 1999. All other values are the actual year. See the example.
• monthIndex: Integer value representing the month, beginning with 0 for January to 11 for December.
• day: Optional Integer value representing the day of the month. The default is 1.
• hours: Optional Integer value between 0 and 23 representing the hour of the day. Defaults to 0.
• minutes: Optional Integer value representing the minute segment of a time. The default is 0 minutes past the hour.
• seconds: Optional Integer value representing the second segment of a time. The default is 0 seconds past the minute.
• milliseconds: Optional Integer value representing the millisecond segment of a time. The default is 0 milliseconds past the second.

Examples

new Date(1999, 9)
// Fri Oct 01 1999 00:00:00 GMT-0400 (Eastern Daylight Time)

new Date(1999, 9, 9)
// Sat Oct 09 1999 00:00:00 GMT-0400 (Eastern Daylight Time)

new Date(1999, 9, 9, 9)
// Sat Oct 09 1999 09:00:00 GMT-0400 (Eastern Daylight Time)

new Date(1999, 9, 9, 9, 9)
// Sat Oct 09 1999 09:09:00 GMT-0400 (Eastern Daylight Time)

new Date(1999, 9, 9, 9, 9, 9)
// Sat Oct 09 1999 09:09:09 GMT-0400 (Eastern Daylight Time)

new Date(1999, 9, 9, 9, 9, 9, 9)
// Sat Oct 09 1999 09:09:09 GMT-0400 (Eastern Daylight Time)

dateAdd

Add the specified years, months, weeks, days, hours, minutes and seconds to the given date.

Syntax

dateAdd(date, duration)

date - Date the date to be changed

duration - the object with years, months, weeks, days, hours, minutes and seconds to be added. Positive decimals will be rounded using Math.floor, decimals less than zero will be rounded using Math.ceil.

• years Amount of years to be added
• months Amount of months to be added
• weeks Amount of weeks to be added
• days Amount of days to be added
• hours Amount of hours to be added
• minutes Amount of minutes to be added
• seconds Amount of seconds to be added

All values default to 0

Example

// Add the following duration to 1 September 2014, 10:19:50
dateAdd(new Date(2014, 8, 1, 10, 19, 50), {
  years: 2,
  months: 9,
  weeks: 1,
  days: 7,
  hours: 5,
  minutes: 9,
  seconds: 30,
})
//=> Thu Jun 15 2017 15:29:20

Sourced from https://date-fns.org/v2.29.3/docs/add

dateFormat

Return the formatted date string in the given format. The result may vary by locale.

caution

Please note that the format tokens differ from Moment.js and other libraries. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

The characters wrapped between two single quotes characters (') are escaped. Two single quotes in a row, whether inside or outside a quoted sequence, represent a 'real' single quote. (see the last example)

Format of the string is based on Unicode Technical Standard #35: https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table with a few additions (see note 7 below the table).

Unit	Pattern	Result examples	Notes
Era	G..GGG	AD, BC
	GGGG	Anno Domini, Before Christ	2
	GGGGG	A, B
Calendar year	y	44, 1, 1900, 2017	5
	yo	44th, 1st, 0th, 17th	5,7
	yy	44, 01, 00, 17	5
	yyy	044, 001, 1900, 2017	5
	yyyy	0044, 0001, 1900, 2017	5
	yyyyy	...	3,5
Local week-numbering year	Y	44, 1, 1900, 2017	5
	Yo	44th, 1st, 1900th, 2017th	5,7
	YY	44, 01, 00, 17	5,8
	YYY	044, 001, 1900, 2017	5
	YYYY	0044, 0001, 1900, 2017	5,8
	YYYYY	...	3,5
ISO week-numbering year	R	-43, 0, 1, 1900, 2017	5,7
	RR	-43, 00, 01, 1900, 2017	5,7
	RRR	-043, 000, 001, 1900, 2017	5,7
	RRRR	-0043, 0000, 0001, 1900, 2017	5,7
	RRRRR	...	3,5,7
Extended year	u	-43, 0, 1, 1900, 2017	5
	uu	-43, 01, 1900, 2017	5
	uuu	-043, 001, 1900, 2017	5
	uuuu	-0043, 0001, 1900, 2017	5
	uuuuu	...	3,5
Quarter (formatting)	Q	1, 2, 3, 4
	Qo	1st, 2nd, 3rd, 4th	7
	QQ	01, 02, 03, 04
	QQQ	Q1, Q2, Q3, Q4
	QQQQ	1st quarter, 2nd quarter, ...	2
	QQQQQ	1, 2, 3, 4	4
Quarter (stand-alone)	q	1, 2, 3, 4
	qo	1st, 2nd, 3rd, 4th	7
	qq	01, 02, 03, 04
	qqq	Q1, Q2, Q3, Q4
	qqqq	1st quarter, 2nd quarter, ...	2
	qqqqq	1, 2, 3, 4	4
Month (formatting)	M	1, 2, ..., 12
	Mo	1st, 2nd, ..., 12th	7
	MM	01, 02, ..., 12
	MMM	Jan, Feb, ..., Dec
	MMMM	January, February, ..., December	2
	MMMMM	J, F, ..., D
Month (stand-alone)	L	1, 2, ..., 12
	Lo	1st, 2nd, ..., 12th	7
	LL	01, 02, ..., 12
	LLL	Jan, Feb, ..., Dec
	LLLL	January, February, ..., December	2
	LLLLL	J, F, ..., D
Local week of year	w	1, 2, ..., 53
	wo	1st, 2nd, ..., 53th	7
	ww	01, 02, ..., 53
ISO week of year	I	1, 2, ..., 53	7
	Io	1st, 2nd, ..., 53th	7
	II	01, 02, ..., 53	7
Day of month	d	1, 2, ..., 31
	do	1st, 2nd, ..., 31st	7
	dd	01, 02, ..., 31
Day of year	D	1, 2, ..., 365, 366	9
	Do	1st, 2nd, ..., 365th, 366th	7
	DD	01, 02, ..., 365, 366	9
	DDD	001, 002, ..., 365, 366
	DDDD	...	3
Day of week (formatting)	E..EEE	Mon, Tue, Wed, ..., Sun
	EEEE	Monday, Tuesday, ..., Sunday	2
	EEEEE	M, T, W, T, F, S, S
	EEEEEE	Mo, Tu, We, Th, Fr, Sa, Su
ISO day of week (formatting)	i	1, 2, 3, ..., 7	7
	io	1st, 2nd, ..., 7th	7
	ii	01, 02, ..., 07	7
	iii	Mon, Tue, Wed, ..., Sun	7
	iiii	Monday, Tuesday, ..., Sunday	2,7
	iiiii	M, T, W, T, F, S, S	7
	iiiiii	Mo, Tu, We, Th, Fr, Sa, Su	7
Local day of week (formatting)	e	2, 3, 4, ..., 1
	eo	2nd, 3rd, ..., 1st	7
	ee	02, 03, ..., 01
	eee	Mon, Tue, Wed, ..., Sun
	eeee	Monday, Tuesday, ..., Sunday	2
	eeeee	M, T, W, T, F, S, S
	eeeeee	Mo, Tu, We, Th, Fr, Sa, Su
Local day of week (stand-alone)	c	2, 3, 4, ..., 1
	co	2nd, 3rd, ..., 1st	7
	cc	02, 03, ..., 01
	ccc	Mon, Tue, Wed, ..., Sun
	cccc	Monday, Tuesday, ..., Sunday	2
	ccccc	M, T, W, T, F, S, S
	cccccc	Mo, Tu, We, Th, Fr, Sa, Su
AM, PM	a..aa	AM, PM
	aaa	am, pm
	aaaa	a.m., p.m.	2
	aaaaa	a, p
AM, PM, noon, midnight	b..bb	AM, PM, noon, midnight
	bbb	am, pm, noon, midnight
	bbbb	a.m., p.m., noon, midnight	2
	bbbbb	a, p, n, mi
Flexible day period	B..BBB	at night, in the morning, ...
	BBBB	at night, in the morning, ...	2
	BBBBB	at night, in the morning, ...
Hour [1-12]	h	1, 2, ..., 11, 12
	ho	1st, 2nd, ..., 11th, 12th	7
	hh	01, 02, ..., 11, 12
Hour [0-23]	H	0, 1, 2, ..., 23
	Ho	0th, 1st, 2nd, ..., 23rd	7
	HH	00, 01, 02, ..., 23
Hour [0-11]	K	1, 2, ..., 11, 0
	Ko	1st, 2nd, ..., 11th, 0th	7
	KK	01, 02, ..., 11, 00
Hour [1-24]	k	24, 1, 2, ..., 23
	ko	24th, 1st, 2nd, ..., 23rd	7
	kk	24, 01, 02, ..., 23
Minute	m	0, 1, ..., 59
	mo	0th, 1st, ..., 59th	7
	mm	00, 01, ..., 59
Second	s	0, 1, ..., 59
	so	0th, 1st, ..., 59th	7
	ss	00, 01, ..., 59
Fraction of second	S	0, 1, ..., 9
	SS	00, 01, ..., 99
	SSS	000, 001, ..., 999
	SSSS	...	3
Timezone (ISO-8601 w/ Z)	X	-08, +0530, Z
	XX	-0800, +0530, Z
	XXX	-08:00, +05:30, Z
	XXXX	-0800, +0530, Z, +123456	2
	XXXXX	-08:00, +05:30, Z, +12:34:56
Timezone (ISO-8601 w/o Z)	x	-08, +0530, +00
	xx	-0800, +0530, +0000
	xxx	-08:00, +05:30, +00:00	2
	xxxx	-0800, +0530, +0000, +123456
	xxxxx	-08:00, +05:30, +00:00, +12:34:56
Timezone (GMT)	O...OOO	GMT-8, GMT+5:30, GMT+0
	OOOO	GMT-08:00, GMT+05:30, GMT+00:00	2
Timezone (specific non-locat.)	z...zzz	GMT-8, GMT+5:30, GMT+0	6
	zzzz	GMT-08:00, GMT+05:30, GMT+00:00	2,6
Seconds timestamp	t	512969520	7
	tt	...	3,7
Milliseconds timestamp	T	512969520900	7
	TT	...	3,7
Long localized date	P	04/29/1453	7
	PP	Apr 29, 1453	7
	PPP	April 29th, 1453	7
	PPPP	Friday, April 29th, 1453	2,7
Long localized time	p	12:00 AM	7
	pp	12:00:00 AM	7
	ppp	12:00:00 AM GMT+2	7
	pppp	12:00:00 AM GMT+02:00	2,7
Combination of date and time	Pp	04/29/1453, 12:00 AM	7
	PPpp	Apr 29, 1453, 12:00:00 AM	7
	PPPppp	April 29th, 1453 at ...	7
	PPPPpppp	Friday, April 29th, 1453 at ...	2,7

Notes:

1. "Formatting" units (e.g. formatting quarter) in the default en-US locale are the same as "stand-alone" units, but are different in some languages. "Formatting" units are declined according to the rules of the language in the context of a date. "Stand-alone" units are always nominative singular:

format(new Date(2017, 10, 6), 'do LLLL', {locale: cs}) //=> '6. listopad'

format(new Date(2017, 10, 6), 'do MMMM', {locale: cs}) //=> '6. listopadu'

2. Any sequence of the identical letters is a pattern, unless it is escaped by the single quote characters (see below). If the sequence is longer than listed in table (e.g. EEEEEEEEEEE) the output will be the same as default pattern for this unit, usually the longest one (in case of ISO weekdays, EEEE). Default patterns for units are marked with "2" in the last column of the table.

format(new Date(2017, 10, 6), 'MMM') //=> 'Nov'

format(new Date(2017, 10, 6), 'MMMM') //=> 'November'

format(new Date(2017, 10, 6), 'MMMMM') //=> 'N'

format(new Date(2017, 10, 6), 'MMMMMM') //=> 'November'

format(new Date(2017, 10, 6), 'MMMMMMM') //=> 'November'

3. Some patterns could be unlimited length (such as yyyyyyyy). The output will be padded with zeros to match the length of the pattern.

format(new Date(2017, 10, 6), 'yyyyyyyy') //=> '00002017'

4. QQQQQ and qqqqq could be not strictly numerical in some locales. These tokens represent the shortest form of the quarter.

5. The main difference between y and u patterns are B.C. years:

Year	y	u
AC 1	1	1
BC 1	1	0
BC 2	2	-1

Also yy always returns the last two digits of a year, while uu pads single digit years to 2 characters and returns other years unchanged:

Year	yy	uu
1	01	01
14	14	14
376	76	376
1453	53	1453

The same difference is true for local and ISO week-numbering years (Y and R), except local week-numbering years are dependent on options.weekStartsOn and options.firstWeekContainsDate (compare getISOWeekYear and getWeekYear).

6. Specific non-location timezones are currently unavailable in date-fns, so right now these tokens fall back to GMT timezones.

7. These patterns are not in the Unicode Technical Standard #35:

• i: ISO day of week
• I: ISO week of year
• R: ISO week-numbering year
• t: seconds timestamp
• T: milliseconds timestamp
• o: ordinal number modifier
• P: long localized date
• p: long localized time

8. YY and YYYY tokens represent week-numbering years but they are often confused with years. You should enable options.useAdditionalWeekYearTokens to use them. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

9. D and DD tokens represent days of the year but they are often confused with days of the month. You should enable options.useAdditionalDayOfYearTokens to use them. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

Syntax

formatDate(date, format)

• date - Date the original date
• format - the string of tokens

Example

// Represent 11 February 2014 in middle-endian format:
const result = formatDate(new Date(2014, 1, 11), 'MM/dd/yyyy')
//=> '02/11/2014'

Sourced from https://date-fns.org/v2.29.3/docs/format

dateFormatDistance

Return the distance between the given dates in words.

Distance between dates	Result
0 ... 30 secs	less than a minute
30 secs ... 1 min 30 secs	1 minute
1 min 30 secs ... 44 mins 30 secs	[2..44] minutes
44 mins ... 30 secs ... 89 mins 30 secs	about 1 hour
89 mins 30 secs ... 23 hrs 59 mins 30 secs	about [2..24] hours
23 hrs 59 mins 30 secs ... 41 hrs 59 mins 30 secs	1 day
41 hrs 59 mins 30 secs ... 29 days 23 hrs 59 mins 30 secs	[2..30] days
29 days 23 hrs 59 mins 30 secs ... 44 days 23 hrs 59 mins 30 secs	about 1 month
44 days 23 hrs 59 mins 30 secs ... 59 days 23 hrs 59 mins 30 secs	about 2 months
59 days 23 hrs 59 mins 30 secs ... 1 yr	[2..12] months
1 yr ... 1 yr 3 months	about 1 year
1 yr 3 months ... 1 yr 9 month s	over 1 year
1 yr 9 months ... 2 yrs	almost 2 years
N yrs ... N yrs 3 months	about N years
N yrs 3 months ... N yrs 9 months	over N years
N yrs 9 months ... N+1 yrs	almost N+1 years

Syntax

formatDistance(date, baseDate, [options])

• date - Date, the date
• baseDate - Date, the date to compare with
• options - (optional) missing or {addSuffix: true} to indicate to add "ago" or {includeSeconds: true} to include seconds (or can be combined like {addSuffix: true, includeSeconds: true} )

Example

// What is the distance between 2 July 2014 and 1 January 2015?
dateFormatDistance(new Date(2014, 6, 2), new Date(2015, 0, 1))
//=> '6 months'


// What is the distance between 1 January 2015 00:00:15
// and 1 January 2015 00:00:00, including seconds?
dateFormatDistance(
  new Date(2015, 0, 1, 0, 0, 15),
  new Date(2015, 0, 1, 0, 0, 0),
  { includeSeconds: true }
)
//=> 'less than 20 seconds'

// What is the distance from 1 January 2016
// to 1 January 2015, with a suffix?
dateFormatDistance(new Date(2015, 0, 1), new Date(2016, 0, 1), {
  addSuffix: true
})
//=> 'about 1 year ago'

Sourced from https://date-fns.org/v2.29.3/docs/formatDistance

dateSubtract

Subtract the specified years, months, weeks, days, hours, minutes and seconds from the given date.

Syntax

dateSubtract(date, duration)

• date - Date, the date to be changed
• duration - the object with years, months, weeks, days, hours, minutes and seconds to be subtracted

Key	Description
years	Amount of years to be subtracted
months	Amount of months to be subtracted
weeks	Amount of weeks to be subtracted
days	Amount of days to be subtracted
hours	Amount of hours to be subtracted
minutes	Amount of minutes to be subtracted
seconds	Amount of seconds to be subtracted

Example

// Subtract the following duration from 15 June 2017 15:29:20
dateSubtract(new Date(2017, 5, 15, 15, 29, 20), {
  years: 2,
  months: 9,
  weeks: 1,
  days: 7,
  hours: 5,
  minutes: 9,
  seconds: 30
})
//=> Mon Sep 1 2014 10:19:50

Sourced from https://date-fns.org/v2.29.3/docs/formatDistance

differenceInDays

Get the number of full day periods between two dates. Fractional days are truncated towards zero.

One "full day" is the distance between a local time in one day to the same local time on the next or previous day. A full day can sometimes be less than or more than 24 hours if a daylight savings change happens between two dates.

Syntax

differenceInDays(dateLeft, dateRight)

• dateLeft - Date, the later date
• dateRight - Date, the earlier date

Examples

// How many full days are between
// 2 July 2011 23:00:00 and 2 July 2012 00:00:00?
differenceInDays(
  new Date(2012, 6, 2, 0, 0),
  new Date(2011, 6, 2, 23, 0)
)
//=> 365

// How many full days are between
// 2 July 2011 23:59:00 and 3 July 2011 00:01:00?
differenceInDays(
  new Date(2011, 6, 3, 0, 1),
  new Date(2011, 6, 2, 23, 59)
)
//=> 0

// How many full days are between
// 1 March 2020 0:00 and 1 June 2020 0:00 ?
// Note: because local time is used, the
// result will always be 92 days, even in
// time zones where DST starts and the
// period has only 92*24-1 hours.
const result = differenceInDays(
  new Date(2020, 5, 1),
  new Date(2020, 2, 1)
)
//=> 92

Sourced from https://date-fns.org/v2.29.3/docs/differenceInDays

differenceInHours

Get the number of hours between the given dates

Syntax

differenceInHours(dateLeft, dateRight)

• dateLeft - Date, the later date
• dateRight - Date, the earlier date

Example

// How many hours are between 2 July 2014 06:50:00 and 2 July 2014 19:00:00?
differenceInHours(
  new Date(2014, 6, 2, 19, 0),
  new Date(2014, 6, 2, 6, 50)
)
//=> 12

Sourced from https://date-fns.org/v2.29.3/docs/differenceInHours

differenceInMinutes

Get the signed number of full (rounded towards 0) minutes between the given dates

Syntax

differenceInMinutes(dateLeft, dateRight)

• dateLeft - Date, the later date
• dateRight - Date, the earlier date

Example

// How many minutes are between 2 July 2014 12:07:59 and 2 July 2014 12:20:00?
differenceInMinutes(
  new Date(2014, 6, 2, 12, 20, 0),
  new Date(2014, 6, 2, 12, 7, 59)
)
//=> 12

// How many minutes are between 10:01:59 and 10:00:00
differenceInMinutes(
  new Date(2000, 0, 1, 10, 0, 0),
  new Date(2000, 0, 1, 10, 1, 59)
)
//=> -1

max

Determine the maximum of a list of numbers.

Syntax

max(number1, number2, number3, ...)

Example

max(1,2,3)
// => 3

min

Determine the minimum of a list of numbers.

Syntax

min(number1, number2, number3, ...)

Example

min(1,2,3)
// => 1

now

Returns the current date. It is sensitive to the Simulator's as at feature so sometimes it will return the simulated date, not the actual date.

Syntax

now()

Example

now()
// => current date time

firstStr

firstVal

firstVal and firstStr retrieve the first submitted value of the specific data reference.

Note for the carePlan entity, there is no difference between firstVal and lastVal since there is only one instance of a plan.

If the form was never submitted it returns undefined

Str vs Val versions

The difference between the Str and Val variations is the data type that is returned. If Str is used, the value is ready to be displayed to a user and the system will attempt to format it with whatever metadata can be found. In the future, this will pick up units labels and decimals defined by a Unit of Measure. So use Str versions when you want to display the value in a view.

The Val version should be used if you wanted to interrogate the value. For example if you wanted to use min, max, > against the results.

Syntax

firstStr("data reference")
firstVal("data reference")

Examples

firstStr("submission.form1.field1")
// Returns a printable string of field1 in form1 the first time it was submitted

firstVal("submission.form1.field1")
// Returns the value of field1 in form1 the first time it was submitted

firstStr("carePlan.status")
// Returns the plan status

lastStr

lastVal

lastVal and lastStr retrieve the latest submitted value of the specific data reference.

Note for the carePlan entity, there is no difference between firstVal and lastVal since there is only one instance of a plan.

If the form was never submitted it returns undefined

See Str vs Val versions

Syntax

lastStr("data reference")
lastVal("data reference")

Examples

lastStr("submission.form1.field1")
// Returns a printable string of field1 in form1 the last time it was submitted

lastVal("submission.form1.field1")
// Returns the value of field1 in form1 the last time it was submitted

lastStr("carePlan.status")
// Returns the plan status

submissionStr

submissionVal

submissionVal and submissionStr retrieve the submitted value of the specific data reference for the form submission that is in context.

See Str vs Val versions

Unlike lastVal, etc., use only the field name. "submission.form-name" is implied. You may not access plan attributes.

Syntax

submissionStr("field name")
submissionVal("field name")

Examples

submissionStr("field1")
// Returns a printable string of field1 in the form that was submitted

submissionVal("field1")
// Returns the value of field1 in the form that was submitted

power

The power function computes an exponential.

Syntax

power(base,exp)

Example

power(2,2)
// => 4