Class: TZTimestamp

• Inheritance
• Description
• Class protocol
  • instance creation
• Instance protocol
  • accessing
  • converting
  • private
  • testing

Inheritance:

   Object
   |
   +--Magnitude
      |
      +--AbstractChronologyObject
         |
         +--AbstractTime
            |
            +--Timestamp
               |
               +--TZTimestamp

Package:

stx:libbasic

Category:

Kernel-Chronology

Version:

rev: 1.23 date: 2023/07/07 12:53:13

user: cg

file: TZTimestamp.st directory: libbasic

module: stx stc-classLibrary: libbasic

Description:

This class represents time values in milliSeconds starting some time in the past,
which were created in a particular (explicit) timezone.
Internally, they keep the milliseconds based on UTC time (just like the other timestamps),
so the time values can be compared easily.
However, when printed, the original timezone information is taken into account.

Also Note:
    On UNIX, osTime can only hold dates between 1970-01-01T00:00:00Z and 2038-01-19T00:00:00Z
    However, timestamp instances can hold negative osTime values (which are timestamps
    before 1.1.1970 and greater than 4294967295 (2^32-1) for timestamps after 2038-01-19.

[example:]
  the current time as local time (no TZ info):
    Transcript showCR:Timestamp now

  the current time in your timezone:       
    Transcript showCR:TZTimestamp now.
  same:
    Transcript showCR:Timestamp now asTZTimestamp.

  the current time as utc time:       
    Transcript showCR:UtcTimestamp now.
  same:
    Transcript showCR:Timestamp now asUtcTimestamp.

  the current time in NewYork:         
    Transcript showCR:( Timestamp now asTZTimestamp:(Timestamp utcOffsetFrom:'EST') ) 
  same
    Transcript showCR:( Timestamp now asTZTimestampInZone:'EST' )
  same
    Transcript showCR:( Timestamp now asTZTimestamp:(5*3600) ) 

  what is the current time in Berlin:
    Transcript showCR:( Timestamp now asTZTimestampInZone:'MEZ' ) 

  and the date:
    Transcript showCR:( Timestamp now asTZTimestampInZone:'MEZ' ) asDate
  and the date in Tokio:
    Transcript showCR:( Timestamp now asTZTimestampInZone:'JST' ) asDate
  and the date in Hawai:
    Transcript showCR:( Timestamp now asTZTimestampInZone:'HAST' ) asDate
  and the date in NewYork:
    Transcript showCR:( Timestamp now asTZTimestampInZone:'EST' ) asDate

copyright
COPYRIGHT (c) 2014 by eXept Software AG
             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:

 fromDate: aDate andTime: aTime utcOffset: utcOffsetSeconds

return an instance of the receiver,
initialized from a time and a date object.
utcOffset: is positive towards the east.
Both date and time are assumed to be the utcOffset's local time.
See also `Timestamp now' and other protocol inherited
from my superclass.

Usage example(s):

Timestamp fromDate:(Date today) andTime:(Time now) Timestamp fromDate:(Date today) andTime:(Time nowWithMilliseconds) TZTimestamp fromDate:(Date today) andTime:(Time now) utcOffset:3600 Timestamp fromDate:(Date today plusDays:1) andTime:(Time now) Timestamp now

 new

return a timestamp for this timezone (osTime is uninitialized)

Instance protocol:

 isLocalTimestamp

return true, if I am a local timestamp (i.e. with no TZ info)

 timeInfo

fake it. Convert to utc, ask OS for the info, then convert back.
This is returns wrong info for weekday and we have to compensate again.
Also, it (currently) only works for timestamps after the epoch

 utcOffset

return the difference between UTC (Greenwich Mean Time) and the local time in seconds.
If daylight saving time applies to ourself, take that into account.

Add utcOffset to convert from local time to UTC time.
Subtract utcOffset to convert from UTC time to local time.

If utcOffset is negative, the local timezone is east of Greenwich.
If utcOffset is positive, the local timezone is west of Greenwich.

Usage example(s):

TZTimestamp now utcOffset => -3600 UtcTimestamp now utcOffset => 0

 utcOffset: secondsOrTimeDuration

set the difference between UTC (Greenwich Mean Time) and the local time in seconds.
If daylight saving time applies to ourself, take that into account.

Add utcOffset to convert from local time to UTC time.
Subtract utcOffset to convert from UTC time to local time.

If utcOffset is negative, the local timezone is east of Greenwich.
If utcOffset is positive, the local timezone is west of Greenwich.

 asLocalTimestamp

return a local timestamp, representing the same time as the receiver

 asTZTimestamp: utcOffsetArg

return a timestamp in a given timezone, representing the same time as the receiver

Usage example(s):

what is the time now in NewYork? Timestamp now asTZTimestamp:(Timestamp utcOffsetFrom:'EST') what is the time now in Stuttgart? Timestamp now asTZTimestamp:(Timestamp utcOffsetFrom:'MEZ')

 midnight

return an Timestamp instance, representing midnight of last night in that very timezone

Usage example(s):

UtcTimestamp now => 2023-06-06 19:50:56.039Z UtcTimestamp now midnight => 2023-06-06 00:00:00Z midnight local: TZTimestamp now => 2023-06-06 20:50:40.631+01 TZTimestamp now midnight => 2023-06-06 00:00:00+02 midnight somewhere in the east: (TZTimestamp now utcOffset:-36000) midnight => 2023-06-06 00:00:00+10

 speciesNew

 storeStringClass

my storeString will ask Timestamp to read the instance

 isTZTimestamp

return true, if I am a timestamp with TZ info