<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE edoc PUBLIC "-//Elucidator2 edoc//EN" "">

<!-- initial comment -->

<edoc>
<enode role="essay">
<head>

<!-- The topic must characterize and introduce the thematic contents of -->
<!-- the node, not merely categorize (label) it. The topic should aim -->
<!-- to convey positions and results. Topics are more likely to be -->
<!-- representative and topically faithful if they are (1) constructed as -->
<!-- sentence fragments and (2) rewritten after composition of the node. -->
<topic> 
Time Conversion
</topic>

<!-- The abstract is supposed to be a thematic window into the -->
<!-- contents of the node. The abstract must boil down the node body -->
<!-- to typicalle 3-5 lines of text. It should expose rationales, results -->
<!-- and main characteristics of content of the node. -->
<abstract>
This program shows how to convert time from milliseconds elapsed since
January 1, 1970, 00:00:00 GMT to a representation with year, month,
day, hour, minutes and seconds.<br/><br/> 

It does so via a class that stores and convert the given time. The
class has an interface that allow one to retrieve the needed
information about the time.<br/><br/> 

A test example is provided to illustrate the use of the class.<br/><br/>

This documentation is to be viewed as an small example of
<em>Elucidative Programming</em> with Java and was part of the
week-assignment for the authors DAT5 project exam.<br/><br/>  
</abstract>

<!-- The status of the node, being new, inprogress or finished. -->
<status><new/></status>

<!-- A list of representative keywords for the node. -->
<keywords><kw>Time</kw>
	  <kw>Conversion</kw>
	  <kw>Elucidative programming</kw>
</keywords>

<!-- The name of the author that has last change the node (Will be -->
<!-- filled in automatically). -->
<author>Max Rydahl Andersen and Claus Nyhus Christensen</author>

<created>2000/09/12 21:43:32</created>

<last-updated>$Date: 2000/09/04 11:55:46 $</last-updated>
</head>

    <section>
      <title>Introduction</title>

This example is based on the <xlink role="mentions"
href="http://www.cs.auc.dk/~normark/elucidative-programming/time-conversion/time/time.html">Scheme Time Example</xlink> made by 
Kurt Noermark.<br/><br/> The goal is to create a Java application that
can convert time from one representation to another. To do this we
create a class named <slink role="mentions" href="ugeopgave/Date">Date</slink>, that can be used to store a
specifc instance of time and provides an interface to set and get
information about the time.<br/><br/>  

There exists a range of different time representations and many rules
for calculation and exceptions to these rules. We are not going to
discuss all the different methods of time conversions but focus on one
of the simpler solutions: <em>Universal Time</em>(UT). UT is based on
the elapsed time since January 1, 1970, 00:00:00 GMT. <br/><br/> 

Javas own <slink role="mentions"
href="java/util/Date">java.util.Date</slink> class uses milliseconds
to store the elapsed time, in this example we are going to use seconds
instead.<br/><br/> 

The following sections will first describe the structure of the class
and secondly the methods used for doing the actual time
conversion.<br/><br/> 
    </section>

    <section sbase="ugeopgave/Date">
      <title>Class structure</title>
     
The <slink role="mentions" href="">Date</slink> class stores the UT
seconds in the <slink role="describes" href="@ut">ut</slink> field.  This
field can be set either through the class single parameter <slink
role="describes" href="@Date(long)">constructor</slink> or via the <slink
role="describes" href="@setUT(long)">setUT(long)</slink>
method.<br/><br/> 
     
Whenever the <slink role="mentions" href="@ut">ut</slink> field is set,
each part of the time is calculated. The method used for the
calculation is described <dlink role="mentions" href="/Time.edoc@conversionmethod">later</dlink>. Each part is stored in a slot
and this is described in the following <dlink role="mentions"
href="/Time.edoc@slots">section</dlink>. 

    <section label="slots">
      <title>Slots</title>
We use slots to store each interesting item of a <em>time</em>. A slot
is just a plain <em>long</em> and all slots are stored in the <slink
role="describes" href="@slots">slots</slink> field.<br/><br/> 

