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

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

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

        str := aStringOrStream readStream.

        hour := Integer readFrom:str.
        (hour between:0 and:24) ifFalse:[^ exceptionBlock value].

        min := 0.
        sec := 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].
                ].
                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
    ] 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'  
    "

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

utcNow
    "return an instance of myself representing this moment."

    ^ 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
    LanguageTerritory == #us ifTrue:[
        ^ self formatString12us
    ] ifFalse:[
        ^ self formatString24
    ]

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

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


!Time methodsFor:'Compatibility-Squeak'!

asMilliseconds
    ^ self asMilliSeconds

    "Created: / 05-09-2011 / 14:56:36 / cg"
!

intervalString
    "Treat the time as a difference.  
     Give it in hours and minutes with two digits of accuracy."

    |hours minutes seconds hh mm ss s|

    hours := self hours.
    minutes := self minutes.
    seconds := self seconds.

    hours = 0   
        ifTrue: [hh := ''] 
        ifFalse: [
            hh := hours printString, ' hour'.
            hours > 1 ifTrue:[
                hh := hh , 's'
            ]
        ].
    minutes = 0 
        ifTrue: [mm := ''] 
        ifFalse: [
            mm := minutes printString, ' minute'.
            minutes > 1 ifTrue:[
                mm := mm , 's'
            ]
        ].
    seconds = 0 
        ifTrue: [ss := ''] 
        ifFalse: [
            ss := seconds printString, ' second'.
            seconds > 1 ifTrue:[
                ss := ss , 's'
            ]
        ].

    "/ do not show seconds, if hours are there
    hh size > 0 ifTrue: [ss := ''].

    s := hh.
    mm notEmpty ifTrue:[
        s notEmpty ifTrue:[
            s := s , ' '
        ].
        s := s , mm.
    ].
    ss notEmpty ifTrue:[
        s notEmpty ifTrue:[
            s := s , ' '
        ].
        s := s , ss
    ].
    ^ s

    "
     (Time fromSeconds:3600) intervalString     
     (Time fromSeconds:3605) intervalString    
     (Time fromSeconds:3700) intervalString    
     (Time fromSeconds:5) intervalString       
     (Time fromSeconds:65) intervalString      
    "
!

print24:prnt24FormatBoolean on:aStream
    "print me either US or 24hr format on a stream"

    ^ self print24:prnt24FormatBoolean showSeconds:true on:aStream

    "
     Time now print24:true on:Transcript. Transcript cr.
     Time now print24:false on:Transcript. Transcript cr.
    "
!

print24:prnt24Format showSeconds:doSeconds on:aStream
    "print me either US or 24hr format, optionally with
     seconds on a stream"

    |format|

    prnt24Format ifTrue:[
        doSeconds ifTrue:[
            format := '%h:%m:%s'
        ] ifFalse:[
            format := '%h:%m'
        ].
    ] ifFalse:[
        "/ US format
        doSeconds ifTrue:[
            format := '%u:%m:%s %a'
        ] ifFalse:[
            format := '%u:%m %a'
        ].
    ].
    ^ self
        printOn:aStream 
        format:format.

    "
     Time now print24:true showSeconds:true on:Transcript. Transcript cr.
     Time now print24:false showSeconds:true on:Transcript. Transcript cr.
     Time now print24:true showSeconds:false on:Transcript. Transcript cr.
     Time now print24:false showSeconds:false on:Transcript. Transcript cr.
    "
! !

!Time methodsFor:'accessing'!

hours
    "return the number of hours since midnight (i.e. 0..23)"

    ^ self getSeconds // 3600

    "
     Time now hours
    "
!

milliseconds
    "time does not keep milliseconds 
     - for compatibility with Timestamp"

    ^ 0
!

minutes
    "return the number of minutes within the hour (i.e. 0..59)"

    ^ (self getSeconds \\ 3600) // 60

    "
     Time now minutes
    "
!

seconds
    "return the number of seconds within the minute (i.e. 0..59)"

    ^ self getSeconds \\ 60

    "
     Time now seconds
    "
!

timeZoneDeltaInMinutes
    "answer the number of minutes between local time and utc time.
     Delta is positive if local time is ahead of utc, negative if behind utc.

     Time is local time, so answer the delta of today"

    ^ Timestamp now timeZoneDeltaInMinutes


    "
      Time now timeZoneDeltaInMinutes
    "
! !

!Time methodsFor:'comparing'!

< aTime
    "return true if the receiver is before the argument"

    aTime class == self class ifTrue:[
        ^ timeEncoding < aTime timeEncoding
    ].
    ^ self getSeconds < aTime getSeconds
