DTime+, A collection of Date and Time Classes for C++/MFC

Version 3.09

Copyright (c) 1995 - 2007 PJ Naughter

DTime+ is a collection of classes & functions designed to ease the MFC programmers’ burden when handling date and time values. If like me, having taken a look at the built in MFC classes CTime and CTimeSpan or the OLE based COleDateTime and COleDateTimeSpan classes, you decided they did not meet your requirements, and you decided to write your own super-duper date and time classes, but deadlines were looming, then look no further. The basis of the algorithms for conversion from the Julian and Gregorian calendar to the underlying storage was adopted from an article by Peter J.G. Meyer for the March 1993 issue of Dr Dobbs Journal. You can find the article online at http://www.ddj.com/184408959. The algorithm used to determine the date of Easter Sunday is taken from the book ‘Astronomical Algorithms’ by Jean Meeus. The algorithms for the Moslem (Islamic) and Hebrew calendar are provided by the book "Calendrical Calculations, The Millenium Edition" by Edward M. Reingold and Nachum Dershowitz. Calendrical Calculations has always been a favourite topic of the author and was in fact some of the first code which I published on the web back in the mid 90's. Originally the code was shareware but I've now decided to make it freeware in the hope that more people will find it useful in their day to day projects.

Sections in this Document

Copyright

Features

History

How to Use

CDate Index

CLTimeSpan Index

CLTimeOfDay Index

CLDate Index

Structures used by the classes

Future Enhancements

UI Support

Contacting the Author

Copyright

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

Features

• The classes provided are implemented as a C++ template based class framework.
• The code fully supports the Gregorian, Julian and Moslem (Islamic) and Hebrew calendars. DTime+ also supports proleptic versions of all of these calendars. You can also easily convert between all the calendar types. The 4 most common forms of the Moslem Arithmetic calendar are supported namely the 15th and 16th year leap year rules as well as the Civil Epoch (16 July 622 C.E. O.S) and the Astronomical Epoch (15 July 622 C.E. O.S).
• The classes stick very closely to the MFC class structures and provide routines to map from CTime, COleDateTime, COleDateTimeSpan and CTimeSpan. Mappings are also available to convert to and from Win32 SDK date and time structures.
• The classes do not rely on the ‘C’ runtime library like CTime does. If you have used the CTime class then you will no doubt have come across its dependence on the environment variable ‘TZ’ and all the problems that can give. The classes use of UTC / Local is much less vague than CTime which performs automatic mappings which can confuse even the most experienced developer. There are also various static buffer issues with the built in MFC classes which can provide for very difficult to debug issues.
• A number of date / time classes are provided namely CDate, CLTimeSpan, CLTimeOfDay and CLDate.
• Methods are provided to integrate with the date time UI controls on Windows.
• Includes comprehensive support for Holidays, Christian Saints Days, National Holidays, US Specific Holidays, Christian Feast Days, Moslem and Hebrew holidays.
• Tight integration with the Win32 NLSAPI. For example all the day of week and month strings are taken from Win32. This means that if DTime+ is used on an international version of Windows, the days of week etc. will be in the local language.
• Format functions with a superset of the functionality provided by CTime/CTimeSpan::Format.
• The Format functions are also able to display a date or time according to display characteristics as specified in the Windows Control Panel.
• The CDate class provides a resolution of 1 day and uses a long to represent the count of days. Its range is valid for roughly the whole range of a long i.e. +/- 2 billion days (or just under 5.5 million years!) from the current era.
• The CLTimeOfDay class represents a time of day i.e. 00:00:00 to 23:59:59 and provides a resolution of 1 second.
• The CLTimeSpan class represents the time interval between two CLDate instances and provides a resolution of 1 second.
• The CLDate class represents the composite of a date and a time of day together and provides a granularity of 1 second. As with CDate, the full range of a long is valid i.e. +/- 5.5 million years. This is ‘quite’ larger than the roughly 60-year time span for CTime (assuming you are not using the 64 bit CTime data type available in Visual Studio 2005) and the 100 CE - 9999CE time span for COleDateTime. Using CLDate means that you can represent +/- 5.5 million years from the current era with a resolution of 1 second.
• All classes are fully Unicode enabled and Unicode build configurations are provided in the sample apps provided.
• All classes and defines are declared in a C++ namespace called DTimePlus. This helps reduce pollution of the C++ global namespace.
• DTime+ is compatible with MFC and Microsoft Visual C++ 6 and later.

History

• Initial public Win32 release.

• Port to Win16 and DOS.
• Implementation of a comprehensive OS detection routine.
• A number of classes and functions to make code portable across OS platforms.
• Addition of a number of member functions to return a C runtime tm struct version.
• TermDTime added and InitDTimeDll now renamed to InitDTime.
• ‘printf’ like function made available under Win16.
• A CStringEx class which provides a Format method under Win16 and DOS and a LoadString method under DOS.

• v1.0 translation to German.

• Tighter integration with Win32 NLSAPI.
• Provision of a real control panel applet.
• Enhanced data entry routines.
• Numerous bug fixes.
• Removal of OS detection routine to separate package.
• Removal of Pushpin class to separate package.
• Removal of DOS and Win16 code no longer used.
• DTime has dropped support for millisecond fields in the CLTimeOfDay, CLTimeSpan and CLDate classes. You will need to check code that was used with DTime v1.x to make sure the correct constructors are being called. This functionality was removed following customer feedback about its usefulness. The extra fields required to support milliseconds also introduced a number of subtle bugs that were discovered during testing of v2.0.

• v2.0 translation to German.
• Addition of extra CDate and CLDate functions to interact with SYSTEMTIME and FILETIME SDK structures.
• Addition of extra CDate, CLTimeOfDay and CLDate functions which return a tm struct.
• Major modification to CLDate::SetTimeFrame function to correctly handle timezones other than GMT correctly.
• Number of other minor tweaks and bug fixes following feedback from customers.
• Fixed a number of anomalies in the help file dating back to v1.1.
• Enhanced the data entry methods DTime supports. It now allows a Julian Day to be entered. Also additional flags have been added to control how the data entry operates.
• All the arithmetic operators have been enhanced to handle invalid state of their operands, instead of just asserting when an invalid operand is found.

v2.2

• Modification to serialize functions to save space on disk.
• Replaced use of AFX_EXT_API and AFX_EXT_CLASS to allow use of DTime in another extension dll.
• Added support for using the DTime source code directly in your application instead of through an Extension DLL.
• Added a DTIME_NO_OLE_SUPPORT macro which removes the dependency of DTime on the MFC OLE dlls. Note that this can only be used if you include the DTime source code directly in your application.
• Changed the load address of all variants of the DTime dll. This reduces the occurrences of dll collisions at process load up time.
• Made DTime and its sample programs compatible with VC++ 5.0.
• Added support in DTime for Propalactive Julian and Gregorian Calendars.
• Added support for converting from a CLDate to a COleDateTime.
• Removed the ‘Apply Now’ buttons from the data entry dialogs.
• Major revamp of the install program to give it a more professional look.
• Major update to the help file. Includes changes suggested by customers such as making its look and feel more consistent with VC++ books online and Windows 95 Help. Also fixed a number of mistakes which were in the 2.1 version of the help file.

v2.21 (17 July 1998)

• Updated 2 files for DTime which fixes a problem with usage of DTime in a multithreading application. Basically it boiled down to code in DTime which was making changes to a global array "MonthLength" from two threads. Now a local array is used, thus preventing the problem. Just copy the two files into your DTime "SRC" directory over the existing files of the same name.

• Updated 4 files for DTime. This fixes a number of problems DTime was having when compiled with Visual C++ 6, Just copy the three cpp files into your DTime "SRC" and the one h file into your DTime "Include" directory over the existing files of the same name. 4 files are included in total (1 file which was modified in v2.21) meaning that you do not need to apply the v2.21 patch as the v2.22 patch includes all of the changes since the v2.2 main release.

• Refresh of the code following the creation of my new site http://www.naughter.com.

v3.0 (22 April 2006)

• Following a long term of hibernation, DTime is now back. It is now freeware as opposed to Shareware, has been extensively reworked and has been renamed to DTime+.
• Updated copyright details.
• Classes are no longer derived from CObject as this was not really necessary.
• Reworked the layout of the directories to ship as a more standard collection of standard C++ modules. Like other code provided by the author. the code now does not ship pre-built as an extension dll, instead it is provided as a pure source code library. You are of course free to include DTime+ in an extension dll if you so desire.
• Removed the timeframe concept from CLDate instance data.
• Removed support for ET and DeltaT. If you would like support for this please check out the author's AA+ class framework at http://www.naughter.com/aa.html.
• Integrating the concept of a Windows locale (LCID) into all functions which return strings. This allows the code to easily mix and match calendar strings from multiple languages in the one program.
• Because the code now tightly integrates with the Win32 NLS API's, DTime+ now does not need to carry around any resources of its own.
• Removed all virtual functions from all DTime+ classes.
• Removed the need to use friend classes.
• Updated the references to where the basic algorithms used by DTime+ are based on. See the comments in the CDate::Set() method.
• Provided updated UI support via the standard Windows date / time controls.
• Updated the code to ensure relatively clean compiles using Visual Studio 2003 and 2005 (Still warnings in 2005 with calling the so called unsafe "C" runtime functions).
• Did a full spell check and update of the documentation.

