home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / fdater.zip / TRUEDATE.TXT < prev   
Text File  |  1995-04-29  |  7KB  |  148 lines
  1. ======================================================================
  2.             TRUEDATE: A Portable Routine for Date Arithmetic
  3.                      by Stephen Ferg
  4.                  Copyright Stephen Ferg, 1994
  5. ======================================================================
  6. AUTHOR:     Stephen Ferg
  7.             608 N. Harrison Street
  8.             Arlington, VA 22203-1416
  9.             USA
  10.  
  11.             telephone (voice, not FAX): (703) 525-2241
  12.             CompuServe ID             : 73377,1157
  13.             Internet                  : ferg_s@bls.gov
  14.             Internet                  : 73377.1157@compuserve.com
  15.  
  16. =====================================================================
  17.  
  18. It's not hard to find a date arithmetic routine when you need one.
  19. They are available in journal articles, in books, and on electronic
  20. bulletin boards such as CompuServe.  But if you are building a business
  21. application, the chances that you will find a routine that you can
  22. actually use are slim.
  23.  
  24. Most date arithmetic routines are direct or indirect descendants of a
  25. FORTRAN algorithm published in 1968 by two astronomers: Henry F.
  26. Fliegel of the Georgetown University Observatory, and Thomas C. Van
  27. Flandern or the U.S. Naval Observatory.\1\  Consequently, their
  28. fundamental concepts are drawn from astronomy, not business.  For these
  29. routines, a day is the time it takes for the earth to make one complete
  30. rotation on its axis; a year is the time it takes for the earth to make
  31. one complete revolution around the sun.  For such routines, the number
  32. of days in a year is not built into the concept year, but is something
  33. to be discovered through scientific investigation.  As we all know,
  34. astronomers have discovered that a year is equal to approximately
  35. 365.25 days.
  36.  
  37. Astronomy-based routines typically depend on hard-coded "magic
  38. numbers": a year is 365.2425 days, for example.  A month is 367/12
  39. days, or 30.6001 days, and so on.  They also involve a lot of
  40. back-and-forth multiplication/division operations.  The purpose of the
  41. repeated multiplication and division operations is to force truncation
  42. of numbers that are stored internally in a particular format.  You
  43. might find, for example, a number being multiplied by 12 and then
  44. immediately divided by 12, then multiplied by another number, and then
  45. multiplied by 12 and divided by 12 again.  The "magic numbers" truly
  46. are magic, for they were carefully selected to interact with the
  47. internal storage format of the numbers and the multiplication/division
  48. cycles to produce the desired result.
  49.  
  50. These routines have two major drawbacks: (1) they are not portable, and
  51. (2) they are not maintainable.  Because they depend on numbers being
  52. stored internally in a format determined by a particular language as
  53. implemented by a particular compiler for a particular hardware
  54. platform, such routines are usually not portable to another language or
  55. another machine.  (I've personally dealt with a COBOL version of the
  56. Fliegel/Van Flandern algorithm that worked correctly on an IBM
  57. mainframe but broke when ported to the MicroFocus COBOL compiler on a
  58. PC.)
  59.  
  60. Second, they are unmaintainable because their magic numbers and
  61. algorithms are derived primarily from the behavior of the platform they
  62. were designed to run on, not from problem-domain concepts such as year
  63. and leap year.  Because the problem-domain basis of the algorithms is
  64. so obscure, the algorithms are incomprehensible and unmodifiable.  The
  65. main problem you will have in using one of these routines is that you
  66. will not be able to modify its leapyear scheme- the algorithm for
  67. determining which years are leap years and which are not- if you need
  68. to.
  69.  
  70. In order to overcome these problems, I developed a date routine called
  71. TRUEDATE that is designed to be both portable and modifiable.
  72.  
  73. TRUEDATE is portable because its algorithms are independent of any
  74. particular language, compiler, or hardware platform.  It requires support only
  75. for an integer data type of at least seven significant digits and normal
  76. arithmetic operations on integers: addition, subtraction, multiplication,
  77. integer division, and division remainder (modulo).
  78.  
  79. TRUEDATE is maintainable because its algorithms are based on the
  80. application-domain logic of date concepts.  For TRUEDATE:
  81.  
  82. *  An ordinary year is a year that contains 365 days; in an ordinary year
  83.    February contains 28 days.
  84.  
  85. *  A leap year is a year that contains 366 days; in a leap year February
  86.    contains 29 days.
  87.  
  88. *  The leapyear scheme is clearly represented in TRUEDATE's source code.
  89.  
  90. In designing TRUEDATE, there were several possible leapyear schemes to
  91. choose from, since several different leapyear schemes are in common use, or
  92. have been proposed.  Leapyear scheme #1 is:
  93.    Every year is an ordinary year
  94.    EXCEPT THAT every year evenly divisible by 4 is a leap year.
  95.  
  96. Scheme #2 adds the following exception to scheme #1:
  97.    EXCEPT THAT every year evenly divisible by 100 is not a leap year.
  98.  
  99. Scheme #3 adds the following exception to scheme #2:
  100.    EXCEPT THAT every year evenly divisible by 400 is a leap year.
  101.  
  102. Scheme #4\2\ adds the following exception to scheme #3:
  103.    EXCEPT THAT every year evenly divisible by 4000 is not a leap year.
  104.  
  105. TRUEDATE uses leapyear scheme #3.  According to it:
  106.          1983  is nota leap year
  107.          1984  is a leap year
  108.          1900  is nota leap year
  109.          2000  is a leap year
  110.  
  111. The [REXX] source code for TRUEDATE is shown in [FDATER.REX].  Some
  112. obvious opportunities for optimization have been ignored in order to
  113. leave the pattern of the algorithm clear.
  114.  
  115. TRUEDATE is intended for business applications, not historical ones.  It
  116. knows nothing about historical changes in the calendar such as the 10-day jump
  117. that occurred when Britain moved from the Julian to the Gregorian calendar in
  118. the 18th century.  As far as TRUEDATE is concerned, the calendar has followed
  119. the same pattern, unchanged, since January 1, 0001.
  120.  
  121. Central to all date arithmetic routines is the concept of an "absolute" or
  122. "true Julian" date:  a date expressed as the number of days from some day in
  123. the distant past.  The apparently arbitrary base date for the Fliegel/Van
  124. Flandern algorithm- January 1, 4713 BCE- reflects its basis in implementation,
  125. rather than application-domain, considerations.  TRUEDATE's base date is
  126. January 1, 0001 (i.e. day 1 of month 1 of year 1).  For this base, the absolute
  127. date for January 1, 1992 is 727198.
  128.  
  129. The heart of TRUEDATE is two routines that, respectively, convert a calendar
  130. date to and from an absolute date.  With such routines available, doing date
  131. arithmetic is easy.  To determine, for example, an invoice date that is 60 days
  132. in the future, one simply translates today's calendar date into an absolute
  133. date, adds 60 to the absolute date, and translates the resulting absolute date
  134. back into a calendar date.  When absolute dates are available, day-of-week
  135. determination is similarly easy.  Dividing an absolute date by 7 will produce a
  136. remainder in the range 0..6 that will tell you the number of the day of the
  137. week.
  138.  
  139.  
  140. REFERENCES
  141.  
  142. 1.  "A Machine Algorithm for Processing Calendar Dates", by Henry F.
  143. Fliegel and Thomas C. Van Flandern, Communications of the ACM, Volume
  144. 11, Number 10, October 1968.
  145.  
  146. 2. "The Dating Game" (Bit By Bit column), Stan Kelly-Bootle, Computer
  147. Language, July, 1989.
  148.