"

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

"{ NameSpace: Smalltalk }"

Magnitude subclass:#AbstractTime

	instanceVariableNames:''

	classVariableNames:''

	poolDictionaries:''

	category:'Magnitude-Time'

!

!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 Timestamp (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 Timestamp

        Delay ProcessorScheduler

"

!

iso8601FormatDocumentation

"

  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)'

                Timestamp now printStringFormat:'%(year)'  

       Year and month:

          YYYY-MM (eg 1997-07)

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

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

       Complete date:

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

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

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

       Complete date plus hours and minutes:

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

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

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

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

"

!

printFormatDocumentation

"

     bindings:

        %h      hours, 00..23 (i.e. european)  0-padded to length 2

        %u      hours, 00..12 (i.e. us)        0-padded to length 2

        %m      minutes, 00..59                0-padded to length 2

        %s      seconds, 00..59                0-padded to length 2

        %i      milliseconds, 000..999         0-padded to length 3

        %a      am/pm

     Timestamp only:

        %(day)   day, 00..31                    0-padded to length 2

        %(month) month, 00..12                  0-padded to length 2

        %(year)  year, 4 digits                 0-padded to length 4

     special:

        %H      24-hours - unpadded

        %U      12-hours - unpadded

        %M      minutes - unpadded

        %S      seconds - unpadded

        %I      milliseconds, unpadded

        %A      AM/PM   - uppercase

        %t      seconds within hour  (unpadded)

        %T      seconds from midNight  (unpadded)

        %(TZD)  timeZone delta of the receiver from UTC in the format +/-hh:mm

        %(milli1) milliseconds, truncated to 1/10th of a second 0..9

        %(milli2) milliseconds, truncated to 1/100th of a second 00..99 0-padded to length 2

        %(milli3) milliseconds, same as %i for convenience

     Timestamp only:

        %(Day)         - day - unpadded

        %(Month)       - month - unpadded

        %(yearOrTime)  - year or time 5 digits    as in unix-ls:

                                                  year if it is not the current year;

                                                  time otherwise

        %(weekDay)      - day in week (1->monday, 2->tuesday, ... ,7->sunday)

        %(dayName)      - full day name

        %(DayName)      - full day name, first character uppercase

        %(DAYNAME)      - full day name, all uppercase

        %(monthName)    - full month name

        %(MonthName)    - full month name, first character uppercase

        %(MONTHNAME)    - full month name, all uppercase

        %(shortDayName) - short (abbreviated) day name

        %(ShortDayName) - short (abbreviated) day name, first character uppercase

        %(SHORTDAYNAME) - short (abbreviated) day name, all uppercase

        %(shortMonthName) - short (abbreviated) month name

        %(ShortMonthName) - short (abbreviated) month name, first character uppercase

        %(SHORTMONTHNAME) - short (abbreviated) month name, all uppercase

        %(nth)          - counting day-in-month (1->'st'; 2->'nd'; 3->'rd'; 4...->'th')

        %(weekDayNth)   - counting day-in-week (1->'st'; 2->'nd'; 3->'rd'; 4...->'th')

        %(weekNth)      - counting week-in-year (1->'st'; 2->'nd'; 3->'rd'; 4...->'th')

        %(yearRoman)    - year, in roman letters

        %(monthRoman)   - month, in roman letters

     The ISO8601 printString are documented in iso8601FormatDocumentation:

"

! !

!AbstractTime class methodsFor:'instance creation'!

dateAndTimeNow

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

     As these provide no timezone info, this should be only used for user interface purposes.

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

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

    "

     Time dateAndTimeNow       

     Date dateAndTimeNow       

    "

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

!

epoch

    "answer the time when we start counting"

    ^ self new setSeconds:0

    "

     Timestamp epoch

     Time epoch     

    "

!

now

    "return an instance of myself representing this moment with at least second precision.

     Timestamps will redefine this to always return millisecond precision."

    ^ self basicNew fromOSTime:(OperatingSystem getOSTime)

    "

     Timestamp now   

     Time now   

    "

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

!

