"

 COPYRIGHT (c) 1989 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' }"

AbstractTime subclass:#AbsoluteTime

	instanceVariableNames:'osTime'

	classVariableNames:''

	poolDictionaries:''

	category:'Magnitude-General'

!

!AbsoluteTime class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1989 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 class represents absolute time values in milliSeconds starting some

    time in the past. 

    (typically, from 1st. Jan 1970, as used in the Unix operating system,

     but other systems may bias the time differently.

     Actually, the implementation does not depend or even know which time/date 

     the OperatingSystem bases its time upon - it is simply keeping the value(s)

     as returned from the OS.

     For conversion, these values are given back to the OS, which will know

     how to convert these times. This has the advantage, that timestamps on files 

     (such as last-access-time or last-modification-time) can be handled transparently - 

     especially when performing comparisons).

    You should not interpret the osTime instance variable directly, instead

    (if at all), ask the OS to convert.

    The implementation of this class is not the same as in ST-80 

    (which represents the time as seconds from Jan 1., 1901).

    This class should not be confused with Time (which only represents the

    time within one day). Time instances cannot be used to compare times across midnight; 

    instances of AbsoluteTime can.

    Notice: this class is aliased as Timestamp for ST-80 compatibility.

    [author:]

        Claus Gittinger

    [See also:]

        Time Date

        Delay ProcessorScheduler

"

! !

!AbsoluteTime class methodsFor:'instance creation'!

