zdate.man

来自「国外网站上的一些精典的C程序」· MAN 代码 · 共 696 行 · 第 1/3 页

             ZDATE - THE COMPLETE DATE MANIPULATION SOLUTION
             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

           The zDate class (all code, manuals and examples) is
             Copyright (c) 1995, 1996 Branislav L. Slantchev
                         (CompuServe: 73023,262)

       THIS VERSION IS EXPLICITLY DONATED BY THE AUTHOR TO THE SNIPPETS
       COLLECTION MAINTAINED BY BOB STOUT. YOU ARE ALLOWED TO USE THE
       CODE FOR ANY PURPOSE (INCLUDING COMMERCIAL) FREE OF CHARGE AS
       LONG AS YOU ACKNOWLEDGE IT. YOU ARE NOT ALLOWED TO REMOVE THE
       COPYRIGHT NOTICES FROM THE CODE. YOU ARE FREE TO MAKE ANY
       MODIFICATIONS NECESSARY TO SUIT YOUR NEEDS. I WILL APPRECIATE IF
       YOU NOTIFY ME OF THESE CHANGES BUT THIS IS NOT A REQUIREMENT.
       THERE ARE NO WARRANTIES, EITHER EXPRESS OR IMPLIED ABOUT THE
       FITNESS OF THIS PRODUCT FOR ANY PARTICULAR PURPOSE. USE AT YOUR
       OWN RISK. THE AUTHOR WILL BE IN NO WAY LIABLE FOR ANY USE, MISUSE
       OR INABILITY TO USE OF THIS PRODUCT, AS WELL AS ANY LOSSES THAT
       MIGHT HAVE OCCURRED AS RESULT OF THESE.

The zDate class provides your C++ programs with one of the most useful and
easy to use date classes I have seen. It has been developed over a period of
almost two years, with the functionality being refined to the point that the
class interface is unobtrusive and intuitive. You won't have to worry about
hidden assumptions, or side effects or oddly-named member functions.
Everything is in plain sight. Having said that, let's look at some class
specifics.

The zDate class is not meant to be used as a base class. You can, of course,
but there's little point in doing it. There are no date formatting functions.
I felt that these are fairly easy to find and the ANSI C library provides a
very useful implementation in its strftime() function. There was simply no
need to re-invent the wheel. The class, however, provides all the
functionality you might need. Simple operators like comparison and assignment
make the class as straightforward as can be. All the enumerated constants are
encapsulated within the class to avoid namespace pollution. This class was
written with the century roll-over in mind. It will work just fine after the
year 2000 unlike many other implementations.

I should note here that the day numbering used internally (and retrievable
via the DayNumber() function) is NOT the true Julian day scheme. This one
begins at 1 A.D. unlike the Julian day numbers which go back 4000 years B.C.
Effectively, this means that you cannot have dates which go into negative
years, but I have yet to see this as a limitation worthy of a class re-
design.

