The HotDocs Computation Archive

Tut. 04 - Dates


Description:

How to use and compute date values.

 

• Introduction •

In HotDocs, date calculations as powerful as they are easy. This tutorial will guide you through all you need to know to begin calculating dates.

 
 
Section 1:  Simple Date Calculations

Open or create a computation variable that you can experiment with. In turn, type each of the following scripts, replacing the existing script each time. Click "Test" after each step.

 
Type the items in green: Click the "Test" button:
01 JAN 1976 January 1, 1976. This is the default date format for HotDocs
01 JAN 1976 + 1 DAY January 2, 1976
01 JAN 1976 - 1 DAY December 31, 1975
01 JAN 1976 + 10 DAYS January 11, 1976
01 JAN 1976 - 7 DAYS December 25, 1975
01 JAN 1976 + 1 WEEK Error
01 JAN 1976 - 10 WEEKS Error. HotDocs does not understand a "WEEK"; use 7 DAYS instead
01 JAN 1976 + 1 MONTH February 1, 1976
01 JAN 1976 - 2 MONTHS November 1, 1975
01 JAN 1976 + 1 YEAR January 1, 1977
01 JAN 1976 - 76 YEARS January 1, 1900
01 JAN 1976 + 1 day Error
01 JAN 1976 + 1 Day Error. HotDocs keywords must always be in ALL CAPS
01 JAN 1976 + 1 DAY January 2, 1976
 

• Explanation •

Date Models. These are the models relevant to calculating dates:

Date + Num DAY(S)
Date - Num DAY(S)
Date + Num MONTH(S)
Date - Num MONTH(S)
Date + Num YEAR(S)
Date - Num YEAR(S)

(Note that the "S" at the end of each model is optional. So 01 JAN 1950 + 1 DAY is functionally identical to 01 JAN 1950 + 1 DAYS.)

With each of these models you simply provide a date (more on this soon) plus or minus a number of DAYS, MONTHS, or YEARS, and HotDocs will compute the new date. The makers of HotDocs have taken great pains to make these date calculations as close to natural English as they reasonably can, a fact which you will grow to appreciate (if you have not already).

 
 
Section 2:  The Fine Points of Date Calculations

In turn, type each of the following, replacing the existing script each time. Click "Test" after each step.

 
Type the items in green: Click the "Test" button:
01 JAN 1976 + 1 MONTH February 1, 1976
31 JAN 1976 + 1 MONTH February 29, 1976
29 FEB 1976 - 1 MONTH January 29, 1976
29 FEB 1976 + 1 YEAR February 28, 1977
28 FEB 1977 - 1 YEAR February 28, 1976
01 MAR 1976 - 1 DAY February 29, 1976
28 FEB 1977 + 1 MONTH March 28, 1977
31 DEC 1976 + 1 DAY January 1, 1977
How does HotDocs deal with months of varying lengths and Leap Year? (Explanation below)
 

• Explanation •

HotDocs automatically takes care of rolling over months and years, working with months of varying lengths, and keeping track of leap years. But it is necessary for you, as a HotDocs programmer, to understand the logic behind the choices that HotDocs makes. For example, what is 31 JAN 1976 + 1 MONTH? Is it the same as 31 JAN 1976 + 30 DAYS? Or 31 JAN 1976 + 31 DAYS? What is a MONTH? There are a number of complexities that come into play when calculating dates. HotDocs resolves them as follows:

 
 
Section 3:  Date Values: Date Variables, TODAY

In this section, you will need the date and number variables you created in Tutorial 02, DateVar and NumVar. These should be available on the list of variables at the bottom left of the computation editor. If they are not there: On the "Show variables of type" or "Components" drop-down list, select "Date Variables." Click the "New" button to create a new date variable. Call it, simply, DateVar. For the prompt, put "Please provide a date." Now select "Number Variables" on the list and create one called NumVar.

