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.

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.

• 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).

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

• 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:

• DAY calculations are very straightforward. HotDocs simply counts forward (or backward) the given number of days and returns the date it finds there. Leap years are taken into account. So 31 JAN 1976 + 31 DAYS is March 2, 1976 (because of leap year).
   
• MONTH calculations move forward or backward by the given number of months. HotDocs then tries to find the target day in the resulting month. If the target day does not exist, HotDocs finds the nearest day in the target month that does exist. So in the case of 31 JAN 1976 + 1 MONTH, HotDocs looks for February 31, 1976, and not finding it, falls back to February 29, 1976 (because it is leap year). Going backwards, 29 FEB 1976 - 1 MONTH is January 29, 1976. Why not January 31? Because the target date is the 29th. You will see a sure-fire way to find the last day of any month below.
   
• YEAR calculations work much like the MONTH calculations. HotDocs looks for the same day and month a given number of years away (forward or backward). If the target date does not exist, HotDocs finds the nearest day in the target month that does exist.
   

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.

• 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.

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

• 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.

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

• 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.

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.

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.

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).

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.

• 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.

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.

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

•  •  •  •  •  •  •

• Contributors •