Class: Time

• Inheritance
• Description
• Class protocol
  • format strings
  • instance creation
• Instance protocol
  • Compatibility-Backward
  • Compatibility-Squeak
  • accessing
  • comparing
  • converting
  • double dispatching
  • printing & storing
  • private
  • testing
  • visiting

Inheritance:

   Object
   |
   +--Magnitude
      |
      +--AbstractChronologyObject
         |
         +--AbstractTime
            |
            +--Time
               |
               +--TimeDuration

Package:

stx:libbasic

Category:

Kernel-Chronology

Version:

rev: 1.128 date: 2023/06/06 16:05:30

user: cg

file: Time.st directory: libbasic

module: stx stc-classLibrary: libbasic

Description:

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; 
bare in mind that, Time instances are not prepared and made for time zone aware
time handling: always use Timestamp instances.

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 milliseconds).

  On the other hand: 
        a change of the default printformat is not done, 
        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


[aliases:]
    TimeLocal (ANSI)

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.

Class protocol:

 defaultFormatString

a language specific format string to present times in user interfaces.
Do not use this to store/retrieve times (use ISO8601 for that)

 defaultFormatStringWithMilliseconds

 formatString12us

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

 formatString24

return the format string used to format non US times

Usage example(s):

Time now printStringFormat:(Time formatString24) Time now printStringFormat:(Time formatString12us)

 formatStringWithMilliseconds12us

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

 formatStringWithMilliseconds24

return the format string used to format non US times

 fromString: aString

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

 hour: h minute: m

compatibility

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 hour: h minute: m second: s

compatibility

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 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:

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 hours: h minutes: m

return a new TimeDuration representing a duration of h hours and m minutes.
See also Time now / Date today / Timestamp now.

Usage example(s):

TimeDuration hours:2 minutes:33 TimeDuration hours:100 minutes:33

 hours: h minutes: m seconds: s

return an instance of Time representing the given time.
See also Time now / Date today / Timestamp now.

