"

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

"{ NameSpace: Smalltalk }"

AbstractTime subclass:#Timestamp

	instanceVariableNames:'osTime additionalPicoseconds'

	classVariableNames:'Epoch MaxOSTime MinOSTime TimeZoneInfo'

	poolDictionaries:''

	category:'Magnitude-Time'

!

Object subclass:#TimestampBuilderAbstract

	instanceVariableNames:'year month day hour minute second millisecond isUtcTime

		hasTimezone yearAlreadyRead utcOffset picos'

	classVariableNames:''

	poolDictionaries:''

	privateIn:Timestamp

!

Timestamp::TimestampBuilderAbstract subclass:#TimestampISO8601Builder

	instanceVariableNames:'stream'

	classVariableNames:''

	poolDictionaries:''

	privateIn:Timestamp

!

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

    This base-time is called 'epoch' and always an UTC time.

    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 TZTimestamp, which remembers the timezone in which it was created).

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

    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 them. 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, whereas instances of Timestamp can.

    Also, it should not be confused with TimeDuration, which represents a time-difference.

    Notice: 

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

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

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

        AbsoluteTime was kept as an alias for backward compatibility and was finally removed in 2017.

    Also Note:

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

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

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

        Thus, ST/X will have no problem when dealing with dates before the epoch or after 2038.

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

        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.

    ALso Note:

        because all timestamps keep the internal time value in UTC, they can be easily compared

        for being before/same/after another. Only when printing, a difference is made.

        The timezone is compensated out when a timestamp is created and recalculated in when printed.

    News:

        The additional instance variable picoSeconds can be used to add more resolution. 

        If non-nil, it holds additional picoseconds to be added to the millisecond osTime

        (i.e. the picoSeconds are an integer between 0 and 1000*1000*1000.

        Although, not all OSs give us that detail when asking for the current time,

        the picos can still be used in physical computations. 

        Some OSs will provide microsecond resolution.

        Notice: 

            the picos are to be added to the millis, to get picos within the second.

            this is ugly, but makes all the rest backward compatible.

            Also, most timestamps only require/have millisecond resolution,

            so the pico instvar is nil/0 and does not require an aditional largeInteger operation.

        The typical OS-time resolution is in the milli- or microsecond range.

        External logging hardware may generate timestamps in the micro- or nanosecond range.

        Picosecond resolution should be good enough for almost any application (at least for the near future).

    [author:]

        Claus Gittinger

    [See also:]

        UtcTimestamp Time Date

        Delay ProcessorScheduler

"

! !

!Timestamp class methodsFor:'initialization'!

initialize

    MinOSTime := OperatingSystem epochStartOSTime.

    MaxOSTime := OperatingSystem epochEndOSTime.

    Epoch := UtcTimestamp basicNew setSeconds:0.

    "Modified: / 19-01-2017 / 17:01:59 / stefan"

! !

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

!

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

    "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

        additionalPicoseconds:picos

    "

     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

                    raiseWith:anArray errorString:' - Timestamp 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

!

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

	year:aDate year

	month:aDate month

	day:aDate day

	hour:0

	minute:0

	second:0

	millisecond:0

    "

     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

	year:aDate year

	month:aDate month

	day:aDate day

	hour:aTime hours

	minute:aTime minutes

	second:aTime seconds

	millisecond:aTime milliseconds

    "

     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"

!

fromDate:aDate hour:hour minute:minute second:second

    "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 fromDate:aDate hour:hour minute:minute second:second millisecond:0

    "

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

     Timestamp fromDate:(Date today) hour:10 minute:5 second:30

    "

!

fromDate:aDate hour:hour minute:minute second:second microsecond:micros

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

        minute:minute

        second:second

        millisecond:0

      ) setMicrosecond:micros

    "

     Timestamp fromDate:(Date today) hour:10 minute:5 second:30 microsecond:123456

     Timestamp fromDate:(Date today) hour:10 minute:5 second:30 microsecond:140

    "

!

fromDate:aDate hour:hour minute:minute second:second millisecond:millis

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

        minute:minute

        second:second

        millisecond:millis

    "

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

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

     Timestamp fromDate:(Date today) hour:10 minute:5 second:30 millisecond:140

    "

!

fromDate:aDate hour:hour minute:minute second:second nanosecond:nanos

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

        minute:minute

        second:second

        millisecond:0

      ) setNanosecond:nanos

    "

     Timestamp fromDate:(Date today) hour:10 minute:5 second:30 microsecond:123456

     Timestamp fromDate:(Date today) hour:10 minute:5 second:30 microsecond:140

    "

!

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 (UTC).

     This is the format used in the UNIX world.

     Notice that the internal storage is always UTC based."

    ^ self basicNew setSeconds:secs.

    "

     UtcTimestamp secondsSince1970:0        -> 1970-01-01 00:00:00Z       

     Timestamp secondsSince1970:0           -> 1970-01-01 01:00:00 (local germany, ST)

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

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

    ^ self basicNew setMilliseconds:millis

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

    "Modified (format): / 14-12-2018 / 19:45:12 / Claus Gittinger"

!

utcNow

    "return now as utc timestamp"

    ^ UtcTimestamp now

    "

     Timestamp now

     Timestamp utcNow

    "

!

utcSecondsSince1970:secs

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

     This is the format used in the UNIX world.

     Notice that the internal storage is always UTC based."

    ^ UtcTimestamp secondsSince1970:secs

    "

     UtcTimestamp secondsSince1970:0        -> 1970-01-01 00:00:00Z       

     Timestamp secondsSince1970:0           -> 1970-01-01 01:00:00 (local germany, ST)

     UtcTimestamp secondsSince1970:3600     -> 1970-01-01 01:00:00Z

     Timestamp secondsSince1970:3600        -> 1970-01-01 02:00:00 (local)

     Timestamp secondsSince1970:3600*24

    "

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

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

!

year:year month:month day:day  

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

     Date protocol compatibility"

    ^ self

        year:year

        month:month

        day:day

        hour:0

        minute:0

        second:0

        millisecond:0

    "

     Timestamp year:1996 month:1 day:1 

    "

!

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

     Timestamp year:2080 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 microsecond:micros

    "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) setMicrosecond:micros

    "

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

    "

!

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