The <code>slots</code> array contain currently five items. These are
      listed here with their corresponding value intervals. 
      <slink role="describes" href="@YEAR">YEAR</slink> [1970..292278994]),
      <slink role="describes" href="@MONTH">MONTH</slink> [1..12],
      <slink role="describes" href="@DAY">DAY</slink> [1..31],
      <slink role="describes" href="@HOUR">HOUR</slink> [0..23],
      <slink role="describes" href="@MINUTE">MINUTE</slink> [0..59] and
      <slink role="describes" href="@SECONDS">SECONDS</slink> [0.59].<br/><br/>
     
The slots array is used to have each item pre-calculated.  This
     removes the need for recalculation when each item of the time is
     accessed via the <slink role="describes"
     href="@e:slotgetset">get-methods</slink>.  
     In a larger industrial application it probably will be more
     important to be able to write the human readable format for the
     time instead of the elapsed seconds since 1970. The
     "slot-solution" would be the best solution for this as the
     readable format is straightforward to extract. A more complete
     example of such an implementation is in the <xlink href=" http://www.javasoft.com/j2se/1.3/docs/api/java/util/Date.html">standard Java
     API</xlink><br/><br/>
     
     The disadvantage is the need for extra storage, but this is not
     an issue for this example. If only the elapsed seconds is needed
     in an application a solution is to just store the UT in a simple
     long and use the date class when it is needed to present the date
     in readable form.<br/><br/>
    </section>

    <section label="conversionmethod">
      <title>Conversion method</title>
      The conversion from UT(elapsed seconds) to a representation
      with year, month, day, hour, minute and seconds is handled by
      <slink role="describes" href="@calcTime()">calcTime()</slink>.<br/><br/>

      To convert from elapsed seconds to each part of the time can be done
      either through a formula or via succesive
      counting. A formula is most efficient but can be hard to
      comprehend, successive counting is just the opposite - not so
      efficient, but easier to comprehend.<br/><br/>

      We are going to use both methods, calculation for the simplest
      issues and successive counting for the rest.<br/><br/>

      The general strategy is to start with the total elapsed seconds
      and then subtract the seconds for each item in the time. We
      start out by calculating the <slink role="mentions"
      href="@calcTime()@e:a">year</slink> and the remainding
      seconds. From the seconds and year we calculate the exact <slink
      role="mentions" href="@calcTime()@e:b">day and
      month</slink> and from the last remaining seconds <slink role="mentions" href="@calcTime()@e:c">hour, minute
      and seconds</slink> is calculated.<br/><br/>

      After each calculation the relevant item is stored in their
      respective location, in the <slink role="mentions"
      href="@slots">slots</slink> field, which is described <dlink role="mentions" href="/Time.edoc@slots">else where</dlink>. 
      <br/><br/>

      The internal details of the different calculations is described
      in their own section, 
      <dlink role="mentions" href="/Time.edoc@year">year</dlink>, 
      <dlink role="mentions" href="/Time.edoc@daymonth">day/month</dlink>,
      <dlink role="mentions" href="/Time.edoc@hourminsec">hour/minute/seconds</dlink>.
    </section>

    <section label="year">
      <title>Year</title>
        To calculate which year a given UT time occur in the <slink
        role="describes" href="@calcYear(long)">calcYear(long)</slink> method
        uses successive counting.<br/><br/>
        
        It starts out with the <slink role="describes"
        href="@BASE_YEAR">base year</slink> and <slink role="mentions" href="@calcYear(long)@e:b">succesivly adds</slink>
        the number of seconds for the year in the loop until it ends
        up with <slink role="mentions" href="@calcYear(long)@e:a">less seconds</slink> than the next year contains.<br/><br/>

        The length of a given year is returned by the method <slink
        role="describes" href="@yearLength(long)">yearLength(long)</slink>,
        which check if the year is a <dlink role="mentions" href="/Time.edoc@leapyear">leap
        year</dlink> and returns the correct amount of seconds.
    </section>

    <section label="leapyear">
      <title>Finding leap year</title>
       To handle leap years, we have the method <slink role="describes"
       href="@isLeapYear(long)">isLeapYear(long)</slink>.          
       <br/><br/>

       The method returns true if <code>year</code> is a leap year
       and false otherwise.
       <br/><br/>

       It uses the following rules:<br/>
       A year is only a leap year if it is divisible with 4 and
       not divisible by 100. An exception to this rule is that if the
       year is divisible by 400 it <em>is</em> a leap year.
       <br/><br/>
    </section>
    </section>

    <section label="daymonth" sbase="ugeopgave/Date">
      <title>Month and day</title>
        To find the month and day we have the method       
        <slink role="describes" href="@calcDayAndMonth(long,long)">calcDayAndMonth</slink>.
        This method receives the number of seconds elapsed since 1. January of the relevant year.
        Hence the number of the actual day is relatively easy to calculate by 
        <slink role="describes" href="@calcDayAndMonth(long,long)@e:div">division</slink> 
        of a normal day length.<br/>
        
        The remaining seconds are saved and is later returned by this method.<br/><br/>
        
        The exact month is found by using a pre-calculated array that
        contains <slink role="describes"
        href="@calcDayAndMonth(long,long)@numOfDays">number of
        days</slink> passed since the first in each of the twelve
        months. There are two pre-calculated arrays, one for <slink
        role="describes" href="@MONTH_LENGTHS">regular months</slink>  and
        another for <slink role="describes" href="@LEAP_MONTH_LENGTHS">leap-year months</slink>.<br/><br/>

        By <slink role="describes"
        href="@calcDayAndMonth(long,long)@e:search">searching
        through</slink> this array a month is found. The actual
        day in the month can be calculated by 
        <slink role="describes" href="@calcDayAndMonth(long,long)@e:subtract">subtracting</slink>
        the days stored in the found months entry in the array.<br/><br/>
        
        Note, we add 1 to the actual day as the calculation is
        based on the first day being 0(zero) and we want to deliver the result in the range from 1 to 31. 
    </section>


    <section label="hourminsec" sbase="ugeopgave/Date">
      <title>Hour, minute and second</title>
         The <slink role="describes"
        href="@calcHourMinuteSeconds(long)">calcHourMinuteSeconds(long)</slink>
        method receives the number of seconds elapsed in the day.

        The last parts of the time is easily calculated via division and modulo.<br/><br/>

        First we divide the seconds with the length of an hour to get
        the 
        <slink role="mentions" href="@calcHourMinuteSeconds(long)@e:a">correct hour</slink>. 

        The 
        <slink role="mentions" href="@calcHourMinuteSeconds(long)@e:b">remainder</slink> of this division is found by
        modulo and this is used to find the <slink role="mentions" href="@calcHourMinuteSeconds(long)@e:c">minute-number</slink> by dividing
        with the length of a minute.
        The 
        <slink role="mentions" href="@calcHourMinuteSeconds(long)@e:d">remainder</slink> of this division is finally stored as the 
        <slink role="mentions" href="@calcHourMinuteSeconds(long)@e:e">second-number</slink>.
    </section>

    <section sbxase="ugeopgave/Date">
      <title>Miscellaneous</title>
      <!-- The topic must characterize and introduce the thematic contents of -->
      This section contains some miscellaneous issues concerning the class.<br/><br/>

      <b>Further work</b><br/>
      The class can be extended with much more functionality, e.g. the reverse conversion would be highly relevant.
      If the class should be used to keep track of time it would be beneficial to look at issues such as timezones,
      leap-seconds, Gregorian vs. Julian calendar, etc.<br/><br/>

      <b>Test</b><br/>
      There also exist a class that <slink role="describes" href="ugeopgave/DateTest">tests</slink> the conversion and
      compares it with the <slink role="mentions" href="java/util/Date">standard Date class</slink> in Java. This
      test uses the <slink role="mentions" href="ugeopgave/Date@toString()">toString()</slink> to produce a more human readable format.<br/><br/>

      <b>JavaDoc</b><br/>
      To get a better overview of the class the automatically generated 
      <xlink href="http://dopu.cs.auc.dk/data/maxtime/ugeopgave/apidoc/">JavaDoc</xlink> is a good place to start.
    </section>

</enode>
</edoc>

<!-- Final comment -->