!

= aTime
    "return true if the argument, aTime represents the same timeOfDay"

    aTime class == self class ifTrue:[
        ^ timeEncoding = aTime timeEncoding
    ].
    (aTime species == self species) ifFalse:[^ false].
    ^ self getSeconds = aTime getSeconds

    "Modified: / 18-07-2007 / 14:16:34 / cg"
!

> aTime
    "return true if the receiver is before the argument"

    aTime class == self class ifTrue:[
        ^ timeEncoding > aTime timeEncoding
    ].
    ^ self getSeconds > aTime getSeconds
!

hash
    "return an integer useful for hashing on times"

    ^ timeEncoding
! !

!Time methodsFor:'converting'!

asLocalTimestamp
    "return an Timestamp object from the receiver.
     So I am interpreted as a Time in the local timezone.
     The date components are taken from today."

    |todayTimestamp|

    todayTimestamp := Timestamp now.
    todayTimestamp year:todayTimestamp year month:todayTimestamp month day:todayTimestamp day
                   hour:(self hours) minute:(self minutes) second:(self seconds)
                   millisecond:(self milliseconds).

    ^ todayTimestamp.

    "
      Time now asLocalTimestamp
    "
!

asMilliSeconds
    "return the number of milliseconds elapsed since midnight"

    ^ self getMilliseconds

    "
     Time now asMilliSeconds
     (TimeDuration days:1) asMilliSeconds 
     (TimeDuration hours:1) asMilliSeconds 
    "

    "Created: / 05-09-2011 / 10:40:15 / cg"
!

asSeconds
    "return the number of seconds elapsed since midnight"

    ^ self getSeconds

    "
     Time now asSeconds
     (TimeDuration days:1) asSeconds 
    "
!

asTime
    "return a Time object from the receiver - thats the receiver."

    ^ self
!

asTimeDuration
    "return an TimeDuration object from the receiver, taking the time since midnight."

    ^ TimeDuration 
                   hours:(self hours) minutes:(self minutes) seconds:(self seconds)
                   milliseconds:(self milliseconds)
    "
     Time now asTimeDuration 
    "
!

asTimestamp
    "return an Timestamp object from the receiver.
     The date components are taken from today."

    ^ self asLocalTimestamp

    "
      Time now asTimestamp
    "
!

asUtcTimestamp
    "return an UtcTimestamp object from the receiver.
     So I am interpreted as a Time in the UTC zone.
     The date components are taken from today."

    |todayTimestamp|

    todayTimestamp := UtcTimestamp now.
    todayTimestamp year:todayTimestamp year month:todayTimestamp month day:todayTimestamp day
                   hour:(self hours) minute:(self minutes) second:(self seconds)
                   millisecond:(self milliseconds).

    ^ todayTimestamp.

    "
      Time now asUtcTimestamp
    "
! !

!Time methodsFor:'printing & storing'!

print12HourFormatOn:aStream
    "append a human readable printed representation of the receiver to aStream.
     Format is hh:mm:ss am/pm (i.e. 12-hour american format)."

    ^ self
        printOn:aStream 
        format:(self class formatString12us)

"/    |h m s ampm|
"/
"/    h := self hours.
"/
"/    "/ 0 -> 12 am
"/    "/ 12 -> 12 pm
"/
"/    h // 12 == 0 ifTrue:[
"/        ampm := ' am'.
"/    ] ifFalse:[
"/        ampm := ' pm'.
"/    ].
"/
"/    h == 0 ifFalse:[
"/        h := h - 1 \\ 12 + 1.
"/    ].
"/
"/    h printOn:aStream.
"/    aStream nextPut:$:.
"/    m := self minutes.
"/    (m < 10) ifTrue:[aStream nextPut:$0].
"/    m printOn:aStream.
"/    aStream nextPut:$:.
"/    s := self seconds.
"/    (s < 10) ifTrue:[aStream nextPut:$0].
"/    s printOn:aStream.
"/    aStream nextPutAll:ampm

    "
     Time now print12HourFormatOn:Transcript. Transcript cr
     (Time now subtractHours:12) print12HourFormatOn:Transcript. Transcript cr
     (Time hour:24 minutes:0 seconds:0) print12HourFormatOn:Transcript. Transcript cr
     (Time hour:12 minutes:0 seconds:0) print12HourFormatOn:Transcript. Transcript cr
     (Time hour:0 minutes:0 seconds:0) print12HourFormatOn:Transcript. Transcript cr
     0 to:24 do:[:h |
         (Time hour:h minutes:0 seconds:0) print12HourFormatOn:Transcript. Transcript cr
     ]
    "
