"

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

	instanceVariableNames:'timeEncoding'

	classVariableNames:''

	poolDictionaries:''

	category:'Magnitude-Time'

!

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

"

    Instances of time represent a particular time-of-day.

    Since they only store hours, minutes and seconds within a day,

    they cannot be used to compare times across midnight

    (i.e. they should not be used as timeStamps).

    Use instances of Timestamp (and read the comment there) to do this.

    Time now returns the time in the local timezone.

    Use Time utcNow to get the time in the UTC zone.

    Note: time was changed recently to keep the number of milliseconds since midnight.

          However, all existing instance creators so far only create time instances with 0-millis.

          I.e. Time now still returns a time with second precision.

          It is not done currently, to remain backward compatible, as users may get confused

          to see t1 > t2 although they print the same (as long as the printed representation does not

          include the milli seconds).

          On the other side: a change of the default printformat is not done now, 

          as it may affect many existing applications.

          Any application which needs the millisecond precision time should call the new

            Time nowWithMilliseconds.

    Examples:

        |t|

        t := Time now.

        Transcript showCR:t.

        |t1 t2|

        t1 := Time now.

        (Delay forSeconds:10) wait.

        t2 := Time now.

        t2 - t1

    [author:]

        Claus Gittinger

    [see also:]

        Date Timestamp AbstractTime OperatingSystem

        Filename

"

! !

!Time class methodsFor:'instance creation'!

fromString: aString

    ^ self readFrom: (ReadStream on: aString).

    "Modified (format): / 20-08-2011 / 16:46:39 / cg"

!

hour:h minute:m

    "compatibility"

    ^ self hours:h minutes:m seconds:0

    "

     Time hour:2 minute:33

    "

!

hour:h minute:m second:s

    "compatibility"

    ^ self hours:h minutes:m seconds:s

    "

     Time hour:2 minute:33 second:0

    "

!

hour:h minutes:m seconds:s

    "return an instance of Time representing the given time.

     See also Time now / Date today / Timestamp now.

     Obsolete: please use #hours:minutes:seconds:"

    <resource:#obsolete>

    self obsoleteMethodWarning:'use #hours:minutes:seconds:'.

    ^ self hours:h minutes:m seconds:s

    "

     Time hours:2 minutes:33 seconds:0

     Time hours:0 minutes:0 seconds:0

     Time hours:24 minutes:0 seconds:0

     Time hours23 minutes:59 seconds:59

    "

    "Modified: 19.4.1996 / 15:32:40 / cg"

!

hours:h minutes:m seconds:s

    "return an instance of Time representing the given time.

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

    ^ self basicNew setHours:h minutes:m seconds:s

    "

     Time hours:2 minutes:33 seconds:0

     Time hours:0 minutes:0 seconds:0

     Time hours:24 minutes:0 seconds:0

     Time hours:23 minutes:59 seconds:59

    "

    "Modified: 19.4.1996 / 15:32:40 / cg"

!

hours:h minutes:m seconds:s milliseconds:ms

    "return an instance of Time representing the given time.

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

    ^ self basicNew setHours:h minutes:m seconds:s milliseconds:ms

    "

     Time hours:2 minutes:33 seconds:0

     Time hours:0 minutes:0 seconds:0

     Time hours:24 minutes:0 seconds:0

     Time hours:23 minutes:59 seconds:59

    "

    "Modified: 19.4.1996 / 15:32:40 / cg"

!

midnight

    "Answer a new instance at midnight."

    ^ self fromSeconds: 0

    "

     Time midnight

    "

!

noon

    "Answer a new instance at noon."

    ^ self fromSeconds: 43200 "12*60*60"

    "

     Time noon

    "

