(ast "edoc" ((ast "enode" ((ast "head" ((xml-comment "The topic must characterize and introduce the thematic contents of ") "-->" #t (xml-comment "the node, not merely categorize (label) it. The topic should aim ") "-->" #t (xml-comment "to convey positions and results. Topics are more likely to be ") "-->" #t (xml-comment "representative and topically faithful if they are (1) constructed as ") "-->" #t (xml-comment "sentence fragments and (2) rewritten after composition of the node. ") "-->" #t (ast "topic" ("Time Conversion" #t) () double time ()) (xml-comment "The abstract is supposed to be a thematic window into the ") "-->" #t (xml-comment "contents of the node. The abstract must boil down the node body ") "-->" #t (xml-comment "to typicalle 3-5 lines of text. It should expose rationales, results ") "-->" #t (xml-comment "and main characteristics of content of the node. ") "-->" #t (ast "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." (ast "br" () () single time ()) (ast "br" () () single time ()) "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." (ast "br" () () single time ()) (ast "br" () () single time ()) "A test example is provided to illustrate the use of the class." (ast "br" () () single time ()) (ast "br" () () single time ()) "This documentation is to be viewed as an small example of" #t (ast "em" ("Elucidative Programming") () double time ()) "with Java and was part of the week-assignment for the authors DAT5 project exam." (ast "br" () () single time ()) (ast "br" () () single time ())) () double time ()) (xml-comment "The status of the node, being new, inprogress or finished. ") "-->" #t (ast "status" ((ast "new" () () single time ())) () double time ()) (xml-comment "A list of representative keywords for the node. ") "-->" #t (ast "keywords" ((ast "kw" ("Time") () double time ()) (ast "kw" ("Conversion") () double time ()) (ast "kw" ("Elucidative programming") () double time ())) () double time ()) (xml-comment "The name of the author that has last change the node (Will be ") "-->" #t (xml-comment "filled in automatically). ") "-->" #t (ast "author" ("Max Rydahl Andersen and Claus Nyhus Christensen") () double time ()) (ast "created" ("2000/09/12 21:43:32") () double time ()) (ast "last-updated" ("$Date: 2000/09/04 11:55:46 $") () double time ())) () double time ()) (ast "section" ((ast "title" ("Introduction") () double time ()) "This example is based on the" #t (ast "xlink" ("Scheme Time Example") (role "mentions" href "http://www.cs.auc.dk/~normark/elucidative-programming/time-conversion/time/time.html") double time ()) "made by Kurt Noermark." (ast "br" () () single time ()) (ast "br" () () single time ()) "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" #t (ast "slink" ("Date") (role "mentions" href "ugeopgave/Date") double time ()) ", that can be used to store a specifc instance of time and provides an interface to set and get information about the time." (ast "br" () () single time ()) (ast "br" () () single time ()) "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:" #t (ast "em" ("Universal Time") () double time ()) "(UT). UT is based on the elapsed time since January 1, 1970, 00:00:00 GMT." #t (ast "br" () () single time ()) (ast "br" () () single time ()) "Javas own" #t (ast "slink" ("java.util.Date") (role "mentions" href "java/util/Date") double time ()) "class uses milliseconds to store the elapsed time, in this example we are going to use seconds instead." (ast "br" () () single time ()) (ast "br" () () single time ()) "The following sections will first describe the structure of the class and secondly the methods used for doing the actual time conversion." (ast "br" () () single time ()) (ast "br" () () single time ())) () double time ()) (ast "section" ((ast "title" ("Class structure") () double time ()) "The" #t (ast "slink" ("Date") (role "mentions" href "") double time ()) "class stores the UT seconds in the" #t (ast "slink" ("ut") (role "describes" href "@ut") double time ()) "field. This field can be set either through the class single parameter" #t (ast "slink" ("constructor") (role "describes" href "@Date(long)") double time ()) "or via the" #t (ast "slink" ("setUT(long)") (role "describes" href "@setUT(long)") double time ()) "method." (ast "br" () () single time ()) (ast "br" () () single time ()) "Whenever the" #t (ast "slink" ("ut") (role "mentions" href "@ut") double time ()) "field is set, each part of the time is calculated. The method used for the calculation is described" #t (ast "dlink" ("later") (role "mentions" href "/Time.edoc@conversionmethod") double time ()) ". Each part is stored in a slot and this is described in the following" #t (ast "dlink" ("section") (role "mentions" href "/Time.edoc@slots") double time ()) "." #t (ast "section" ((ast "title" ("Slots") () double time ()) "We use slots to store each interesting item of a" #t (ast "em" ("time") () double time ()) ". A slot is just a plain" #t (ast "em" ("long") () double time ()) "and all slots are stored in the" #t (ast "slink" ("slots") (role "describes" href "@slots") double time ()) "field." (ast "br" () () single time ()) (ast "br" () () single time ()) "The" #t (ast "code" ("slots") () double time ()) "array contain currently five items. These are listed here with their corresponding value intervals." #t (ast "slink" ("YEAR") (role "describes" href "@YEAR") double time ()) "[1970..292278994])," #t (ast "slink" ("MONTH") (role "describes" href "@MONTH") double time ()) "[1..12]," #t (ast "slink" ("DAY") (role "describes" href "@DAY") double time ()) "[1..31]," #t (ast "slink" ("HOUR") (role "describes" href "@HOUR") double time ()) "[0..23]," #t (ast "slink" ("MINUTE") (role "describes" href "@MINUTE") double time ()) "[0..59] and" #t (ast "slink" ("SECONDS") (role "describes" href "@SECONDS") double time ()) "[0.59]." (ast "br" () () single time ()) (ast "br" () () single time ()) "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" #t (ast "slink" ("get-methods") (role "describes" href "@e:slotgetset") double time ()) ". 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" #t (ast "xlink" ("standard Java API") (href " http://www.javasoft.com/j2se/1.3/docs/api/java/util/Date.html") double time ()) (ast "br" () () single time ()) (ast "br" () () single time ()) "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." (ast "br" () () single time ()) (ast "br" () () single time ())) (label "slots") double time ()) (ast "section" ((ast "title" ("Conversion method") () double time ()) "The conversion from UT(elapsed seconds) to a representation with year, month, day, hour, minute and seconds is handled by" #t (ast "slink" ("calcTime()") (role "describes" href "@calcTime()") double time ()) "." (ast "br" () () single time ()) (ast "br" () () single time ()) "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." (ast "br" () () single time ()) (ast "br" () () single time ()) "We are going to use both methods, calculation for the simplest issues and successive counting for the rest." (ast "br" () () single time ()) (ast "br" () () single time ()) "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" #t (ast "slink" ("year") (role "mentions" href "@calcTime()@e:a") double time ()) "and the remainding seconds. From the seconds and year we calculate the exact" #t (ast "slink" ("day and month") (role "mentions" href "@calcTime()@e:b") double time ()) "and from the last remaining seconds" #t (ast "slink" ("hour, minute and seconds") (role "mentions" href "@calcTime()@e:c") double time ()) "is calculated." (ast "br" () () single time ()) (ast "br" () () single time ()) "After each calculation the relevant item is stored in their respective location, in the" #t (ast "slink" ("slots") (role "mentions" href "@slots") double time ()) "field, which is described" #t (ast "dlink" ("else where") (role "mentions" href "/Time.edoc@slots") double time ()) "." #t (ast "br" () () single time ()) (ast "br" () () single time ()) "The internal details of the different calculations is described in their own section," #t (ast "dlink" ("year") (role "mentions" href "/Time.edoc@year") double time ()) "," #t (ast "dlink" ("day/month") (role "mentions" href "/Time.edoc@daymonth") double time ()) "," #t (ast "dlink" ("hour/minute/seconds") (role "mentions" href "/Time.edoc@hourminsec") double time ()) "." #t) (label "conversionmethod") double time ()) (ast "section" ((ast "title" ("Year") () double time ()) "To calculate which year a given UT time occur in the" #t (ast "slink" ("calcYear(long)") (role "describes" href "@calcYear(long)") double time ()) "method uses successive counting." (ast "br" () () single time ()) (ast "br" () () single time ()) "It starts out with the" #t (ast "slink" ("base year") (role "describes" href "@BASE_YEAR") double time ()) "and" #t (ast "slink" ("succesivly adds") (role "mentions" href "@calcYear(long)@e:b") double time ()) "the number of seconds for the year in the loop until it ends up with" #t (ast "slink" ("less seconds") (role "mentions" href "@calcYear(long)@e:a") double time ()) "than the next year contains." (ast "br" () () single time ()) (ast "br" () () single time ()) "The length of a given year is returned by the method" #t (ast "slink" ("yearLength(long)") (role "describes" href "@yearLength(long)") double time ()) ", which check if the year is a" #t (ast "dlink" ("leap year") (role "mentions" href "/Time.edoc@leapyear") double time ()) "and returns the correct amount of seconds." #t) (label "year") double time ()) (ast "section" ((ast "title" ("Finding leap year") () double time ()) "To handle leap years, we have the method" #t (ast "slink" ("isLeapYear(long)") (role "describes" href "@isLeapYear(long)") double time ()) "." #t (ast "br" () () single time ()) (ast "br" () () single time ()) "The method returns true if" #t (ast "code" ("year") () double time ()) "is a leap year and false otherwise." #t (ast "br" () () single time ()) (ast "br" () () single time ()) "It uses the following rules:" (ast "br" () () single time ()) "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" #t (ast "em" ("is") () double time ()) "a leap year." #t (ast "br" () () single time ()) (ast "br" () () single time ())) (label "leapyear") double time ())) (sbase "ugeopgave/Date") double time ()) (ast "section" ((ast "title" ("Month and day") () double time ()) "To find the month and day we have the method" #t (ast "slink" ("calcDayAndMonth") (role "describes" href "@calcDayAndMonth(long,long)") double time ()) ". 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" #t (ast "slink" ("division") (role "describes" href "@calcDayAndMonth(long,long)@e:div") double time ()) "of a normal day length." (ast "br" () () single time ()) "The remaining seconds are saved and is later returned by this method." (ast "br" () () single time ()) (ast "br" () () single time ()) "The exact month is found by using a pre-calculated array that contains" #t (ast "slink" ("number of days") (role "describes" href "@calcDayAndMonth(long,long)@numOfDays") double time ()) "passed since the first in each of the twelve months. There are two pre-calculated arrays, one for" #t (ast "slink" ("regular months") (role "describes" href "@MONTH_LENGTHS") double time ()) "and another for" #t (ast "slink" ("leap-year months") (role "describes" href "@LEAP_MONTH_LENGTHS") double time ()) "." (ast "br" () () single time ()) (ast "br" () () single time ()) "By" #t (ast "slink" ("searching through") (role "describes" href "@calcDayAndMonth(long,long)@e:search") double time ()) "this array a month is found. The actual day in the month can be calculated by" #t (ast "slink" ("subtracting") (role "describes" href "@calcDayAndMonth(long,long)@e:subtract") double time ()) "the days stored in the found months entry in the array." (ast "br" () () single time ()) (ast "br" () () single time ()) "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." #t) (label "daymonth" sbase "ugeopgave/Date") double time ()) (ast "section" ((ast "title" ("Hour, minute and second") () double time ()) "The" #t (ast "slink" ("calcHourMinuteSeconds(long)") (role "describes" href "@calcHourMinuteSeconds(long)") double time ()) "method receives the number of seconds elapsed in the day. The last parts of the time is easily calculated via division and modulo." (ast "br" () () single time ()) (ast "br" () () single time ()) "First we divide the seconds with the length of an hour to get the" #t (ast "slink" ("correct hour") (role "mentions" href "@calcHourMinuteSeconds(long)@e:a") double time ()) ". The" #t (ast "slink" ("remainder") (role "mentions" href "@calcHourMinuteSeconds(long)@e:b") double time ()) "of this division is found by modulo and this is used to find the" #t (ast "slink" ("minute-number") (role "mentions" href "@calcHourMinuteSeconds(long)@e:c") double time ()) "by dividing with the length of a minute. The" #t (ast "slink" ("remainder") (role "mentions" href "@calcHourMinuteSeconds(long)@e:d") double time ()) "of this division is finally stored as the" #t (ast "slink" ("second-number") (role "mentions" href "@calcHourMinuteSeconds(long)@e:e") double time ()) "." #t) (label "hourminsec" sbase "ugeopgave/Date") double time ()) (ast "section" ((ast "title" ("Miscellaneous") () double time ()) (xml-comment "The topic must characterize and introduce the thematic contents of ") "--> This section contains some miscellaneous issues concerning the class." (ast "br" () () single time ()) (ast "br" () () single time ()) (ast "b" ("Further work") () double time ()) (ast "br" () () single time ()) "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." (ast "br" () () single time ()) (ast "br" () () single time ()) (ast "b" ("Test") () double time ()) (ast "br" () () single time ()) "There also exist a class that" #t (ast "slink" ("tests") (role "describes" href "ugeopgave/DateTest") double time ()) "the conversion and compares it with the" #t (ast "slink" ("standard Date class") (role "mentions" href "java/util/Date") double time ()) "in Java. This test uses the" #t (ast "slink" ("toString()") (role "mentions" href "ugeopgave/Date@toString()") double time ()) "to produce a more human readable format." (ast "br" () () single time ()) (ast "br" () () single time ()) (ast "b" ("JavaDoc") () double time ()) (ast "br" () () single time ()) "To get a better overview of the class the automatically generated" #t (ast "xlink" ("JavaDoc") (href "http://dopu.cs.auc.dk/data/maxtime/ugeopgave/apidoc/") double time ()) "is a good place to start." #t) (sbxase "ugeopgave/Date") double time ())) (role "essay") double time ())) () double time ())