"

 COPYRIGHT (c) 1989 by Claus Gittinger

 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

!

Object subclass:#TimestampBuilderAbstract

!

Timestamp::TimestampBuilderAbstract subclass:#TimestampISO8601Builder

!

!Timestamp class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1989 by Claus Gittinger

 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.

    When printing and accessing values like #hour,

    the timestamp will be interpreted in the local timezone 

    (as opposed to UtcTimestamp, which presents itself in UTC,

     and as opposed to LocalTimestamp, which remembers the timezone in which it was created).

    The internal representation, osTime, will typically start with 1970-01-01 0:00,

    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.

    Also Note:

        On UNIX, osTime can only hold dates between 1970-01-01T00:00:00Z and 2038-01-19T00:00:00Z

        However, timestamp instances can now hold negative osTime values (which are timestamps

        before 1.1.1970 and greater than 4294967295 (2^32-1) for timestamps after 2038-01-19.

        For dates before 1582 (when calendars were changed from Julian to Grgorian),

        the so called 'proleptic gregorian calendar' is used. This assumes leap years to continue in

        the past as if a gregorian calendar was used. Thus, 0000 is considered a leap year.

    [author:]

        Claus Gittinger

    [See also:]

        UtcTimestamp Time Date

        Delay ProcessorScheduler

"

! !

!Timestamp class methodsFor:'initialization'!

initialize

    AbsoluteTime := self.       "backward compatibility"

    EpochEndOSTime := self epochEnd osTime.

! !

!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,

     interpreted in the UTC timezone."

    ^ self basicNew

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

    "

     Timestamp UTCYear:1970 month:1 day:1 hour:0 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

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

!

decodeFromLiteralArray:anArray

    "decode a 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 conversionErrorSignal

                    raiseErrorString:'literal array decoding' ]

    "

     Timestamp

        decodeFromLiteralArray:#(Timestamp '20050323175226.014')

     Timestamp

        decodeFromLiteralArray:#(Timestamp '20050323175226.014-01')

     Timestamp

        decodeFromLiteralArray:#(Timestamp '20050323175226.014Z')

    "

!

epoch

    "the epoch is based to 0 for 1970-01-01 00:00:00.

     However, we allow negative values to represent timestamps before that"

    Epoch isNil ifTrue:[

        Epoch := UtcTimestamp new setSeconds:0.

    ].

    ^ Epoch

!

epochEnd

    "the epoch is based to 0 for 1970-01-01 00:00:00.

     However, we allow negative values to represent timestamps before that"

    EpochEnd isNil ifTrue:[

        EpochEnd := UtcTimestamp new setSeconds:16r7FFFFFFF.

    ].

    ^ EpochEnd

!

epochEndOSTime

    "the epoch ends at some OS dependent limit.

     For now, hard wire this limit - should be an os query, to prepare for mktim64 to appear..."

    ^ EpochEndOSTime.

!

fromDate:aDate

    "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

    "

     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"

!

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

    "

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

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

     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:day month:month year:year

    "return a new Timestamp, given the year, month and day (starting at 1).

     Date protocol compatibility"

    ^ self

    "

     Timestamp newDay:1 month:1 year:1996

    "

!

newDay:dayInYear year:year

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

     Date protocol compatibility"

    ^ self fromDate:(Date newDay:dayInYear year:year)

    "

     Timestamp newDay:183 year:1996

     Timestamp newDay:1 year:1996

    "

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

!

secondsSince1970:secs

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

     This is the format used in the UNIX world"

    ^ self basicNew setSeconds:secs.

    "

     Timestamp secondsSince1970:0

     Timestamp secondsSince1970:3600

     Timestamp secondsSince1970:3600*24

     (Timestamp year:2010 month:7 day:1 hour:0 minute:0 second:0)

       =

     (Timestamp secondsSince1970:1277935200)

    "

    "Created: / 21-10-1996 / 17:48:30 / stefan"

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

    "Modified: / 08-01-2011 / 16:06:28 / cg"

!

utcMillisecondsSince1970:secs

    "set time from elapsed milliseconds since the epoch 1-1-1970, 00:00:00."

    ^ self basicNew setMilliseconds:secs

    "Created: / 08-01-2011 / 16:09:32 / cg"

!

utcNow

    "return now as utc timestamp"

    ^ UtcTimestamp now

    "

     Timestamp now

     Timestamp utcNow

    "

!

utcSecondsSince1970:secs

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

     This is the format used in the UNIX world"

    ^ self secondsSince1970:secs

"/    |divMod|

"/

"/    divMod := secs 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

    "

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

    "Created: / 08-01-2011 / 16:05:09 / cg"

!

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:7 day:1 hour:1 minute: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

    "

     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:7 day:1 hour:1 minute:0 second:0

     UtcTimestamp year:2000 month:7 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:'Compatibility-Squeak'!

current

    ^ self now

!

readFrom:aStringOrStream

    "Answer a new instance for the value given by aStringOrStream"

    ^ self

    "

     self readFrom:'23-jun-2000 15:00'

     self fromString:'23-jun-2000 15:00'

     self readFrom:'23-jun-2000 '

    "

    "Modified (comment): / 20-08-2011 / 16:52:10 / cg"

! !

!Timestamp class methodsFor:'format strings'!

defaultFormatString

    "a format string to present times in user interfaces.

     Do not use this to store/retrieve times (use ISO8601 for that).

     Although the string below looks like ISO8601, it does not include TZ information,

     so when read back, it will always be interpreted as a local timestamp."

    ^ '%(year)-%(month)-%(day) %h:%m:%s.%i'

    "Created: / 16-01-2011 / 11:23:36 / cg"

! !

!Timestamp class methodsFor:'obsolete'!

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

    <resource: #obsolete>

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

    ^ self

    "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

    <resource: #obsolete>

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

! !

!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, which is iso8601

     This is more or less a heuristic attempt to read any reasonable format.

     If the input starts with an integer > 31,

     it is assumed to be a year and the rest is read in iso8601 format.

     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"

    |pos firstNumber secondNumber day month year hour min sec millis usFormat possibeMonthName ch utcOffsetOrNil|

    pos := aStream position.

    firstNumber := Integer readFrom:aStream onError:[TimeConversionError raiseErrorString:' - integer expected'].

    firstNumber > 31 ifTrue:[

        "/ assume iso8601 format;

        aStream position:pos.

        ^ self readIso8601FormatFrom:aStream.

    ].

    aStream skipSeparators.

    "/ consider this a kludge

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

    [(ch := aStream peekOrNil) notNil and:[ch isLetterOrDigit]] whileFalse:[aStream next].

    ((ch := aStream peekOrNil) notNil and:[ch isDigit]) ifTrue:[

        secondNumber := Integer readFrom:aStream onError:-1.

        usFormat ifTrue:[

            month := firstNumber.

            day := secondNumber.

        ] ifFalse:[

            month := secondNumber.