"

 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:#Timestamp

	instanceVariableNames:'osTime'

	classVariableNames:''

	poolDictionaries:''

	category:'Magnitude-Time'

!

!Timestamp 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 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 Timestamp can.

    Notice: this class was once called AbsoluteTime. Einstein told us in 1905, that talking

    about a absolute time is not a good idea (at least in our universe). So the class

    has been renamed to Timestamp which makes us more compatible to other ST dialects (e.g. VW)

    AbsoluteTime is still kept as an alias for backward compatibility.

    [author:]

        Claus Gittinger

    [See also:]

        Time Date

        Delay ProcessorScheduler

"

! !

!Timestamp class methodsFor:'initialization'!

initialize

    AbsoluteTime := self.       "backward compatibility"

! !

!Timestamp 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 `Timestamp 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)

    "

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

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

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

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

     Timestamp 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"

!

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

    "

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

     Timestamp 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

    "

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

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

     Timestamp 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 Timestamp literalArray.

     anArray may be:

        #(Timestamp '200004182000.123')

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

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

        #(Timestamp #osTime: 12345678)     

    "

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

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

    ].

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

    "

     Timestamp

        decodeFromLiteralArray:#(Timestamp '20050323175226.014')      

    "

!

fromDate:aDate andTime:aTime

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

     object.

     See also `Timestamp 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 

    "

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

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

     Timestamp 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 Timestamp, given the year and the day-in-year (starting at 1).

     Date protocol compatibility"

    ^ (Date newDay:dayInYear year:year) asTimestamp

    "

     Timestamp newDay:183 year:1996

    "

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

!

readFrom:aStringOrStream onError:exceptionBlock

    "return a new Timestamp, 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"

    |stream newTime|

    stream := aStringOrStream readStream.

    Error handle:[:ex |

        newTime := super readFrom:stream onError:exceptionBlock 

    ] do:[

        newTime := self basicReadFrom:stream.

    ].

    ^ newTime

    "

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

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

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

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

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

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

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

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

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

     Timestamp readFrom:'foo' onError:'wrong'                           

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

    "

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

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

!

readGeneralizedFrom:aStringOrStream 

    "return a new Timestamp, 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 either

        yyyymmddHHMMSS.iii+uuuu, which is the ASN1 GeneralizedTime format.

     or:

        yyyy-mm-dd HH:MM:SS.iii +uuuu.

    "

    ^ self readGeneralizedFrom:aStringOrStream onError:[self error:'Timestamp format error'].

    "Created: / 22-08-2006 / 16:05:55 / cg"

!

