"

 COPYRIGHT (c) 1995 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

"{ Package: 'stx:libbasic' }"

Magnitude subclass:#AbstractTime

	instanceVariableNames:''

	classVariableNames:''

	poolDictionaries:''

	category:'Magnitude-General'

!

!AbstractTime class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1995 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

documentation

"

    This is an abstract class providing common protocol for Time (time in day)

    and AbsoluteTime (time plus day).

    There are no instances of this class in the system.

    It is meant as a home for methods common to time handling classes.

    [author:]

        Claus Gittinger

    [See also:]

        Time Date AbsoluteTime

        Delay ProcessorScheduler

"

!

iso8601Format

"

  Abstract

    This document defines a profile of ISO 8601, the International Standard for the representation of dates and times. ISO

    8601 describes a large number of date/time formats. To reduce the scope for error and the complexity of software, it is

    useful to restrict the supported formats to a small number. This profile defines a few date/time formats, likely to satisfy

    most requirements. 

  Formats

    Different standards may need different levels of granularity in the date and time, so this profile defines six levels.

    Standards that reference this profile should specify one or more of these granularities. If a given standard allows more

    than one granularity, it should specify the meaning of the dates and times with reduced precision, for example, the result

    of comparing two dates with different precisions.

    The formats are as follows. Exactly the components shown here must be present, with exactly this punctuation. Note

    that the 'T' appears literally in the string, to indicate the beginning of the time element, as specified in ISO 8601. 

       Year:

          YYYY (eg 1997)

       Year and month:

          YYYY-MM (eg 1997-07)

       Complete date:

          YYYY-MM-DD (eg 1997-07-16)

       Complete date plus hours and minutes:

          YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+01:00)

       Complete date plus hours, minutes and seconds:

          YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00)

       Complete date plus hours, minutes, seconds and a decimal fraction of a

    second

          YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)

    where:

         YYYY = four-digit year

         MM   = two-digit month (01=January, etc.)

         DD   = two-digit day of month (01 through 31)

         hh   = two digits of hour (00 through 23) (am/pm NOT allowed)

         mm   = two digits of minute (00 through 59)

         ss   = two digits of second (00 through 59)

         s    = one or more digits representing a decimal fraction of a second

         TZD  = time zone designator (Z or +hh:mm or -hh:mm)

    This profile does not specify how many digits may be used to represent the decimal fraction of a second. An adopting

    standard that permits fractions of a second must specify both the minimum number of digits (a number greater than or

    equal to one) and the maximum number of digits (the maximum may be stated to be 'unlimited').

    This profile defines two ways of handling time zone offsets:

       1.Times are expressed in UTC (Coordinated Universal Time), with a special UTC designator ('Z'). 

       2.Times are expressed in local time, together with a time zone offset in hours and minutes. A time zone offset of

         '+hh:mm' indicates that the date/time uses a local time zone which is 'hh' hours and 'mm' minutes ahead of

         UTC. A time zone offset of '-hh:mm' indicates that the date/time uses a local time zone which is 'hh' hours and

         'mm' minutes behind UTC. 

    A standard referencing this profile should permit one or both of these ways of handling time zone offsets.

  The ISO8601 printString are generated with:

       Year:

          YYYY (eg 1997)

                Date today printStringFormat:'%(year)'

                AbsoluteTime now printStringFormat:'%(year)'  

       Year and month:

          YYYY-MM (eg 1997-07)

                Date today printStringFormat:'%(year)-%(month)'  

                AbsoluteTime now printStringFormat:'%(year)-%(month)'  

       Complete date:

          YYYY-MM-DD (eg 1997-07-16)

                Date today printStringFormat:'%(year)-%(month)-%(day)'    

                AbsoluteTime now printStringFormat:'%(year)-%(month)-%(day)'  

       Complete date plus hours and minutes:

          YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+01:00)

                AbsoluteTime now printStringFormat:'%(year)-%(month)-%(day)T%h:%m%(TZD)'  

       Complete date plus hours, minutes and seconds:

          YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00)

                AbsoluteTime now printStringFormat:'%(year)-%(month)-%(day)T%h:%m:%s%(TZD)'  

       Complete date plus hours, minutes, seconds and a decimal fraction of a second

          YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)

                AbsoluteTime now printStringFormat:'%(year)-%(month)-%(day)T%h:%m:%s.%(milli2)%(TZD)'  

"

! !

!AbstractTime class methodsFor:'instance creation'!

dateAndTimeNow

    "return an array filled with the current date and time.

     See also: Date today / Time now / AbsoluteTime now."

    ^ Array with:(Date today) with:(Time now)

    "

     Time dateAndTimeNow

    "

    "Modified: 19.4.1996 / 15:23:37 / cg"

!

now

    "return an instance of myself representing this moment."

    ^ self basicNew fromOSTime:(OperatingSystem getOSTime)

    "

     AbsoluteTime now   

     Time now   

    "

    "Modified: 1.7.1996 / 15:20:10 / cg"

! !

!AbstractTime class methodsFor:'Compatibility - VW'!

totalSeconds

    "returns an internal second clock. Dont interpret the returned

     value - if at all, use it to compute time deltas, by subtracting

     returned values."

    ^ self secondClock