UTCYear:y month:m day:d hour:h minute:min second:s millisecond:millis

    "return an instance of the receiver, given individual components.

     See also `AbsoluteTime now' and other protocol inherited

     from my superclass."

    ^ self basicNew 

	fromOSTime:(OperatingSystem 

			computeOSTimeFromUTCYear:y month:m day:d 

					 hour:h minute:min second:s

					 millisecond:millis)

    "

     AbsoluteTime UTCYear:1970 month:1 day:1 hour:1 minute:0 second:0 millisecond:0

     AbsoluteTime UTCYear:1991 month:1 day:2 hour:12 minute:30 second:0 millisecond:0

     AbsoluteTime UTCYear:1991 month:1 day:2 hour:12 minute:30 second:0 millisecond:100

     AbsoluteTime UTCYear:1999 month:7 day:1 hour:1 minute:0 second:0 millisecond:0

     AbsoluteTime UTCYear:2000 month:1 day:1 hour:1 minute:0 second:0 millisecond:0

    "

    "Modified: / 1.7.1996 / 15:22:07 / cg"

    "Created: / 13.7.1999 / 12:34:37 / stefan"

    "Modified: / 13.7.1999 / 12:42:30 / stefan"

!

basicReadFrom:aStringOrStream

    "return a new AbsoluteTime, reading a printed representation from aStream.

     The string is interpreted as 24 hour format, as printed.

     Notice, that this is not the storeString format and 

     is different from the format expected by readFrom:.

     KLUDGE: 

        us and non-us format have different ordering of day and month;

        The format read here is (non-us) dd-mm-yyyy hh:mm:ss.iii

        or (us-format, for Travis) mm/dd/yyyy hh:mm:ss.iii.

     On error, raise an exception"

    |str first second day month year hour min sec millis usFormat|

    str := aStringOrStream readStream.

    first := Integer readFrom:str.

    first > 31 ifTrue:[

        "/ assume iso8601 format;

        ^ self readIso8601FormatFrom:str yearAlreadyRead:first.

    ].

    "/ consider this a kludge

    usFormat := (str peek == $/ ).

    [str peek isDigit] whileFalse:[str next].

    second := Integer readFrom:str.

    usFormat ifTrue:[

        month := first.

        day := second.

    ] ifFalse:[

        month := second.

        day := first.

    ].

    (day between:1 and:31) ifFalse:[ ConversionError raiseErrorString:'bad day' ].

    (month between:1 and:12) ifFalse:[ ConversionError raiseErrorString:'bad month' ].

    [str peek isDigit] whileFalse:[str next].

    year := Integer readFrom:str.

    [str peek isDigit] whileFalse:[str next].

    hour := Integer readFrom:str.

    (hour between:0 and:24) ifFalse:[ ConversionError raiseErrorString:'bad hour' ].

    [str peek isDigit] whileFalse:[str next].

    min := Integer readFrom:str.

    (min between:0 and:59) ifFalse:[ ConversionError raiseErrorString:'bad minute' ].

    str atEnd ifTrue:[

        sec := millis := 0.

    ] ifFalse:[

        [str peek isDigit] whileFalse:[str next].

        sec := Integer readFrom:str.

        (sec between:0 and:59) ifFalse:[ ConversionError raiseErrorString:'bad second' ].

        str peek = $. ifTrue:[

            str next.

            millis := Integer readFrom:str.

            millis >= 1000 ifTrue:[ ConversionError raiseErrorString:'bad millisecond' ].

        ] ifFalse:[

            millis := 0.

        ].

    ].

    "special check - only 24:00:00 is allowed;

     every time after that must wrap"

    hour == 24 ifTrue:[

        (min ~~ 0 or:[sec ~~ 0 or:[millis ~~ 0]]) ifTrue:[ ConversionError raiseErrorString:'bad hour' ].

    ].

    ^ self year:year month:month day:day hour:hour minute:min second:sec millisecond:millis.

    "

     AbsoluteTime basicReadFrom:'20-2-1995 13:11:06'    

     (AbsoluteTime basicReadFrom:'10-9-1995 13:11:06') month   

     (AbsoluteTime basicReadFrom:'10/9/1995 13:11:06') month   

     AbsoluteTime basicReadFrom:'20-2-1995 13:11'       

     AbsoluteTime basicReadFrom:'20-2-1995 13:11:06.100'    

     AbsoluteTime basicReadFrom:'32-2-1995 13:11:06.100'  

     AbsoluteTime basicReadFrom:'32-foo-1995 13:11:06.100' 

     AbsoluteTime basicReadFrom:'20-13-1995 13:11:06.100'   

     AbsoluteTime basicReadFrom:'20-12-1995 25:11:06.100'   

     AbsoluteTime basicReadFrom:'20-12-1995 23:61:06.100'   

     AbsoluteTime basicReadFrom:'20-12-1995 23:10:66.100'   

     AbsoluteTime basicReadFrom:'20-12-1995 23:10:00.1000'   

     AbsoluteTime basicReadFrom:'20-2-1995 24:01:00.100' 

     AbsoluteTime basicReadFrom:'20-2-1995 24:00:01.100' 

     AbsoluteTime basicReadFrom:'foo'                    

     AbsoluteTime basicReadFrom:(AbsoluteTime now printString)                  

     AbsoluteTime basicReadFrom:'1995-10-20 24:00:00.000' 

     AbsoluteTime basicReadFrom:'1995-10-20 12:10:00.000' 

    "

!

day:d month:m year:y hour:h minutes:min seconds:s

    "This is obsolete. User #year:month:day:hour:minute:second:"

    ^ self 

	year:y month:m day:d hour:h 

	minute:min second:s millisecond:0

    "

     AbsoluteTime day:2 month:1 year:1991 hour:12 minute:30 second:0 

     AbsoluteTime day:8 month:1 year:1995 hour:0 minute:43 second:48 

    "

    "Modified: / 1.7.1996 / 15:22:26 / cg"

    "Modified: / 13.7.1999 / 12:29:56 / stefan"

!

day:d month:m year:y hour:h minutes:min seconds:s milliseconds:millis

    "This is obsolete. User #year:month:day:hour:minute:second:millisecond:"

    ^ self year:y month:m day:d hour:h minute:min second:s millisecond:millis

    "

     AbsoluteTime day:1 month:1 year:1970 hour:1 minute:0 second:0 

     AbsoluteTime day:2 month:1 year:1991 hour:12 minute:30 second:0 

     AbsoluteTime day:2 month:1 year:1991 hour:12 minute:30 second:0 millisecond:100

    "

    "Created: / 1.7.1996 / 14:46:09 / cg"

    "Modified: / 1.7.1996 / 15:22:07 / cg"

    "Modified: / 13.7.1999 / 12:30:26 / stefan"

!

decodeFromLiteralArray:anArray

    "decode an AbsoluteTime literalArray.

     anArray may be:

        #(AbsoluteTime '200004182000.123')

     or the deprecated old format, that is not portable between different architectures.

     We parse this for backward compatibility (will be eventually removed).

        #(AbsoluteTime #osTime: 12345678)     

    "

    (anArray at:2) == #osTime: ifTrue:[

        ^ self new osTime:(anArray at:3).

    ].

    ^ self readGeneralizedFrom:(anArray at:2) onError:[self error:'literal array decoding']

!

fromDate:aDate andTime:aTime

    "return an instance of the receiver, initialized from a time and a date

     object.

     See also `AbsoluteTime now' and other protocol inherited

     from my superclass."

    ^ self 

	year:aDate year 

	month:aDate month 

	day:aDate day 

	hour:aTime hours 

	minute:aTime minutes 

	second:aTime seconds 

    "

     AbsoluteTime fromDate:(Date today) andTime:(Time now)  

     AbsoluteTime fromDate:(Date today plusDays:1) andTime:(Time now) 

     AbsoluteTime now 

    "

    "Modified: / 8.9.1995 / 15:07:30 / claus"

    "Modified: / 19.4.1996 / 15:25:46 / cg"

    "Modified: / 13.7.1999 / 12:30:47 / stefan"