nowWithMicroseconds

    "return an instance of myself representing this moment with at least microsecond precision."

    |osTime millis micros|

    osTime := OperatingSystem getOSTimeWithMicros.

    millis := osTime at:1.

    micros := osTime at:2.

    ^ self basicNew fromOSTimeWithMilliseconds:millis additionalPicoseconds:(micros*(1000*1000)).

    "

     Timestamp now   

     Time now

     Timestamp nowWithMilliseconds

     Timestamp nowWithMicroseconds

    "

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

!

nowWithMilliseconds

    "return an instance of myself representing this moment with at least millisecond precision."

    ^ self basicNew fromOSTimeWithMilliseconds:(OperatingSystem getOSTime)

    "

     Time now

     Time nowWithMilliseconds 

     Timestamp now   

     Timestamp nowWithMilliseconds

     Timestamp nowWithMicroseconds

    "

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

!

utcNow

    "return an instance of myself representing this momentin the UTC timezone."

    ^ self subclassResponsibility

    "

     Timestamp utcNow   

     Timestamp utcNow

     Time now   

     Time utcNow   

    "

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

! !

!AbstractTime class methodsFor:'Compatibility-Squeak'!

dateAndTimeFromSeconds:secondCount

    "set date and time from seconds since 1901-01-01 00:00 UTC"

    |timestamp|

"   

    secondsBetween1901and1970 := 

        (Timestamp epoch asDate subtractDate:(Date day:1 month:1 year:1901))

        *  (24 * 60 * 60)

"

    "stc cannot make large integers"

    timestamp := Timestamp fromSeconds:secondCount - 2177452800.

    ^ Array

        with: (timestamp asDate)

        with: (timestamp asTime)

    "

     Timestamp dateAndTimeFromSeconds: (Time primSecondsClock) 

     Time dateAndTimeFromSeconds: (Time totalSeconds) 

     Date dateAndTimeFromSeconds: (Time totalSeconds)

    "

!

milliseconds:msTime1 since:msTime2

    "return the number of milliseconds between two

     millisecond time values, compensating for roll-over.

     The same as millisecondsBetween:and: for Squeak compatibility."

    ^ OperatingSystem millisecondTimeDeltaBetween:msTime1 and:msTime2

!

millisecondsSince: lastTime

        "Answer the elapsed time since last recorded in milliseconds.

        Compensate for rollover."

        ^self milliseconds: self millisecondClockValue since: lastTime

!

primSecondsClock

    "returns the number of seconds since 1.1.1901 UTC"

    ^ Timestamp now utcSecondsSince1901

    "

     Timestamp primSecondsClock

    "

! !

!AbstractTime class methodsFor:'Compatibility-VW'!

totalSeconds

    "returns the number of seconds since 1.1.1901 UTC"

    ^ Timestamp now utcSecondsSince1901

! !

!AbstractTime class methodsFor:'error handling'!

conversionErrorSignal

    "return the signal used for conversion error handling"

    ^ TimeConversionError

! !

!AbstractTime class methodsFor:'format strings'!

defaultFormatString

    ^ '%h:%m:%s'

! !

!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

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

                                    on others: don't know

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

        getSeconds                  on UNIX: returns 0

                                    on others: don't know

    "

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

! !

!AbstractTime class methodsFor:'queries'!

isAbstract

    ^ self == AbstractTime

!

microsecondClockValue

    "return microseconds seconds of now"

    ^ OperatingSystem getMicrosecondTime

    "

     Time microsecondClockValue

    "

    "

     |t1 t2 overhead|

     t1 := Time microsecondClockValue.

     t2 := Time microsecondClockValue.

     overhead := t2 - t1.  

     t1 := Time microsecondClockValue.

     100 factorial.

     t2 := Time microsecondClockValue.

     t2 - t1 - overhead        

    "

!

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:'reading'!

readFrom:aStringOrStream format:formatString

    "see format description in readFrom:format:language:onError:"

    ^ self 

        readFrom:aStringOrStream format:formatString language:nil 

        onError:[

            self conversionErrorSignal raiseErrorString:' - Timestamp format error'

        ].

!

readFrom:aStringOrStream format:formatString language:languageString onError:exceptionalValue

    ^ self subclassResponsibility

!

readFrom:aStringOrStream format:formatString onError:exceptionalValue

    "see format description in readFrom:format:language:onError:"

    ^ self readFrom:aStringOrStream format:formatString language:nil onError:exceptionalValue