----------------------------------------------- DateTime.e 2003 - by Cyrek, aka Carl R. White ----------------------------------------------- Welcome to the second release of the Euphoria Date and Time handling library. A few tweaks, minor bug fixes and extras have been added to the library and this document provides a guide to the major changes. 1. Bug Fixes ============ While it can be said that no software is completely bug free, the last release of DateTime.e was surprisingly robust. Only one glaring error is evident in the old source: [Fixed] A spurious 'with trace' statement and a 'trace(1)' call were accidentally left in the source code around the 'daysDifference' function. No other bugs were found or reported. The documentation also contained occasional mistakes. In each noted case the mistake was not serious, but has now been fixed to the best knowledge of the author. This does not guarantee that there are no errors in the new documentation, however... 2. Tweaks - Updates to existing functions ========================================= Most of the functions from the last release have been left alone only two major changes have been made: * Consistency has been introduced in the use of the return value of Euphoria's own 'date()' function. Originally, various methods were used to add 1900 to the year value. The fastest of these has been chosen and is now used whenever it is called for. * The 'addToTime()' and 'subFromTime()' functions will now accept any combination of Times and atoms as their parameters. This was done since the second parameter has always been variably typed and the logical step was to carry the philosophy through to the first parameter also. 3. Omissions - Deprecated functions =================================== * The 'addToDateTime()' and 'subFromDateTime()' functions are now deprecated and are no longer documented in the main manual. They are replaced by new four new functions, two of which functional identically to the originals. In the interests of backwards compatibility the original functions are still available, but this may not be the case should there ever be another release of the library. 4. Extras - New functions in the library ======================================== For each of the functions mentioned below, please see the relevant manual (DateTime.txt) entry for more information. * Functions that returned a integer representing a number of days (e.g. number of days between one Date and another), now have counterpart functions with a DT suffix that take DateTime combination types and return a fractional number of days. For instance, the number of days between midnight today and noon tomorrow is 1.5. This was not easy to calculate with the previous version of the library. The integer-only functions were left alone as they are a great deal faster than their newer DT equivalents. An exception was made in the naming of the DT-suffix counterpart of the 'julianDate()' function; This function was named 'julianDateTime()' as this seemed a more logical name for the function. * To facilitate the functions above, functions handling conversions to and from fractions of days have been added. e.g. 6 hours = 0.25 days. As an unfortunate side-effect of the resolution of Euphoria atoms (32-bit IEEE float), some rounding errors may occur whilst using the new 'dayFraction' and 'DT' functions. * A new counterpart to the 'dayOfWeek()' function has been added. 'validDayOfWeek()' is identical in function except returns -1 rather than the standard week-day number if the date is invalid (e.g. 31st June). * Four new functions for adding seconds or days to DateTimes have been added; 'addSecondsToDateTime()', 'addDaysToDateTime()' and their similar 'sub...FromDateTime()' functions replace the removed 'addToDateTime()' and 'subFromDateTime()'. The '...Seconds...' functions are identical to those removed, while the new '...Date...' functions happily deal with the new 'dayFraction' idiom. * Boolean comparison functions have been added that compare native data-types and return a truth value. These are 'isEquivalent()', 'isBefore()' and 'isAfter()'. These are comparable to Euphoria's '=' '<' and '>' operators respectively. * Generic conversion functions able to convert any Euphoria data-type into a DateTime.e native type have been added. These are 'ToSeconds()' and 'ToDateTime()'. Both recognise if they have been passed something that is already a native data-type and deal with the data accordingly. However, if they come across something unrecognised, the a best-guess algorithm is activated to convert the unknow data structure. * Finally, a debugging / conversion-to-string function has been included. Taking any native data-type, 'sDumpDT()' will return a string sequence containing a printable form for the inputted data. 5. Time Zone and Daylight Savings (Summertime) Handling ======================================================= Each of the operating systems the Euphoria programming language is avaliable for has its own way of handling time zones and daylight savings (MS-DOS in fact, has no method for this whatsoever). Therefore it is impossible to provide handling for timezones and daylight savings without introducing platform specific code. The philosophy behind DateTime.e is that it should be as generic as possible and so there is no intention to add daylight savings or time zone handling to the library. The lack of any timezone code is usually only a problem when converting Unix style dates, since these are stored as the number of seconds since 1970-1-1 at midnight _GMT_. Of course, if GMT is not your timezone, this will cause resultant dates to be offset by the number of seconds different your timezone is from GMT. One way to work around this is to offset the internal 'Epoch' variable by the same number of seconds to compensate before doing any Unix time calculations. The place to do this is directly after 'include'-ing the library. e.g.: include datetime.e -- For United States EST = GMT minus 5 hours: Epoch = subSecondsFromDateTime(Epoch, {5,0,0}) -- For Yangon, Myanmar = GMT plus 6_1/2 hours: Epoch = addSecondsToDateTime(Epoch, {6,30,0}) -- For Sydney, Australia = GMT plus 10 hours: Epoch = addSecondsToDateTime(Epoch, {10,0,0}) The above is purely an example; the Epoch should only ever be offset once!