CVAZ 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

 

 

 

 

 

 

CVAZ 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

 

 

 

 

 

 

CVAZ 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

 

 

 

 

 

 

CVAZ 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

 

 

 

 

 

 

CVAZ 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

 

 

 

 

 

 

CVAZ 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

 

 

 

 

 

 

CVAZ 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