eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Time':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: Time


Inheritance:

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

Package:
stx:libbasic
Category:
Magnitude-Time
Version:
rev: 1.118 date: 2019/05/08 11:06:46
user: cg
file: Time.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

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


Related information:

    Date
    Timestamp
    AbstractTime
    OperatingSystem
    Filename

Class protocol:

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

o  defaultFormatStringWithMilliseconds

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

o  formatString24
return the format string used to format non US times

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

o  formatStringWithMilliseconds24
return the format string used to format non US times

instance creation
o  fromString: aString
Modified (format): / 20-08-2011 / 16:46:39 / cg

o  hour: h minute: m
compatibility

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

o  hour: h minute: m second: s
compatibility

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

o  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) **

o  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  

o  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

o  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

o  midnight
Answer a new instance at midnight.

usage example(s):

     Time midnight

o  noon
Answer a new instance at noon.

usage example(s):

     Time noon

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

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

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'

o  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

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

Compatibility-Backward
o  asMilliSeconds
return the number of milliseconds elapsed since midnight

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

Compatibility-Squeak
o  intervalString
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

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

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

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

usage example(s):

     Time now hours

o  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

o  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

o  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

o  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

comparing
o  hash
return an integer useful for hashing on times

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

o  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

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

o  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

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

usage example(s):

      Time now asTimestamp

o  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

double dispatching
o  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

printing & storing
o  inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package )
returns a string to be shown in the inspector's list

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

o  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

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

o  printIso8601CompressedOn: aStream
prints the receiver as local time

o  printIso8601FormatOn: aStream
prints the receiver as local 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. 

o  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

o  printString12HourFormat
return a printed representation in 12 hour format

usage example(s):

     Time now printString12HourFormat

o  printString24HourFormat
return a printed representation in 24 hour format

usage example(s):

     Time now printString24HourFormat

o  shortPrintString
dummy - for now

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

o  fromOSTimeWithMilliseconds: osTime
set my time in the local timezone, given an osTime

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

o  fromUtcOSTimeWithMilliseconds: osTime
set my time in the local timezone, given an osTime

o  getMilliseconds
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.

usage example(s):

     Time now getMilliseconds
     Time nowWithMilliseconds getMilliseconds

o  getSeconds
return the number of (truncated) seconds since midnight

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

o  setHours: h minutes: m seconds: s milliseconds: ms
set my time given individual values

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

o  setMilliseconds: millis additionalPicoseconds: ignoredPicos
for protocol compatibility with timestamp.
However, the picos are ignored here

o  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

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

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

visiting
o  acceptVisitor: aVisitor with: aParameter
dispatch for visitor pattern; send #visitTime:with: to aVisitor



ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Fri, 29 Mar 2024 10:27:09 GMT