!

print24HourFormatOn:aStream
    "append a human readable printed representation of the receiver to aStream.
     Format is hh:mm:ss (i.e. 24-hour european format)."

    ^ self
        printOn:aStream 
        format:(self class formatString24).

"/    |h m s|
"/
"/    h := self hours.
"/    (h < 10) ifTrue:[aStream nextPut:$0].
"/    h printOn:aStream.
"/    aStream nextPut:$:.
"/    m := self minutes.
"/    (m < 10) ifTrue:[aStream nextPut:$0].
"/    m printOn:aStream.
"/    aStream nextPut:$:.
"/    s := self seconds.
"/    (s < 10) ifTrue:[aStream nextPut:$0].
"/    s printOn:aStream

    "
     Time now print24HourFormatOn:Transcript. Transcript cr
    "
!

printOn:aStream
    "append a human readable printed representation of the receiver to aStream.
     The format is suitable for a human - not meant to be read back.

     Format is hh:mm:ss either in 12-hour or 24-hour format.
     depending on the setting of LanguageTerritory.
     I dont know what ST-80 does here (12-hour format ?)"

    ^ self
        printOn:aStream 
        format:(self class defaultFormatString)               

    "
     Time now printOn:Transcript. Transcript cr
    "

    "Modified: / 16-01-2011 / 11:27:24 / cg"
!

printString12HourFormat
    "return a printed representation in 12 hour format"

    ^ self printStringFormat:(self class formatString12us)               

    "
     Time now printString12HourFormat
    "
!

printString24HourFormat
    "return a printed representation in 24 hour format"

    ^ self printStringFormat:(self class formatString24)               

    "
     Time now printString24HourFormat
    "

!

shortPrintString
    "dummy - for now"

    ^ self printString

    "Created: 20.6.1997 / 17:17:01 / cg"
! !

!Time methodsFor:'private'!

fromOSTime:osTime
    "set my time in the local timezone, given an osTime"

    |i|

    i := OperatingSystem computeTimeAndDateFrom:osTime.
    self setHours:(i hours) minutes:(i minutes) seconds:(i seconds)

    "Modified: 1.7.1996 / 15:21:06 / cg"
!

fromUtcOSTime:osTime
    "set my time in the local timezone, given an osTime"

    |i|

    i := OperatingSystem computeUTCTimeAndDateFrom:osTime.
    self setHours:(i hours) minutes:(i minutes) seconds:(i seconds)

    "Modified: 1.7.1996 / 15:21:06 / cg"
!

getMilliseconds
    "return the number of milliseconds since midnight"

    ^ self getSeconds * 1000
!

getSeconds
    "return the number of seconds since midnight"

    ^ timeEncoding
!

setHours:h minutes:m seconds:s
    "set my time given individual values"

    self setSeconds:(((h\\24) * 60 * 60 ) + (m * 60) + s).
!

setMilliseconds:millis
    "set my time given milliseconds since midnight"

    self setSeconds:(millis // 1000)
!

setSeconds:secs
    "set my time given seconds since midnight.
     Notice the modulo operations here - there cannot be a time beyond 24hours
     (use TimeDuration, if you need that)."

    secs < 0 ifTrue:[
        timeEncoding := (24 * 3600) - (secs negated \\ (24 * 3600))
    ] ifFalse:[
        timeEncoding := secs
    ].
    timeEncoding > (24 * 3600) ifTrue:[
        timeEncoding := timeEncoding \\ (24 * 3600).
    ]

    "
     Time basicNew setSeconds:0 
     Time fromSeconds:3601  
     Time now seconds
     Time now timeEncoding
     (Time now addDays:5) seconds     
     (Time now addDays:5) timeEncoding
    "
!

timeEncoding
    "the internal encoding is stricktly private, 
     and should not be used outside."

    ^ timeEncoding
!

timeEncoding:encoding
    "the internal encoding is stricktly private, 
     and should not be used outside."

    timeEncoding := encoding
! !


!Time class methodsFor:'documentation'!

version
    ^ '$Id: Time.st 10700 2011-09-29 15:44:37Z vranyj1 $'
!

version_CVS
    ^ '§Header: /cvs/stx/stx/libbasic/Time.st,v 1.92 2011/09/05 13:03:28 cg Exp §'
!

version_SVN
    ^ '$Id: Time.st 10700 2011-09-29 15:44:37Z vranyj1 $'
! !