! !

!AbstractTime class methodsFor:'private instance creation'!

fromOSTime:osTime

    "return a time, representing the time given by the operatingSystem time.

     Not meant for public use."

    ^ self basicNew fromOSTime:osTime.

    "Modified: 1.7.1996 / 15:09:54 / cg"

!

fromSeconds:seconds

    "return an instance that is constructed from seconds.

     This method is only allowed for second values as returned by

     getSeconds, possibly adding/subtracting to that. 

     Never depend on any specific interpretation of the seconds,

     since it depends on how the OperatingSystem counts time

     (some start at 1900, others with 1970 ...)"

   ^ self basicNew setSeconds:seconds

    "

     Time fromSeconds:0             should return midnight

     AbsoluteTime fromSeconds:0     on UNIX: returns 1st. Jan 1970

                                    on others: dont know

     (AbsoluteTime day:1 month:1 year:1970 hour:1 minutes:0 seconds:0)

        getSeconds                  on UNIX: returns 0

                                    on others: dont know

    "

    "Modified: 1.7.1996 / 13:39:30 / cg"

! !

!AbstractTime class methodsFor:'queries'!

millisecondClockValue

    "return the millisecond clock - since this one overruns

     regularly, use the value only for short timing deltas.

     Also remember that it wraps when comparing these values."

    ^ OperatingSystem getMillisecondTime.

    "

     Time millisecondClockValue 

    "

!

secondClock

    "return seconds of now - for GNU-ST compatibility"

    ^ OperatingSystem getOSTime // 1000

    "

     AbstractTime secondClock    

    "

    "Modified: 1.7.1996 / 15:20:14 / cg"

! !

!AbstractTime class methodsFor:'timing evaluations'!

millisecondsToRun:aBlock

    "evaluate the argument, aBlock; return the number of milliseconds it took"

    |startTime endTime|

    startTime := OperatingSystem getMillisecondTime.

    aBlock value.

    endTime := OperatingSystem getMillisecondTime.

    ^ endTime - startTime

    "

     Time millisecondsToRun:[100 factorial]  

    "

    "Modified: 17.6.1996 / 16:57:37 / cg"

!

secondsToRun:aBlock

    "evaluate the argument, aBlock; return the number of seconds it took"

    |startTime endTime|

    startTime := self secondClock.

    aBlock value.

    endTime := self secondClock.

    ^ endTime - startTime

    "

     Time secondsToRun:[1000 factorial]  

    "

! !

!AbstractTime methodsFor:'abstract'!

hours

    "return the hours (0..23)"

    ^ self subclassResponsibility

    "

     AbsoluteTime now hours 

     Time now hours 

    "

!

milliseconds

    "return the milliseconds (0..999)"

    ^ self subclassResponsibility

    "

     AbsoluteTime now milliseconds 

     Time now milliseconds 

    "

!

minutes

    "return the minutes (0..59)"

    ^ self minutes.

    "

     AbsoluteTime now minutes 

     Time now minutes 

    "

!

seconds

    "return the seconds (0..59)"

    ^ self subclassResponsibility

    "

     AbsoluteTime now seconds 

     Time now seconds 

    "

! !

!AbstractTime methodsFor:'accessing'!

hourInDay

    "return the hours (0..23)"

    ^ self hours

    "

     AbsoluteTime now hourInDay 

     Time now hourInDay 

    "

!

minuteInDay

    "return the minutes (0..59)"

    ^ self minutes.

    "

     AbsoluteTime now minuteInDay 

     Time now minuteInDay 

    "

!

secondInDay

    "return the seconds (0..59)"

    ^ self seconds

    "

     AbsoluteTime now secondInDay 

     Time now seconds 

    "

    "Created: 22.10.1996 / 09:27:47 / stefan"

!

timeZoneDeltaInMinutes

    ^ 0

!

timeZoneName

    ^ 'utc'

!

weekInYear

    "return the week number of the receiver - 1 for Jan, 1st."

    ^ Date weekInYearOf:self

    "

     (AbsoluteTime newDay:1 year:2000) weekInYear    

     (AbsoluteTime newDay:2 year:2000) weekInYear    

     (AbsoluteTime newDay:3 year:2000) weekInYear    

    "

! !

!AbstractTime methodsFor:'arithmetic'!

- aTime

    "return the delta in seconds between 2 times."

    ^ self getSeconds - (aTime getSeconds)

    "

     |t1 t2|

     t1 := AbsoluteTime now.

     (Delay forSeconds:5) wait.

     t2 := AbsoluteTime now.

     Transcript showCR:('seconds passed: ' , (t2 - t1) printString).

    "

!

addDays:numberOfDays

    "return a new instance of myself, numberOfDays afterwards."

    ^ self addSeconds:(numberOfDays * (60 * 60 * 24))

    "

     |t|

     t := AbsoluteTime now.

     Transcript showCR:t.

     Transcript showCR:(t addDays:7)

    "

!

addHours:numberOfHours

    "return a new instance of myself, numberOfHours afterwards."

    ^ self addSeconds:(numberOfHours * (60 * 60))

    "

     |t|

     t := AbsoluteTime now.

     Transcript showCR:t.

     Transcript showCR:(t addHours:12).

    "

    "

     |t|