!

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

    "return a new Time, reading a printed representation from aStream using a formatString.

     The formatString is similar to the one used when printing.

     On error, exceptionalValue is returned.

     If exceptionalValue is a one-arg block, an error message is passed as argument.

     Format:

        %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

     an optional length after the % gives a field length;

        i.e. %2h%2m%2s parses '123557' as 12:35:37

     Please consider using a standard format, such as iso8601.

    "

    |hour minute second millisecond

     utcOffset inStream formatStream error fChar format itemHandler

     len s|

    error := [:msg |

                exceptionalValue isBlock ifTrue:[

                    ^ exceptionalValue valueWithOptionalArgument:'format error'

                ] ifFalse:[

                    ^ exceptionalValue value

                ].

             ].

    itemHandler := [:format |

        |input|

        input := len isNil ifTrue:[ inStream ] ifFalse:[ inStream next: len ].

        ( format = 'h' or:[ format = 'H' ]) ifTrue:[

            hour := Integer readFrom:input onError:[ error value:'invalid hour' ].

        ] ifFalse:[ ( format = 'u'  or:[ format = 'U']) ifTrue:[

            hour := Integer readFrom:input onError:[ error value:'invalid hour' ].

        ] ifFalse:[ ( format = 'm'  or:[ format = 'M' ]) ifTrue:[

            minute := Integer readFrom:input onError:[ error value:'invalid minute' ].

        ] ifFalse:[ ( format = 's'  or:[ format = 'S' ]) ifTrue:[

            second := Integer readFrom:input onError:[ error value:'invalid second' ].

        ] ifFalse:[ ( format = 'i'  or:[ format = 'I' ]) ifTrue:[

            millisecond := Integer readFrom:input onError:[ error value:'invalid millsecond' ].

        ] ifFalse:[ ( format = 'tz' ) ifTrue:[

            utcOffset := Timestamp utcOffsetFrom:input.

            utcOffset isNil ifTrue:[ error value:'invalid timezone' ]

        ] ifFalse:[ ( format = 'a' ) ifTrue:[

            s := (input next:2) asLowercase.

            s = 'am' ifTrue:[

                (hour between:0 and:12) ifFalse:[ error value:'invalid hour' ]

            ] ifFalse:[

                s = 'pm' ifTrue:[

                    (hour between:1 and:12) ifFalse:[ error value:'invalid hour' ].

                    hour := hour + 12.

                ] ifFalse:[

                    error value:'invalid am/pm'

                ]

            ]

        ] ifFalse:[

            error value:'unhandled format:',format

        ]]]]]]]

    ].

    hour := 0.

    minute := 0.

    second := 0.

    millisecond := 0.

    utcOffset := 0.

    inStream := aStringOrStream readStream.

    formatStream := formatString readStream.

    [formatStream atEnd] whileFalse:[

        fChar := formatStream next.

        fChar = Character space ifTrue:[

            inStream peek isSeparator ifFalse:[ error value: 'format error; space expcected' ].

            inStream skipSeparators.

        ] ifFalse:[

            fChar == $% ifTrue:[

                len := nil.

                (formatStream peek isDigit) ifTrue:[

                    len := Integer readFrom:formatStream onError:[ error value: 'format error; invalid length' ]

                ].

                (formatStream peek == $() ifTrue:[

                    formatStream next.

                    format := formatStream upTo:$).

                ] ifFalse:[

                    (formatStream peek == ${) ifTrue:[

                        formatStream next.

                        format := formatStream upTo:$}.

                    ] ifFalse:[

                        (formatStream peek isLetter) ifTrue:[

                            format := formatStream nextAlphaNumericWord.

                        ] ifFalse:[

                            error value:'unhandled format:',formatStream peek

                        ]

                    ]

                ].

                itemHandler value:format.

            ] ifFalse:[

                inStream peek = fChar ifFalse:[^ error value: 'format error; ',fChar,' expcected'].

                inStream next.

            ]

        ].

    ].

    ^ (self 

        hours:(hour ? 0) minutes:(minute ? 0) seconds:(second ? 0) milliseconds:millisecond) 

            + utcOffset

    "

     Time readFrom:'13:11:06' format:'%h:%m:%s' language:nil onError:[self halt]

     Time readFrom:'131106' format:'%2h%2m%2s' language:nil onError:[self halt]

     Time readFrom:'7:30pm EST' format:'%u:%m%a %tz' language:#en onError:[self halt]

     Time readFrom:'7:30pm UTC' format:'%u:%m%a %tz' language:#en onError:[self halt]

    "

!

