Description :
The *inPeriod* function determines if a given time falls within a given
period. *inPeriod* returns *1* if the time does fall within the given
period, *0* if not, and *-1* if *inPeriod* detects a malformed time or
period.
The time is specified as per the \'time()\' function, which is assumed to be
the number of non-leap seconds since January 1, 1970.
The period is specified as a string which adheres to the format
sub-period[, sub-period...]
or the string \"none\" or whitespace. The string \"none\" is not case
sensitive.
If the period is blank, then any time period is assumed because the time
period has not been restricted. In that case, *inPeriod* returns 1. If the
period is \"none\", then no time period applies and *inPeriod* returns 0.
A sub-period is of the form
scale {range [range ...]} [scale {range [range ...]}]
Scale must be one of nine different scales (or their equivalent codes):
Scale | Scale | Valid Range Values
| Code |
*******|*******|************************************************
year | yr | n where n is an integer 0< =n< =99 or n>=1970
month | mo | 1-12 or jan, feb, mar, apr, may, jun, jul,
| | aug, sep, oct, nov, dec
week | wk | 1-6
yday | yd | 1-366
mday | md | 1-31
wday | wd | 1-7 or su, mo, tu, we, th, fr, sa
hour | hr | 0-23 or 12am 1am-11am 12noon 12pm 1pm-11pm
minute | min | 0-59
second | sec | 0-59
The same scale type may be specified multiple times. Additional scales
simply extend the range defined by previous scales of the same type.
The range for a given scale must be a valid value in the form of
v
or
v-v
For the range specification v-v, if the first value is larger than the
second value (e.g. \"min {20-10}\"), the range wraps around unless the scale
specification is year.
Year does not wrap because the year is never really reset, it just
increments. Ignoring that fact has lead to the dreaded year 2000 nightmare.
When the year rolls over from 99 to 00, it has really rolled over a
century, not gone back a century. *inPeriod* supports the dangerous two
digit year notation because it is so rampant. However, *inPeriod* converts
the two digit notation to four digits by prepending the first two digits
from the current year. In the case of 99-1972, the 99 is translated to
whatever current century it is (probably 20th), and then range 99-1972 is
treated as 1972-1999. If it were the 21st century, then the range would be
1972-2099.
Anyway, if v-v is 9-2 and the scale is month, September, October, November,
December, January, and February are the months that the range specifies. If
v-v is 2-9, then the valid months are February, March, April, May, Jun,
July, August, and September. 9-2 is the same as Sep-Feb.
v isn\'t a point in time. In the context of the hour scale, 9 specifies the
time period from 9:00:00 am to 9:59:59 am. This is what most people would
call 9-10. In other words, v is discrete in its time scale. 9 changes to 10
when 9:59:59 changes to 10:00:00, but it is 9 from 9:00:00 to 9:59:59. Just
before 9:00:00, v was 8.
Note that whitespace can be anywhere and case is not important. Note also
that scales must be specified either in long form (year, month, week, etc.)
or in code form (yr, mo, wk, etc.). Scale forms may be mixed in a period
statement.
Furthermore, when using letters to specify ranges, only the first two for
week days or the first three for months are significant. January is a valid
specification for jan, and Sunday is a valid specification for su. Sun is
also valid for su.
|
