Date and time functions

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.

The following functions evaluate to the current date and time:

 

now	The current date and time
datenow	The current date, without time information
timenow	The current time, without date information

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

 

max	The latest date
min	The earliest date

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

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

Expression	Result
date_diff( years, date( 1963, 10, 22 ), date( 2003, 8, 1) )	40
time_diff( years, date( 1963, 10, 22 ), date( 2003, 8, 1) )	39
date_diff( month, date( 2000, 5, 31 ), date( 2000, 6, 1) )	1
time_diff( month, date( 2000, 5, 31 ), date( 2000, 6, 1) )	0
date_diff( hour, time( 10, 30, 45 ), time( 15, 0, 0 ) )	5
time_diff( hour, time( 10, 30, 45 ), time( 15, 0, 0 ) )	4

 

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.

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.

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.

Examples

valid_date( '23/12/1990', 'dd/mm/yyyy' )	True
valid_date( '23/12/1990', 'mm/dd/yyyy' )	False (invalid month)
valid_date( '23 12 1990 12-00-00', 'dd-mm-yyyy hh:mm:ss' )	True (separators do not need to match)
valid_date( '27:92:00', 'hh:mm:ss' )	False (invalid hour and minute)

 

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.

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

 

second	seconds
minute	minutes
hour	hours
day	days
week	weeks
month	months
year	years

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.