!

newDay:dayInYear year:year

    "return a new AbsoluteTime, given the year and the day-in-year (starting at 1).

     Date protocol compatibility"

    ^ (Date newDay:dayInYear year:year) asAbsoluteTime

    "

     AbsoluteTime newDay:183 year:1996

    "

    "Modified: 2.7.1996 / 09:39:30 / cg"

!

readFrom:aStringOrStream onError:exceptionBlock

    "return a new AbsoluteTime, reading a printed representation from aStream.

     The string is interpreted as 24 hour format, as printed.

     Notice, that this is not the storeString format and 

     is different from the format expected by readFrom:.

     The format read here is dd-mm-yyyy hh:mm:ss.iii"

    |newTime|

    Error handle:[:ex |

        ^ super readFrom:aStringOrStream onError:exceptionBlock 

    ] do:[

        newTime := self basicReadFrom:aStringOrStream.

    ].

    ^ newTime

    "

     AbsoluteTime readFrom:'20-2-1995 13:11:06'                            

     AbsoluteTime readFrom:'20-2-1995 13:11'                               

     AbsoluteTime readFrom:'20-2-2001 13:11'                               

     AbsoluteTime readFrom:'20-2-1995 13:11:06.100'                        

     AbsoluteTime readFrom:'32-2-1995 13:11:06.100' onError:'wrong'        

     AbsoluteTime readFrom:'32-foo-1995 13:11:06.100' onError:'wrong'      

     AbsoluteTime readFrom:'20-2-1995 24:01:00.100' onError:'wrong'        

     AbsoluteTime readFrom:'20-2-1995 24:00:01.100' onError:'wrong'        

     AbsoluteTime readFrom:'2002-08-02 24:00:01.100' onError:'wrong'        

     AbsoluteTime readFrom:'foo' onError:'wrong'                           

     AbsoluteTime readFrom:(AbsoluteTime now storeString) onError:'wrong'                     

    "

    "Modified: / 8.10.1996 / 19:25:59 / cg"

    "Modified: / 13.7.1999 / 12:31:14 / stefan"

!

readGeneralizedFrom:aStringOrStream onError:exceptionBlock

    "return a new AbsoluteTime, reading a printed representation from aStream.

     The string is interpreted as 24 hour format, as printed.

     Notice, that this is not the storeString format and 

     is different from the format expected by readFrom:.

     The format read here is yyyymmddHHMMSS.iii+uuuu,

     which is the ASN1 GeneralizedTime format."

    |newTime|

    ^ [

        |str day month year hour min sec millis c|

        sec := millis := 0.

        str := aStringOrStream readStream.

        year := Integer readFrom:(str next:4).

        month := Integer readFrom:(str next:2).

        (month between:1 and:12) ifFalse:[^ exceptionBlock value].

        day := Integer readFrom:(str next:2).

        (day between:1 and:31) ifFalse:[^ exceptionBlock value].

        hour:= Integer readFrom:(str next:2).

        (hour between:0 and:24) ifFalse:[^ exceptionBlock value].

        min:= Integer readFrom:(str next:2).

        (min between:0 and:59) ifFalse:[^ exceptionBlock value].

        str atEnd ifFalse:[

            sec := Integer readFrom:(str next:2).

            (sec between:0 and:59) ifFalse:[^ exceptionBlock value].

            str peek == $. ifTrue:[

                str next.

                millis := Integer readFrom:str.

            ].

        ]. 

        str atEnd ifTrue:[

            "/ this is local time

            newTime := self year:year month:month day:day 

                              hour:hour minute:min second:sec millisecond:millis.

        ] ifFalse:[

            c := str next.

            c ~~ $Z ifTrue:[ |tzh tzmin|

                tzh := Integer readFrom:(str next:2).

                tzmin := Integer readFrom:(str next:2).

                c == $+ ifTrue:[

                    "/ add hours and minutes

                    hour := hour + tzh.

                    min := min + tzmin.

                ] ifFalse:[

                    c ~~ $- ifTrue:[

                       self error:'bad time offset'.

                    ].

                    "/ subtract hours and minutes

                    hour := hour - tzh.

                    min := min - tzmin.

                ].

            ].

            "/ this is UTC time

            newTime := self UTCYear:year month:month day:day 

                              hour:hour minute:min second:sec millisecond:millis.

        ].

        newTime

    ] on:Error do:exceptionBlock.

    "

     |s|

     s := '' writeStream.

     AbsoluteTime now printGeneralizedOn:s.

     AbsoluteTime readGeneralizedFrom:s contents onError:[]

     AbsoluteTime readGeneralizedFrom:'20001018000000+0200' onError:[]

     AbsoluteTime readGeneralizedFrom:'20001018000000+0300' onError:[]

     AbsoluteTime readGeneralizedFrom:'20000202000000+0100' onError:[]

     AbsoluteTime readGeneralizedFrom:'20000202000000+0200' onError:[]

     AbsoluteTime readGeneralizedFrom:'19950220131106' onError:[]   

     AbsoluteTime readGeneralizedFrom:'199502201311' onError:[]    

     AbsoluteTime readGeneralizedFrom:'19950220131106.100' onError:[]    

     AbsoluteTime readGeneralizedFrom:'19950232131106.100' onError:'wrong'    

     AbsoluteTime readGeneralizedFrom:'19950fo2131106.100' onError:'wrong'    

     AbsoluteTime readGeneralizedFrom:'foo' onError:'wrong'                     

    "

    "Modified: / 8.10.1996 / 19:25:59 / cg"

    "Modified: / 13.7.1999 / 12:31:14 / stefan"