Usage example(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

 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.

Usage example(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

 midnight

Answer a new instance at midnight.

Usage example(s):

Time midnight

 noon

Answer a new instance at noon.

Usage example(s):

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
%f fractional seconds any length, but only milliseconds are read
%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.

Usage example(s):

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] Time readFrom:'13:11:06.111' format:'%h:%m:%s.%i' language:nil onError:[self halt] Time readFrom:'13:11:06.1' format:'%h:%m:%s.%f' language:nil onError:[self halt] Time readFrom:'13:11:06.01' format:'%h:%m:%s.%f' language:nil onError:[self halt] Time readFrom:'13:11:06.001' format:'%h:%m:%s.%f' language:nil onError:[self halt] Time readFrom:'13:11:06.1234567' format:'%h:%m:%s.%f' language:nil 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.
If it starts with T, assume iso8601 format

Usage example(s):

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'

 utcNow

return an instance of myself representing this moment in UTC.
That is, the current time in London without any daylight saving adjustments.

Usage example(s):

Timestamp now Timestamp utcNow Time now Time utcNow

 utcNowWithMilliseconds

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

Usage example(s):

Time now -> 01:05:10 PM Time nowWithMilliseconds -> 01:05:14.359 PM Time utcNow -> 11:05:16 AM Time utcNowWithMilliseconds -> 11:05:18.753 AM

Instance protocol:

 asMilliSeconds

return the number of milliseconds elapsed since midnight

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 asDuration
( an extension from the stx:libcompat package )

sigh

 asTimeStamp
( an extension from the stx:libcompat package )

typing different

 intervalString
( an extension from the stx:libcompat package )

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

Usage example(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

Usage example(s):

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

Usage example(s):

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.

 hours

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

Usage example(s):

Time now hours

 milliseconds

get the milliseconds part
(notice: that is NOT the total number of millis (since midnight),
but the fractional part only. Use this only for printing.
asMilliseconds or getMilliseconds is probably what you want

 minutes

return the number of minutes within the hour (i.e. 0..59).
(notice: that is NOT the total number of minutes (since midnight),
but the fractional part only. Use this only for printing.

Usage example(s):

Time now minutes

 seconds

return the number of seconds within the minute (i.e. 0..59).
(notice: that is NOT the total number of seconds (since midnight),
but the fractional part only. Use this only for printing.
asSeconds or getSeconds give you the nr of seconds since midnight

Usage example(s):

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 ask a local timestamp

Usage example(s):

Time now timeZoneDeltaInMinutes

 hash

return an integer useful for hashing on times

 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.

Usage example(s):

Time now asLocalTimestamp

 asTZTimestamp

return a TZTimestamp object from the receiver.
This includes the local timezone information.

Usage example(s):

Time now asTZTimestamp -> 2017-07-17 14:11:16+02 Time now asUtcTimestamp -> 2017-07-17 12:11:16Z Time now asLocalTimestamp -> 2017-07-17 14:11:16

 asTime

return a Time object from the receiver - that's the receiver.

 asTimeDuration

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

Usage example(s):

Time now asTimeDuration 10 asTimeDuration 10 seconds asTimeDuration '10m 20s' asTimeDuration

 asTimestamp

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

Usage example(s):

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.

Usage example(s):

Time now asTimestamp -> 2017-07-17 14:08:22 Time now asLocalTimestamp -> 2017-07-17 14:08:24 Time now asUtcTimestamp -> 2017-07-17 12:08:27Z

 differenceFromTimestamp: aTimestamp

return the time difference as a timeDuration instance.
Use only the time part of aTimestamp (so interpret it as a time today).

Usage example(s):

Time nowWithMilliseconds differenceFromTimestamp:Timestamp now. Time now differenceFromTimestamp:Time now + 1 seconds

 inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package )

returns a string to be shown in the inspector's list

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

Usage example(s):

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

Usage example(s):

Time now print24HourFormatOn:Transcript. Transcript cr

 printAsUTCIso8601FormatOn: aStream

prints the receiver as UTC time

Usage example(s):

Time now printString -> '04:23:33 PM' Time now printStringIso8601 -> 'T16:23:39' (notice: this is local time) Time now printAsUTCIso8601FormatOn:Transcript. Transcript cr. Time now printIso8601FormatOn:Transcript. Transcript cr.

 printIso8601CompressedOn: aStream

prints the receiver as local time

 printIso8601FormatOn: aStream

prints the receiver as local time

Usage example(s):

Time now printString -> '04:23:33 PM' Time now printStringIso8601 -> '16:23:39' (notice: this is local time) Time now printAsUTCIso8601FormatOn:Transcript. Transcript cr. Time now printIso8601FormatOn:Transcript. Transcript cr. Time now printIso8601CompressedOn:Transcript. Transcript cr.

 printIso8601FormatWithSubMilliseconds: withSubMilliseconds on: aStream

prints the receiver (as local time) with sub-millisecond resolution

Usage example(s):

(1 seconds + 30 milliseconds)printIso8601FormatOn:Transcript. Transcript cr; endEntry (1 seconds + 30 milliseconds)printIso8601FormatWithSubMilliseconds:false on:Transcript. Transcript cr; endEntry (1 seconds + 30 milliseconds)printIso8601FormatWithSubMilliseconds:true on:Transcript. Transcript cr; endEntry (1 seconds + 30 microseconds)printIso8601FormatOn:Transcript. Transcript cr; endEntry (1 seconds + 30 microseconds)printIso8601FormatWithSubMilliseconds:false on:Transcript. Transcript cr; endEntry (1 seconds + 30 microseconds)printIso8601FormatWithSubMilliseconds:true on:Transcript. Transcript cr; endEntry (1 seconds + 30 nanoseconds)printIso8601FormatOn:Transcript. Transcript cr; endEntry. (1 seconds + 30 nanoseconds)printIso8601FormatWithSubMilliseconds:true on:Transcript. Transcript cr; endEntry (1 seconds + 30 nanoseconds)printIso8601FormatWithSubMilliseconds:false on:Transcript. Transcript cr; endEntry (1 seconds + 30 milliseconds + 30 nanoseconds)printIso8601FormatOn:Transcript. Transcript cr; endEntry (1 seconds + 30 milliseconds + 30 nanoseconds)printIso8601FormatWithSubMilliseconds:true on:Transcript. Transcript cr; endEntry (1 seconds + 30 milliseconds + 30 nanoseconds)printIso8601FormatWithSubMilliseconds:false on:Transcript. Transcript cr; endEntry (1 seconds + 30 picoseconds)printIso8601FormatWithSubMilliseconds:true on:Transcript. Transcript cr; endEntry (1 seconds + 30 picoseconds - 1 seconds)

 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 don't know what ST-80 does here (12-hour format ?)

Usage example(s):

Time now printOn:Transcript. Transcript cr Time now printString Time now printStringIso8601

 printString12HourFormat

return a printed representation in 12 hour format

Usage example(s):

Time now printString12HourFormat

 printString24HourFormat

return a printed representation in 24 hour format

Usage example(s):

Time now printString24HourFormat

 shortPrintString

dummy - for now

 fromOSTime: osTime

set my time in the local timezone, given an osTime

 fromOSTimeWithMilliseconds: osTime

set my time in the local timezone, given an osTime

 fromUtcOSTime: osTime

set my time in the local timezone, given an osTime

 fromUtcOSTimeWithMilliseconds: osTime

set my time in the local timezone, given an osTime

 getMilliseconds

return the number of milliseconds since midnight.
Backward compatibility;
Please use getSecondsSinceMidnight for a self-explaining message name.
Notice that the receiver may or may not have millisecond resolution,
depending on whether it was created by Time now or by Time nowWithMilliseconds.
Notice:
does not include any timezone info (in contrast to Timestamp),
so this always represent a time depending on the context (usually: local)
Notice:
beacuse of that, always use Timestamps for comparisons.

Usage example(s):

Time now getMilliseconds Time nowWithMilliseconds getMilliseconds

 getMillisecondsSinceMidnight

return the number of milliseconds since midnight.
Notice that the receiver may or may not have millisecond resolution,
depending on whether it was created by Time now or by Time nowWithMilliseconds.
Notice:
does not include any timezone info (in contrast to Timestamp),
so this always represent a time depending on the context (usually: local)
Notice:
beacuse of that, always use Timestamps for comparisons.

 getSeconds

return the number of (truncated) seconds since midnight.
Backward compatibility;
Please use getSecondsSinceMidnight for a self-explaining message name

 getSecondsSinceMidnight

return the number of (truncated) seconds since midnight

 getSecondsWithinHour

return the number of (truncated) seconds within the hour.

 setHours: h minutes: m seconds: s

set my time given individual values

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

set my time given individual values

 setMilliseconds: millis

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

 setMilliseconds: millis additionalPicoseconds: ignoredPicos

for protocol compatibility with timestamp.
However, the picos are ignored here

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

Usage example(s):

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

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

 isTime

(comment from inherited method)
return true if the receiver is some kind of time;
false is returned here - the method is only redefined in Time.

 acceptVisitor: aVisitor with: aParameter

dispatch for visitor pattern; send #visitTime:with: to aVisitor