readFrom:aStringOrStream onError:exceptionBlock

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

     If no am/pm follows the time, the string is interpreted as

     either 24 hour format or being am."

    ^ [

	|str hour min sec peekC millis|

	str := aStringOrStream readStream.

	hour := Integer readFrom:str.

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

	min := 0.

	sec := 0.

	millis := 0.

	str atEnd ifFalse:[

	    peekC := str peek.

	    (peekC == $:) ifTrue:[

		str next.

		min := Integer readFrom:str.

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

		(str peek == $:) ifTrue:[

		    str next.

		    sec := Integer readFrom:str.

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

		    (str peek == $.) ifTrue:[

			str next.

			millis := ((Fraction readDecimalFractionFrom:str onError:[^ exceptionBlock value]) * 1000) asInteger.

		    ].

		].

		peekC := str peek.

	    ].

	    [peekC == Character space] whileTrue:[str next. peekC := str peek].

	    (peekC == $p or:[peekC == $P]) ifTrue:[

		str next.

		(str peek == $m or:[str peek == $M]) ifTrue:[

		    str next

		].

		(hour <= 0 or:[hour > 12]) ifTrue:[^ exceptionBlock value].

		"pm"

		hour ~~ 12 ifTrue:[

		    hour := hour + 12

		].

		peekC := str peek

	    ] ifFalse:[

		(peekC == $a or:[peekC == $A]) ifTrue:[

		    str next.

		    (str peek == $m or:[str peek == $M]) ifTrue:[

			str next

		    ].

		    hour == 12 ifTrue:[

			hour := 0.

		    ].

		    hour > 12 ifTrue:[^ exceptionBlock value].

		    peekC := str peek

		] ifFalse:[

		    "/ cg: dont be too picky here - we do not care, what comes after the

		    "/ time string. (Needed to be able to read rfc822 strings where a timezone

		    "/ follows (-/+0700 GMT, for example)

"/                    peekC notNil ifTrue:[

"/                        peekC isSeparator ifFalse:[^ exceptionBlock value].

"/                    ]

		].

	    ]

	].

	self basicNew setHours:hour minutes:min seconds:sec milliseconds:millis

    ] on:Error do:exceptionBlock.

    "

     Time readFrom:'0:00'

     Time readFrom:'2:00'

     Time readFrom:'12:00'

     Time readFrom:'14:00'

     Time readFrom:'23:00'

     Time readFrom:'24:00'

     Time readFrom:'2:30 am'

     Time readFrom:'2:30 pm'

     Time readFrom:'14'

     Time readFrom:'2 am'

     Time readFrom:'2 pm'

     Time readFrom:'12:05 pm'

     Time readFrom:'12:06 am'

     Time readFrom:'18:22:00'

     Time readFrom:'14:00:11'

     Time readFrom:'7:00:11'

     Time readFrom:'24:00:00'

     Time readFrom:'0:00:00'

     Time readFrom:'12:00:00'

     Time readFrom:'0:00:00'

     Time readFrom:'6:22:00 pm'

     Time readFrom:'2:00:11 pm'

     Time readFrom:'7:00:11 am'

     Time readFrom:'12:00:00 am'

     Time readFrom:'0:00:00 am'

     Time readFrom:'24:00:00 am'

     Time readFrom:'12:00:00 pm'

     Time readFrom:'0:00:00 pm' onError:'invalid'

     Time readFrom:'24:00:00 pm'

     Time readFrom:'13:00:00.5'

     Time readFrom:'13:00:00.123'

     Time readFrom:'1:00:00.123 pm'

    "

    "Modified: 8.10.1996 / 19:32:11 / cg"

!

utcNow

    "return an instance of myself representing this moment in UTC.

     That is, the current time in London without any daylight saving adjustments."

    ^ self basicNew fromUtcOSTime:(OperatingSystem getOSTime)

    "

     Timestamp now

     Timestamp utcNow

     Time now

     Time utcNow

    "

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

! !

!Time class methodsFor:'format strings'!

defaultFormatString

    "a language specific format string to present times in user interfaces.

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

    LanguageTerritory == #us ifTrue:[

	^ self formatString12us

    ] ifFalse:[

	^ self formatString24

    ]

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

!

defaultFormatStringWithMilliseconds

    LanguageTerritory == #us ifTrue:[

	^ self formatStringWithMilliseconds12us

    ] ifFalse:[

	^ self formatStringWithMilliseconds24

    ]

!

formatString12us

    "return the format string used to format US times (and other areas)"

    ^ '%u:%m:%s %A'

!

formatString24

    "return the format string used to format non US times"

    ^ '%h:%m:%s'

!

formatStringWithMilliseconds12us

    "return the format string used to format US times (and other areas)"

    ^ '%u:%m:%s.%i %A'

!

formatStringWithMilliseconds24

    "return the format string used to format non US times"

    ^ '%h:%m:%s.%i'