In turn, type each of the following, replacing the existing script each time. Click "Test" after each step and answer whatever questions are asked.

 
Type the items in green: Click the "Test" button:
DateVar Your date in the default date format
DateVar + 1 DAY Your date plus one day
DateVar - 1 DAY Your date minus one day
DateVar + 10 DAYS Your date plus 10 days
DateVar - 7 DAYS Your date minus seven days
DateVar + 1 MONTH Your date plus one month
DateVar - 2 MONTHS Your date minus two months
DateVar + 1 YEAR Your date plus one year
DateVar - 76 YEARS Your date minus seventy-six years
DateVar + 99 YEARS - 1 DAY X years minus one day is common for expirations (statute of limitations, dissolution date for a limited liability company, etc.)
DateVar + NumVar YEARS Your date shifted by the number of years you provide
DateVar - NumVar DAYS Your date minus the number of days you provide
 

• Explanation •

In our computations so far we have used explicit date values. In other words, we have spelled the date out, as in 01 JAN 1976. In practice this really is not very useful, since we rarely deal with fixed dates. Instead we work almost exclusively with date variables.

Each of the date models we have seen will work with a date variable just as easily as it does with an explicit date. The only difference is that HotDocs will ask the user to provide the date. Likewise, the number value for DAYS, MONTHS, or YEARS can come from a number variable just as easily as from an explicit number.