!

readIso8601FormatFrom:aStringOrStream

    "return a new AbsoluteTime, reading an iso8601 UTC representation from aStream.

     Missing month/day values are replaced with 1; i.e. 1999T24:00

     is the same as 1999-01-01T24:00:00.

     Missing minute, second and ms values are replaced with 0;

     i.e. 1999T12 is the same as 1999-01-01T12:00:00.000.

     Of course, a 24 hour clock is used.

     On error, raise an exception.

     Please use this format for all external representations - its the standard."

    ^ self

        readIso8601FormatFrom:aStringOrStream yearAlreadyRead:nil

    "

     AbsoluteTime readIso8601FormatFrom:'1995-02-20T13:11:06'    

     AbsoluteTime readIso8601FormatFrom:'1995-02T13:11:06'     

     AbsoluteTime readIso8601FormatFrom:'1995T13:11:06'        

     AbsoluteTime readIso8601FormatFrom:'1995T13:11'           

     AbsoluteTime readIso8601FormatFrom:'1995T13'              

     AbsoluteTime readIso8601FormatFrom:'1995'              

     AbsoluteTime readIso8601FormatFrom:'1995-02-20 13:11:06'    

     AbsoluteTime readIso8601FormatFrom:'1995-02-20 13:11'    

     AbsoluteTime readIso8601FormatFrom:'1995-02-20 13'    

   24 is allowed with ISO, and is 00:00 of the next day:

     AbsoluteTime readIso8601FormatFrom:'1995-02-20 24:00:00'    

    "

!

readIso8601FormatFrom:aStringOrStream yearAlreadyRead:yearOrNil

    "common helper for read methods.

     Return a new AbsoluteTime, reading an iso8601 UTC representation from aStream.

     Missing month/day values are replaced with 1; i.e. 1999T24:00

     is the same as 1999-01-01T24:00:00.

     Missing minute, second and ms values are replaced with 0;

     i.e. 1999T12 is the same as 1999-01-01T12:00:00.000.

     Of course, a 24 hour clock is used.

     On error, raise an exception.

     Please use this format for all external representations - its the standard."

    |str day month year hour min sec millis fraction|

    str := aStringOrStream readStream.

    month := day := 1.

    hour := min := sec := millis := 0.

    yearOrNil notNil ifTrue:[

        year := yearOrNil

    ] ifFalse:[

        year := Integer readFrom:str.

    ].

    str skipSeparators.

    str peek == $- ifTrue:[

        str next.

        "/ month follows.

        month := Integer readFrom:str.

        (month between:1 and:12) ifFalse:[ ConversionError raiseErrorString:'bad month' ].

        str skipSeparators.

        str peek == $- ifTrue:[

            str next.

            "/ day follows.

            day := Integer readFrom:str.

            (day between:1 and:31) ifFalse:[ ConversionError raiseErrorString:'bad day' ].

        ].

    ].

    str skipSeparators.

    str atEnd ifFalse:[

        "time follows"

        str peek == $T ifTrue:[

            "we treat the T as optional here"

            str next.

            str skipSeparators.

        ].

        hour := Integer readFrom:str.

        (hour between:0 and:24) ifFalse:[ ConversionError raiseErrorString:'bad hour' ].

        str skipSeparators.

        str peek == $: ifTrue:[

            str next.

            "/ minutes follow.