v3.01 (1 May 2006)

• Reworked the CDate and CLDate classes to use templates to specify the calendar type to use (Julian, Gregorian or Moslem). By making these classes template based, we have dispensed with a bool member variable in each instance, thereby reducing the per instance memory size of each of these classes. It also means that the serialized size for both of these classes has shrunk by 1 byte. By also making the classes template based, the code should also have a better chance of being optimized by the compiler. An example of the changes this implies to client code is as follows:
  
  CDate x(1990, CDate::March, 4, CDate::Gregorian) -> DTimePlus::CDate<CGregorianCalendar>(1990, March, 4) and
  
  CDate x(1990, CDate::March, 4, CDate::Julian) -> DTimePlus::CDate<CJulianCalendar>(1990, March, 4)
• Because of the move to templates, I had a problem getting CLTimeSpan and CLTimeOfDay to compile because there is a circular dependence between these two classes. When you make a class template based, using forward class references to resolve these issues now no longer works. Instead the CLTimeOfDay is now also template based which works around the circular reference issue. An example of the change this implies to client code is as follows:
  
  CLTimeOfDay y(10, 12, 14) -> DTimePlus::CLTimeOfDay<> y(10, 12, 14);
• Moved all the classes and methods out of the global namespace and into a namespace called "DTimePlus"
• Implemented extensive support for the Moslem Calendar. The algorithms are taken from the book "Calendrical Calculations, The Millenium Edition" by Edward M. Reingold and Nachum Dershowitz. The 4 most common forms of the Moslem Arithmetic calendar are supported namely the 15th and 16th year leap year rules as well as the Civil Epoch (16 July 622 C.E. O.S) and the Astronomical Epoch (15 July 622 C.E. O.S). These are implemented by the template classes CMoslemCalendarCivil16, CMoslemCalendarCivil15, CMoslemCalendarAstronomical16 and finally CMoslemCalendarAstronomical15. For example to create a date which represents Muharram 1, A.H. 1 using the Civil epoch and the 16th year leap rule you would use:
  
  DTimePlus::CDate<CMoslemCalendarCivil16> FirstDayOfMoslemEpoch(1, Muharram, 1);
  
  The Moslem month's are defined as a standard enum in the DTimePlus namespace just like you can use the Julian / Gregorian month names.
• Optimized the operation of the various Format methods.

v3.02 (20 May 2006)

• Canonical DaysInMonth method now takes a Year and a Month parameter instead of a month and a leap year boolean. This is required for support of the Hebrew calendar where knowing whether a year is a leap year or not is not good enough to determine the number of days in any month. This is because of the more complex nature of the Hebrew calendar and its' postponement rules for the Hebrew New Year (Rosh ha-Shannah). Please note that this means you should examine all calls to this method in client code to ensure it is updated correctly.
• Canonical DaysInYear method layout has been updated to take a year instead of a leap year boolean. The reason is as for item one above. Again you should examine all calls to this method in client code to ensure it is updated correctly.
• Canonical DaysSinceEndPreviousYear and DaysSinceFirstOfYear parameter layout has been updated. Both now take a year, month and day value. The reason is as for item one above. Again you should examine all calls to this method in client code to ensure it is updated correctly.
• Moslem classes now uses functors for leap year functionality. This does not affect client code in any way.
• CJulianCalendar now uses functors for leap year calculations. This does not affect client code in any way.
• CGregorianCalendar now uses functors for leap year calculations. This does not affect client code in any way.
• Now includes comprehensive support for the Hebrew calendar. The algorithms are taken from the book "Calendrical Calculations, The Millenium Edition" by Edward M. Reingold and Nachum Dershowitz. For example to create a date which represents the date of Passover in 922 C.E., that is Nisan 15 A.M. 4682, you would use:
  
  DTimePlus::CDate<CHebrewCalendar> Passover(4682, Nisan, 15);
  
  The Hebrew month's are defined as a standard enum in the DTimePlus namespace just like you can use the Julian / Gregorian month names. Also various helper functions are provided in the class CHebrewCalendar to handle the various intricacies of this calendar.
• Addition of a AsHebrewCDate method to CDate class.
• Addition of a constructor and Set method to CLDate which allows construction from a floating point days value.
• Updated the sample app, to verify the algorithms produce monotonically increasing day counts for all Calendars (Gregorian, Julian, 4 flavours of the Moslem calendar and Hebrew).
• Updated the sample app to widen the verification years for the algorithms to cover the span -100,000  to 100,000 C.E.
• Updated the sample app to report the relative speeds of the various calendar algorithms.

v3.03 (22 May 2006)

• Fixed a compile issue in VC 2003 with the multiplication operator for CLTimeSpan. The issue was related to the tighter ISO conformance of the compiler. Thanks to Itamar Syn-Hershko for reporting this issue.

v3.04 (25 May 2006)

• Updated the string and enums for the 7th month in the Hebrew calendar to be "Tishrei". Thanks to Itamar Syn-Hershko for reporting this issue.
• Updated the string and enums for the first month in the Hebrew calendar to be "Nissan". Thanks to Itamar Syn-Hershko for reporting this issue.
• Updated the string and enums for the 8th month in the Hebrew calendar to be "Cheshvan". Thanks to Itamar Syn-Hershko for reporting this issue.
• Now includes spaces in the strings returned for AdarI and AdarII (the 12th and 13th month of the Hebrew calendar).
• Fixed a typo in the string and enums for the 11th month in the Hebrew calendar "Shevat". Thanks to Itamar Syn-Hershko for reporting this issue.
• Optimized the code in CJulianGregorianCalendar::DaysInMonth.
• Optimized the DTimePlus::WeekOfDayModulo and DTimePlus::lfloor functions. This results in a 2 fold increase in the speed of the key algorithms for the Julian and Gregorian calendars.
• made all the functions in CJulianGregorianCalendar inline.
• Optimizied the CBaseMoslemCalendar::DaysInMonth code.
• Made some Moslem functions inline to aid optimization. These tweaks to the Moslem algorithms result in a c. 40% speed improvement
• Made some Hebrew functions inline to aid optimization.

v3.05 (27 May 2006)

• Renamed the CHebrewCalendar::LongMarheshvan function to LongCheshvan.
• Renamed the CHebrewCalendar::ShortMarheshvan function to ShortCheshvan.
• Reworked Hebrew algorithms to support dates before the Hebrew epoch i.e. a proleptic Hebrew calendar.
• Reworked Moslem algorithms to support dates before the Moslem epoch i.e. a proleptic Moslem calendar.
• Updated the month enum names and month strings for the Moslem calendar.
• Updated the weekday strings for the Moslem calendar.
• Removed the need for the function DTimePlus::WeekOfDaysModulo.

v3.06 (29 May 2006)

• Further performance optimizations for the core CJulianCalendar algorithms. There is a 3% increase in performance compared to v3.05. On my Quad Opteron system, the round trip tests for 1000 years of Julian dates takes just 48 ms.
• Further performance optimizations for the core CGregorianCalendar algorithms. There is a 3% increase in performance compared to v3.05. On my Quad Opteron system, the round trip tests for 1000 years of Gregorian dates takes just 79 ms.
• Now includes comprehensive support for Holidays, Christian Saints Days, National Holidays, US Specific Holidays, and Christian Feast Days via the new class CJulianGregorianHolidays.
• Updated the month enum name and month strings for Moslem month "Ramadan".
• Now includes comprehensive support for Moslem Holidays via the new module DTime+MoslemHolidays.h. Also you can determine Moslem holidays occurring in a Gregorian year via MoslemOccurencesInGregorianYear.
• Now includes comprehensive support for Hebrew Holidays via the new module DTime+HebrewHolidays.h. Also you can determine Hebrew holidays occurring in a Gregorian year via HewbrewOccurencesInGregorianYear.
• Removed the now unnecessary defines DTIMEPLUS_EXT_CLASS and DTIMEPLUS_EXT_API. These are no longer required because DTime+ is template based.

v3.07 (30 May 2006)