TODAY. Perhaps the most useful date value available is a special HotDocs variable called TODAY. The TODAY variable always gives the current date. (Actually, it gives the current date according to your computer's internal clock, which may or may not be accurate. If you will be preparing date-sensitive documents, it is imperative that your computer always be set to the correct date and time).


•  •  •  •  •  •  •

Replace the script in your computation with TODAY and click the Test button. The computation should provide the current date. Repeat the exercises above, replacing DateVar with TODAY.

 
 
Section 4:  Introduction to DATE OF( )

In turn, type each of the following, replacing the existing script each time. Click "Test" after each step.

 
Type the items in green: Click the "Test" button:
DATE OF( 1, 1, 1975 ) January 1, 1975
DATE OF( 2, 1, 1975 ) January 2, 1975
DATE OF( 10, 1, 1975 ) January 10, 1975
DATE OF( 31, 1, 1975 ) January 31, 1975
DATE OF( 1, 1, 1975 ) January 1, 1975
DATE OF( 1, 2, 1975 ) February 1, 1975
DATE OF( 1, 10, 1975 ) October 1, 1975
DATE OF( 1, 13, 1975 ) Nothing
DATE OF( 1, 31, 1975 ) Nothing. Month must be in the range 1-12
DATE OF( 1, 1, 1975 ) January 1, 1975
DATE OF( 1, 1, 76 ) Nothing. Year must have at least four digits
DATE OF( 1, 2, 1975 ) February 1, 1975
DATE OF( 31, 2, 1975 ) Invalid date
DATE OF( 30, 2, 1975 ) Invalid date
DATE OF( 29, 2, 1975 ) Invalid date. February typically only has 28 days
DATE OF( 28, 2, 1975 ) February 28, 1975
DATE OF( 29, 2, 1976 ) February 29, 1976. HotDocs accounts for Leap Year
DATE OF( NumVar, 1, 1976 ) If you entered a number between 1 and 31, you got a date sometime in the month of January, 1976. Otherwise you got an error
 

• Explanation •

There is another very useful model, called DATE OF( ). We will only mention it briefly here and then revisit it shortly.

The DATE OF( ) model is a way of piecing together a date value. It takes three arguments: day, month, and year. Each of these is a number value - either an explicit number, or a number variable. The day value is a number between 1 and the last day of the month. The month is a number from 1 to 12. And the year is a four-digit number representing the year. For the sake of trivia, the earliest allowable year is 1582 and the latest is 30000 (yes, thirty thousand; this should cover any perpetuities imaginable).


•  •  •  •  •  •  •

In turn, create each of the following dates with the DATE OF( ) model, replacing the existing script each time. Click "Test" after each step to check your work.

July 4, 1776
February 7, 1812
December 17, 1903
November 11, 1918
January 15, 1929
July 24, 1969
Your Birthdate

• Explanation •

Two observations. First, the DATE OF( ) model must produce a valid date or HotDocs will raise an error. Second, at first glance DATE OF( ) seems like a more complicated way of just using "01 JAN 1976." But we will soon see how powerful the DATE OF( ) model really is when we grasp that it accepts not just fixed numbers for its arguments, but also variables and portions of other dates. This makes it a truly flexible and useful date-constructing model.

 
 
Section 5:  Parsing Dates

In turn, create each of the following scripts replacing the existing script each time. Click "Test" after each step to check your work.

 
Type the items in green: Click the "Test" button:
DAY OF( TODAY ) Day of the month
MONTH OF( TODAY ) Month as a number
YEAR OF( TODAY ) Four-digit year
Look at the title bar of the computation editor. What kind of value do these models return? Number, not date. These models extract a single number value (day, month, or year) from a date
 

• Explanation •

The DATE OF( ) model has three companion models:

DAY OF( Date )
MONTH OF( Date )
YEAR OF( Date )

Each of these models extracts, or parses out, one element of a date value, returning it as a number. So the DAY OF( 04 JUL 1776 ) is 4, the MONTH OF( 04 JUL 1776 ) is 7 (July is month number 7 of 12), and the YEAR OF( 04 JUL 1776 ) is 1,776 (note the comma; this is a number value).

To reiterate an essential point, just because these models take a date value as their argument, do not get confused into thinking that they return dates. They return number values.

 
 
Section 6:  Putting It All Together

You will now notice that the DATE OF( ) model is the opposite of its three companions, DAY OF( ), MONTH OF( ), and YEAR OF( ). These three take dates apart while DATE OF( ) puts them back together. This combination becomes a very powerful date creation tool.

In turn, create each of the following scripts, using the date variable DateVar where required. Replace the existing script each time. Click "Test" after each step to check your work.

 
Type the items in green: Click the "Test" button:
DATE OF( 14, 2, YEAR OF( TODAY ) ) Valentine's Day of this year (February 14)
DATE OF( 1, 4, YEAR OF( TODAY ) ) April Fool's Day of this year (April 1)
DATE OF( DAY OF( DateVar ), MONTH OF( DATE VAR ), YEAR OF( TODAY )
 
(select your date of birth in DateVar)
Your Birthday this year
DATE OF( DAY OF( DateVar ), MONTH OF( DATE VAR ), YEAR OF( TODAY ) ) + 10 YEARS
 
(select your date of birth in DateVar)
Your Birthday ten years from now
DATE OF( 1, MONTH OF( DateVar ) + 6, YEAR OF( DateVar ) ) The first day of the month six months away if you chose a month from January to June. Otherwise an invalid date. Why? If the MONTH OF( DateVar ) is 7, adding 6 to it produces 13, and invalid month
DATE OF( 1, MONTH OF( DateVar ), YEAR OF( DateVar ) ) + 6 MONTHS The first day of the month six months away. Why is this better than the method above?
DATE OF( 29, 2, 1976 ) February 29, 1976 (Leap Year)
DATE OF( 29, 2, YEAR OF( TODAY ) ) February 29 of this year if it is Leap Year. Otherwise, an invalid date
DATE OF( 31, MONTH OF( DateVar ), YEAR OF( DateVar ) ) The thirty-first day of the month in DateVar, which may or may not be valid. Try a few different months. Some have thirty-one days, others don't
DATE OF( 1, MONTH OF( DateVar ), YEAR OF( DateVar ) ) + 1 MONTH - 1 DAY The last day of the month in DateVar. Try a few different months, including February and February of 1976 (or another leap year)
How can you accurately obtain the last day of a month without getting errors? Obtain the first day of the month, then add one month and subtract one day. This will account for months of varying lengths and leap years
 

These can be real brain-benders. Take them one element at a time, and you'll soon get the hang of them.

Tip: Use the DATE OF( ) model to produce a date, then follow it with the Date + DAYS/MONTHS/YEARS models to perform your date calculations. Remember that HotDocs automatically accounts for leap years, year roll-overs, and varying month lengths when it makes date calculations. You probably do not.

 
RULE
The DATE OF( day, month, year ) model builds a date piece by piece. Each argument must be a number. These numbers can be explicit (e.g. 02), number variables, or they can be from DAY OF( ), MONTH OF( ), or YEAR OF( ).
 
 
RULE
The DAY OF( Date ), MONTH OF( Date ), and YEAR OF( Date ) models take dates apart. Each one returns just one piece of a date as a number.
 
 
 
Section 7:  A Note on Whitespace

Whitespace is defined as everything in a script that is not script. In other words, spaces, tabs, and returns. HotDocs is very tolerant of whitespace. For example, all of the following will produce the same result:

DATE OF( 31, MONTH OF( DateVar ), YEAR OF( DateVar ) )

DATE OF (31, MONTH OF (DateVar), YEAR OF (DateVar))

DATE OF(31,MONTH OF(DateVar),YEAR OF(DateVar))

DATE OF(
	31,
	MONTH OF( DateVar ),
	YEAR OF( DateVar )
)

DATE OF( 31,
         MONTH OF( DateVar ),
         YEAR OF(  DateVar ))

Some are much more readable than others. You are encouraged to use as much whitespace as you would like, and to especially make use of tabs and returns. Judicious and consistent use of whitespace can make complicated scripts very readable. (Note: To produce a tab, hold down the Ctrl key while you tab).

 
 
Section 8:  Date Models That Return Numbers

In turn, create each of the following scripts, using the date variable DateVar where required. Replace the existing script each time. Click "Test" after each step to check your work.

 
Type the items in green: Click the "Test" button:
AGE( DateVar ) The number of years from DateVar to TODAY
YEARS FROM( DateVar, TODAY ) Same as AGE( TODAY )
YEARS FROM( 29 FEB 1976, TODAY ) Number of years since February 29, 1976 (Leap Year)
YEARS FROM( 01 JAN 1976, TODAY ) Number of years since January 1, 1976
YEARS FROM( TODAY, 01 JAN 1976 ) Number of years since January 1, 1976. The order of dates does not matter
YEARS FROM( 29 FEB 1976, 28 FEB 1977 ) 0
YEARS FROM( 29 FEB 1976, 01 MAR 1977 ) 1
What does HotDocs consider a year to be? Same day of the same month is reached. So February 29 - February 28 is not a year. February 29 - March 1 is
MONTHS FROM( 01 JAN 1976, 01 FEB 1976 ) 1
MONTHS FROM( 02 JAN 1976, 01 FEB 1976 ) 0
MONTHS FROM( 31 JAN 1976, 29 FEB 1976 ) 0
MONTHS FROM( 31 JAN 1976, 01 MAR 1976 ) 1
MONTHS FROM( 29 FEB 1976, 29 MAR 1976 ) 1
MONTHS FROM( 01 JAN 1976, 14 FEB 1976 ) 1
MONTHS FROM( 14 JAN 1976, 01 FEB 1976 ) 0
What does HotDocs consider a month to be? The same day of the month is reached. So January 31 - February 28/29 is not a month. However, what is 31 JAN 1976 + 1 MONTH?
MONTHS FROM( 01 JAN 1976, TODAY ) Many (more than 240)
MONTHS FROM( TODAY, 01 JAN 1976 ) Same. The order of dates does not matter
DAYS FROM( 01 JAN 1976, 01 FEB 1976 ) 31
DAYS FROM( 01 JAN 1976, 29 FEB 1976 ) 59
DAYS FROM( 01 JAN 1976, 01 MAR 1976 ) 60
DAYS FROM( 01 JAN 1977, 01 MAR 1977 ) 59
How does HotDocs calculate the number of days lapsed? Actual days between the dates, leap year and varying-length months taken into consideration
DAY OF WEEK( DateVar ) The day of the week from 1 to 7
DAY OF WEEK( DateVar ) + 1 DAY Invalid. Why? DAY OF WEEK is a number value. Date + DAYS is a date value. You cannot add numbers and dates
DAY OF WEEK( DateVar + 1 DAY ) The day of the week of the day after DateVar
DAY OF WEEK( DateVar )
 
(select your date of birth for DateVar)
The weekday you were born on
DAY OF WEEK( DATE OF( DAY OF( DateVar ), MONTH OF( DateVar ), YEAR OF( TODAY ) ) )
 
(select your date of birth for DateVar)
The weekday your Birthday will be on this year
DAY OF WEEK(
    DATE OF(
        DAY OF( DateVar ),
        MONTH OF( DateVar ),
        YEAR OF( TODAY )
    )
)
Same as previous computation, but much more readable
 

• Explanation •

You have already seen three date models that return numbers rather than date values: DAY OF( ), MONTH OF( ), and YEAR OF( ). There are five others:

AGE( BirthDate )
DAY OF WEEK( Date )
DAYS FROM( Date, Date )
MONTHS FROM( Date, Date )
YEARS FROM( Date, Date )

The AGE( ) model returns age as of TODAY. It is exactly the same as YEARS FROM( BirthDate, TODAY ). The DAY OF WEEK( ) model returns a number from 1-7, where 1 is the first day of the week and 7 is the last. The DAYS/MONTHS/YEARS FROM models return a count up to and including the second date. If, in the case of MONTHS FROM and YEARS FROM, there is a partial month or year, it will not be included in the count. For example, YEARS FROM( 01 JAN 1976, 31 DEC 1977 ) is 0. Also note that with these models it does not matter which date is first or last.

 
 
Section 9:  DAY OF YEAR( )

HotDocs does not provide a DAY OF YEAR( Date ) model to give the day of the year (1-355/6). Let's create our own. The DAY OF YEAR is simply the number of days which have elapsed since January 1 of this year, where January 1 is day one.

 
Steps: Solution:
Which model should we use to obtain January 1 of this year? DATE OF( )
If we want to obtain the date of January 1 of this year, what should the day value be for DATE OF( )? 1
What should the month value be? 1
What should the year value be? Remember that this should automatically adjust itself from year to year YEAR OF( TODAY )
Put together the DATE OF( ) portion of the computation DATE OF( 1, 1, YEAR OF( TODAY ) )
Which model will now give us the number of lapsed days? DAYS FROM( )
Add this to the computation so that it will tell us the number of days from January 1 of this year to TODAY DAYS FROM( DATE OF( 1, 1, YEAR OF( TODAY ) ), TODAY )
If TODAY's date were January 1, what number would the computation produce? 0. No days have lapsed from January 1 to January 1
Update the computation so that the first day of the year will be Day 1 instead of Day 0 DAYS FROM( DATE OF( 1, 1, YEAR OF( TODAY ) ), TODAY ) + 1
Why use "+ 1" and not "+ 1 DAY"? You only add DAYS to date values. This computation is producing a number
 

So the DAY OF YEAR computation is:

DAYS FROM( DATE OF( 1, 1, YEAR OF( TODAY ) ), TODAY ) + 1

Or, you might prefer:

DAYS FROM(
    DATE OF( 1, 1, YEAR OF( TODAY )),
    TODAY
)
RESULT + 1
 
 
Section 10:  Practical Examples
LU:DAYS LU:WEEKS LU:MONTHS LU:YEARS LU:TODAY LU:DAYS FROM LU:MONTHS FROM LU:YEARS FROM LU:AGE LU:DAY OF LU:MONTH OF LU:YEAR OF LU:DATE OF

•  •  •  •  •  •  •

 

• Contributors •

LegalCS