Date Calculations

Learn how to perform calculations on dates to compare, manipulate or extract information.

Date calculations are a type of calculation that can:

• use a date as an input; and/or
• return a date as an output.

Rulestar supports a range of date calculations using our custom calculation engine.

There are three main types of date calculation:

1. Duration - calculate the duration (e.g. the number of months) between two dates.
2. Comparison - comparing the order of two dates (e.g. which one is first).
3. Arithmetic - adding or subtracting a duration of time (e.g. 5 days) to a date.

In addition to the above, there are also several Properties of dates that can be observed using calculations.

The type of value that a date calculation returns determines what type of field is required to perform the calculation. If a date calculation returns a number (e.g. a duration), the calculation must be done in a number field. If a date calculation returns a date or time (e.g. a manipulation), a Date/Time Field must be used.

Using a date as an input

A date can be used as an input for a date calculation by using:

1. Date/Time Fields  - an answered Date/Time Field (including a Date/Time Field answer from a calculation); and/or
2. Today - equals the date on which a user is answering the smart online form. This is case sensitive as must be written as "Today".

In the following examples, a reference to Date (including Date1 and Date2) is any date provided in one of these formats and X is any number.

Date calculations where the output is a Number:

Use a number field for the following types of date calculations:

1. Duration - the duration of time (e.g. the number of days) between two dates.
2. Boolean date comparison - a boolean (true or false) comparison on the order of two dates.
3. Date properties - the day, month or year of the date.

These calculations are performed in number fields as their return value is a number (not a date).

To perform a date calculation within a number field, you will first need to create a new number field (shown here). As with all calculations, ensure that the field is either read-only or hidden.

Duration

Date duration calculations to return the duration of time between two dates are done with the "Diff" methods. The duration can be returned as a number of years, months or days. For example, to calculate the number of years between two dates, you can use the following "DIffYears" method:

Date1.DiffYears(Date2)

If you wanted to know the number of months between two dates, you would use:

Date1.DiffMonths(Date2)

For the number of days between two dates, you can use:

Date1.DiffDays(Date2)

 

 

A fourth date duration method can be used when the unit (years, months and days) is variable within your smart online form. This unit can be changed given the user's answers eg, to a radio or select field.

To perform a date duration calculation using the "Diff" method:

Date1.Diff(Date2, "unit")

Valid units of the "Diff" method are as follows and are not case sensitive:

• year or years,
• month or months, and
• day or days.

Results of all "Diff" methods are truncated to zero decimal places, returning an integer eg, 0.95 years returns 0.

Comparing dates

Calculations that compare two dates return either 0 or 1, representing the false and true boolean values. Date comparisons are performed using the same equality and relational operators that can be used in logical expressions within the logic builder.

For example, to see Date1 is strictly earlier than Date2, you would use the following calculation:

Date1 < Date2

If Date1 is the earlier date this calculation will return 1, otherwise, it will return 0.

To check Date1 is the same as Date2, you would use the equality operator:

Date1 = Date2

If the dates are the same, this calculation will return 1, otherwise, it will return 0.

Date calculations where the output is a Date/Time

As Date/Time Fields can only hold and display dates and times, any calculation performed in a Date/Time Field must return a date, a time, or a date and time. Date/Time Fields are therefore used to perform the following calculations:

1. Arithmetic - add or subtract a period of time (e.g. 5 months) to a date.
2. Min/max date - find the earliest or latest of two or more dates.

Arithmetic with dates

You can perform simple arithmetic with dates using various "Add" methods. The units of time that can be added to or subtracted from a date are years, months and days. For example, to calculate the date one year into the future from a date, you can use the following "AddYears" method:

Date.AddYears(X)

The "Add" methods accept negative X values to perform date subtractions. For example, to calculate the date five months before a date, you would use the "AddMonths" method with a negative X:

Date.AddMonths(-X)

The "AddDays" method follows the same syntax as the "AddYears" and "AddMonths" methods described above, however, a number of days can be added or subtracted from a date in two ways:

Date.AddDays(X) is the same as Date + X

Date.AddDays(-X) is the same as Date - X

Like the "Diff" method, there is a generic "Add'" method that can be used when the unit (years, months, days) is variable within your smart online form. Using the "Add" method is easy: 

Date.Add(X, "unit")

Valid units of the "Diff" method are:

• year or years,
• month or months, and
• day or days.

Units are not case-sensitive.

 

Minimum and maximum date comparisons

Unlike the boolean date comparisons that return the true and false values (0 and 1), the minimum and maximum date comparisons return the minimum or maximum of the dates compared. You can compare two or more dates.

For example, to find out which is the earliest of Date1, Date2 and Date3 you would use the following calculation:

Min(Date1,Date2,Date3)

Likewise, you can use Max() to find out which is the latest of two or more dates.

Date Properties

Date properties where the output is a number

You can use a calculation to determine the numeric value of the day, month or year of a date, as well as the name of the day or month, which we explain under, date calculations where the output is text.

For example, the calculation to return the "month" of a date is:

Date.Month

Accessing the year and day properties follow as expected.

For example, if a Date/Time Field is answered 12 May 2019:

1. Date.Day will return 12, and
2. Date.Year will return 2019.

Additional, you can use the "DayOfWeek" property that returns the number of the day in a week, for example, Monday = 1, Tuesday = 2, Wednesday = 3 etc.

For example, if the value of a date field is 21 July 2022, then:

Date.DayOfWeek returns 4.

 

Date properties where the output is text

There are two further properties of dates that return a string rather than a number.  As the output is a string, unless these calculations are part of another calculation, they must be used inside a Text Field.

Date.DayName returns the name of the day. 

Date.MonthName returns the name of the month.

For example, if the value of a date field is 21 July 2022, then

1. Date.DayName returns "Thursday"; and
2. Date.MonthName returns "July".