• Added support for Rosh HaShanah 2
• Renamed CSimhatTorahFunctor to CCSimhatTorahOutsideIsraelFunctor
• Renamed CPassoverFunctor to CPesachFunctor
• Renamed CEndingOfPassoverFunctor to CShviiPesachFunctor
• Added support for Yom Ha'atzmaut
• Added support for Erev Pesach
• Added support for Ta'anit Bechorim
• Added support for Pesach Shenni
• Added support for Yom Yerushalaiym
• Renamed to CHoshahaRabbaFunctor to CHoshanahRabahFunctor. All of these updates for the Hebrew calendar for v3.07 are thanks to Itamar Syn-Hershko.

v3.08 (2 July 2006)

• Updated the code to clean compile on VC 2005
• Code now uses new C++ style casts rather than old style C casts where necessary.

v3.09 (13 April 2007)

• Updated copyright details.
• Updated sample apps to clean compile on VC 2005
• Fixed a bug in CDate::Set(const CTime& ctime, ...) and CLDate& CLDate::Set which incorrectly used GetGmtTm instead of GetLocalTm. Thanks to Martin Copland for reporting this bug.

How to use

As DTime+ is provided as a C++ template class library, you simple need to #include the relevant header files (e.g. DTime+.h) in your project. You can also reference individual DTime+ headers also if you want. For example if you want to use the UI support for DTime+, you can include DTime+UI.h.

CDate Index

Construction

CDate

Setting

Set

Static Constructors

CurrentSystemDate

CurrentLocalDate

JDEpoch

MJDEpoch

Epoch1900

Epoch1950

EpochCTime

Epoch2000

GregorianEpoch

Static Operations

IsLeap

DaysInYear

DaysInMonth

DaysSinceFirstOfYear

DaysSinceEndPreviousYear

GetBeginingDayOfWeek

GetFullStringDayOfWeek

GetAbrStringDayOfWeek

GetFullStringMonth

GetAbrStringMonth

Operations

DaysSinceFirstOfYear

DaysSinceEndPreviousYear

GetDate

GetDay

GetMonth

GetYear

GetCEBCEYear

Get2DigitYear

GDN

JD

IsLeap

DaysInYear

DaysInMonth

AddYear

AddMonth

AddWeek

GetDayOfWeek

GetFullStringDayOfWeek

GetAbrStringDayOfWeek

GetFullStringMonth

GetAbrStringMonth

GetAsSystemTime

GetAsFileTime

GetAsTM

GetWeekOfYear

GetWeekOfMonth

IsValid

Collate

Construction based on this instance

FirstThisMonth

LastThisMonth

FirstThisYear

LastThisYear

Overloaded Arithmetic Operators

operator=

operator+,-

operator+=, -=

operator++

operator--

operator==, <, etc.

Display

GetWindowsFormatString

Format

Serialization

Serialize

operator<<

operator>>

CDate::CDate

CDate();

CDate(long Year, WORD month, WORD Day, bool bDoAssert = true);

CDate(const SYSTEMTIME& SystemTime, bool bDoAssert = true);

CDate(const FILETIME& FileTime, bool bDoAssert = true);

CDate(long Year, WORD month, WORD WeekOfMonth, DayOfWeek dow, bool bDoAssert = true);

CDate(long Days, DateEpoch e, bool bDoAssert = true);

CDate(const CDate& d);

CDate(const CTime& ctime, bool bDoAssert = true);

CDate(const COleDateTime& oleTime);

CDate(const CString& sDate, const CString& sFormat, bool bDoAssert = true);

Parameters

Year, Month, Day Indicates a year, month and day.

SystemTime A Win32 SDK SYSTEMTIME struct.

FileTime A Win32 SDK FILETIME struct.

d Indicates a CDate object that already exists.

ctime Indicates a CTime object that already exists.   

WeekOfMonth The week of the month (1 - 5).

DayOfWeek The day of the week e.g. Sunday.

oleTime An OLE Date.

sDate A string representation of the date to construct

sFormat The format that the string date uses

bDoAsserts If set, the constructors will assert in debug mode if any of the parameters are invalid

Remarks

• The default constructor creates an invalid CDate
• if WeekOfMonth is 5 then it means the last week in the month. This is similar to the way the Win32 SDK operates.
• Only the day, month and year values in the SYSTEMTIME structure and CTime class are used.
• See the Structures used by the classes for the definition of the enums used to represent the day of week.
• sDate is a legal date string as defined by sFormat
• sFormat is a 5 character string where the first 3 indicate the order of the month/day/year, the fourth character indicates the length of the year, and the fifth character indicates the separator. For example:

This feature allows for the creation of CDate's from a string as entered in a masked edit field or from a parsed report.

CDate::Set

CDate& Set();

CDate& Set(long Year, WORD month, WORD Day, bool bDoAssert = true);

CDate& Set(const SYSTEMTIME& SystemTime, bool bDoAssert = true);

CDate& Set(const FILETIME& FileTime, bool bDoAssert = true);

CDate& Set(long Year, WORD month, WORD WeekOfMonth, DayOfWeek dow, bool bDoAssert = true);

CDate& Set(long Days, CDate::DateEpoch e, bool bDoAssert = true);

CDate& Set(const CTime& ctime, bool bDoAssert = true);

CDate& Set(const COleDateTime& oleTime);

CDate& Set(const CString& sDate, const CString& sFormat, bool bDoAssert = true);

Parameters

See CDate Constructors

Remarks

• These functions are actually called by the constructors. They allow a CDate’s value to be modified even after construction.

static CDate::CurrentSystemDate(bool bDoAssert = true);

Returns a CDate which represents the current UTC date as taken from the system clock.

static CDate::CurrentLocalDate(bool bDoAssert = true);

Returns a CDate which represents the current local date as taken from the system clock.

static CDate CDate::JDEpoch();

Returns a CDate which represents Julian Day Epoch i.e. 1st January -4712 (when specified in the Julian calendar)

static CDate CDate::MJDEpoch();

Returns a CDate which represents 1st January -4712 + 2400000 Days (which corresponds to 17 November 1858 in the Gregorian calendar)

static CDate CDate::Epoch1900();

Returns a CDate which represents 1st January 1900

static CDate CDate::Epoch1950();

Returns a CDate which represents 1st January 1950

static CDate CDate::EpochCTime();

Returns a CDate which represents a CTime of 0 seconds (i.e. 1st January 1970)

static CDate CDate::Epoch2000();

Returns a CDate which represents 1st January 2000

static CDate CDate::GregorianEpoch();

Returns a CDate which represents when the change from the Julian to Gregorian calendar occurred.

static bool CDate::IsLeap(long Year);

returns true if the year is leap otherwise false.

Remarks

The routine correctly allows for the exception whereby dates in the Gregorian calendar are leap (or bissextile) if divisible by 4 with the following exception: the centurial years that are not divisible by 400, such as 1700, 1800, 1900, and 2100, are not leap years. The other century years, which are divisible by 400, are leap years, for instance 1600, 2000 and 2400. If we have instantiated for the Julian Calendars, then the simpler 4 year leap year rule is applied. If we have instantiated the CDate for the Moslem or Hebrew calendars, then their specific leap year / leap month rules will be applied.

static WORD CDate::DaysInYear(long Year);

Returns the number of days in a year i.e. 366 if the year is leap otherwise 365, assuming we have instantiated the CDate class using the Gregorian or Julian Calendars. If instantiated for the Moslem or Hebrew calendars, then their specific leap year / leap month rules will be applied. In the Moslem calendar, a year can contain 354 or 355 days. In the Hebrew calendar, a year can contain 353, 354, 355, 383, 384 or 385 days.

static WORD CDate::DaysInMonth(long Year, WORD month);

Returns the number of days in a month e.g. 31 for January, 28 for a common February, 29 for a leap February etc, assuming we have instantiated the CDate class using the Gregorian or Julian Calendars. If instantiated for the Moslem or Hebrew calendars, then their specific leap year / leap month rules will be applied.

static WORD CDate::DaysSinceFirstOfYear(long Year, WORD month, WORD Day);

Returns the number of days since 1st of January. If the CDate class has been instantiated using the Moslem calendar, then the first of the year will correspond to the 1st day of the Moslem month Muharram. If the CDate class has been instantiated using the Hebrew calendar, then it returns the number of days since 1st day of Tishri. Note this function does not return the number of days since 1st of Nisan which is the 1st month in the Hebrew calendar because Hebrew New Year is 1st of Tishri which is the 7th month.

static WORD CDate::DaysSinceEndPreviousYear(long Year, WORD month, WORD Day);