The class follows the general PB-Lib coding standards. For a complete
reference, read the file Standard.Doc available with the library release.
It should suffice to note that all member functions use mixed-case naming,
with the first letters of each word capitalized. Functions that do not
modify the class internals are declared as const. Functions that can be
used without actually instantiating an object of the class are declared
static. These can be used with the simple scope resolution operator without
an object pointer. What follows is a complete class reference for all public
data members and methods. Note that private and protected members and methods
are not documented here. They are, however, fully explained with code
comments.


   ZDATE::MONTH
   --------------------------------------------------------------------------
     Synopsis   Enumeration type for the months of the year.

     Syntax     enum month { jan=1, feb, mar, apr, may, jun,
                             jul, aug, sep, oct, nov, dec };

     Remarks    Use this enumeration to interpret the return values of
                various member functions. You should use the scope
                resolution operator to access them outside the class.

     Return     n/a

     See also   zDate::week_day; zDate::moon_phase

     Example    zDate::month myMonth = zDate::jul;
                if( zDate::aug == myMonth ) cout << "This can't be.";



   ZDATE::WEEK_DAY
   --------------------------------------------------------------------------
     Synopsis   Enumeration type for the different days of the week.

     Syntax     enum week_day { mon=1, tue, wed, thu, fri, sat, sun };

     Remarks    Use these enumerated constants to access the various day of
                week return values of functions. You must use the scope
                resolution operator to access them.

     Return     n/a

     See also   zDate::month; zDate::moon_phase

     Example    zDate::week_day wday = zDate::sun;
                switch( wday ){
                    case zDate::sat:
                    case zDate::sun:
                        cout << "Oh, weekend! I love those" << endl;
                    break;
                   default: cout << "Another boring day!" << endl;
                }


   ZDATE::MOON_PHASE
   --------------------------------------------------------------------------
     Synopsis  Enumeration constants to access the return value of the
               MoonPhase routines.

     Syntax    enum moon_phase{ new_moon, waxing_crescent, first_quarter,
                                waxing_gibbous, full_moon, waning_gibbous,
                                third_quarter, waning_crescent };

     Remarks   Use these enumerated constants to interpret the return value
               of the MoonPhase() member function. You should use the scope
               resolution operator to access them.

     Return    n/a

     See also  zDate::MoonPhase; zDate::month; zDate::week_day

     Example   zDate::moon_phase phase = zDate::MoonPhase(zDate::Today());
               switch( phase ){
                   case zDate::full_moon:
                       cout << "Grrrrr! The Werewolves are out!";
                       break;
                   default: cout << "Nothing yet!" << endl;
               }


   ZDATE::ZDATE
   --------------------------------------------------------------------------
     Synopsis  Various constructors to initialize the date objects.

     Syntax    zDate();
               zDate(month aMonth, int aDay, int aYear);
               zDate(int dayOfYear, int aYear);
               zDate(const zDate &aDate);
               zDate(ulong nDayNumber);
               zDate(const struct tm *tmDate);

     Remarks   These constructors are used to initialize the date object in
               various ways. The parameter names are self-explanatory.
               Things you should know are that none of these constructors
               will check the validity of the data being passed to it. You
               must verify that all parameters are correct or the results
               will be unpredictable. Years are specified in full (i.e. for
               1996, you must pass 1996 as the aYear parameter, not 96 or
               anything else). Years can go back to 1 A.D. You cannot use
               negative years. The earliest date that is valid for the zDate
               class is January 1, 0001. The 'dayOfYear' parameter must be
               the number of the day for the 'aYear', starting with January 1
               as day number 1. The 'nDayNumber' parameter is NOT the true
               Julian day number of the day (these start some 4,000 years BC).
               Rather, it's the day number with base of January 1, 0001 as
               the 1st day. For the last constructor, the 'tmDate' parameter
               must be correctly initialized as per its specifications (see
               your compiler manual). With this format, the year is an
               offset from 1900 (that is, 1996 is 96 and 2012 is 112). Also,
               the month numbering scheme is different. These are all taken
               care of in the zDate constructor itself. Finally, the copy
               constructor will initialize the current zDate object with the
               value of another one.

     Return    n/a

     See also  zDate::Today(); zDate::EndDST(); zDate::BeginDST()

     Example   // here are examples of all possible ways of initialization
               zDate date1;                       // January 1, 0001
               zDate date2(zDate::jul, 16, 1973); // July 16, 1973
               zDate date3(15, 1995);             // January 15, 1995
               zDate date4(date2);                // same as date2
               zDate date5(728945L);              // October 11, 1996
               time_t secs = time(0);             // current time/date
               zDate date6( localtime(&secs) );   // (use struct tm*)
               zDate date7(zDate::Today());       // current date


   ZDATE::ADDMONTHS
   --------------------------------------------------------------------------
     Synopsis  Adds or subtracts months from the date object.

     Syntax    zDate AddMonths(int nMonths) const;

     Remarks   This member function will add or subtract (if 'nMonths' is
               negative) the number of months to the current date object and
               will return another zDate object with the new values. It does
               not modify the current object. This will adjust the number of
               years if necessary. Note that month arithmetic is fairly
               straightforward as only the month will be changed regardless
               of the days in each month. However, this may cause some
               invalid dates (such as July 31 minus 5 months is February 31,
               which is clearly invalid). The function will adjust the day
               of the month in that case according to the following rules:
               if adding months, the month will roll over into the next one
               (causing a year increase, if necessary) and the new day number
               will be the overflow (i.e. April 31 will become May 1). If
               subtracting, the overflow is subtracted from the current day
               number (i.e. in the example with February, the new day will
               be 27 or 26, depending on whether the year is leap or not).
               Care must be taken when subtracting months not to cause the
               year to become less that 1 A.D.

     Return    A zDate object with the new date value.

     See also  zDate::AddYears(); zDate::AddWeeks(); zDate::operator+();

     Example   zDate ind(zDate::jul, 4, 1776);
               assert(ind.AddMonths(2400)==zDate(zDate::jul,4,1996));


   ZDATE::ADDWEEKS
   --------------------------------------------------------------------------
     Synopsis  Adds or subtracts a number of weeks from the date object.

     Syntax    zDate AddWeeks(int nWeeks) const;

     Remarks   This member function will add or subtract (if 'nWeeks' is
               negative) the number of weeks from the current date object
               and will return a new zDate object with the resulting value.
               It does not modify the calling object. There are no fancy
               calculations with this function, it simply uses weeks as
               spans of 7 days and actually adds/subtracts days. This will
               modify the year and the month, as well as the day as necessary.
               Care must be taken that the year does not become less than
               1 A.D.

     Return    A zDate object with the new date value.

     See also  zDate::AddYears(); zDate::AddMonths(); zDate::operator+();

     Example   zDate date(zDate::oct, 11, 1996);