Study Definition module

Date and time functions

There are several functions in Arezzo that let you compare and manipulate date/time questions. You will find them on the Dates tab in the Expression Builder. See image

If you are using the Partial Date handling feature, click here for extra information.

Dates in Arezzo

Within the Arezzo language, explicit date/time terms are specified in one of the following formats.

date( Year, Month, Day )

datetime( Year, Month, Day, Hour, Minute, Second )

time( Hour, Minute, Second )

The values for Year, Month, Day, Hour, Minute and Second must all be integers (or Arezzo expressions which evaluate to integers) in the appropriate range.

For example,

date( 2003, 7, 11 )

represents 11th July 2003, and

date( 1999, 12, 25, 19, 30, 0 )

represents 7.30pm on 25th December 1999.

Combining dates

If you have a date and a time, you can combine them into a date/time value using the date_and_time function. For example, if AEDate is a date question, and AETime is a time question, the expression

date_and_time( AEDate, AETime )

represents the combined date and time value.

Current date and time

The following functions evaluate to the current date and time:

Earliest and latest dates

The following functions are found on the Sets tab but apply to dates as well as to numbers:

Comparing dates

There are three comparison operators for comparing dates.

Date1 isbefore Date2

This condition is true if Date1 is before Date2.

Date1 and Date2 can be date, time or date/time expressions. The comparison will use whatever information is available.

For example, to generate a warning if a date is before 1900, you could use the validation condition

me:value isbefore date( 1900, 1, 1 )

Date1 isafter Date2

This condition is true if Date1 is after Date2.

Date1 and Date2 can be date, time or date/time expressions. The comparison will use whatever information is available.

For example, to issue a warning if a date is in the future, you could use the validation condition

me:value isafter datenow

Date1 isduring [Date2,Date3]

This condition is true if Date1 is after Date2 but before Date3. If Date2 is after Date3, the condition will be false.

This is just a shorter way to write

Date1 isafter Date2 and Date1 isbefore Date3

Calculating dates

You can add or subtract time units to or from dates using the + and - operators. The available time units are listed below. The format of such an expression is

Date + N TimeUnits

or

Date - N TimeUnits

For example, the expression

datenow + 2 years

represents a date 2 years from now.

The validation condition

me:value isbefore PrevTime - 1 hour

will be true if the current value is earlier than one hour before the value of PrevTime.

Parts of dates

The datepart function returns an integer representing one part of a date/time expression.

datepart( TimeUnit, Date )

For example, the expression

datepart( year, datenow )

will return the current year. The expression

datepart( hour, MedTime )

will return an integer representing the hour in the value of the question MedTime.

Date subtraction

You can use the date_diff and time_diff functions to find the difference between two date/time values as a number of specified time units. These functions both operate on either dates or times, but they are subtly different.

The expression

date_diff( TimeUnit, Date1, Date2 )

returns the calendar difference between two dates or times. It returns the arithmetic difference between the specified parts of the two values, not taking into account partial units. For example, if the time unit is months, the calculation does not consider the day part of the dates.

The expression

time_diff( TimeUnit, Date1, Date2 )

returns the elapsed time difference between two dates or times, in complete time units.

Use this to calculate an age from a date of birth, e.g.

time_diff( years, DOB, datenow )

Note: Both these functions return a positive integer result, regardless of the order in which the two dates are given.

Examples

Note: For backwards compatibility with early versions of Arezzo, the datediff function is also supported, although its behaviour is identical to the time_diff function. To avoid confusion, you should not use the datediff function.

Formatting dates

If you use a date/time value in a text string, it will automatically be represented in the format yyyy/mm/dd.

The format_date function can be used to display dates in a format of your own choosing.

format_date( Date, FormatString )

The Date is any date/time term (which can be a question), and the FormatString is any of the allowed date formats, enclosed in single quotes. This function returns a text string.

For example, the expression

format_date( now, 'dd-mm-yyyy hh:mm' )

will give a text string displaying the current date and time, like this:

29-07-2003 10:42

The following expression could be a validation message to warn that the current value should be after the date question PrevDate.

'This date should be after ' & format_date( PrevDate, 'mm/dd/yyyy' )

Note: If you are displaying a date/time value in a date/time question, you do not need to use the format_date function. The date/time question will be automatically formatted according to the question's own format.

Converting text to dates

There are two functions which help you to convert text strings to dates.

Use valid_date to see if a text string represents a valid date/time. The condition

valid_date( Text, FormatString )

is true if the Text represents a valid date/time according to the format in FormatString. The format should be enclosed in single quotes. The Text can be any text expression, e.g. a question code. The separators in the FormatString do not have to match the separators in the Text.

This function works with partial dates if the input string is a valid partial date according to the specified format. For example

valid_date( '12/2003', 'dd/mm/yyyy')

will return True, because 12/2003 is a valid partial date.

Examples:

To check for a full date in a text string, the length of the string must be taken into account. For example, the following warning condition will fire for either a partial date or an invalid full date in a text field expecting dd/mm/yyyy format:

not ( len(me:value) between (8,10) and valid_date(me:value, 'dd/mm/yyyy') )

Use read_date to "read" a date from a text string in a given format. The expression

read_date( Text, FormatString )

returns a date/time value representing the date in the Text string according to the given FormatString. The separators in the format do not have to match those in the Text string.

For example, the expression

read_date( '2-26-2003', 'mm/dd/yyyy' )

returns a date value representing 26th February 2003.

This function also works with partial dates if the input string is a valid partial date according to the specified format.

Units of time

Any of the following keywords may be used to represent a time unit. These are available in the Time Units drop down list in the Expression Builder. See image

Response timestamps

You can use the dateof function to find out the time at which a question response was entered.

The expression

dateof( Question )

returns a date/time value representing the date and time at which the specified question was answered. The Question can be the code of a question on the same eForm, or a general question specification, for example

dateof( InvSig )

dateof( Treatment(first):Vital:BPSystolic(last) )

Click here to see how this function can be used to help manage dynamic derivations.

Related Topics

Arezzo functions and operators in alphabetic order

Arezzo Basics

Partial date handling