Returns the number of days since 0th of January (previous 31st December). If the CDate class has been instantiated using the Moslem calendar, then the end of the previous year will correspond to the 29th or 30th of the Moslem month Dhu al-Hijja. If the CDate class has been instantiated using the Hebrew calendar, then it returns the number of days since 0th of Tishri (previous 29th of Elul). Note this function does not return the number of days since the last day of Adar I or Adar II (if it is a leap year) because Hebrew New Year is 1st of Tishri which is the 7th month.

static CString CDate::GetFullStringDayOfWeek(DayOfWeek dow, LCID Locale = LOCALE_USER_DEFAULT);

Returns a representation of the day of week parameter as a CString, returning for example ‘Sunday’, ‘Monday’ etc assuming the locale specified is for an English language and you have constructed the CDate instance using the Julian or Gregorian calendar.

Remarks

• The Locale value controls which windows locale and hence language should be used to return the string in.
• The value is interpreted as defined in the Set() functions.

See Also

CDate::GetAbrStringDayOfWeek

static CString CDate::GetAbrStringDayOfWeek(DayOfWeek dow, LCID Locale = LOCALE_USER_DEFAULT);

Returns an abbreviated representation for the day of week parameter as a CString, returning for example ‘Sun’, ‘Mon’ etc assuming the locale specified is for an English language and you have constructed the CDate instance using the Julian or Gregorian calendar.

Remarks

• The Locale value controls which windows locale and hence language should be used to return the string in.
• The value is interpreted as defined in the Set() methods.

See Also

CDate::GetFullStringDayOfWeek

static CString CDate::GetFullStringMonth(WORD month, LCID Locale = LOCALE_USER_DEFAULT);

Returns a CString representation for the month parameter, returning for example ‘January’, ‘February’ etc assuming the locale specified is for an English language and you have constructed the CDate instance using the Julian or Gregorian calendar.

See Also

CDate::GetAbrStringMonth

static CString CDate::GetAbrStringMonth(WORD month, LCID Locale = LOCALE_USER_DEFAULT);

Returns a CString representation for the month parameter, returning for example ‘Jan’, ‘Feb’ etc assuming the locale specified is for an English language and you have constructed the CDate instance using the Julian or Gregorian calendar.

See Also

CDate::GetFullStringMonth

WORD CDate::DaysSinceFirstOfYear() const;

Returns the number of days since 1st of January for this instance. If the CDate class has been instantiated using the Moslem calendar, then the first of the year will correspond to the 1st day of the Moslem month Muharram.

WORD CDate::DaysSinceEndPreviousYear() const;

Returns the number of days since 0th of January (previous 31st December) for this instance. If the CDate class has been instantiated using the Moslem calendar, then the end of the previous year will correspond to 29th or 30th of the Moslem month Dhu al-Hijja.

static WORD CDate::GetBeginingDayOfWeek(LCID Locale = LOCALE_USER_DEFAULT);

Gets the day of week considered to be the beginning day of week for the specified locale. It uses this value in CDate::GetWeekOfYear() and CDate::GetWeekOfMonth()

Remarks

• The returned WORD is interpreted as defined in the Set() methods

CDate::DateS CDate::GetDate() const;

Returns a DateS structure for this instance.

WORD CDate::GetDay() const;

Returns the Day of the month for this instance (1 - 31).

WORD CDate::GetMonth() const;

Returns the Month enum for this instance (January(1) - December (12)).

long CDate::GetYear() const;

Returns the Year for this instance.

long CDate::GetCEBCEYear(bool& IsCE) const;

Returns the Current Epoch / Before Current Epoch year for this instance.

e.g.

bool bIsCE;

CDate<CGregorianCalendar> x(1990, January, 32);

long y = x.GetCEBCEYear(bIsCE);        //y will be 1990, bIsCE will be true

x.Set(-1990, January, 32);

y = x.GetCEBCEYear(bIsCE);                   //y will be 1989, bIsCE will be false

long CDate::Get2DigitYear() const;

Returns the last 2 digits of the year.

e.g.

CDate<CGregorianCalendar> x(1995, January, 15);

long y = x.Get2DigitYear();

ASSERT(y == 95);

long CDate::GDN() const;

Returns the number of days for this instance since the Gregorian Epoch.

long CDate::JD() const;

Returns the Julian Day or number of days for this instance since 1st January -4712.

bool CDate::IsLeap() const;

Returns true if the year for this instance is leap otherwise false.

WORD CDate::DaysInYear() const;

Returns the number of days for this instance’s year.

WORD CDate::DaysInMonth() const;

Returns the number of days for this instance’s month.

void CDate::AddYear(int Years = 1);

Adds a number of years to this instance.

void CDate::AddMonth(int Months = 1);

Adds a number of months to this instance.

Remarks

• Invalid Day of Months are always rounded down and will not overflow into subsequent months. e.g. if you add 1 month to March 31 you will get April 30.

void CDate::AddWeek(int Weeks = 1);

Adds a number of weeks i.e. 7 days to this instance.

WORD CDate::GetDayOfWeek() const;

Returns the day of week for this instance. (1 for Sunday, 2 for Monday, and so forth).

Remarks

• See the Structures used by the classes for the enums compatible with how the day of week is returned from this member function.

CString CDate::GetFullStringDayOfWeek(LCID Locale = LOCALE_USER_DEFAULT) const;

Returns the day of week for this instance as a CString. e.g. 'Sunday', 'Monday' etc  assuming the locale specified is for an English language and you have constructed a Julian or Gregorian CDate instance.

See Also

CDate::GetAbrStringDayOfWeek

CString CDate::GetAbrStringDayOfWeek(LCID Locale = LOCALE_USER_DEFAULT) const;

Returns an abbreviated CString version for the day of week for this instance. e.g. ‘Sun’, ‘Mon’ etc assuming the locale specified is for an English language and you have constructed a Julian or Gregorian CDate instance.

See Also

CDate::GetFullStringDayOfWeek

CString CDate::GetFullStringMonth(LCID Locale = LOCALE_USER_DEFAULT) const;

Returns the full CString version for the month for this instance. e.g. ‘January’, ‘February’ etc assuming the locale specified is for an English language and you have constructed a Julian or Gregorian CDate instance.

See Also

CDate::GetAbrStringMonth

CString CDate::GetAbrStringMonth(LCID Locale = LOCALE_USER_DEFAULT) const;

Returns an abbreviated CString version for the month for this instance. e.g. ‘Jan’, ‘Feb’ etc assuming the locale specified is for an English language and you have constructed a Julian or Gregorian CDate instance.

See Also

CDate::GetFullStringMonth

bool CDate::GetAsSystemTime(SYSTEMTIME& SystemTime) const;

Returns a Win32 SDK SYSTEMTIME struct version of this instance.

Remarks

• If the date is outside of the allowable range which a SYSTEMTIME struct can hold or the CDate instance is invalid, then the method will return false.

bool CDate::GetAsFileTime(FILETIME& FileTime) const;

Returns a Win32 SDK FILETIME struct version of this instance.

Remarks

• If the date is outside of the allowable range which a FILETIME struct can hold or the CDate is invalid, then the method will return false.

bool CDate::GetAsTM(tm& time) const;

Returns a ‘C’ runtime tm struct version of this instance.

WORD CDate::GetWeekOfYear(LCID Locale = LOCALE_USER_DEFAULT) const;

Returns the week of the year for this instance. As an example of how this is determined:

Suppose the 1^st of January occurred on a Thursday and the day of week considered the beginning of the week is Monday as specified by the locale value 'Locale'. The following results would then be obtained:

Date                        GetWeekOfYear() return value

Thursday 1^st            0

Friday 2^nd                0

Saturday 3^rd            0

Sunday 4^th              0

Monday 5^th             1

Tuesday 6^th            1

.

.

Monday 12^th           2

.

.

.

WORD CDate::GetWeekOfMonth(LCID Locale = LOCALE_USER_DEFAULT) const;

Returns the week of the month for this instance. As an example of how this is determined:

Suppose the 1^st of the month occurred on a Thursday and the day of week considered the beginning of the week is Monday as specified by the locale value 'Locale', The following results would then be obtained:

Date                        GetWeekOfMonth() return value

Thursday 1^st            0

Friday 2^nd                0

Saturday 3^rd            0

Sunday 4^th              0

Monday 5^th             1

Tuesday 6^th            1

.

.

Monday 12^th           2

.

.

.

bool CDate::IsValid() const;

Returns true if this instance is valid otherwise false.

e.g. CDate<CGregorianCalendar> Inval(1990, January, 33, false); //an invalid day of month

ASSERT(IsValid(Inval) == false);

long CDate::Collate() const;

Returns a long which can be used in a date collation purposes i.e. the year value is stored as units of 10000, the month value is stored as units of 100 and the day value as units of 1.

e.g. CDate<CGregorianCalenda> x(1978, March, 3);

ASSERT(x.Collate = 19780403L);