readGeneralizedFrom:aStringOrStream onError:exceptionBlock

    "return a new Timestamp, 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 either

        yyyymmddHHMMSS.iii+uuuu, which is the ASN1 GeneralizedTime format.

     or:

        yyyy-mm-dd HH:MM:SS.iii +uuuu.

    "

    |newTime|

    ^ [

        |str day month year hour min sec millis c tzDelta|

        sec := millis := 0.

        str := aStringOrStream readStream.

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

        str peek == $- ifTrue:[ str next].

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

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

        str peek == $- ifTrue:[ str next].

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

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

        str skipSeparators.

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

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

        str peek == $: ifTrue:[ str next].

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

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

        str atEnd ifFalse:[

            str peek == $: ifTrue:[ str next].

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

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

            str atEnd ifFalse:[

                str peek == $. ifTrue:[

                    str next.

                    millis := Integer readFrom:str.

                ].

                str skipSeparators.

            ].

        ].

        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:[

                    "the timezone is ahead of UTC or EAST from Greenwich: subtract hours and minutes"

                    hour := hour - tzh.

                    min := min - tzmin.

                ] ifFalse:[

                    c ~~ $- ifTrue:[

                        ^ exceptionBlock value.

                    ].

                    "the timezone is behind of UTC or WEST from Greenwich: add 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.

     Timestamp now printGeneralizedOn:s.

     Timestamp readGeneralizedFrom:s contents onError:[]

 Daylight saving time:

     Timestamp readGeneralizedFrom:'20000718120000Z' onError:[]

     Timestamp readGeneralizedFrom:'20000718120000+0200' onError:[]

     Timestamp readGeneralizedFrom:'20000718120000+0300' onError:[]

 No daylight saving time:

     Timestamp readGeneralizedFrom:'20000202120000Z' onError:[]

     Timestamp readGeneralizedFrom:'20000202120000+0100' onError:[]

     Timestamp readGeneralizedFrom:'20000202120000+0200' onError:[]

     Timestamp readGeneralizedFrom:'19950220131106' onError:[]   

     Timestamp readGeneralizedFrom:'199502201311' onError:[]    

     Timestamp readGeneralizedFrom:'19950220131106.100' onError:[]    

     Timestamp readGeneralizedFrom:'19950232131106.100' onError:'wrong'    

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

     Timestamp readGeneralizedFrom:'foo' onError:'wrong'                     

     Timestamp readGeneralizedFrom:'2000-02-02 12:00:00' onError:[]   

     Timestamp readGeneralizedFrom:'2000-02-02 12:00:00.100' onError:[]

     Timestamp readGeneralizedFrom:'2000-02-02 12:00:00.100 +0100' onError:[] 

     Timestamp readGeneralizedFrom:'2000-02-02 12:00:00 -0100' onError:[]

     Timestamp readGeneralizedFrom:'2000-02-02 12:00:00 +0000' onError:[] 

    "

    "Modified: / 13-07-1999 / 12:31:14 / stefan"

    "Modified: / 22-08-2006 / 12:30:11 / cg"

!

readIso8601FormatFrom:aStringOrStream

    "return a new Timestamp, 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

    "

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

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

     Timestamp readIso8601FormatFrom:'1995T13:11:06'        

     Timestamp readIso8601FormatFrom:'1995T13:11'           

     Timestamp readIso8601FormatFrom:'1995T13'              

     Timestamp readIso8601FormatFrom:'1995'              

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

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

     Timestamp readIso8601FormatFrom:'1995-02-20 13'    

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

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

    "

!

readIso8601FormatFrom:aStringOrStream onError:exceptionValue

    "return a new Timestamp, 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 

        onError:exceptionValue

!

secondsSince1970:sec

    "set time from elapsed seconds since 1-1-1970, 0:0:0.

     This is the format used in the UNIX world"

    |divMod|

    divMod := sec divMod:3600.

    ^ self year:1970 month:1 day:1 hour:(divMod at:1) minute:0 second:(divMod at:2) millisecond:0.

    "

     Timestamp secondsSince1970:0      

     Timestamp secondsSince1970:3600

     Timestamp secondsSince1970:3600*24

    "

    "Created: / 21.10.1996 / 17:48:30 / stefan"

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

!

year:y month:m day:d hour:h minute:min second:s

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

     See also `Timestamp now' and other protocol inherited

     from my superclass."

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

    "

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

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

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

     Timestamp year:2000 month:1 day:1 hour:1 minutes:0 second:0 

    "

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

    "Created: / 13.7.1999 / 12:06:39 / stefan"

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

!

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

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

     See also `Timestamp now' and other protocol inherited

     from my superclass."

    ^ self basicNew 

        fromOSTime:(OperatingSystem 

                        computeOSTimeFromYear:y month:m day:d 

                                         hour:h minute:min seconds:s millis:millis)

    "

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

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

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

     Timestamp year:2000 month:1 day:1 hour:1 minute:0 second:0 

    "

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

    "Created: / 13.7.1999 / 12:28:44 / stefan"

    "Modified: / 13.7.1999 / 12:37:57 / stefan"

! !

!Timestamp class methodsFor:'private'!

basicReadFrom:aStream

    "return a new Timestamp, 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"