Date and Time are important notions (mainly for commercial applications). They both are "absolute" values (Albert Einstein's theory will not be evaluated here) and are called timestamps. The interval between two subsequent timestamps is a relative temporal value called "duration". The library allows to manipulate with all these objects reflecting the desired accuracy.
The term "duration" must be refined to be useful. How this refinement is performed depends on the actual application. So it may be interesting to count DURATION in years or in picoseconds - this depends from the individual whose age you are measuring. It may be a crocodile or an atomic particle. We choose the terms LONG_DURATION to measure days and longer durations (it is sometimes not necessary to count the seconds) and SHORT_DURATION to measure seconds. Note that SHORT_DURATION can be used for time spans longer than one day - it just delivers seconds and fractions of seconds - maybe even negative values.
It is meaningless to mix short and long durations, e.g., it makes no sense to add a LONG_DURATION and a SHORT_DURATION as the long value has not enough precision. In contrast, adding two SHORT_DURATIONs or two LONG_DURATIONs as well DURATION with SHORT_DURATION has an acceptable semantics. But DURATION can not be incremented by LONG_DURATION.
The class DURATION itself delivers most informations you can imagine about - if you need more, you should supply your own class. The top class in the hierarchy of "duration" classes is SIMPLE_DURATION.
The library provides two basic classes:
TIMESTAMP itself inherits both from both DATE and TIME and contains all time information.
From the first sight, it seems problematic to use TIME class as day time starts counting at midnight. Nevertheless objects of this class can be useful as our daily experience proves.
Class DATE implements the Julian calendar for dates before October 4, 1582 and the Gregorian calendar after that date (i.e. since October 15, 1582).
The Julian calendar was introduced by Julius Caesar in 46 B.C. It defines a year as having an average length of 365¼ days. This is achieved by leap years that have 366 days while common years have 365 days. Every fourth year is considered leap. This calendar suffer from inaccuracies because a sigle revolution of the earth around the sun takes slightly less time than 365¼ days.
The problem was fixed by Pope Gregory XIII in 1582. He decided to trim extra days counted by Julian calendar by 10 and refine the definition of leap years. So October 4, 1582 was followed by October 15, 1582. Since then all years evenly divisible by 4 are leap except those that are evenly divisible by 100 and not divisible by 400. The calendar was named Gregorian.
The Gregorian calendar was not immediately adopted in all the countries, so before you use past date, you should check in which style it is given.
To avoid the problems with different calendars, there is a notion of Julian days. They were introduced by the monk who started the counting since January 1, 4713 B.C. The days were called after his father Julius, so they should not be confused with Julian calendar. By convention, October 15, 1582 is generally accepted as Julian day 2_299_161.
The simplest way to use the cluster is to rely on 3 classes: DURATION, TIMESTAMP and TIME_TOOLS. They cover most requirements.
The classes provide a uniform interface to calculate relations between two timestamps. This is achieved by the representation of time in milliseconds and date in Julian days.
Durations are intervals between two timestamps. They can even be negative. In this case all queries return values that are less than or equal to zero. For example, the difference between two dates may result into the following result:
1994/ 12/ 10 1994/ 12/ 10 - 1995/ 12/ 10 - 1995/ 12/ 1 ----------------------------------- = -1/ 0/ 0 = 0/-11/-21
Some additional features that has no relation to the specific date or time value can be found in the class TIME_TOOLS. For example, it contains a definition of the days of the week.
It is also possible to define proper descendants of the class TIME_TOOLS. In this way the following classes are defined: FRENCH_TIME_TOOLS, GERMAN_TIME_TOOLS, RUSSIAN_TIME_TOOLS.
a, b, c: TIMESTAMP d, e: DURATION t: TIME_TOOLS i: INTEGER; da, db: DATE; xl: LONG_DURATION do !! b.set_to_now -- today !! a.set (b.year, 1, 1, 0, 0, 0) -- begin of this year d := b.difference (a) -- calculate duration print (d.as_hours) -- number of hours until now print (d.as_days) -- number of days -- -- -- -- -- -- -- !! d.set_from_compressed (7, 0) -- one week print (b) -- print the date of the day prnt (b.plus (d)) -- exactly one week later prnt (b.plus (d.multiply_by (4))) -- exactly four weeks later prnt (b.minus (d.multiply_by (4))) -- exactly four weeks before -- measuring some activities !! a.set_to_now -- .. -- do first activity (x seconds) !! b.set_to_now -- .. -- do second activity (y seconds) !! c.set_to_now d := b.difference (a) e := c.difference (b) print (d.as_seconds) -- numbers of seconds for -- result is x -- the first activity print (e.ratio (d)) -- and the ratio between -- result is y/x -- the two activities -- -- -- -- -- -- -- !! b.set_to_now print ("%Nb= " + b.day.out + b.month.out + b.year.out) print ("%Na= " + b.hour.out + b.minute.out + b.second.out) -- prnt-ing date & time !! t print ("today is " + t.day_name (b.day_of_week).out) -- another way to calculate the difference between two DATES !! da.set_date (1996, 7, 13) !! db.set_date (1995, 7, 13) i := da.absolute_days - db.absolute_days; print ("%Ni= " + i.out) !! xl.set_days (i) print ("%Nxl= " + xl.out) -- the last two lines can be replaced by: !! xl.set_days (da.absolute_days - db.absolute_days) print ("%Nxl= " + xl.out) -- or more readable by: xl := da.difference (db) print ("%Nxl= " + xl.out)