NCCI Perl Documentation DateMan(3)
NAME
DateMan - Date Management Routines
SYNOPSIS
# Access to modules (see the NOTES section for setup)
BEGIN {
...
push (@INC, "../sys/csbase/lib");
}
use DateMan;
$dm = new DateMan;
DESCRIPTION
This Perl module provides various and sundry Date and Time
maniuplation routines.
Definitions
These are useful in deciphering the routines in this module:
Ddd Three character Day-of-the-week designator, in Upper-
lower case.
Mmm Three character Month designator, in Upper-lower case.
yyyymmdd
For example: 19971215 or 20050306
HH_MM An HH:MM formatted time. The HH is in the range 00-23
and the MM is 00-60. Yes, it can actually go to 60 -
see Leap Seconds above.
yyyymmdd_HH_MM
A yyyymmdd formatted date with a " " (blank) and an
HH:MM formatted time. The HH is in the range 00-23 and
the MM is 00-60. Yes, it can actually go to 60 - see
Leap Seconds above.
ddMMMyyyy
For example: 12-APR-1997. This format is the 'native'
format for Oracle databases.
ddMMMyyy
This is an 'input' format to routines in this module.
It indicates acceptance of EITHER dd-MMM-yy or dd-
MMM-yyyy formatted dates (2- or 4-digit year). Also,
the month can be in ANY case (upper, lower, or
arbitrarily mixed).
19/Mar/01 Last change: perl 5.004, patch 01 1
NCCI Perl Documentation DateMan(3)
colloqDate
A "Colloquial Date" is a date representation which
takes into account the current year. If the year
matches this year: "Dec 20" If the year
doesn't match this year: "Dec 20 1998"
relDate
A "Colloquial Date" relative to today. It takes into
account the current date and (optionally) includes the
day of the week. Examples:
Today Mon Dec 20
Tomorrow Tue Dec 21
Yesterday Sun Dec 19
Sat Dec 18
Dec 22
Dec 23 1997
calDayBias
"Calendar Day Bias" - a number of actual calendar days
to "bias" a given date.
busDayBias
"Business Day Bias" - a number of business days to
"bias" a given date. Business days are Mon through
Fri, without considering any holidays.
weekBias
Number of weeks between the Monday which is equal to
or preceeding each of two dates.
relDayName
"Relative Day Name" - a day name in relation to today.
Could be (for example) "Yesterday", "Today",
"Tomorrow", "Monday", "Next Monday", "Last Friday",
etc.
hhmm Time of day in HH:MM format, with special cases values
for "Noon" and "Midnight". The hh is in the range
01-12 and the mm is in the range 00-60 (see the
disussion of Leap Seconds above).
hhmmam
Same as hhmm with " AM" and " PM" added (except in the
"Noon" and "Midnight" cases). The hh is in the range
01-12 and the mm is in the range 00-60 (see the
disussion of Leap Seconds above).
hourSlot
Number of hours since midnight, to the nearest minute,
expressed as a real number. So:
19/Mar/01 Last change: perl 5.004, patch 01 2
NCCI Perl Documentation DateMan(3)
9:01 AM would be 9.0166666667 (approximately)
9:06 AM would be 9.10
1:09 PM would be 13.15
12:30 AM would be 0.50
semiSlot
Integer number of half-hours since midnight. This is
(you might have guessed) a special case time format.
It's used for conference room scheduling, which are
done in half-hour increments. REMEMBER: it's always
an integer.
About Leap Seconds
In the formats below, the minutes typically take on the
value 00-59. However, they can take on the value 60, due to
the presence of leap-seconds. If the time being represented
happens to be a leap second, then the minute has 61 seconds.
If the minute happens to be 59, then the HH:MM or hh:mm
format represents the leap second as the first second of
minute "60".
Functions
DateMan->new();
Create a new DateMan object.
busDayBiasFromToday2relDayName ($busDaysFromNow)
Return a relDayName for a given number of Business days
from today.
For example, if today is Thursday, we map 0=>Today,
1=>Tomorrow, 2=>Monday, ...
The (currently) valid range of daysFromNow is -1 to 5.
busDayBiasFromToday2calDayBias ($busDaysFromNow)
Return the number of calendar days, given the number of
business days from today.
For example, if today is Friday, we map 1=>3, since one
business day from now is Monday, 3 actual days away.
The (currently) valid range of argument is: -1 to 5
hourSlot2hhmm ($hourSlot)
Return the colloquial time-of-day from an hourSlot with
no AM/PM indicator.
hh_mm2hhmmAm ($hh_mm)
Return the colloquial time-of-day from an HH_MM format
19/Mar/01 Last change: perl 5.004, patch 01 3
NCCI Perl Documentation DateMan(3)
time with AM and PM where appropriate.
hourSlot2hhmmAm ($hourSlot)
Return the colloquial time-of-day from an hourSlot with
AM and PM where appropriate.
hourSlot2hhmmOptAm ($hourSlot)
Return the colloquial time-of-day from an hourSlot with
AM and PM for times before 9AM and 6PM or after.
semiSlot2hhmm ($semiSlot)
Return the colloquial time-of-day from a semiSlot
(half-hours from midnight) with no AM/PM indicator.
semiSlot2hhmmAm ($semiSlot)
Return the colloquial time-of-day from a semiSlot
(half-hours from midnight) with AM and PM where
appropriate.
semiSlot2hhmmOptAm ($semiSlot)
Return the colloquial time-of-day from a semiSlot
(half-hours from midnight) with AM and PM for times
before 9AM and 6PM or after.
yyyymmdd_HH_MM2hourSlot ($yyyymmdd_HH_MM)
Return the hourSlot for a given yyyymmdd_HH_MM date/time
now2hourSlot ()
Return the hourSlot for the current time..
now2semiSlot ()
Return the semiSlot for the current time..
now2hhmm ()
Return the hh:mm time-of-day for the current time.
now2hhmmAm ()
Return the hh:mm AM/PM time-of-day for the current time.
now2hhmmOptAm ()
Return the colloquial time-of-day for the current time.
calDayBiasFromNow2yyyymmdd ($calDayBias)
Return the YYYYMMDD format for a given number of days
from now
today2yyyymmdd ()
Return today's date in YYYYMMDD format.
tomorrow2yyyymmdd ()
Return tomorrow's date in YYYYMMDD format.
19/Mar/01 Last change: perl 5.004, patch 01 4
NCCI Perl Documentation DateMan(3)
yesterday2yyyymmdd ()
Return yesterday's date in YYYYMMDD format.
calDayBiasFromYyyymmdd2yyyymmdd ($yyyymmdd, $calDayBias)
Return the YYYYMMDD format for a given number of days
from a given YYYYMMDD date.
yyyymmdd2Ddd ($yyyymmdd)
Return a Ddd 3-character day-of-week name for the given
yyyymmdd
yyyymmdd2Mmm ($yyyymmdd)
Return a Mmm 3-character Month name for the given
yyyymmdd
yyyymmdd2Mmm2 ($yyyymmdd)
Return the full name of the given month from yyyymmdd
yyyymmdd2ddMMMyyyy ($yyyymmdd)
Return an Oracle-friendly dd-MMM-yyyy formatted date,
given yyyymmdd
yyyymmdd2ddMmmyyyy ($yyyymmdd)
Return an Oracle-friendly dd-Mmm-yyyy formatted date,
given yyyymmdd
ddMMMyyy2yyyymmdd ($ddMMMyyy)
Convert a date in EITHER dd-MMM-yy or dd-MMM-yyyy format
into yyyymmdd
ddMMMyyy2yyyymmdd2 ($ddMMMyyy)
Convert a date in EITHER dd-MMM-yy or dd-MMM-yyyy format
into yyyymmdd This one makes sure the month is in two
digit format
yyyymmdd_HH_MM2colloqTime ($yyyymmdd_HH_MM)
Return the colloqTime for a given yyyymmdd_HH_MM
date/time
yyyymmdd_HH_MM2relTime ($yyyymmdd_HH_MM, $yyyymmddBase)
Return the relative time for a given yyyymmdd_HH_MM
date/time compared with yyyymmddBase.
yyyymmdd2colloqDate ($yyyymmdd)
Return a colloquial date for a given yyyymmdd
yyyymmdd2colloqDate2 ($yyyymmdd)
Return a colloquial date for a given yyyymmdd, but
always includes the year.
yyyymmdd2relDate ($yyyymmdd, $showDayOfWeek)
Return a relative date for a given yyyymmdd If
19/Mar/01 Last change: perl 5.004, patch 01 5
NCCI Perl Documentation DateMan(3)
$showDayOfWeek is true, the "Mon", "Tue", ... is
inserted in the result Examples:
Today Mon Dec 20
Tomorrow Tue Dec 21
Yesterday Sun Dec 19
Sat Dec 18
Dec 22
Dec 23 1997
yyyymmdd2calDayBiasFromToday ($yyyymmdd)
Return the day bias to get us from today to the day
which contains the given date.
yyyymmdd_yyyymmdd2calDaysBetween ($yyyymmdd1, $yyyymmdd2)
Return the calendar days between two yyyymmdd dates.
yyyymmdd2weekBiasFromThisWeek ($yyyymmdd)
Given a yyyymmdd date, return the weekBias from this
week.
yyyy2yyyymmddFirstMonday ($yyyy)
Given a yyyy year, return the yyyymmdd of the first
Monday of that year.
yyyymmdd2yyyymmddStartOfWeek ($yyyymmdd)
Given a yyyymmdd date, return the yyyymmdd of the Monday
at the beginning of that week. The input yyyymmdd
defaults to today.
yyyymmdd2yyyymmddEndOfWeek ($yyyymmdd)
Given a yyyymmdd date, return the yyyymmdd of the Friday
at the end of that week. The input yyyymmdd defaults to
today.
yyyymmdd2yyyymmddFirstMondayofMonth ($yyyymmdd)
Given a yyyymmdd date, return the yyyymmdd of the first
day of the month
yyyymmdd2yyyymmddLastDayofMonth ($yyyymmdd)
Given a yyyymmdd date, return the yyyymmdd of the last
day of the month
yyyymmdd2yyyymmddNextDay ($yyyymmdd)
Given a yyyymmdd date, return the yyyymmdd of the next
day.
yyyymmdd2yyyymmddPriorDay ($yyyymmdd)
Given a yyyymmdd date, return the yyyymmdd of the prior
day.
WARNING
None
19/Mar/01 Last change: perl 5.004, patch 01 6
NCCI Perl Documentation DateMan(3)
NOTES
This module has not yet been set up for "installation" in
your local Perl. We currently use a set of conventions for
access to this module, until the install procedures are
developed:
- The source code lives on development and production hosts
in the directory /Volumes/app/cs/csbase/lib.
- By convention, a project maintains perl scripts in
subdirectories of some top-level directory, which we will
call $TOP.
- By convention, projects establish a $TOP/sys directory
which contains a symbolic link from csbase to
/Volummes/app/cs/csbase.
- To get access to the modules, you typically include a
BEGIN of the form:
BEGIN {
...
push (@INC, "../sys/csbase/lib");
}
BUGS
None known.
SEE ALSO
AUTHOR
Clint Goss <clint@goss.com>, December 1997