calc: Date Functions
8.5.2 Date Functions
--------------------
The ‘t N’ (‘calc-now’) [‘now’] command pushes the current date and time
on the stack as a date form. The time is reported in terms of the
specified time zone; with no numeric prefix argument, ‘t N’ reports for
the current time zone.
The ‘t P’ (‘calc-date-part’) command extracts one part of a date
form. The prefix argument specifies the part; with no argument, this
command prompts for a part code from 1 to 9. The various part codes are
described in the following paragraphs.
The ‘M-1 t P’ [‘year’] function extracts the year number from a date
form as an integer, e.g., 1991. This and the following functions will
also accept a real number for an argument, which is interpreted as a
standard Calc day number. Note that this function will never return
zero, since the year 1 BC immediately precedes the year 1 AD.
The ‘M-2 t P’ [‘month’] function extracts the month number from a
date form as an integer in the range 1 to 12.
The ‘M-3 t P’ [‘day’] function extracts the day number from a date
form as an integer in the range 1 to 31.
The ‘M-4 t P’ [‘hour’] function extracts the hour from a date form as
an integer in the range 0 (midnight) to 23. Note that 24-hour time is
always used. This returns zero for a pure date form. This function
(and the following two) also accept HMS forms as input.
The ‘M-5 t P’ [‘minute’] function extracts the minute from a date
form as an integer in the range 0 to 59.
The ‘M-6 t P’ [‘second’] function extracts the second from a date
form. If the current precision is 12 or less, the result is an integer
in the range 0 to 59. For higher precision, the result may instead be a
floating-point number.
The ‘M-7 t P’ [‘weekday’] function extracts the weekday number from a
date form as an integer in the range 0 (Sunday) to 6 (Saturday).
The ‘M-8 t P’ [‘yearday’] function extracts the day-of-year number
from a date form as an integer in the range 1 (January 1) to 366
(December 31 of a leap year).
The ‘M-9 t P’ [‘time’] function extracts the time portion of a date
form as an HMS form. This returns ‘0@ 0' 0"’ for a pure date form.
The ‘t M’ (‘calc-new-month’) [‘newmonth’] command computes a new date
form that represents the first day of the month specified by the input
date. The result is always a pure date form; only the year and month
numbers of the input are retained. With a numeric prefix argument N in
the range from 1 to 31, ‘t M’ computes the Nth day of the month. (If N
is greater than the actual number of days in the month, or if N is zero,
the last day of the month is used.)
The ‘t Y’ (‘calc-new-year’) [‘newyear’] command computes a new pure
date form that represents the first day of the year specified by the
input. The month, day, and time of the input date form are lost. With
a numeric prefix argument N in the range from 1 to 366, ‘t Y’ computes
the Nth day of the year (366 is treated as 365 in non-leap years). A
prefix argument of 0 computes the last day of the year (December 31). A
negative prefix argument from -1 to -12 computes the first day of the
Nth month of the year.
The ‘t W’ (‘calc-new-week’) [‘newweek’] command computes a new pure
date form that represents the Sunday on or before the input date. With
a numeric prefix argument, it can be made to use any day of the week as
the starting day; the argument must be in the range from 0 (Sunday) to 6
(Saturday). This function always subtracts between 0 and 6 days from
the input date.
Here’s an example use of ‘newweek’: Find the date of the next
Wednesday after a given date. Using ‘M-3 t W’ or ‘newweek(d, 3)’ will
give you the _preceding_ Wednesday, so ‘newweek(d+7, 3)’ will give you
the following Wednesday. A further look at the definition of ‘newweek’
shows that if the input date is itself a Wednesday, this formula will
return the Wednesday one week in the future. An exercise for the reader
is to modify this formula to yield the same day if the input is already
a Wednesday. Another interesting exercise is to preserve the
time-of-day portion of the input (‘newweek’ resets the time to midnight;
hint: how can ‘newweek’ be defined in terms of the ‘weekday’ function?).
The ‘pwday(DATE)’ function (not on any key) computes the day-of-month
number of the Sunday on or before DATE. With two arguments,
‘pwday(DATE, DAY)’ computes the day number of the Sunday on or before
day number DAY of the month specified by DATE. The DAY must be in the
range from 7 to 31; if the day number is greater than the actual number
of days in the month, the true number of days is used instead. Thus
‘pwday(DATE, 7)’ finds the first Sunday of the month, and ‘pwday(DATE,
31)’ finds the last Sunday of the month. With a third WEEKDAY argument,
‘pwday’ can be made to look for any day of the week instead of Sunday.
The ‘t I’ (‘calc-inc-month’) [‘incmonth’] command increases a date
form by one month, or by an arbitrary number of months specified by a
numeric prefix argument. The time portion, if any, of the date form
stays the same. The day also stays the same, except that if the new
month has fewer days the day number may be reduced to lie in the valid
range. For example, ‘incmonth(<Jan 31, 1991>)’ produces ‘<Feb 28,
1991>’. Because of this, ‘t I t I’ and ‘M-2 t I’ do not always give the
same results (‘<Mar 28, 1991>’ versus ‘<Mar 31, 1991>’ in this case).
The ‘incyear(DATE, STEP)’ function increases a date form by the
specified number of years, which may be any positive or negative
integer. Note that ‘incyear(d, n)’ is equivalent to
‘incmonth(d, 12*n)’, but these do not have simple equivalents in terms
of day arithmetic because months and years have varying lengths. If the
STEP argument is omitted, 1 year is assumed. There is no keyboard
command for this function; use ‘C-u 12 t I’ instead.
There is no ‘newday’ function at all because ‘F’ [‘floor’] serves
this purpose. Similarly, instead of ‘incday’ and ‘incweek’ simply use
‘d + n’ or ‘d + 7 n’.
Basic Arithmetic, for the ‘f ]’ [‘incr’] command which can
adjust a date/time form by a certain number of seconds.
Info Catalog
calc: Date Conversions
calc: Date Arithmetic
calc: Business Days