CDate CDate::FirstThisMonth();

Returns a CDate for the first of the month for this instance

e.g. CDate<CGregorianCalendar> x(1990, March, 4);

CDate<CGregorianCalendar> f(x.FirstThisMonth());

ASSERT(f = CDate<CGregorianCalendar>(1990, March, 1);

See Also

CDate::LastThisMonth

CDate CDate::LastThisMonth();

Returns a CDate for the last of the month for this instance

e.g. CDate<CGregorianCalendar> x(1990, March, 4);

CDate<CGregorianCalendar> f(x.LastThisMonth());

ASSERT(f = CDate<CGregorianCalendar>(1990, CDate::March, 31);

See Also

CDate::FirstThisMonth

CDate CDate::FirstThisYear();

Returns a CDate for the 1st January for this instance

e.g. CDate<CGregorianCalendar> x(1990, March, 4);

CDate<CGregorianCalendar> f(x.FirstThisYear());

ASSERT(f = CDate<CGregorianCalendar>(1990, January, 1);

See Also

CDate::LastThisYear

CDate CDate::LastThisYear();

Returns a CDate for the 31st December for this instance

e.g. CDate<CGregorianCalendar> x(1990, March, 4);

CDate<CGregorianCalendar> f(x.LastThisYear());

ASSERT(f = CDate<CGregorianCalendar>(1990, December, 31);

See Also

CDate::FirstThisYear

CDate& CDate::operator=(const CDate& d);

Copies a CDate into this CDate and returns a reference to this instance

CDate CDate::operator+(long Days) const;

CDate CDate::operator-(long Days) const;

Standard arithmetic operators to add and subtracts a number of days.

e.g. CDate<CGregorianCalendar> Tomorrow(CDate<CGregorianCalendar>::CurrentLocalDate()) + 1;

long OneMonth = CDate<CGregorianCalendar>(1990, March, 4) - CDate<CGregorianCalendar>(1990, February, 4);

CDate<CGregorianCalendar> Yesterday(CDate<CGregorianCalendar>::GetLocalDate()) - 1;

CDate& CDate::operator+=(long Days);

CDate& CDate::operator-=(long Days);

Standard arithmetic increment and decrement operators

e.g. CDate<CGregorianCalendar> x(1990, January, 1);

x += 7;

ASSERT(x == CDate<CGregorianCalendar>(1990, January, 8));

x -= 7;

ASSERT(x == CDate<CGregorianCalendar>(1990, January, 1));

CDate& CDate::operator++();

Standard arithmetic increment operator. Adds one day to this instance

CDate& CDate::operator--();

Standard arithmetic decrement operator. Subtracts one day from this instance.

bool CDate::operator==(const CDate& d) const;

bool CDate::operator>(const CDate& d) const;

bool CDate::operator>=(const CDate& d) const;

bool CDate operator<(const CDate& d) const;

bool CDate operator<=(const CDate& d) const;

bool CDate operator!=(const CDate& d) const;

Standard arithmetic equality operators.

CString CDate::GetWindowsFormatString(LCID Locale = LOCALE_USER_DEFAULT)

Returns a CDate::Format string appropriate for the specified windows locale as specified by 'Locale'

See Also

CDate::Format

CString CDate::Format(const CString& sFormat = GetWindowsFormatString(LOCALE_USER_DEFAULT), LCID Locale = LOCALE_USER_DEFAULT) const;

Generates a formatted string that corresponds to this CDate object.

The sFormat string supports the following replaceable parameters:

• %a Abbreviated weekday name
• %A Full weekday name
• %b Abbreviated month name
• %B Full month name
• %d Day of month as decimal number (01 - 31)
• %j Day of year as decimal number (001 - 366)
• %m Month as decimal number (01 - 12)
• %U Week of year as decimal number
• %w Weekday as decimal number (1 - 7; Sunday is 1)
• %x Short date representation, appropriate to current locale
• %y Year without century, as decimal number (00 - 99)
• %Y Year with century, as decimal number
• %#x Long date representation, appropriate to current locale
• %#d, %#j, %#m, %#U, %#y Remove leading zeros (if any)

Remarks

• If the CDate is invalid then an empty string will be returned.

See Also

CDate::GetWindowsFormatString

void CDate::Serialize(CArchive& ar);

Standard MFC override to allow streaming of this CDate to and from an archive. The space taken is 6 bytes (4 data bytes + 2 schema bytes).

Remarks

As of v3 of DTime+, the serialization is not backward compatible with earlier versions.

friend CArchive& operator<<(CArchive& ar, CDate& Date);

Simply calls the Serialize method of ‘Date’, asserting that the archive ‘ar’ is storing.

friend CArchive& operator>>(CArchive& ar, CDate& Date);

Simply calls the Serialize method of ‘Date’, asserting that the archive ‘ar’ is loading.

CLTimeSpan Index

Construction

CLTimeSpan

Setting

Set

Static Constructors

OneDay

OneHour

OneMinute

OneSecond

Operations

GetTotalDays

GetHours

GetMinutes

GetSeconds

IsValid

Negate

IsPositiveSpan

SecondsAsDouble

Overloaded Arithmetic Operators

operator=

operator+,-

operator+=.-=

operator*, /

operator*=, /=

Overloaded Equality Operators

operator==, > etc.

Display

GetWindowsFormatString

Format

Serialization

Serialize

operator<<

operator>>

CLTimeSpan Constructors

CLTimeSpan();

CLTimeSpan(long Day, WORD Hour, WORD Minute, WORD Second);

CLTimeSpan(const CLTimeSpan& lts);

CLTimeSpan(const CTimeSpan& ts);

CLTimeSpan(const CLTimeOfDay& tod);

CLTimeSpan(const COleDateTimeSpan& oleTimeSpan);

CLTimeSpan(const __int64& Seconds);

Parameters

Day, Hour, Minute, Second Indicates a count of day, hour, minute and second values.

lts Indicates a CLTimeSpan object that already exists.

ts Indicates a CTimeSpan object that already exists.

tod Indicates a CLTimeOfDay object that already exists.

Seconds Indicates a count of seconds as a 64 bit integer.

oleTime An OLE time span.

Remarks

• The default constructor creates an invalid CLTimeSpan

CLTimeSpan Set functions

CLTimeSpan& Set();

CLTimeSpan& Set(long Day, WORD Hour, WORD Minute, WORD Second);

CLTimeSpan& Set(const CTimeSpan& ts);

CLTimeSpan& Set(const CLTimeOfDay& tod);

CLTimeSpan& Set(const COleDateTimeSpan& oleTimeSpan);

CLTimeSpan& Set(const __int64& Seconds);

Parameters

See CLTimeSpan Constructors

Remarks

• These functions are actually called by the constructors. They allow a CLTimeSpan’s value to be modified even after construction.

static CLTimeSpan CLTimeSpan::OneDay();

Returns a CLTimeSpan which represents one day.

static CLTimeSpan CLTimeSpan::OneHour();

Returns a CLTimeSpan that represents one hour.

static CLTimeSpan CLTimeSpan::OneMinute();

Returns a CLTimeSpan that represents one minute.

static CLTimeSpan CLTimeSpan::OneSecond();

Returns a CLTimeSpan that represents one second.

long CLTimeSpan::GetTotalDays() const;

Returns the total number of days this CLTimeSpan contains.

e.g. CLTimeSpan x(10, 12 , 13, 14)

ASSERT(x.GetTotalDays() == 10);

WORD CLTimeSpan::GetHours() const;

Returns the number of hours this CLTimeSpan contains.

e.g. CLTimeSpan x(10, 12 , 13, 14)

ASSERT(x.GetHours() == 12);

WORD CLTimeSpan::GetMinutes() const;

Returns the number of minutes this CLTimeSpan contains.

e.g. CLTimeSpan x(10, 12 , 13, 14)

ASSERT(x.GetMinutes() == 13);

WORD CLTimeSpan::GetSeconds() const;

Returns the number of seconds this CLTimeSpan contains.

e.g. CLTimeSpan x(10, 12 , 13, 14)

ASSERT(x.GetSeconds() == 14);

bool CLTimeSpan::IsValid() const;

Returns true if this instance is valid otherwise false.

e.g. CLTimeSpan Inval;

ASSERT(IsValid(Inval) == false);

CLTimeSpan& CLTimeSpan::Negate();

Negates this CLTimeSpan and returns a reference to it.

e.g. CLTimeSpan x(10, 12 , 13, 14)

x.Negate();

ASSERT(x == CLTimeSpan(-10, 12, 13, 14);

bool CLTimeSpan::IsPositiveSpan() const;

Returns true if this CLTimeSpan represents a positive time span (value >= 0 seconds) else negative.

e.g. CLTimeSpan x(-10, 12 , 13, 14)

ASSERT(!x.IsPositiveSpan());

double CLTimeSpan::SecondsAsDouble() const;

Returns the underlying number of seconds this CLTimeSpan contains as a double.

CLTimeSpan& CLTimeSpan::operator=(const CLTimeSpan& TimeSpan)

Copies a CLTimeSpan into this CLTimeSpan and returns a reference to this instance

CLTimeSpan CLTimeSpan::operator+(const CLTimeSpan& TimeSpan) const;

CLTimeSpan CLTimeSpan::operator-(const CLTimeSpan& TimeSpan) const;

Standard arithmetic operators to add and subtracts CLTimeSpan’s.

CLTimeSpan& CLTimeSpan::operator+=(const CLTimeSpan& TimeSpan);

CLTimeSpan& CLTimeSpan::operator-=(CLTimeSpan& TimeSpan);

Standard arithmetic auto increment and decrement operators.

CLTimeSpan CLTimeSpan::operator*(WORD Multiplier) const;

CLTimeSpan operator*(WORD Multiplier, const CLTimeSpan& TimeSpan);

CLTimeSpan CLTimeSpan::operator/(WORD divisor) const;

Standard arithmetic operators to multiply and divide CLTimeSpan’s.

CLTimeSpan& CLTimeSpan::operator*=(WORD Multiplier);

CLTimeSpan& CLTimeSpan::operator/=(WORD Divisor);

Standard arithmetic auto multiply and divide operators.

bool CLTimeSpan::operator==(const CLTimeSpan& TimeSpan) const;

bool CLTimeSpan::operator>(const CLTimeSpan& TimeSpan) const;

bool CLTimeSpan::operator>=(const CLTimeSpan& TimeSpan) const;

bool CLTimeSpan::operator<(const CLTimeSpan& TimeSpan) const;

bool CLTimeSpan::operator<=(const CLTimeSpan& TimeSpan) const;

bool CLTimeSpan::operator!=(const CLTimeSpan& TimeSpan) const;

Standard arithmetic equality operators.

CString CLTimeSpan::GetWindowsFormatString(LCID Locale = LOCALE_USER_DEFAULT)

Returns a CLTimeSpan::Format string appropriate for the specified windows locale as specified by 'Locale'

See Also

CLTimeSpan::Format

CString CLTimeSpan::Format(const CString& sFormat = GetWindowsFormatString(LOCALE_USER_DEFAULT), LCID Locale = LOCALE_USER_DEFAULT) const;

Generates a formatted string that corresponds to this CLTimeSpan object.

The sFormat string supports the following replaceable parameters:

• %D Total days in this CLTimeSpan
• %H Hours in this CLTimeSpan (00 - 23)
• %M Minutes in the current hour in this CLTimeSpan (00 - 59)
• %S Seconds in the current minute in this CLTimeSpan (00 - 59)
• %% Percent sign
• %#H, %#M, %#S Remove leading zeros (if any).

Remarks

• If the CLTimeSpan is invalid then an empty string will be returned

See Also

CLTimeSpan::GetWindowsFormatString

void CLTimeSpan::Serialize(CArchive& ar);

Standard MFC override to allow streaming of this CLTimeSpan to and from an archive. The space taken is 10 bytes (8 data bytes + 2 schema bytes).

Remarks

As of v3 of DTime+, the serialization is not backward compatible with earlier versions.

friend CArchive& operator<<(CArchive& ar, CLTimeSpan& TimeSpan);

Simply calls the Serialize method of ‘TimeSpan’, asserting that the archive ‘ar’ is storing.

friend CArchive& operator>>(CArchive& ar, CLTimeSpan& TimeSpan);

Simply calls the Serialize method of ‘TimeSpan’, asserting that the archive ‘ar’ is loading.

CLTimeOfDay Index

Constructors

CLTimeOfDay

Setting

Set

Static Constructors

CurrentSystemTime

CurrentLocalTime

Midnight

Midday

Static Operations

GetAMString

GetPMString

Operations

GetHours

GetMinutes

GetSeconds

GetTotalSeconds

GetAMPMHours

GetAMPMString

IsValid

Collate

GetAsSystemTime

GetAsTM

Overloaded Arithmetic Operators

operator=

operator+,-

operator+=.-=

Overloaded Equality Operators

operator==, > etc.

Display

GetWindowsFormatString

Format

Serialization

Serialize

operator<<

operator>>

CLTimeOfDay Constructors

CLTimeOfDay();

CLTimeOfDay(WORD Hour, WORD Minute, WORD Second, bool bDoAssert = true);

CLTimeOfDay(const SYSTEMTIME& st, bool bDoAssert = true);

CLTimeOfDay(const CLTimeOfDay& ltod);

CLTimeOfDay(DWORD TotalSeconds, bool bDoAssert = true);

Parameters

Hour, Minute, Second Indicates a hour, minute and second values.

st A Win32 SYSTEMTIME structure.

ltod Indicates an existing CLTimeOfDay instance.

TotalSeconds Indicates a accumulated number of seconds.

bDoAsserts if set, the constructors will assert in debug mode if any of the parameters are invalid

Remarks

• The default constructor creates an invalid CLTimeOfDay

CLTimeOfDay Set functions

CLTimeOfDay& Set();

CLTimeOfDay& Set(WORD Hour, WORD Minute, WORD Second, bool bDoAssert = true);

CLTimeOfDay& Set(const SYSTEMTIME& st, bool bDoAssert = true);

CLTimeOfDay& Set(DWORD TotalSeconds, bool bDoAssert = true);

Parameters

See CLTimeOfDay Constructors

Remarks

• These methods are actually called by the constructors. They allow a CLTimeOfDay’s value to be modified even after construction

static CLTimeOfDay CLTimeOfDay::CurrentSystemTime();

Returns a CLTimeOfDay which represents the current UTC time of day as taken from the system clock.

static CLTimeOfDay CLTimeOfDay::CurrentLocalTime();

Returns a CLTimeOfDay which represents the current Local time of day as taken from the system clock.

static CLTimeOfDay CLTimeOfDay::Midnight();

Returns a CLTimeOfDay that represents midnight.

static CLTimeOfDay CLTimeOfDay::Midday();

Returns a CLTimeOfDay that represents midday.

static CString CLTimeOfDay::GetAMString(LCID Locale = LOCALE_USER_DEFAULT);

Returns the string to used for the 'AM' indicator for the specified locale.

static CString CLTimeOfDay::GetPMString(LCID Locale = LOCALE_USER_DEFAULT);

Returns the string to used for the 'PM' indicator for the specified locale.

WORD CLTimeOfDay::GetHours() const;

Returns the number of hours this CLTimeOfDay contains.

e.g. CLTimeOfDay<> x(12 , 13, 14, 15)

ASSERT(x.GetHours() == 12);

WORD CLTimeOfDay::GetMinutes() const;

Returns the number of minutes this CLTimeOfDay contains.

e.g. CLTimeOfDay<> x(12 , 13, 14, 15)

ASSERT(x.GetMinutes() == 13);

WORD CLTimeOfDay::GetSeconds() const;

Returns the number of seconds this CLTimeOfDay contains.

e.g. CLTimeOfDay<> x(12 , 13, 14, 15)

ASSERT(x.GetSeconds() == 14);

DWORD CLTimeOfDay::GetTotalSeconds() const;

Returns the total number of seconds this CLTimeOfDay contains.

e.g. CLTimeOfDay<> x(0 , 1, 14, 15)

ASSERT(x.GetTotalSeconds() == 74);

WORD  CLTimeOfDay::GetAMPMHours() const;

Returns the 12 hour version of the hour this CLTimeOfDay represents.

e.g. CLTimeOfDay<> x(17 , 13, 14, 15)

ASSERT(x.GetAMPMHour() == 5);

CString CLTimeOfDay::GetAMPMString(LCID Locale = LOCALE_USER_DEFAULT) const;

Returns the string to used for the 'AM'or 'PM' indicator for the specified locale for this instance's hour value.

bool CLTimeOfDay::IsValid() const;

Returns true if this instance is valid otherwise false.

e.g. CLTimeOfDay<> Inval;

ASSERT(IsValid(Inval) == false);

DWORD CLTimeOfDay::Collate() const;

Returns a long which can be used in a date collation purposes i.e. the hours value is stored as units of 10000, the minutes value is stored as units of 100 and the seconds value as units of 1.

e.g. CLTimeOfDay<> x(13, 12, 11);

ASSERT(x.Collate = 131211L);

bool CLTimeOfDay::GetAsSystemTime(SYSTEMTIME& SystemTime) const;

Returns a SYSTEMTIME structure representing this CLTimeOfDay

Remarks

• Only the wHour, wMinute, wSecond parameters of the SYSTEMTIME struct are filled in. All the other values are set to 0.

bool CLTimeOfDay::GetAsTM(tm& time) const;

Returns a ‘C’ runtime tm struct version of this instance.

CLTimeOfDay& CLTimeOfDay::operator=(const CLTimeOfDay& Tod);

Copies a CLTimeOfDay into this CLTimeOfDay and returns a reference to this instance.

CLTimeOfDay CLTimeOfDay::operator+(const CLTimeSpan& TimeSpan) const;

CLTimeOfDay CLTimeOfDay::operator-(const CLTimeSpan& TimeSpan) const;

Standard arithmetic operators to add and subtracts CLTimeOfDay’s.

CLTimeOfDay& CLTimeOfDay::operator+=(const CLTimeSpan& TimeSpan);

CLTimeSpan& CLTimeOfDay::operator-=(CLTimeSpan& TimeSpan);

Standard arithmetic auto increment and decrement operators.

bool CLTimeOfDay::operator==(const CLTimeOfDay& Tod) const;

bool CLTimeOfDay::operator>(const CLTimeOfDay& Tod) const;

bool CLTimeOfDay::operator>=(const CLTimeOfDay& Tod) const;

bool CLTimeOfDay::operator<(const CLTimeOfDay& Tod) const;

bool CLTimeOfDay::operator<=(const CLTimeOfDay& Tod) const;

bool CLTimeOfDay::operator!=(const CLTimeOfDay& Tod) const;

Standard arithmetic equality operators.

CString CLTimeOfDay::GetWindowsFormatString(LCID Locale = LOCALE_USER_DEFAULT)

Returns a CLTimeOfDay::Format string appropriate for the specified windows locale as specified by 'Locale'

See Also

CLTimeOfDay::Format

CString CLTimeOfDay::Format(const CString& sFormat = GetWindowsFormatString(LOCALE_USER_DEFAULT), LCID Locale = LOCALE_USER_DEFAULT) const;

Generates a formatted string that corresponds to this CLTimeOfDay object.

The sFormat string supports the following replaceable parameters:

• %H Hours in the current day
• %M Minutes in the current hour
• %h 12 Hour format Hours in this CLTimeSpan (00 - 12)
• %P AM / PM indicator for the specified locale 'Locale'
• %S Seconds in the current minute
• %% Percent sign
• %x Time Of Day representation for specified locale in 'Locale'
• %#H, %#h, %#M, %#S Remove leading zeros (if any).

Remarks

• If the CLTimeOfDay is invalid then an empty string will be returned

See Also

CLTimeOfDay::GetWindowsFormatString

void CLTimeOfDay::Serialize(CArchive& ar);

Standard MFC override to allow streaming of this CLTimeOfDay to archive. The space taken is exactly 6 bytes (4 data bytes + 2 schema bytes).

Remarks

As of v3 of DTime+, the serialization is not backward compatible with earlier versions.

friend CArchive& operator<<(CArchive& ar, CLTimeSpan& Tod);

Simply calls the Serialize method of ‘Tod’, asserting that the archive ‘ar’ is storing.

friend CArchive& operator>>(CArchive& ar, CLTimeSpan& Tod);

Simply calls the Serialize method of ‘Tod’, asserting that the archive ‘ar’ is loading.

CLDate Index

Constructors

CLDate

Seting

Set

Static Constructors

CurrentSystemTime

CurrentLocalTime

Operations

GetCDate

GetCLTimeOfDay

GetDate

GetAsSystemTime

GetAsFileTime

GetAsCOleDateTime

GetAsTM

AddYear

AddMonth

AddWeek

IsValid

Overloaded Arithmetic Operators

operator=

operator+,-

operator+=.-=

operator++

operator--

Overloaded Equality Operators

operator==, > etc.

Display

GetWindowsFormatString

Format

Serialization

Serialize

operator<<

operator<<

CLDate Constructors

CLDate();

CLDate(long Year, WORD month, WORD Day, WORD Hour, WORD Minute, WORD Second, bool bDoAssert = true);

CLDate(const SYSTEMTIME& SystemTime, bool bDoAssert = true);

CLDate(const FILETIME& FileTime, bool bDoAssert = true);

CLDate(long Year, WORD month, WORD WeekOfMonth, DayOfWeek dow, WORD Hour, WORD Minute, WORD Second, bool bDoAssert = true);

CLDate(long Days, CDate::DateEpoch e, WORD Hour, WORD Minute, WORD Second, bool bDoAssert = true);

CLDate(const CLDate& ld);

CLDate(const CTime& ctime, bool bDoAssert = true);

CLDate(const CDate<TCALENDAR>& Date, const CLTimeOfDay& Tod);

CLDate(const COleDateTime& oleTime, bool bDoAssert = true);

Parameters

Year, Month, Day Indicates a year, month and day.

Hour, Minute, Second Indicates a hour, minute and second values.

SystemTime A Win32 SDK SYSTEMTIME structure.

FileTime A Win32 SDK FILETIME structure.

ld Indicates a CLDate object that already exists.

ctime Indicates a CTime object that already exists.

WeekOfMonth The week of the month (0 - 5).

DayOfWeek The day of the week e.g. CDate::Sunday.

oleTime An OLE Date.

bDoAsserts if set, the constructors will assert in debug mode if any of the parameters are invalid

Remarks

• The default constructor creates an invalid CLDate
• if WeekOfMonth is 5 then it means the last week in the month. This is similar to the way the Win32 SDK operates.
• See the Structures used by the classes for the definition of the enums used to represent the day of week.

CLDate Set functions

CLDate& Set();

CLDate& Set(long Year, WORD month, WORD Day, WORD Hour, WORD Minute, WORD Second, bool bDoAssert = true);

CLDate& Set(const SYSTEMTIME& st, bool bDoAssert = true);

CLDate& Set(const FILETIME& FileTime, bool bDoAssert = true);

CLDate& Set(long Year, WORD month, WORD WeekOfMonth, DayOfWeek dow, WORD Hour, WORD Minute, WORD Second, bool bDoAssert = true);

CLDate& Set(long Days, CDate::DateEpoch e, WORD Hour, WORD Minute, WORD Second, bool bDoAssert = true);

CLDate& Set(const CTime& ctime, bool bDoAssert = true);

CLDate& Set(const CDate<TCALENDAR>& Date, const CLTimeOfDay& Tod);

CLDate& Set(const COleDateTime& oleTime, bool bDoAssert = true);

Parameters

See CLDate Constructors

Remarks

• These functions are actually called by the constructors. They allow a CLDate’s value to be modified even after construction.

static CLDate CLDate::CurrentSystemTime(bool bDoAssert = true);

Returns a CLDate which represents the current UTC date as taken from the system clock.

static CLDate CLDate::CurrentLocalTime(bool bDoAssert = true);

Returns a CLDate which represents the current local date as taken from the system clock.

CDate<TCALENDAR> CLDate::GetCDate() const;

Returns a CDate that represents the date part of this instance. Allows co-ordinated access to all the range of CDate functions.

Remarks

• Changes to the returned CDate are not reflected in the underlying CLDate.

CLTimeOfDay<> CLDate::GetCLTimeOfDay() const;

Returns a CLTimeOfDay that represents the time of day part of this long date. Allows co-ordinated access to all the range of CLTimeOfDay functions.

Remarks

• Changes to the returned CLTimeOfDay are not reflected in the underlying CLDate.

DateLS CLDate::GetDate() const;

Returns a DateLS structure for this instance.

bool CLDate::GetAsSystemTime(SYSTEMTIME& SystemTime) const;

Returns a Win32 SDK SYSTEMTIME struct version of this instance.

Remarks

• The wDayOfWeek parameter of SYSTEMTIME is 0 based i.e. Sunday = 0, Monday = 1, and so on. This is unlike the value returned from CDate::GetDayOfWeek method.

bool CLDate::GetAsFileTime(FILETIME& FileTime) const;

Returns a Win32 SDK FILETIME struct version of this instance.

bool CLDate::GetAsCOleDateTime(COleDateTime& OleDateTime) const;

Returns a COleDateTime representation of this instance. This may prove useful in environments where you have to integrate with VB, ODBC or DAO.

bool CLDate::GetAsTM(tm& time);

Returns a ‘C’ runtime tm struct version of this instance.

void CLDate::AddYear(int Years = 1);

Adds a number of years to this instance.

void CLDate::AddMonth(int Months = 1);

Adds a number of months to this instance.

Remarks

• Invalid Day of Months are always rounded down and will not overflow into subsequent months. e.g. if you add 1 month to March 31 you will get April 30.

void CLDate::AddWeek(int Weeks = 1);

Adds a number of weeks i.e. 7 days to this instance.

bool CLDate::IsValid() const;

Returns true if this instance is valid otherwise false.

e.g. CLDate Inval;

ASSERT(IsValid(Inval) == false);

CLDate& CLDate::operator=(const CLDate& ld);

Copies a CLDate into this CLDate and returns a reference to this instance.

CLDate CLDate::operator+(const CLTimeSpan& ts);

CLTimeSpan CLDate::operator-(const CLDate& ld);

CLDate CLDate::operator-(const CLTimeSpan& ts);

Standard arithmetic operators to add and subtracts CLDate’s.

CLDate& CLDate::operator+=(const CLTimeSpan& ts);

CLDate& CLDate::operator-=(const CLTimeSpan& ts);

Standard auto increment and decrement operators.

CLDate& CLDate::operator++();

Standard arithmetic increment operator. Adds one day to this instance

CLDate& CLDate::operator--();

Standard arithmetic decrement operator. Subtracts one day from this instance.

bool CLDate::operator==(const CLDate& ld);

bool CLDate::operator>(const CLDate& ld);

bool CLDate::operator>=(const CLDate& ld);

bool CLDate operator<(const CLDate& ld);

bool CLDate operator<=(const CLDate& ld);

bool CLDate operator!=(const CLDate& ld);

Standard arithmetic equality operators.

CString CLDate::GetWindowsFormatString(LCID Locale = LOCALE_USER_DEFAULT)

Returns a CLDate::Format string appropriate for the specified windows locale as specified by 'Locale'

See Also

CLDate::Format

CString CLDate::Format(const CString& sFormat = GetWindowsFormatString(LOCALE_USER_DEFAULT), LCID Locale = LOCALE_USER_DEFAULT) const;

Generates a formatted string that corresponds to this CLDate object.

The sFormat string supports the following replaceable parameters:

• %a Abbreviated weekday name
• %A Full weekday name
• %b Abbreviated month name
• %B Full month name
• %d Day of month as decimal number (01 - 31)
• %j Day of year as decimal number (001 - 366)
• %m Month as decimal number (01 - 12)
• %P AM / PM indicator
• %U Week of year as decimal number
• %w Weekday as decimal number (1 - 7; Sunday is 1)
• %x Windows short date representation, namely Date representation + ‘ ‘ + Time Representation for specified locale as provided by 'Locale'
• %y Year without century, as decimal number (00 - 99)
• %Y Year with century, as decimal number
• %H Hours in the day
• %h 12 Hour format Hours in (00 - 12)
• %M Minutes in the hour
• %S Seconds in the minute
• %% Percent sign
• %#x Windows long date representation, namely Long Date representation + ‘ ‘ + Time Representation for specified locale as provided by 'Locale'
• %#d, %#j, %#m, %#U, %#w, %#y, %#H, %#h, %#M, %#S  Remove leading zeros (if any).

Remarks

• If the CLDate is invalid then an empty string will be returned.

See Also

CLDate::GetWindowsFormatString

void CLDate::Serialize(CArchive& ar);

Standard MFC override to allow streaming of this CLDate to archive. The space taken is exactly 11 bytes (9 data bytes + 2 schema bytes).

Remarks

As of v3 of DTime+, the serialization is not backward compatible with earlier versions.

friend CArchive& operator<<(CArchive& ar, CLDate& ld);

Simply calls the Serialize method of ‘ld’, asserting that the archive ‘ar’ is storing.

friend CArchive& operator>>(CArchive& ar, CLDate& ld);

Simply calls the Serialize method of ‘ld’, asserting that the archive ‘ar’ is loading.

Structures / Enums / Consts used by the Classes

namespace DTimePlus
{
enum Month
{
  January = 1,
  February = 2,
  March = 3,
  April = 4,
  May = 5,
  June = 6,
  July = 7,
  August = 8,
  September = 9,
  October = 10,
  November = 11,
  December = 12
};

enum MoslemMonth
{
  Muharram = 1,
  Safar = 2,
  Rabi_Al_Awwal = 3,
  Rabi_Ath_Thani = 4,
  Jumada_l_Ula = 5,
  Jumada_Ath_Tania = 6,
  Rajab = 7,
  Sha_ban = 8,
  Ramdadan = 9,
  Shawwal = 10,
  Dhu_l_Qa_da = 11,
  Dhu_l_Hijja = 12
};

enum DayOfWeek
{
  Sunday = 1,
  Monday = 2,
  Tuesday = 3,
  Wednesday = 4,
  Thursday = 5,
  Friday = 6,
  Saturday = 7
};

enum DateEpoch
{
  EPOCH_JD = 0,
  EPOCH_MJD = 1,
  EPOCH_1900 = 2,
  EPOCH_1950 = 3,
  EPOCH_CTIME = 4,
  EPOCH_2000 = 5,
  EPOCH_GREG = 6
};

struct DateS
{
  long lYear;
  WORD wMonth;
  WORD wDay;
  DayOfWeek weekday;
  WORD wYearday;
};

struct DateLS
{
  long lYear;
  WORD wMonth;
  WORD wDay;
  DayOfWeek weekday;
  WORD wYearday;
  WORD wHour;
  WORD wMinute;
  WORD wSecond;
};
} //namespace DTimePlus

Remarks

• The lYear value is interpreted as in CDate::GetYear
• The wMonth value is interpreted as in CDate::GetMonth
• The wDay is interpreted as in CDate::GetDay
• The weekday (weekday) is interpreted as in CDate::GetDayOfWeek
• The wYearday (wYearday) is interpreted as in CDate::DaysSinceEndPreviousYear

• The hour is interpreted as in CLTimeOfDay::GetHours
• The minute is interpreted as in CLTimeOfDay::GetMinutes
• The second is interpreted as in CLTimeOfDay::GetSeconds

Future Enhancements

• Include functions to handle time zones and daylight savings possibly independent of the Win32 SDK functions which provide this support. Also it would be nice to support historical daylight savings support based on the open source tz database available at http://www.twinsun.com/tz/tz-link.htm
• Include methods to convert from local time to UTC and vice-versa. Also provide methods to convert from one arbitrary time zone to another.
• Allow the code to operate in a mode which is not dependent on MFC.
• Provide a port of the classes which is independent of the Win32 API.
• Support other calendars as covered in the "Calendrical Calculations" book such as Coptic, Ethiopic, ISO, Old Hindu, Mayan, Balinese Pawukon, Persian, Baha'i, French Revolutionary, Chinese and Modern Hindu calendars. I plan on adding support for these as requested.
• Support a concept of positive and negative infinity for the CDate, CTimeSpan and CLDate classes.
• Provide higher precision classes i.e. a CLLDate class and a CLLTimeOfDay class. The idea would be that each these would provide an improved resolution of perhaps 1 nanosecond instead of the current 1 second.
• Implement Hebrew Birthdays and Days of Death support.
• Any other suggestions welcome.

UI Support

The UI support for DTime+ is provided by the DTime+UI.h module. This provides a collection of standard DDX functions to allow a date to be mapped to a CDate<CGregorianCalendar> instance and a time of day to be mapped to a CLTimeOfDay instance. To provide data entry for CLDate, you should provide 2 UI controls, one for the CDate component and another for the CLTimeOfDay component. Note that no UI support is currently provided for the CLTimeSpan class or the Julian or Moslem calendars. For this you will need to roll your own by using something like a standard edit control or a masked edit control. If people feel that this would be a nice addition to the framework, then I would consider developing a clone of the standard Windows date / time controls to support this functionality. The UI used for both of these DDX functions uses the standard Date Time control as provided by Windows (and as wrapped by MFC with CDateTimeCtrl).

Usage of the Data entry Routines

• Place a standard date time control on your dialog / form where you want the control to be using your resource editor. Set the 'Format' style of it as appropriate to 'Short Date or 'Long Date' to present a CDate instance or 'Time' for a CLTimeOfDay instance.
• Call the appropriate DDX routine for the value you want to allow to be edited via the control.

Methods

DDX_DateTimeCtrl

void DDX_DateTimeCtrl(CDataExchange* pDX, int nIDC, DTimePlus::CDate<CGregorianCalendar>& value);

void DDX_DateTimeCtrl(CDataExchange* pDX, int nIDC, DTimePlus::CLTimeOfDay<>& value);

Depending on the overloaded function called, it transfers a CDate or CLTimeOfDay to and from the screen. This function would normally be called in your classes DoDataExchange function

Parameters

pDX Standard MFC data exchange class.

nIDC The resource ID of the date and time picker control associated with the member variable.

value Value to retrieve/set in the UI.

Remarks

• See the DTimeUITest Demo project included in the DTime+ workspace provided in the download for a concrete example on using theses functions.

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
13 April 2007