Table of Contents Copyright - Copyright information Distribution - Copying conditions Disclaimer - Legal Information Trademark - Trademark information Support/Updates - How to get updates and support Author - How to reach the author Description - What does the DateLib? Requirements - Requirements for using the DateLib Installation - How to install the DateLib Localization - For catalog translators Developer Info - Information for developers History - Revision history of the DateLib Todo - Todo list Known problems - List of known problems Technical notes - Technical background Acknowledgments - Acknowledgments Please rate - Please rate the DateLib History of the Calendar - A short History of the Calendar References - Background knowledge Software - Software that uses the DateLib Copyright --------- This software and its documentation are copyright © 1994-1998 Kai Hofmann. All rights reserved! - Permission for COMMERCIAL USE is only given by an extra available commercial license that must be validated! Contact me directly for this license, because it will be individually handed out per your needs! - Permission is hereby granted, without written agreement and without license, to USE this software and its documentation for any NON-COMMERCIAL purpose, provided that the above copyright notice and the following paragraph appear in all copies of this software (Non-commercial includes Giftware!). Please include the following note into your software: "This software uses the DateLib (TM) that is copyright © 1994-1998 Kai Hofmann" and send me a full version of your product at no cost including free updates! Money is welcome (For Bank Account see author - but *ONLY* send in DM to this Bank Account!). Distribution ------------ Permission is hereby granted, without written agreement and without license or royalty fees, to copy and distribute this software and its documentation for any purpose, provided that the above copyright notice and the following paragraphs appear in all copies of this software, to: - All who will distribute this software for free! - All free accessible INTERNET servers! - All Aminet® sites - Fred Fish for his great Amiga-Software-Library - The German SAAR AG PD-Library - Angela Schmidt's Meeting Pearls serie - All others who do NOT take more than US$ 3.- for one disk that includes this software! IMPORTANT NOTE: This package may not be included on any further Aminet CD-ROMs unless authors contributing their software to the CD-ROM, (without mentioning distribution "NoCD") are granted a copy of the CD *completely* *free* *of* *charge*. The Meeting Pearls IV CD-ROM demonstrates that a Freebie policy is also possible with "very-low-budget" CD-ROMs (*), so Aminet should quickly re-establish the same Freebie policy it used up to Aminet CD 13. (*) Suggested retail price for MP4 is DM 14,95/US$ 12/£ 8.95. DISCLAIMER ---------- THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDER AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THE AUTHOR HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. Trademark --------- DateLib is a trademark of Kai Hofmann Amiga, AmigaDOS, AmigaGuide and Workbench are registered trademarks of Amiga International, Inc. Aminet is a registered trademark of Stefan Ossowskis Schatztruhe GmbH SAS/C is a registered trademark of SAS Institute Inc. All other trademarked names used herein are used for the purposes of identification and for the benefit of the trademark holder. No infringement of trademarks is intended. Trademarks remain the property of the trademark holder. Support/Updates --------------- - Updates will be available via Aminet® - Support will be available via the authors email address and via http://home.pages.de/~i07m/amiga/DateLib.html http://home.pages.de/~i07m/calendar/ Author ------ Kai Hofmann Arberger Heerstraße 92 28307 Bremen Germany Phone: (+49)-(0)421/480780 EMail: i07m@informatik.uni-bremen.de i07m@zfn.uni-bremen.de IRC : PowerStat@#AmigaGer WWW : http://home.pages.de/~i07m/ Bank account : 1203 7503 Account owner: Kai Hofmann Bank code : 290 501 01 Bank name : Sparkasse in Bremen/Germany Description ----------- A portable library that gives you low level functions for date calculations. Includes the following features: - Support for six different date/time measurement systems: Julian, Gregorian, Heis, Julian Day, Modified Julian Day, Scaliger Year (other systems will follow). - Month/Weekday and other date/time string support for 21 languages. - Support for different countries (implementation not finished!). - Calculating leap years. - Functions to calculate the days of a month or a year or between two dates. - Functions to calculate the weeknumber and the weekday. - Check the validity of a date. - Calculating Easter. - Comparing dates. - Powerfull functions to handle differences between dates. - Transformations from one time measurement system to the others. - Calculating your local time zone out of your position on the earth. - Calculating the age of the moon and the moon phase. - Check the validity of a time. - Comparing times. - Transforming 24h time format into seconds and back. - Transforming 24h time format to Julian Day time format and back. - Every weekday can be the first day of the week. - Supplement two digit years to four digit years. - Formatting of date and time values into strings. - Parsing date and time values from strings via templates or powerfull autoanlysation. - Converting weekday/week/year to day/month/year vice versa. - Autodocs describing all functions of the library. - Interfaces for: C/C++, Modula II, Oberon, Amiga-E, Assembler, Cluster, Blitz Basic 2, ARexx. - Including ANSI-C test example. Requirements ------------ - OS 1.2 Installation ------------ Only use the installer script! (The Installer must be in your system-path!) If you use an Installer prior to V42 you should set the LANGUAGE Tooltype to your language. Installer V42 and better automatically use your current locale. Please note that the installer-script is very special, because: - It features uninstallation - It is automated - It is very flexible - It is very intelligent (for an installer-script ;-) - It uses WrapGuide (if present) for the documentation if running under a pre V39 system. - It can be reused by (hopefully) many other Amiga shared libraries, because the authors of shared libraries need to only change a few things: * The #copyright variable * The #min_os_version and #min_os_revision variables * The #language variable * The P_CustomExists, P_CustomInstall and P_CustomUninstall procedures * The 'APPNAME' tooltype within the MCC-Install icon. Localization ------------ The DateLib supports the following languages for the moment: English, German, French, Spanish, Portuguese, Danish, Italian, Dutch, Norwegian, Swedish, Polish, Finnish, Hungarian, Greek, Esperanto, Turkish, Latin, Russian, Czech, Catalonian, Serbian If your language is none of these, I need a translation of the following words: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday (including the short versions: Mon, Tue, Wed, Thu, Fri, Sat, Sun) January, February, March, April, May, June, July, August, September, October, November, December (including the short versions: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec) day, month, year, week, weekday, hour, minute, second, yesterday, today, tomorrow days, months, years, weeks, weekdays, hours, minutes, seconds daily, monthly, yearly, weekly, hourly, per minute, per second The DateLib also supports the following countries for the moment: Italy, Germany, Switzerland, Denmark, Netherlands, Great Britain, USA, Sweden If you want your country to be supported, I need the exact days that where removed from the calendar by the Gregorian calendar reform. Pope Gregor XVIII removed the days 5.10.1582-14.10.1582 from the calendar, but this reform happened at different times in different countries. Information for Developers -------------------------- - Every function name as well as every datatype name starts with a prefix "date_" or "time_". This makes the library more portable. - For the three calendar systems (Julian, Gregorian, Heis) all functions with the same usage have the same name as well as the same parameters (in the same order). Normally you would only need to use the Gregorian or Heis version (I preffer the last one). For some functions the initial (J, G, H) only is used to identify the calendar system. - Read the Autodocs carefully for each function, some have limitations for the date range! - JD means Julian Day (Date) calendar system. - MJD means the historical(!) Modified Julian Day (Date) calendar system. - Scaliger is a special calendar system for counting years - used for JD. - The country support is still not implemented, because this is really complicate. Please report all problems with the software or its documentation! Also please let me know if and how this documentation could be improved. Are there open questions or things that are not clear? Release history --------------- 13.04.1994 : 33.087 - First release on Aminet3 & SaarAG 707 13.08.1994 : 33.088 - Second release on Aminet4, SaarAG 793, Fred Fish & SimTel 18.12.1994 : 33.093 - Third release on Aminet 06.02.1995 : 33.100 - Fourth release on Aminet (CD 5), Amiga-PD-1 03.08.1995 : 33.158 - Fifth release on Aminet (CD 8, Set2a, Set2c), SaarAG, Fred Fish & SimTel 12.12.1997 : 33.286 - Sixth release on Aminet 22.12.1997 : 33.288 - Seventh release on Aminet 26.12.1997 : 33.290 - Eigth release on Aminet 29.01.1997 : 33.297 - Ninth release on Aminet * General code optimizations * Autodocs fixed * Extended HSYearToJD() implementation * Changed JYearToScaliger() implementation * Added JulianDiffDateRange(), GregorianDiffDateRange(), HeisDiffDateRange(), JulianRangeDiff(), GregorianRangeDiff(), HeisRangeDiff() * Declared JulianDiffDate(), GregorianDiffDate() and HeisDiffDate() as OBSOLETE * Renamed date_Calendar to date_Calendars * Added two countries: USA and Sweden Todo ---- - Daylight saving support (country support?) - Country dependend for 1582 - Optional parameter check code - Locale.library catalogs - Country strings for TextEngine - DATE/ECHO like shell command - EVAL like shell command - GMT <-> ZoneTime (incl. summer/winter change) - TimeZoneDiff - A function to compare date/time of different time zones! - More intelligent var/fix length date/time parser format detection - Rising/setting of moon and sun - Other calendars, like the Islamic and the Jewish Known problems -------------- - See Autodocs Technical notes --------------- A tropical year is 365.2422 days! / 365d, 5h, 48min, 46sec A moon month is 29.53059 days! / 29d, 12h, 44min, 2.9 sec A moon phase is 7.38265 days! The calculations are historical and NOT astronomical! Here are the offsets for days that depend on Easter: Carnival Monday : Easter Sunday - 48 Mardi Gras : Easter Sunday - 47 Ash Wednesday : Easter Sunday - 46 Palm Sunday : Easter Sunday - 7 Maundy Thursday : Easter Sunday - 3 Good Friday : Easter Sunday - 2 Easter Monday : Easter Sunday + 1 Ascension of Christ : Easter Sunday + 39 Whitsunday : Easter Sunday + 49 Whitmonday : Easter Sunday + 50 Feast of Corpus Christi : Easter Sunday + 60 Rules for other days: New Year : 01.01. Epiphany : 06.01. Valentine : 14.02. Begin of daylight savings time in Germany : Last Sunday in March May first observed : 01.05. Day of European : 05.05. Mother's day : Second Sunday in May Grandhawk in Germany : 27.06. Peter and Paul : 29.06. Marie's ascention : 15.08. German day of unity : 03.10. Thanksgiving in Germany : First Sunday in October End of daylight savings time in Germany : Last Sunday in October Reformationday : 31.10. All Saints Day : 01.11. Memorial Day : 4. Advent -35 Penitential and Pray Day : 4. Advent -32 Death Sunday : 4. Advent -28 1. Advent : 4. Advent -21 2. Advent : 4. Advent -14 3. Advent : 4. Advent -7 4. Advent : Sunday <= Christmas Eve Christmas Eve : 24.12. Christmas Day : 25.12. Second Christmas Day : 26.12. New Years Eve : 31.12. Acknowledgments are going to the following people: Rita Reichl - For correcting my English, for the three magic books, for helping in general and especially for being my inspiration. Daniel Amor - For his hint about the Oberon-2 SHORT command Jim Rickman - For reporting a bug Christian Schaefer - For spending time on this lib with his Borland C++ 4.5 compiler Heinz Zemanek - For his great book Jacco van Weert & Frans Slothouber - For the 'Robodoc' utility Martin Huttenloher - For MagicWB Udo Schuermann - For WrapGuide Stefan Kost - For ag2txt Jürgen Kohrmeyer - For the rexxtricks.library James Cooper, Steve Krueger, Doug Walker - For supporting SAS/C® after SAS suspended support. Heinz Wrobel - For reopening my eyes Mathew Wilson - For his text about the calendar Sandor Pogacsas - For the translation into Hungarian Pantelis Kopelias - For the translation into Greek Holger Duerer - For the translation into Esperanto Berend Ozceri - For the translation into Turkish Christian Hujer - For the translation into Latin Eugene Stepanoff - For the translation into Russian Anders Bakkevold - For additional translations into Norwegian Paolo Menichetti - For additional translations into Italian Ole Friis - For additional translations into Danish Nuno Namora - For additional translations into Portuguese Pedro Luis Mieza - For additional translations into Spanish Francis Labrie - For additional translations into French Eric Krieger - For additional translations into Dutch Marcus Alanen - For additional translations into Finnish Marcin Orlowski - For additional translations into Polish Thomas Andersson - For additional translations into Swedish Patrick Delaere - For fixing the nederland translation & for bug reports Vit Sindlar - For the translation into Czech Pedro Kuis Mieza - For the translation into Catalan Ljubomir Jankovic - For the translation into Serbian Erwan Fouret - For his help with the BB2 interface Henning Thielemann - For his help with the Cluster interface Please rate ----------- Please rate DateLib and Lib-Install. To do so, send an email to aminet-server@wuarchive.wustl.edu with the following content: RATE dev/misc/Lib-Install.lha RATE util/libs/DateLib.lha where is a mark from 0..10 with 10 being the best. You can rate several programs in one mail. Thank you! A short History of the Calendar ------------------------------- Copyright Mathew Wilson All rights reserved! The calendar is a very big part of our everyday life yet we often forget the centuries of patient study along with trial and error that went into creating the thing that now controls our lives. This method of recording time, that started with the Babylonians, has gone through many changes to evolve into the modern day calendar we use today. The first calendars were based on the movements of the moon. Later on this was proved to be inaccurate as man learned that the Earth travelled around it's star. The Sun became the base for time recording as the lunar year did not match the cycle of the Earth around the Sun. Although there are still some calendars in use today that are based on the Moon cycle. These ones are usually well entrenched in tradition and would be difficult to change without affecting the culture; especially if it involves religion. The current Jewish calendar is still based on the Moon's movements which begins with the year of creation, set at 3760 BC. The Islamic calendar is also based on the Earth's meteorite impacted satellite. The Egyptians were the first to adopt the Sun as a guideline. Theirs is the long descendant of the Gregorian calendar we use today. The month became an arbitrary unit that was previously related to the cycles of the moon. The Egyptians used a 365 day year. It is thought that they first adopted this calendar in the year 4236 BC. Later on people learnt that the Earth revolved at a period of 365 and about a quarter days around the Sun. Pharaohs and other leaders made many attempts to alter their calendars to reflect this but failed either because of tradition or miscalculations from the priests that were assigned to look after the motions of the calendar. Next came the Romans. They had originally used a Moon based system that was very complicated. It's accuracy was entrusted to the `College of Pontiffs' who often misused this privilege to their own gain. By the time Julius Caesar became virtual dictator of Rome the calendar was in a mess. In 47 BC he called upon famous Greek astronomer Sosigenes to try and correct things. After suggestion by Sosigenes, Caesar decided to adopt the Solar year as the Egyptians did. He gave the year a length of 365 and a quarter days. This quarter day was with held for 4 years and then added as a 'leap year.' To honor Julius, the Senate changed the name of the month Quintilis to Julius (July). Julius also had to make corrections due to the errors in the old calendar. The problems did not end there, for after he was assassinated in 44 BC the Pontiffs in charge of the calendar decided to insert the leap every third instead of every fourth year. When Augustus Caesar came on the scene he restored the correct leap-year in 8 AD. As you may have guessed the Senate also honored this change by renaming the month Sextilis to Augustus (August). This calendar is also referred to as the Julian calendar, for obvious reasons. In 321 AD the Emperor Constantine created the seven day week discarding the old complicated system of `Calends' the Romans had developed to make reference to days within a month. As technology became available it was discovered that the real length of the Solar year is 365.242199 days, or 365 days, 5 hours, 48 minutes and 46 seconds. This meant the Julian calendar was too long by about 11 minutes. After a few centuries this soon amounted to several days. Again the calendar began drifting from the seasons. In 1582 Pope Gregory XIII commissioned the services of the mathematician Christopher Clavius and the astronomer-physician Luigi Lilio Ghiraldi to fix the error. They found the error to amount to 10 days. In October 1582 the calendar was re-adjusted to fix the error. The 4th day was followed by the 15th to loose the 10 days. This created problems for people born on the 5th but they made reference to those dates either using OS (Old Style) or NS (New Style) systems. Then the leap-year rule was changed to avoid further errors. Now any centurial year (ending in `00') was only a leap year if it was divisible by 400. Therefore 1600 was a leap year but 1700,1800 and 1900 were not. This became the `Gregorian' calendar, the one we use today. All Roman Catholic countries immediately adopted the Gregorian reform, but others were slow to follow. The English didn't start using it until 1752. The French originally followed the Gregorian way but changed in 1792 and returned to it in 1805. Japan followed in 1873, China 1912, Greece 1924 and Turkey 1927. Russia had a similar experience to France during the Bolshevik revolution but returned to it in 1940. Since then a few people have been dissatisfied with the calendar and have attempted reforms but a major change has not been affected because the entire world cannot agree on a new system. In 1923, 500 new reforms were heard at the League of Nations. Two new calendars emerged as favourites: the Thirteen Month Calendar and the World Calendar. But these did not get a majority acceptance by the nations due to conflicts with nationalistic dates of importance and the business community said it would complicate things. There were others that came close but they are too many to list. So it seems we are to keep the Gregorian calendar for a while yet. You must therefore remember that dates previous to October 15th, 1582 cannot be calculated by just going back in time a certain amount of days from today. Time is not linear in this sense because of all the changes that have been made. References ---------- English books which were consulted in creating this library: Mathematical Astronomy with a Pocket Calculator Aubrey Jones Fras Unknown (first) Edition David & Charles Newton Abbot, London 1978 ISBN 0-7153-7675-6 Astronomical Algorithms Jean Meeus Unknown Edition (I use the German second edition ;-) Willmann-Bell, Inc., Ruchmond, Virginia (USA) 1991 ISBN 0-943396-35-2 ISO 8601-1988 International Organisation for Standardization, Genf 1988 German books which were consulted in creating this library: Kleine Naturwissenschaftliche Bibliothek, Band 23 Ewige Kalender A.W. Butkewitsch & M.S. Selikson 5. Auflage Teubner, Leipzig 1974 ISBN 3-322-00393-0 Tag und Woche, Monat und Jahr: eine Kulturgeschichte des Kalenders Rudolf Wendorff Westdeutscher, Opladen 1993 ISBN 3-531-12417-X Kalender und Chronologie: Bekanntes & Unbekanntes aus der Kalenderwissenschaft Heinz Zemanek 4. Auflage Oldenbourg, München 1987 ISBN 3-486-20447-5 Meyers Handbuch über das Weltall Karl Schaifers & Gerhard Traving 5. Auflage Bibliographisches Institut, Mannheim 1973 ISBN 3-411-00940-3 Astronomische Algorithmen Jean Meeus 2. Auflage Johann Ambrosius Barth, Berlin 1994 ISBN 3-335-00400-0 Astronomie mit dem Personal Computer Oliver Montenbruck & Thomas Pfleger 2. Auflage Springer, Berlin 1994 ISBN 3-540-57701-7 Handbuch der mathematischen und technischen Chronologie Das Zeitrechnungswesen der Völker Band I F. K. Ginzel 1. Auflage J. C. Hinrichs'sche Buchhandlung, Leipzig 1906 Handbuch der mathematischen und technischen Chronologie Das Zeitrechnungswesen der Völker Band II F. K. Ginzel 1. Auflage J. C. Hinrichs'sche Buchhandlung, Leipzig 1911 Handbuch der mathematischen und technischen Chronologie Das Zeitrechnungswesen der Völker Band III F. K. Ginzel 1. Auflage J. C. Hinrichs'sche Buchhandlung, Leipzig 1914 Software -------- The following software products use the DateLib: Date : By Kai Hofmann Aminet:dev/mui/MCC_Date.lha http://home.pages.de/~i07m/amiga/mui/Date.html DateString : By Kai Hofmann Aminet:dev/mui/MCC_DateString.lha http://home.pages.de/~i07m/amiga/mui/DateString.html DateText : By Kai Hofmann Aminet:dev/mui/MCC_DateText.lha http://home.pages.de/~i07m/amiga/mui/DateText.html MonthNavigator : By Kai Hofmann Aminet:dev/mui/MCC_MonthNavi.lha http://home.pages.de/~i07m/amiga/mui/MonthNavigator.html Time : By Kai Hofmann Aminet:dev/mui/MCC_Time.lha http://home.pages.de/~i07m/amiga/mui/Time.html TimeString : By Kai Hofmann Aminet:dev/mui/MCC_TimeString.lha http://home.pages.de/~i07m/amiga/mui/TimeString.html TimeText : By Kai Hofmann Aminet:dev/mui/MCC_TimeText.lha http://home.pages.de/~i07m/amiga/mui/TimeText.html This product is based on or uses parts of MagicWB - The Workbench Enhancer -------------------------------- Copyright © 1992-1997, Martin Huttenloher If you use and like this product you should very much consider to take a look at MagicWB, which is the authentic source of the style, colors and design elements contained in this package. It features hundreds of original icons, patterns, image-drawers, dock-brushes and some specially designed high-quality fonts to improve the comfort & legibility of your daily Workbench session. What is MagicWB? MagicWB is a full replacement for the Graphical User Interface of the Workbench and has become the standard visual interface on the Amiga. Over the last years MagicWB has received various merits and an overwhelming response from Amiga magazines and users worldwide proclaiming it "a must for all Amiga users". Even commercial applications are supporting the multi-colored look & style of MagicWB. Get yourself the latest version of MagicWB and see for yourself the wonders it can do by automatically transforming your old and dull Amiga Workbench into an impressive workstation environment that will be the envy of all PC Windows and Mac users. Update yourself to the state-of-the-art workbench standard everyone uses on the Amiga! It is also your key to enjoy the new look & feel of many applications and other MWB add-ons and extensions. MagicWB is distributed as shareware. Get yourself the latest FREE PUBLIC RELEASE of MagicWB now: It is called ---------------- MagicWB21p.lha ---------------- and can be found everywhere on Aminet (or your local BBS or public domain series). Install it and witness the instant magic it performs on your old Amiga Workbench. Also included is the latest SASG registration program with which you can order and get the full registered version of MagicWB. If you want to order directly, feel free to send DM 30.- or US$ 20.- (cash, no checks!) to Martin Huttenloher Am Hochstraess 4 D-89081 Ulm Germany You may also choose to visit the official MagicWB homepage on the world wide web. There you can find the latest news & support and even register your MagicWB online (which is much more comfortable and faster). You can even benefit from various special offers & discounts for MagicWB if you order through our website! Come and visit MagicWB at: ---------------------- http://www.sasg.com/ ---------------------- Save 20% by using the discounts on our website! Ordering online also saves you a lot of time and work! WrapGuide is Copyright 1994-1995 Udo Schuermann All rights reserved