Smalltalk/X Webserver

Documentation of class 'Timestamp':

Class: Timestamp

Inheritance
Description
Class protocol
Instance protocol
Private classes

Inheritance:

   Object
   |
   +--Magnitude
      |
      +--AbstractChronologyObject
         |
         +--AbstractTime
            |
            +--Timestamp
               |
               +--JavaScriptEnvironment::Date
               |
               +--TZTimestamp
               |
               +--UtcTimestamp

Package:: stx:libbasic

Category:: Kernel-Chronology

Version:: rev: 1.319 date: 2024/04/22 16:44:29; user: stefan; file: Timestamp.st directory: libbasic; module: stx stc-classLibrary: libbasic

Description:

This class represents time values in milliseconds (*), starting some time in the past.
This base-time is called 'epoch' and always an UTC time.

When printing and accessing values like #hour,
the timestamp will be interpreted in the local timezone.
(as opposed to UtcTimestamp, which presents itself in UTC,
and as opposed to TZTimestamp, which remembers the timezone in which it was created).

The internal representation, osTime, will typically start with 1970-01-01 00:00 UTC,
as used in the Unix operating system, but other systems may bias the time differently.
Actually, the implementation does not depend or even know which time/date
the OperatingSystem bases its time upon - it is simply keeping the value(s)
as returned from the OS.
For conversion, these values are given back to the OS, which will know
how to convert them. This has the advantage that timestamps on files
(such as last-access-time or last-modification-time) can be handled transparently -
especially when performing comparisons.

You should not interpret the osTime instance variable directly,
instead (if at all), ask the OS to convert.

The implementation of this class is not the same as in ST-80
(which represents the time as seconds from Jan 1., 1901).

This class should not be confused with Time (which only represents the time within one day).
Time instances cannot be used to compare times across midnight, whereas instances of Timestamp can.
Also, it should not be confused with TimeDuration, which represents a time-difference.

Notice:
this class was once called AbsoluteTime. Einstein told us in 1905, that talking
about an absolute time is not a good idea (at least in our universe). So in 2004 the class
has been renamed to Timestamp which makes us more compatible to other ST dialects (e.g. VW)
AbsoluteTime was kept as an alias for backward compatibility and was finally removed in 2017.

Also Note:
On (older) UNIXes, osTime can only hold dates between 1970-01-01T00:00:00Z and 2038-01-19T03:14:07Z
However, timestamp instances can hold negative osTime values (which are timestamps
before 1.1.1970 and also osTimes greater than 4294967295 (2^32-1) for timestamps after 2038-01-19.
Thus, ST/X never had a problem in dealing with dates before the epoch or after 2038.

For dates before 1582 (when calendars were changed from Julian to Gregorian),
the so called 'proleptic gregorian calendar' is used. This assumes leap years to continue in
the past as if a gregorian calendar was used. Thus, 0000 is considered a leap year.

Also Note:
because all timestamps keep the internal time value in UTC, they can be easily compared
for being before/same/after another. Only when printing, a difference is made.
The timezone is compensated out when a timestamp is created and recalculated in when printed.

(*) News:
The additional instance variable picoSeconds can be used to add more resolution.
If non-nil, it holds additional picoseconds to be added to the millisecond osTime
(i.e. the picoSeconds are an integer between 0 and 1000*1000*1000.

Although, not all OSs give us that detail when asking for the current time,
the picos can still be used in physical computations.
Some OSs will provide microsecond resolution.
Notice:
the picos are to be added to the millis, to get picos within the second.
this is ugly, but makes all the rest backward compatible.
Also, most timestamps only require/have millisecond resolution,
so the pico instvar is nil/0 and does not require an aditional largeInteger operation.

The typical OS-time resolution is in the milli- or microsecond range.
External logging hardware may generate timestamps in the micro- or nanosecond range.
Picosecond resolution should be good enough for almost any application (at least for the near future).

The separation into osTime and picos was done to prevent the use of LargeIntegers,
which are more expensive to compute and compare (timestamps are created many in some apps).
Also, most timestamps do not even have a pico attached (OSs do not provide them), but some
hi-tec measurement devices do and it is needed in some expecco testsuites.

[aliases:]
DateAndTime (ANSI)

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:

Compatibility-Squeak

current

readFrom: aStringOrStream

Answer a new instance for the value given by aStringOrStream

Usage example(s):

     self readFrom:'23-jun-2000 15:00'
     self fromString:'23-jun-2000 15:00'
     self readFrom:'23-jun-2000 '

year: year day: dayInYear

return a new Timestamp, given the year and the day-in-year (starting at 1).
See also: Date today / Time now / Timestamp now.
Squeak compatibility

Usage example(s):

     self year:1970 day:1
     self year:2000 day:1

year: year month: month day: day hour: hour minute: minute second: second millisecond: millisecond offset: timeDuration

Timestamp year:2015 month:11 day:9 hour:12 minute:0 second:0 millisecond:0 offset:(2 hours)

year: year month: month day: day hour: hour minute: minute second: second offset: timeDuration

Timestamp year:2015 month:11 day:9 hour:12 minute:0 second:0 offset:(2 hours)
Timestamp year:2015 month:11 day:9 hour:12 minute:0 second:0 offset:0

class access

timestampISO8601Builder: I hate private class overuse...
... I need such ugly hacks whenever someone thinks that he/she must keep a secret...
See Time for such its use

format strings

defaultFormatString: a format string to present times in user interfaces.
Do not use this to store/retrieve times (use ISO8601 for that).
Although the string below looks like ISO8601, it does not include TZ information,
so when read back, it will always be interpreted as a local timestamp.

initialization

initialize: (comment from inherited method)
Modified (comment): / 07-06-2023 / 10:43:03 / alkurz

instance creation

UTCYear: y month: m day: d hour: h minute: min second: s millisecond: millis

return an instance of the receiver, given individual components,
interpreted in the UTC timezone.

Usage example(s):

     Timestamp UTCYear:1970 month:1 day:1 hour:0 minute:0 second:0 millisecond:0
     Timestamp UTCYear:1991 month:1 day:2 hour:12 minute:30 second:0 millisecond:0
     Timestamp UTCYear:1991 month:1 day:2 hour:12 minute:30 second:0 millisecond:100
     Timestamp UTCYear:1999 month:7 day:1 hour:1 minute:0 second:0 millisecond:0
     Timestamp UTCYear:2000 month:1 day:1 hour:1 minute:0 second:0 millisecond:0

     UtcTimestamp UTCYear:2000 month:1 day:1 hour:1 minute:0 second:0 millisecond:0

UTCYear: y month: m day: d hour: h minute: min second: s millisecond: millis additionalPicoseconds: picos

return an instance of the receiver, given individual components,
interpreted in the UTC timezone.

Usage example(s):

     Timestamp UTCYear:1970 month:1 day:1 hour:0 minute:0 second:0 millisecond:0
     Timestamp UTCYear:1991 month:1 day:2 hour:12 minute:30 second:0 millisecond:0
     Timestamp UTCYear:1991 month:1 day:2 hour:12 minute:30 second:0 millisecond:100
     Timestamp UTCYear:1999 month:7 day:1 hour:1 minute:0 second:0 millisecond:0
     Timestamp UTCYear:2000 month:1 day:1 hour:1 minute:0 second:0 millisecond:0

     UtcTimestamp UTCYear:2000 month:1 day:1 hour:1 minute:0 second:0 millisecond:0

decodeFromLiteralArray: anArray

decode a Timestamp literalArray.

anArray may be:
#(Timestamp '200004182000.123')

or the deprecated old format, that is not portable between different architectures.
We parse this for backward compatibility (will be eventually removed).

#(Timestamp #osTime: 12345678)

Usage example(s):

     Timestamp
        decodeFromLiteralArray:#(Timestamp '20050323175226.014')
     Timestamp
        decodeFromLiteralArray:#(Timestamp '20050323175226.014-01')
     Timestamp
        decodeFromLiteralArray:#(Timestamp '20050323175226.014Z')

epoch

the epoch is based to 0 for 1970-01-01 00:00:00 (i.e. this is the Unix epoch).
However, we allow negative values to represent timestamps before that

fromDate: aDate

return an instance of the receiver, initialized from a time and a date
object.
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 plusDays:1) andTime:(Time now)
     Timestamp now

fromDate: aDate andTime: aTime

return an instance of the receiver, initialized from a time and a date
object.
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)

     Timestamp fromDate:(Date today plusDays:1) andTime:(Time now)
     Timestamp now

fromDate: aDate hour: hour minute: minute second: second

return an instance of the receiver, initialized from a time and a date object.
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) hour:10 minute:5 second:30

fromDate: aDate hour: hour minute: minute second: second microsecond: micros

return an instance of the receiver, initialized from a time and a date object.
See also `Timestamp now' and other protocol inherited from my superclass.

Usage example(s):

     Timestamp fromDate:(Date today) hour:10 minute:5 second:30 microsecond:123456
     Timestamp fromDate:(Date today) hour:10 minute:5 second:30 microsecond:140

fromDate: aDate hour: hour minute: minute second: second millisecond: millis

return an instance of the receiver, initialized from a time and a date object.
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)
     Timestamp fromDate:(Date today) hour:10 minute:5 second:30 millisecond:140

fromDate: aDate hour: hour minute: minute second: second nanosecond: nanos

return an instance of the receiver, initialized from a time and a date object.
See also `Timestamp now' and other protocol inherited from my superclass.

Usage example(s):

     Timestamp fromDate:(Date today) hour:10 minute:5 second:30 microsecond:123456
     Timestamp fromDate:(Date today) hour:10 minute:5 second:30 microsecond:140

fromDateAndTime: aDateAndTimePair

return an instance of the receiver, initialized from a date and time pair
See also `Timestamp now' and other protocol inherited from my superclass.

Usage example(s):

     Timestamp fromDateAndTime:{ Date today . Time now}

newDay: dayInYear year: year

return a new Timestamp, given the year and the day-in-year (starting at 1).
Date protocol compatibility

Usage example(s):

     Timestamp newDay:183 year:1996
     Timestamp newDay:1 year:1996

newWithTimeZone: timeZoneName

return a timestamp for this timezone (osTime is uninitialized)

nowInTimeZone: tzName

return an instance of myself representing this moment with at least second precision.
Timestamps will redefine this to always return millisecond precision.

Usage example(s):

     TZTimestamp readFrom:'2023-07-07 15:58:24.235 EEST'  => 2023-07-07 15:58:24.235+00     
     TZTimestamp readFrom:'2023-07-07 15:58:24.235+03'    => 2023-07-07 15:58:24.235+03     
     TZTimestamp readFrom:'2023-07-07 15:58:24.235EEST'   => 2023-07-07 15:58:24.235+03

     TZTimestamp nowInTimeZone:'CEST'   => 2023-07-07 14:58:06.329+02
     TZTimestamp nowInTimeZone:'EET'    => 2023-07-07 14:58:10.883+02
     TZTimestamp nowInTimeZone:'EEST'   => 2023-07-07 15:58:24.235+03
     TZTimestamp now                    => 2023-07-07 14:58:33.203+02
     Timestamp now                      => 2023-07-07 14:58:46.155
     UtcTimestamp now                   => 2023-07-07 12:58:52.851Z
     Timestamp now asTZTimestampInZone:'JST'  => 2023-08-14 22:05:55.513+09
     Timestamp nowInTimeZone:'JST'            => 2023-08-14 22:05:42.076+09
     Time now                           => 14:59:00

     Timestamp now utcOffset            => -7200
     (TZTimestamp now) utcOffset        => -7200
     (TZTimestamp nowInTimeZone:'EEST') utcOffset => -10800

secondsSince1900: secs

set time from elapsed seconds since 1-1-1900, 00:00:00 (UTC).
This is the format used in the NTP world.
Notice that the internal storage is always UTC based.

Usage example(s):

     UtcTimestamp secondsSince1900:0        -> 1900-01-01 00:00:00Z       
     Timestamp secondsSince1900:0           -> 1900-01-01 01:00:00 (local germany, ST)

     UtcTimestamp secondsSince1900:3600     
     UtcTimestamp secondsSince1900:3600*24  

     (Timestamp year:2010 month:7 day:1 hour:0 minute:0 second:0)
       =
     (Timestamp secondsSince1970:1277935200)  

     (Timestamp year:2010 month:7 day:1 hour:0 minute:0 second:0)
       =
     (Timestamp secondsSince1900:1277935200+2208988800)

secondsSince1901: secs

set time from elapsed seconds since 1-1-1901, 00:00:00 (UTC).
This is the format used in the Windows world.
Notice that the internal storage is always UTC based.

Usage example(s):

     UtcTimestamp secondsSince1901:0        -> 1900-01-01 00:00:00Z       
     Timestamp secondsSince1901:0           -> 1900-01-01 01:00:00 (local germany, ST)

     UtcTimestamp secondsSince1901:3600     
     UtcTimestamp secondsSince1901:3600*24  

     (Timestamp year:2010 month:7 day:1 hour:0 minute:0 second:0)
       =
     (Timestamp secondsSince1970:1277935200)  

     (Timestamp year:2010 month:7 day:1 hour:0 minute:0 second:0)
       =
     (Timestamp secondsSince1901:1277935200+2177452800)

secondsSince1970: secs

set time from elapsed seconds since 1-1-1970, 00:00:00 (UTC).
This is the format used in the UNIX world.
Notice that the internal storage is always UTC based.

Usage example(s):

     UtcTimestamp secondsSince1970:0        -> 1970-01-01 00:00:00Z       
     Timestamp secondsSince1970:0           -> 1970-01-01 01:00:00 (local germany, ST)

     can be negative
     UtcTimestamp secondsSince1970:-3600    -> 1969-12-31 23:00:00Z
     can be negative
     UtcTimestamp secondsSince1970:(-3600 * 24 * 356 * 100) -> 1872-07-13 00:00:00Z

     Timestamp secondsSince1970:3600
     Timestamp secondsSince1970:3600*24

     (Timestamp year:2010 month:7 day:1 hour:0 minute:0 second:0)
       =
     (Timestamp secondsSince1970:1277935200)

utcMillisecondsSince1970: millis

set time from elapsed milliseconds since the epoch 1-1-1970, 00:00:00.

utcNow

return now as utc timestamp

Usage example(s):

     Timestamp now
     Timestamp utcNow

utcSecondsSince1970: secs

set time from the elapsed seconds since 1-1-1970, 00:00:00 UTC.
This is the format used in the UNIX world.
Notice that the internal storage is always UTC based.

year: year month: month day: day

return a new Timestamp, given the year, month and day (starting at 1).
Date protocol compatibility

Usage example(s):

     Timestamp year:1996 month:1 day:1

year: y month: m day: d hour: h minute: min second: s

return an instance of the receiver, given individual components.
See also `Timestamp now' and other protocol inherited
from my superclass.

Usage example(s):

     Timestamp year:1970 month:1 day:1 hour:1 minute:0 second:0
     Timestamp year:1991 month:1 day:2 hour:12 minute:30 second:0
     Timestamp year:1991 month:1 day:2 hour:12 minute:30 second:0 millisecond:100
     Timestamp year:2000 month:7 day:1 hour:1 minute:0 second:0
     Timestamp year:2080 month:7 day:1 hour:1 minute:0 second:0

year: y month: m day: d hour: h minute: min second: s microsecond: micros

return an instance of the receiver, given individual components.
See also `Timestamp now' and other protocol inherited
from my superclass.

Usage example(s):

     Timestamp year:1991 month:1 day:2 hour:12 minute:30 second:0 microsecond:100

year: y month: m day: d hour: h minute: min second: s millisecond: millis

return an instance of the receiver, given individual components.
See also `Timestamp now' and other protocol inherited
from my superclass.

Usage example(s):

     Timestamp year:1970 month:1 day:1 hour:0 minute:0 second:0
     Timestamp year:1991 month:1 day:2 hour:12 minute:30 second:0
     Timestamp year:1991 month:1 day:2 hour:12 minute:30 second:0 millisecond:100
     Timestamp year:2000 month:7 day:1 hour:1 minute:0 second:0
     UtcTimestamp year:2000 month:7 day:1 hour:1 minute:0 second:0

year: y month: m day: d hour: h minute: min second: s millisecond: millis additionalPicoseconds: picos

return an instance of the receiver, given individual components.
See also `Timestamp now' and other protocol inherited
from my superclass.

Usage example(s):

     Timestamp year:1970 month:1 day:1 hour:0 minute:0 second:0
     Timestamp year:1991 month:1 day:2 hour:12 minute:30 second:0
     Timestamp year:1991 month:1 day:2 hour:12 minute:30 second:0 millisecond:100
     Timestamp year:2000 month:7 day:1 hour:1 minute:0 second:0
     UtcTimestamp year:2000 month:7 day:1 hour:1 minute:0 second:0

obsolete

day: d month: m year: y hour: h minutes: min seconds: s: This is obsolete. User #year:month:day:hour:minute:second:

** This is an obsolete interface - do not use it (it may vanish in future versions) **
day: d month: m year: y hour: h minutes: min seconds: s milliseconds: millis: This is obsolete. User #year:month:day:hour:minute:second:millisecond:

** This is an obsolete interface - do not use it (it may vanish in future versions) **
newDay: day month: month year: year: return a new Timestamp, given the year, month and day (starting at 1).
Date protocol compatibility.
Obsolete: use year:month:day:.

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

private

basicReadFrom: aStream

return a new Timestamp, reading a printed representation from aStream.
The string is interpreted as 24 hour format, as printed.

Notice, that this is NOT the storeString format, which is iso8601
This is more or less a heuristic attempt to read any reasonable format.
If the input starts with an integer > 31,
it is assumed to be a year and the rest is read in iso8601 format.

KLUDGE:
us and non-us format have different ordering of day and month;
The format read here is (non-us) dd-mm-yyyy hh:mm:ss.iii
or (us-format, for Travis) mm/dd/yyyy hh:mm:ss.iii
or (us-format with year first) yyyy-mm-ddThh:mm:ss.iii
On error, raise an exception

Usage example(s):

some ad hoc formats:

     Timestamp basicReadFrom:'20-2-1995 13:11:06' readStream
     Timestamp basicReadFrom:'20-2-1995 13:11:06.' readStream
     Timestamp basicReadFrom:'20-feb-1995 13:11:06' readStream
     Timestamp basicReadFrom:'20-foo-1995 13:11:06' readStream
     (Timestamp basicReadFrom:'10-9-1995 13:11:06' readStream) month    - european
     (Timestamp basicReadFrom:'10/9/1995 13:11:06' readStream) month    - us
     Timestamp basicReadFrom:'20-2-1995 13:11' readStream
     Timestamp basicReadFrom:'20-2-1995 13:11:06.100' readStream
     Timestamp basicReadFrom:'20-2-1995 13:11:06.100 MESZ' readStream
     Timestamp basicReadFrom:'20-2-1995 13:11:06.100+0200' readStream
     Timestamp basicReadFrom:'32-2-1995 13:11:06.100' readStream
     Timestamp basicReadFrom:'32-foo-1995 13:11:06.100' readStream
     Timestamp basicReadFrom:'20-13-1995 13:11:06.100' readStream
     Timestamp basicReadFrom:'20-12-1995 25:11:06.100' readStream
     Timestamp basicReadFrom:'20-12-1995 23:61:06.100' readStream
     Timestamp basicReadFrom:'20-12-1995 23:10:66.100' readStream
     Timestamp basicReadFrom:'20-12-1995 23:10:00.1000' readStream
     Timestamp basicReadFrom:'20-2-1995 24:01:00.100' readStream
     Timestamp basicReadFrom:'20-2-1995 24:00:01.100' readStream
     Timestamp basicReadFrom:'foo' readStream

     any iso8601 format:.
     Timestamp basicReadFrom:(Timestamp now printString readStream)    
     Timestamp basicReadFrom:'1995-10-20 24:00:00.000' readStream      
     Timestamp basicReadFrom:'1995-10-20 12:10:00.000' readStream      
     Timestamp basicReadFrom:'1995-10-20 12:10:00.000-0200' readStream 

     Timestamp basicReadFrom:'1995-10-20T12:10:00.001' readStream       -- millis
     Timestamp basicReadFrom:'1995-10-20T12:10:00.000001' readStream    -- micros
     Timestamp basicReadFrom:'1995-10-20T12:10:00.000000001' readStream -- nanos
     Timestamp basicReadFrom:'1995-10-20T12:10:00.000000000001' readStream -- picos
     Timestamp basicReadFrom:'2018-03-30T03:24:00'readStream  
     Timestamp basicReadFrom:'2018-3-30T03:24:00'readStream   

     UtcTimestamp basicReadFrom:'1995-10-20 12:10:00.000' readStream

readIso8601FormatFrom: aStringOrStream yearAlreadyRead: yearOrNil

common helper for read methods.
Return a new Timestamp, reading an iso8601 representation from aStream.

If the time ends with a 'Z' it is the UTC (or zulu) time,
otherwise it is local time.

Missing month/day values are replaced with 1; i.e. 1999T24:00
is the same as 1999-01-01T24:00:00.
Missing minute, second and ms values are replaced with 0;
i.e. 1999T12 is the same as 1999-01-01T12:00:00.000.
Partial hours, minutes, seconds are allowed at the end,
decimal separators are both $. and $, .
Of course, a 24 hour clock is used.
On error, raise an exception.
Please use this format for all external representations - it's the standard.

Usage example(s):

     Timestamp readIso8601FormatFrom:'1995-02-20T13:11:06.123'
     Timestamp readIso8601FormatFrom:'1995-02-20T13:11:06'
     Timestamp readIso8601FormatFrom:'1995-02T13:11:06'
     Timestamp readIso8601FormatFrom:'1995T13:11:06'
     Timestamp readIso8601FormatFrom:'1995T13:11'
     Timestamp readIso8601FormatFrom:'1995T13:11.5'
     Timestamp readIso8601FormatFrom:'1995T13:11,5'
     Timestamp readIso8601FormatFrom:'1995T13'
     Timestamp readIso8601FormatFrom:'1995T13.25'
     Timestamp readIso8601FormatFrom:'1995T13.333333'
     Timestamp readIso8601FormatFrom:'1995'

     Timestamp readIso8601FormatFrom:'2014W40'   -> 29.sep.2014
     Timestamp readIso8601FormatFrom:'2014W44-4' -> 30.oct.2014
     Timestamp readIso8601FormatFrom:'2014W1'    -> 30.dec.2013      !!! (this week starts in the previous year)
     Timestamp readIso8601FormatFrom:'2014W1-1'  -> same 30.dec.2013 !!! (this week starts in the previous year)
     Timestamp readIso8601FormatFrom:'2014W1-2'  -> 31.dec.2013      !!! (this week starts in the previous year)
     Timestamp readIso8601FormatFrom:'2014W1-3'  -> 1.jan.2014       !!! (this week starts in the previous year)

     Timestamp readIso8601FormatFrom:'1995-02-20 13:11:06'
     Timestamp readIso8601FormatFrom:'1995-02-20 13:11:06Z'

     Timestamp readIso8601FormatFrom:'1995-02-20 13:11'
     Timestamp readIso8601FormatFrom:'1995-02-20 13'

   24 is allowed with ISO, and is 00:00 of the next day:
     Timestamp readIso8601FormatFrom:'1995-02-20 24:00:00'

readIso8601FormatFrom: aStringOrStream yearAlreadyRead: yearOrNil onError: exceptionValue

common helper for read methods.

timezoneInfo

marked as obsolete by exept MBP at 06-06-2023

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

timezoneTable

marked as obsolete by exept MBP at 06-06-2023

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

reading

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

return a new Timestamp, 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 kept
%F fractional seconds any length, up to picoseconds kept
%a am/pm
%tz timezone

%d - day
%D - day
%(day) - day
%(dayOfYear) - 1..365/366

%(month) - month

%(monthName) - monthName

%(year) - year, full 4 digits
%Y - year, last 2 digits only,
0..71 map to 2000..2071;
72..99 map to 1972..1999;
%Y1900 - year, last 2 digits only, map to 1900..1999
%Y2000 - year, last 2 digits only, map to 2000..2099
%Y1950 - year, last 2 digits only, map to 1950..2049
%Y1980 - year, last 2 digits only, map to 1980..2079
%Y1970 - year, last 2 digits only, map to 1970..2069

an optional length after the % gives a field length;
i.e. %2h%2m%2s parses '123557' as 12:35:37
and '%4(year)%2(month)%2(day)' parses '20060620' as 2006-06-20 00:00:00

Please consider using a standard format, such as iso8601.

Usage example(s):

     Timestamp readFrom:'20-2-1995 13:11:06' format:'%day-%month-%year %h:%m:%s' language:nil onError:[self halt]
     Timestamp readFrom:'20021995131106' format:'%2d%2month%4y%2h%2m%2s' language:nil onError:[self halt]
     Timestamp readFrom:'200295131106' format:'%2d%2month%2y%2h%2m%2s' language:nil onError:[self halt]
     Timestamp readFrom:'200260131106' format:'%2d%2month%2(y1900)%2h%2m%2s' language:nil onError:[self halt]
     Timestamp readFrom:'200260131106' format:'%2d%2month%2(y2000)%2h%2m%2s' language:nil onError:[self halt]
     Timestamp readFrom:'200260131106' format:'%2d%2month%2(y1950)%2h%2m%2s' language:nil onError:[self halt]
     Timestamp readFrom:'200260131106' format:'%2d%2month%2(y1980)%2h%2m%2s' language:nil onError:[self halt]
     Timestamp readFrom:'March 7 2009 7:30pm EST' format:'%monthName %day %year %u:%m%a %tz' language:#en onError:[self halt]
     Timestamp readFrom:'March 7 2009 7:30pm UTC' format:'%monthName %day %year %u:%m%a %tz' language:#en onError:[self halt]
     Timestamp readFrom:'2015103' format:'%4y%3dayOfYear' onError:[self halt]

     Timestamp readFrom:'20-2-1995 13:11:06.999' format:'%day-%month-%year %h:%m:%s.%i' language:nil onError:[self halt]
     Timestamp readFrom:'20-2-1995 13:11:06.100' format:'%day-%month-%year %h:%m:%s.%i' language:nil onError:[self halt]
     Timestamp readFrom:'20-2-1995 13:11:06.010' format:'%day-%month-%year %h:%m:%s.%i' language:nil onError:[self halt]

     Timestamp readFrom:'20-2-1995 13:11:06.1' format:'%day-%month-%year %h:%m:%s.%f' language:nil onError:[self halt]
     Timestamp readFrom:'20-2-1995 13:11:06.01' format:'%day-%month-%year %h:%m:%s.%f' language:nil onError:[self halt]
     Timestamp readFrom:'20-2-1995 13:11:06.001' format:'%day-%month-%year %h:%m:%s.%f' language:nil onError:[self halt]
     Timestamp readFrom:'20-2-1995 13:11:06.12345' format:'%day-%month-%year %h:%m:%s.%f' language:nil onError:[self halt]

readFrom: aStringOrStream onError: exceptionBlock

return a new Timestamp, reading a printed representation from aStream.
The string is interpreted as 24 hour format, as printed.
Notice, that this is not the storeString format and
is different from the format expected by readFrom:.
The format read here is either dd-mm-yyyy hh:mm:ss.iii
or iso8601 (if the first integer is >31).

Please consider using a standard format, such as iso8601.

Usage example(s):

     Timestamp readFrom:'20-2-1995 13:11:06'
     Timestamp readFrom:'20-2-1995 13:11'
     Timestamp readFrom:'20-2-2001 13:11'
     Timestamp readFrom:'20-2-1995 13:11:06.100'
     Timestamp readFrom:'32-2-1995 13:11:06.100' onError:'wrong'
     Timestamp readFrom:'32-foo-1995 13:11:06.100' onError:'wrong'
     Timestamp readFrom:'20-2-1995 24:01:00.100' onError:'wrong'
     Timestamp readFrom:'20-2-1995 24:00:01.100' onError:'wrong'
     Timestamp readFrom:'2002-08-02 24:00:01.100' onError:'wrong'
     Timestamp readFrom:'foo' onError:'wrong'
     Timestamp readFrom:(Timestamp now storeString) onError:'wrong'

readGeneralizedFrom: aStringOrStream

return a new Timestamp, reading a printed representation from aStream.
The format read here is either
yyyymmddHHMMSS.iii+uuuu, which is the ASN1 GeneralizedTime format.
or:
yyyy-mm-dd HH:MM:SS.iii +uuuu.
The string is interpreted as 24 hour format, as printed.

This format is used for BER specification of the ASN.1 GeneralizedTime as defined in X.208 Sec. 33,
so read this before changing anything here.

New applications should consider using a standard format, such as iso8601.

Notice, that this is not the storeString format and
is different from the format expected by readFrom:.

readGeneralizedFrom: aStringOrStream onError: exceptionBlock

readGeneralizedFrom: aStringOrStream short: shortFormat onError: exceptionBlock

return a new Timestamp, reading a printed representation from aStream.
The long format read here is either
yyyymmddHHMMSS.iii+uuuu, which is the ASN1 GeneralizedTime format.
or:
yyyy-mm-dd HH:MM:SS.iii +uuuu.
The (not recommended) short forms are:
yymmddHHMMSS.iii+uuuu, which is the ASN1 GeneralizedTime format.
or:
yy-mm-dd HH:MM:SS.iii +uuuu.
The string is interpreted as 24 hour format, as printed.

This format is used for BER specification of the ASN.1 GeneralizedTime and
UTCTime as defined in X.208 Sec. 33, so read this before changing anything here.
The short form is no longer recommended.

New applications should consider using a standard format, such as iso8601.

Notice, that this is not the storeString format and
is different from the format expected by readFrom:.

readISO8601From: aStringOrStream

obsoleted due to uc/lc confusion

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

readISO8601From: aStringOrStream onError: exceptionValue

obsoleted due to uc/lc confusion

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

readIso8601FormatFrom: aStringOrStream

return a new Timestamp, reading an iso8601 UTC representation from aStream.
Missing month/day values are replaced with 1; i.e. 1999T24:00
is the same as 1999-01-01T24:00:00.
Missing minute, second and ms values are replaced with 0;
i.e. 1999T12 is the same as 1999-01-01T12:00:00.000.
Of course, a 24 hour clock is used.
On error, raise an exception.

Please use this format for all external representations - it's the standard.

Usage example(s):

     Timestamp readIso8601FormatFrom:'20141106T123843.299Z'
     Timestamp readIso8601FormatFrom:'20141106T123843.299'

     Timestamp readIso8601FormatFrom:'1995-02-20T13:11:06'
     Timestamp readIso8601FormatFrom:'1995-02T13:11:06'
     Timestamp readIso8601FormatFrom:'1995T13:11:06'
     Timestamp readIso8601FormatFrom:'1995T13:11'
     Timestamp readIso8601FormatFrom:'1995T13'
     Timestamp readIso8601FormatFrom:'1995'

     Timestamp readIso8601FormatFrom:'1995-02-20 13:11:06'
     Timestamp readIso8601FormatFrom:'1995-02-20 13:11'
     Timestamp readIso8601FormatFrom:'1995-02-20 13'

     Timestamp readIso8601FormatFrom:'20141106T122831.894Z'

   24 is allowed with ISO, and is 00:00 of the next day:
     Timestamp readIso8601FormatFrom:'1995-02-20 24:00:00'

readIso8601FormatFrom: aStringOrStream onError: exceptionValue

readRFC1123FormatFrom: rfc1123String onError: exceptionBlock

please use this only for http-requests.
All other programs should use iso8601, which is the standard for times and dates.

All HTTP/1.0 date/time stamps must be represented in Universal Time (UT),
also known as Greenwich Mean Time (GMT), without exception.
This is indicated in the first two formats by the inclusion of
'GMT' as the three-letter abbreviation for time zone,
and should be assumed when reading the asctime format.

HTTP-date = rfc1123-date | rfc850-date | asctime-date

rfc1123-date = wkday ',' SP date1 SP time SP 'GMT'
rfc850-date = weekday ',' SP date2 SP time SP 'GMT'
asctime-date = wkday SP date3 SP time SP 4DIGIT

date1 = 2DIGIT SP month SP 4DIGIT
; day month year (e.g., 02 Jun 1982)
date2 = 2DIGIT '-' month '-' 2DIGIT
; day-month-year (e.g., 02-Jun-82)
date3 = month SP ( 2DIGIT | ( SP 1DIGIT ))
; month day (e.g., Jun 2)

time = 2DIGIT ':' 2DIGIT ':' 2DIGIT
; 00:00:00 - 23:59:59

wkday = 'Mon' | 'Tue' | 'Wed'
| 'Thu' | 'Fri' | 'Sat' | 'Sun'

weekday = 'Monday' | 'Tuesday' | 'Wednesday'
| 'Thursday' | 'Friday' | 'Saturday' | 'Sunday'

month = 'Jan' | 'Feb' | 'Mar' | 'Apr'
| 'May' | 'Jun' | 'Jul' | 'Aug'
| 'Sep' | 'Oct' | 'Nov' | 'Dec'

Mon, 17 Aug 2009 11:11:15 GMT

however, occasionally, someone presents us with non-UTC strings which include a timezone;
thus, this also supports:
Mon, 17 Aug 2009 11:11:15 +xxxx
Mon, 17 Aug 2009 11:11:15 -xxxx
and:
Mon, 17 Aug 2009 11:11:15 PST

Usage example(s):

     self readRFC1123FormatFrom:'Mon, 17 Aug 2009 11:11:15 GMT' onError:nil
     self readRFC1123FormatFrom:'Mon, 17 Aug 2009 11:11:15 UTC' onError:nil
     self readRFC1123FormatFrom:'Mon, 17 Aug 2009 11:11:15 PST' onError:nil
     self readRFC1123FormatFrom:'Mon, 17 Aug 2009 11:11:15 PDT' onError:nil
     self readRFC1123FormatFrom:'Mon, 17 Aug 2009 11:11:15 +0100' onError:nil
     self readRFC1123FormatFrom:'17 Aug 2009 11:11:15 +0100' onError:nil
     self readRFC1123FormatFrom:'Thu Jul 4 15:04:40 2019 +0200' onError:nil
     self readRFC1123FormatFrom:'16:20:40 PDT' onError:nil
     (self readRFC1123FormatFrom:'16:20:40 PDT' onError:nil) asLocalTimestamp

utcOffsetFrom: aStringOrStream

return the utcOffset (in seconds) for a given time-zone name or tz offset string.
Returns nil for invalid formats, 0 if no timezone offset is present.

Notice:
this returns the negated value of what is read from a printed representation,
which means that the sign is the same as what the utcOffset instance variable
in timeStamp and OperatingSystem-timeInfo will be.

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

UtcOffset is what you have to ADD to correct the printed time to GMT.
I.e. for Germany, you'll get -3600 (+01h), for NewYork, you'll get +18000 (-05h)

Usage example(s):

     self utcOffsetFrom:'UTC'
     self utcOffsetFrom:'PST'
     self utcOffsetFrom:'EST'
     self utcOffsetFrom:'CET'    => -3600
     self utcOffsetFrom:'+0130'  => -5400
     self utcOffsetFrom:'+01:30' => -5400
     self utcOffsetFrom:'+1:30'
     self utcOffsetFrom:'+01'

utcOffsetFromString: aString

return the utcOffset (in seconds) for a given time-zone name.
Returns nil for invalid formats

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

Instance protocol:

Javascript support

js_getDate
( an extension from the stx:libjavascript package ): return the Javascript day of the month (1..31).
For JavaScript only:
Generated for getDate() in javascript.
See JavaScriptParser >> commonTranslatedSelectorFor:jsSelector
js_getDay
( an extension from the stx:libjavascript package ): return the Javascript day of the week (0..6); Sunday is 0.
For JavaScript only:
Generated for getDay() in javascript.
See JavaScriptParser >> commonTranslatedSelectorFor:jsSelector
js_getFullYear
( an extension from the stx:libjavascript package ): return the Javascript year.
For JavaScript only:
Generated for getFullYear() in javascript.
See JavaScriptParser >> commonTranslatedSelectorFor:jsSelector
js_getMonth
( an extension from the stx:libjavascript package ): return the Javascript day of the month (1..12).
For JavaScript only:
Generated for getMonth() in javascript.
See JavaScriptParser >> commonTranslatedSelectorFor:jsSelector
js_getYear
( an extension from the stx:libjavascript package ): return the Javascript year relative to 1900 (eg. 95 for 1995 or 118 for 2018).
For JavaScript only:
Generated for getYear() in javascript.
See JavaScriptParser >> commonTranslatedSelectorFor:jsSelector

accessing

abbreviatedMonthName

return the short month name of the receiver as a string.
The returned string depends on the language setting.
Expect things like 'jan', 'feb' ...

Usage example(s):

     Timestamp now abbreviatedMonthName

day

return the day-in-month of the receiver (1..31).
For compatibility, use instances of Date for this.

Usage example(s):

     Timestamp now day

dayInWeek

return the week-day of the receiver - 1 for monday, 7 for sunday.
for pre-gregorian dates, it simply goes on assuming the current leapYear rules
WARNING: different from ANSIs dayOfWeek (which returns 1 for sunday, ... 7 for saturday).

Usage example(s):

     Timestamp now dayInWeek

dayInYear

return the year-day of the receiver - 1 for Jan, 1st.

Usage example(s):

     Timestamp now dayInYear
     (Timestamp newDay:184 year:1996) dayInYear

dayOfMonth

Answer the day of the month represented by me.
Same as day; for ST-80 compatibility.

Usage example(s):

     Timestamp now dayOfMonth
     (Timestamp newDay:184 year:1996) dayOfMonth

dayOfWeek

return the week-day of the receiver - 1 is sunday, 7 for saturday.
WARNING: different from dayInWeek (which returns 1 for monday, ... 7 for sunday).

Usage example(s):

     Timestamp now dayOfWeek

dayOfWeekName

return the week-day of the receiver as a string.
The returned string depends on the language setting.
Expect things like 'monday', 'tuesday' ...

Usage example(s):

     Timestamp now dayOfWeekName
     (Timestamp newDay:184 year:1996) dayOfWeekName

exactMicroseconds

return the exact microseconds within the stamp's second (0 .. 999.999...) as a fixedPoint number.
notice:
that is NOT the total number of microseconds,
but the fractional part (within the second) only.
A fixedPoint number holds the exact value, but prints itself rounded!

Usage example(s):

     |ts|

     ts := Timestamp nowWithMicroseconds.
     Transcript showCR:ts.
     Transcript showCR:ts microseconds.
     Transcript showCR:ts exactMicroseconds.
     Transcript showCR:ts nanoseconds.
     Transcript showCR:ts picoseconds.

exactMilliseconds

return the exact milliseconds within the stamp's second (0 .. 999.999...) as a fixedPoint number.
notice:
that is NOT the total number of microseconds,
but the fractional part (within the second) only.
A fixedPoint number holds the exact value, but prints itself rounded!

Usage example(s):

     |ts|

     ts := Timestamp nowWithMicroseconds.
     Transcript showCR:ts.
     Transcript showCR:ts milliseconds.
     Transcript showCR:ts exactMilliseconds.
     Transcript showCR:ts microseconds.
     Transcript showCR:ts nanoseconds.
     Transcript showCR:ts picoseconds.

exactMinutes

return the exact minutes within the stamp's hour (00 .. 59.999...) as a fixedPoint number.
Notice:
that is NOT the total number of minutes,
but the fractional part (within the hour) only.
A fixedPoint number holds the exact value, but prints itself rounded!

Usage example(s):

     |ts|

     ts := Timestamp nowWithMicroseconds.
     Transcript showCR:ts.
     Transcript showCR:ts minutes.
     Transcript showCR:ts exactMinutes.

exactNanoseconds

return the exact nanoseconds within the stamp's second (0 .. 999.999...).
notice:
that is NOT the total number of nanoseconds,
but the fractional part (within the second) only.
A fixedPoint number holds the exact value, but prints itself rounded!

Usage example(s):

     |ts|

     ts := Timestamp now + 100.3 nanoseconds.
     Transcript showCR:ts.
     Transcript showCR:ts milliseconds.
     Transcript showCR:ts exactMilliseconds.
     Transcript showCR:ts microseconds.
     Transcript showCR:ts exactMicroseconds.
     Transcript showCR:ts nanoseconds.
     Transcript showCR:ts exactNanoseconds.
     Transcript showCR:ts picoseconds.

exactSeconds

return the exact seconds within the stamp's minute (00 .. 59.999...) as a fixedPoint number.
Notice:
that is NOT the total number of seconds,
but the fractional part (within the minute) only.
A fixedPoint number holds the exact value, but prints itself rounded!

Usage example(s):

     |ts|

     ts := Timestamp fromDate:(Date today) hour:10 minute:30 second:20 millisecond:300.
     Transcript showCR:ts.
     Transcript showCR:ts seconds.
     Transcript showCR:ts exactSeconds.

hectonanoseconds

return the truncated 100ns SmallInteger value (used in Windows)
within the stamp's second (0..9999999).
notice: that is NOT the total number of hectonanoseconds,
but the fractional part (within the second) only.

Usage example(s):

     Timestamp now hectonanoseconds
     Timestamp nowWithMicroseconds hectonanoseconds.

     |now|
     now := Timestamp nowWithMicroseconds.
     self assert:(now hectonanoseconds = (now nanoseconds // 100))


     |t1 t2|
     t1 := Timestamp nowWithMicroseconds hectonanoseconds.
     t2 := Timestamp nowWithMicroseconds hectonanoseconds.
     t2-t1

     |t1 t2|
     t1 := Timestamp now hectonanoseconds.
     t2 := Timestamp nowWithMicroseconds hectonanoseconds.
     t2-t1

hours

return the hours (0..23)

Usage example(s):

     Timestamp now hours

microseconds

return the truncated microseconds within the stamp's second (0..999999).
notice: that is NOT the total number of microseconds,
but the fractional part (within the second) only.
Use this only for printing.

midnight

return a new timestamp which represents this day's midnight
(i.e. 00:00:00 of this day, not the next midnight)

Usage example(s):

     Timestamp now midnight                             - local midnight
     UtcTimestamp now midnight                          - utc midnight
     TZTimestamp now midnight                           - utc midnight printed in local 2023-06-05 23:00:00+01
     UtcTimestamp now midnight asTZTimestampInZone:#CET - utc midnight printed in europe 2023-06-06 01:00:00+01    

     Timestamp now midnight asTZTimestampInZone:#EST    - 2023-06-05 17:00:00-05 my midnight in california (winter)  
     Timestamp now midnight asTZTimestampInZone:#EDT    - 2023-06-05 18:00:00-04 my midnight in california (summer)  
     UtcTimestamp now midnight asTZTimestampInZone:#EST - 2023-06-05 19:00:00-05 utc midnight in california (winter)  
     UtcTimestamp now midnight asTZTimestampInZone:#EDT - 2023-06-05 20:00:00-04 utc midnight in california (summer)   
     UtcTimestamp now asTZTimestampInZone:#EST          - 2023-06-06 10:51:46.895-05 now in california winter   
     UtcTimestamp now asTZTimestampInZone:#EDT          - 2023-06-06 11:50:24.951-04 now in california summer

millisecond

return the truncated millisecond within the stamp's second (0..999).
ST-80 Timestamp compatibility (I'd prefer the name #milliseconds).

milliseconds

return the truncated milliseconds within the stamp's second (0..999)

Usage example(s):

     Timestamp now milliseconds

minutes

return the minutes (0..59)

Usage example(s):

     Timestamp now minutes

month

return the month of the receiver (1..12).
For compatibility, use instances of Date for this.

Usage example(s):

     Timestamp now month

monthIndex

return the month of the receiver (1..12).
For compatibility

Usage example(s):

     Timestamp now monthIndex

monthName

return the month of the receiver as a string.
The returned string depends on the language setting.
Expect things like 'january', 'february' ...

Usage example(s):

     Timestamp now monthName

nanoseconds

return the truncated nanoseconds within the stamp's second (0..999999999).
notice: that is NOT the total number of nanoseconds,
but the fractional part (within the second) only.
Use this only for printing.

Usage example(s):

     Timestamp now nanoseconds
     Timestamp nowWithMicroseconds nanoseconds

     |t1 t2|
     t1 := Timestamp nowWithMicroseconds nanoseconds.
     t2 := Timestamp nowWithMicroseconds nanoseconds.
     t2-t1

     |t1 t2|
     t1 := Timestamp now nanoseconds.
     t2 := Timestamp nowWithMicroseconds nanoseconds.
     t2-t1

osTime

get the internal representation of the time.
Warning: do not depend on the value (unix vs. win32 - differences)

picoseconds

return the picoseconds within the stamp's second (0..999999999999).
notice: that is NOT the total number of picoseconds,
but the fractional part (within the second) only.
Use this only for printing.

Usage example(s):

     Timestamp now picoseconds
     Timestamp nowWithMicroseconds picoseconds

seconds

return the truncated seconds (0..59)

Usage example(s):

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

Usage example(s):

     Timestamp now timeZoneDeltaInMinutes
     (Timestamp day:1 month:7 year:1995 hour:12 minutes:0 seconds:0) timeZoneDeltaInMinutes

timeZoneName

find the first zone which is in this range.
This is a bit naive, but should be sufficient in most cases
(for a correct result, we'd have to care for start-end dates of summer time
of that particular year...
sigh: poiticians seem to have no idea, how much trouble some of their populistic ideas make.

Usage example(s):

     Timestamp now timeZoneName     'CET'
     UtcTimestamp now timeZoneName  'UTC'

     (Timestamp now asTZTimestampInZone:'MEZ') timeZoneName  => 'CET'- will find international name 'CET'
     (Timestamp now asTZTimestampInZone:'EST') timeZoneName  => 'EST'
     (Timestamp now asTZTimestampInZone:'IDLE') timeZoneName - sorry - will find 'NZST'
     (Timestamp now asTZTimestampInZone:'BRST') timeZoneName - sorry: will find military 'PMDT'
     (Timestamp now asTZTimestampInZone:'MYT') timeZoneName  - will find hongkong; same timezone

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 (Russia, Asia).
If utcOffset is positive, the local timezone is west of Greenwich (USA).

Usage example(s):

Take the utcOffset without DST

Usage example(s):

     Timestamp now utcOffset
     (Timestamp year:1995 month:7 day:1 hour:12 minute:0 second:0) utcOffset
     (Timestamp year:1995 month:1 day:1 hour:12 minute:0 second:0) utcOffset
     (Timestamp year:1689 month:7 day:1 hour:12 minute:0 second:0) utcOffset
     (Timestamp year:4096 month:7 day:1 hour:12 minute:0 second:0) utcOffset

utcOffsetWithoutDst

return the difference between UTC (Greenwich Mean Time) and the local time in seconds.
If daylight saving time applies to ourself, do not 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):

     Timestamp now utcOffsetWithoutDst

utcSecondsSince1900

return the number of seconds elapsed since Jan, 1st 1900.
(that is an NTP timestamp)

Usage example(s):

     Timestamp now utcSecondsSince1900  => 3850394850
     Timestamp now utcSecondsSince1901  => 3818856815

utcSecondsSince1901

return the number of seconds elapsed since Jan, 1st 1901.
(that is a Windows timestamp)

Usage example(s):

     Timestamp now utcSecondsSince1901

utcSecondsSince1970

return the UTC seconds since 1970.
(that is a Unix timestamp)

Usage example(s):

     Timestamp now utcSecondsSince1970

weekInYear

return the week number of the receiver - 1 for Jan, 1st.

Usage example(s):

     (Timestamp newDay:1 year:2000) weekInYear
     (Timestamp newDay:2 year:2000) weekInYear
     (Timestamp newDay:3 year:2000) weekInYear

weekday

return the week-day of the receiver as a string.
The returned string depends on the current language setting.
Expect things like 'monday', 'tuesday' ...
For ST-80 compatibility

Usage example(s):

     Timestamp now weekday

     but maybe a different day there, in the south pacific:
     (Timestamp now asTZTimestampInZone:'LINT') weekday

     but maybe a different day there, in alaska:
     (Timestamp now asTZTimestampInZone:'AKST') weekday

year

return the year of the receiver i.e. 1992.
For compatibility, use instances of Date for this.

Usage example(s):

     Timestamp now year

arithmetic

ceilingSecond

return a timestamp which represents the next full second

Usage example(s):

     |t1 t2|

     t1 := Timestamp now.
     t2 := t1 ceilingSecond.
     self halt

floorSecond

return a timestamp truncated to the last full second

Usage example(s):

     |t1 t2|

     t1 := Timestamp now.
     t2 := t1 floorSecond.
     self halt

microsecondDeltaFrom: aTimestamp

return the delta in (truncated) microseconds between 2 timestamps.
The argument is supposed to be BEFORE the receiver,
computes self - aTimestamp

Usage example(s):

     |t1 t2|

     t1 := Timestamp now.
     Delay waitForSeconds:0.5.
     t2 := Timestamp now.
     t2 microsecondDeltaFrom:t1

millisecondDeltaFrom: aTimestamp

return the delta in (truncated) milliseconds between 2 timestamps.
The argument is supposed to be BEFORE the receiver,
computes self - aTimestamp

Usage example(s):

     |t1 t2|

     t1 := Timestamp now.
     Delay waitForSeconds:0.5.
     t2 := Timestamp now.
     t2 millisecondDeltaFrom:t1

roundedToSecond

return a timestamp which represents the time rounded to the nearest full second

Usage example(s):

     |t1 t2|

     t1 := Timestamp now.
     t2 := t1 roundedToSecond.
     self halt

secondDeltaFrom: aTimestamp

return the delta in (truncated) seconds between 2 timestamps.
The argument is supposed to be BEFORE the receiver,
computes self - aTimestamp

Usage example(s):

     |t1 t2|

     t1 := Timestamp now.
     Delay waitForSeconds:5.
     t2 := Timestamp now.
     t2 secondDeltaFrom:t1

comparing

hash: return an integer useful for hashing on time stamps

converting

asDate

return a Date object from the receiver.
The returned date will only represent the day - not the timeOfDay.
Notice: if you convert a local timestamp, you will get the local date;
otherwise if you convert an utcTimestamp, you'll get the utc date.

Usage example(s):

     Timestamp now
     Timestamp now asDate
     (Timestamp now addTime:3600) asDate
     (Timestamp now addTime:3600) asTime
     Timestamp fromSeconds:(Timestamp now asSeconds + 3600)
     (Timestamp fromSeconds:(Timestamp now asSeconds + 3600)) asDate

asDateAndTime
( an extension from the stx:libcompat package )

return a vector containing Date and Time objects from the receiver

Usage example(s):

     Timestamp now                                          
     Timestamp now asDateAndTime                            
     (Timestamp now addTime:3600) asDateAndTime             
     (Timestamp now addTime:3600) asDateAndTime             
     (Timestamp fromSeconds:(Timestamp now asSeconds + 3600)) asDateAndTime

asLocalTimestamp

represent myself as a timestamp in the local timezone

Usage example(s):

     Timestamp now asUtcTimestamp
     Timestamp now asUtcTimestamp asLocalTimestamp

asTZTimestamp

return a timestamp which represents the very same time,
but will represent itself as a timestamp with the local utcOffset.
Use this to make sure that a local timestamp can be read back in another timezone

Usage example(s):

see the different printStrings of:
         Timestamp now
     and
         Timestamp now asTZTimestamp
     and
         Timestamp now asUtcTimestamp

asTZTimestamp: utcOffsetInSeconds

return a timestamp which represents the very same time,
but will represent itself as a timestamp with the given utcOffset

Usage example(s):

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

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

asTZTimestampInZone: timeZoneName

return a timestamp which represents the very same time,
but will represent itself as a timestamp in the given timezone.
timeZoneName must be one of the standard names as listed in Timestamp >> timezoneInfo

Usage example(s):

what is the time now in NewYork?
       Timestamp now asTZTimestampInZone:'EST'

     what is the time now in Stuttgart?
       Timestamp now asTZTimestampInZone:'MEZ'

     an error os raised for any unknown/invalid timezone:
       Timestamp now asTZTimestampInZone:'BlaBla'

asTime

return a Time object from the receiver.
The returned time will only represent the timeOfDay - not the day,
and does not include the milliseconds.

Usage example(s):

     Timestamp now
     Timestamp now asTime
     UtcTimestamp now asTime
     (Timestamp now addTime:3600) asTime
     (Timestamp year:2014 month:7 day:1 hour:12 minute:0 second:0) asTime
     (UtcTimestamp year:2014 month:7 day:1 hour:12 minute:0 second:0) asTime

asTimeWithMilliseconds

return a Time object from the receiver.
The returned time will only represent the timeOfDay - not the day,
it will include the milliseconds.

asTimestamp

return an Timestamp object from the receiver - that's the receiver.

asUTC

Timestamp now
Timestamp now asUTC

asUtcTimestamp

return a timestamp which represents the very same timestamp,
but will represent itself as a timestamp in the UTC timezone

Usage example(s):

     Timestamp now asUtcTimestamp
     Timestamp now asUtcTimestamp asLocalTimestamp

literalArrayEncoding

encode myself as an array, from which a copy of the receiver
can be reconstructed with #decodeAsLiteralArray.
The encoding is:
(#Timestamp YYYYMMDDhhmmss.iiiZ)

Usage example(s):

      Timestamp now literalArrayEncoding
        decodeAsLiteralArray
      UtcTimestamp now literalArrayEncoding
        decodeAsLiteralArray

utcOffset: secondsOrTimeDuration

answer a DateTime equivalent to the receiver but offset from UTC by offset.
If utcOffset is negative, the local timezone is east of Greenwich (Russia, Asia).
If utcOffset is positive, the local timezone is west of Greenwich (USA).
If utcOffset is zero, you effectively get UTC time.

Usage example(s):

     Timestamp now  -- now as local time
     Timestamp now asTZTimestamp -- now in your local timezone
     Timestamp now asUtcTimestamp -- now in greenwich
     UtcTimestamp now -- now in greenwich
     Timestamp now utcOffset:(-2 hours) -- now in East Europe
     Timestamp now utcOffset:(5 hours) -- now in Eastern time
     Timestamp now asTZTimestampInZone:'EST' -- now in Eastern time

double dispatching

differenceFromTimestamp: aTimestamp: (comment from inherited method)
return the time difference as a timeDuration instance

initialization

UTCyear: y month: m day: d hour: h minute: min second: s millisecond: millis

private: ask the operating system to compute the internal osTime (based on the epoch),
given y,m,d and h,m,s in my time.
All arguments MUST be integral (for now)

UTCyear: y month: m day: d hour: h minute: min second: s millisecond: millis additionalPicoseconds: picos

private: ask the operating system to compute the internal osTime (based on the epoch),
given y,m,d and h,m,s in my time.
All arguments MUST be integral (for now)

setOSTimeFromUTCYear: y month: m day: d hour: h minute: min second: s millisecond: millis

private: ask the operating system to compute the internal osTime (based on the epoch),
given y,m,d and h,m,s in local time

setOSTimeFromYear: y month: m day: d hour: h minute: min second: s millisecond: millis

private: ask the operating system to compute the internal osTime (based on the epoch),
given y,m,d and h,m,s in local time. If the OS cannot do it, do it here.

year: y month: m day: d hour: h minute: min second: s millisecond: millis

private: ask the operating system to compute the internal osTime (based on the epoch),
given y,m,d and h,m,s in my time.
All arguments MUST be integral (for now)

Usage example(s):

     self basicNew
         year:2016 month:4 day:16 hour:17 minute:21 second:13 millisecond:726

year: y month: m day: d hour: h minute: min second: s millisecond: millis additionalPicoseconds: picos

private: ask the operating system to compute the internal osTime (based on the epoch),
given y,m,d and h,m,s in my time.
All arguments MUST be integral (for now)

Usage example(s):

     self basicNew
         year:2016 month:4 day:16 hour:17 minute:21 second:13 millisecond:726

inspecting

inspectorExtraAttributes
( an extension from the stx:libtool package ): extra (pseudo instvar) entries to be shown in an inspector.
inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package ): returns a string to be shown in the inspector's list

printing & storing

addPrintBindingsTo: dict language: languageOrNil

marked as obsolete by exept MBP at 04-12-2021

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

printGeneralizedOn: aStream

append a representation of the receiver to aStream in a general format,
top-down, without separators: 'yyyymmddHHMMSS.mmmZ'

This format is used for the ASN.1 GeneralizedTime as defined in X.208 Sec. 33,
so read this before changing the output format.

printGeneralizedOn: aStream isLocal: isLocal

append a representation of the receiver to aStream in a general format,
top-down, without separators: 'yyyymmddHHMMSS.mmm+0100'

This format is used for the ASN.1 GeneralizedTime as defined in X.208 Sec. 33,
so read this before changing the output format.

If isLocal is true, represent as local time (Local 'yyyymmddHHMMSS.mmm+0100'),
otherwise as UTC time (UTC 'yyyymmddHHMMSS.mmmZ').

printGeneralizedOn: aStream isLocal: isLocal short: shortFormat

append a representation of the receiver to aStream in a general format,
top-down, without separators;
long format: 'yyyymmddHHMMSS.mmm+0100'
short format: 'yymmddHHMMSS.mmm+0100'
Using the short format is strictly discouraged!

This format is used for the ASN.1 GeneralizedTime and UTCTime
as defined in X.208 Sec. 33, so read this before changing the output format.

If isLocal is true, represent as local time (Local 'yyyymmddHHMMSS.mmm+0100'),
otherwise as UTC time (UTC 'yyyymmddHHMMSS.mmmZ').

Usage example(s):

     Timestamp now printGeneralizedOn:Transcript. Transcript cr.
     Timestamp now printGeneralizedOn:Transcript isLocal:true. Transcript cr.
     (Timestamp fromSeconds:0) printGeneralizedOn:Transcript. Transcript cr.
     Time now printOn:Transcript. Transcript cr.
     Date today printOn:Transcript. Transcript cr.

     Timestamp now printGeneralizedOn:Transcript isLocal:false short:false. Transcript cr.
     Timestamp now printGeneralizedOn:Transcript isLocal:true short:false. Transcript cr.
     UtcTimestamp now printGeneralizedOn:Transcript isLocal:false short:false. Transcript cr.
     UtcTimestamp now printGeneralizedOn:Transcript isLocal:true short:false. Transcript cr.

     Date today asTimestamp printGeneralizedOn:Transcript. Transcript cr.
     Date today printOn:Transcript. Transcript cr.

printISO8601

obsoleted due to uc/lc and print vs. printString confusion

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

printISO8601Compressed

obsoleted due to uc/lc and print vs. printString confusion

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

printISO8601CompressedOn: aStream

obsoleted due to uc/lc confusion

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

printISO8601On: aStream

obsoleted due to uc/lc confusion

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

printIso8601CompressedOn: aStream

print in a format like 20141017T170939Z on aStream

printIso8601FormatOn: aStream

append the iso8601 representation of the receiver to aStream.
This format looks like:
1999-01-01T24:00:00
or, for zero hr:min:sec,
1999-01-01
Of course, a 24 hour clock is used.

Timezone information (eg. Z or +0100) is added for TZ and Utc stamps,
otherwise the reader will read as local time.

Usage example(s):

     Timestamp now printIso8601FormatOn:Transcript. Transcript cr.
     Timestamp readIso8601FormatFrom:(Timestamp now printStringIso8601Format).

     UtcTimestamp now printIso8601FormatOn:Transcript. Transcript cr.
     UtcTimestamp readIso8601FormatFrom:(UtcTimestamp now printStringIso8601Format).

printIso8601FormatOn: aStream compressed: compact timeSeparator: sepChar

Usage example(s):

     Timestamp now printStringIso8601Format.

     Timestamp now printIso8601FormatOn:Transcript. Transcript cr.
     Timestamp readIso8601FormatFrom:(Timestamp now printStringIso8601Format).

     UtcTimestamp now printIso8601FormatOn:Transcript. Transcript cr.
     UtcTimestamp readIso8601FormatFrom:(UtcTimestamp now printStringIso8601Format).

printIso8601FormatOn: aStream timeSeparator: sepChar

Usage example(s):

     Timestamp now printStringIso8601Format.

     Timestamp now printIso8601FormatOn:Transcript. Transcript cr.
     Timestamp readIso8601FormatFrom:(Timestamp now printStringIso8601Format).

     UtcTimestamp now printIso8601FormatOn:Transcript. Transcript cr.
     UtcTimestamp readIso8601FormatFrom:(UtcTimestamp now printStringIso8601Format).

printIso8601On: aStream

print in a format like 2014-10-17T17:08:44Z on aStream

printOn: aStream

append a user readable representation of the receiver to aStream.
The format is compatible with readFromString:, but not with readFrom:.

Usage example(s):

self printOn:aStream format:'%(year)-%(mon)-%(day) %h:%m:%s.%i'

Usage example(s):

self printOn:aStream format:'%(Day)-%(mon)-%(year) %h:%m:%s.%i'

Usage example(s):

self printOn:aStream format:'%(mon)/%(Day)/%(year) %h:%m:%s.%i'

Usage example(s):

     |tHere tNewYork|

     Timestamp now printOn:Transcript. Transcript cr.
     Timestamp now asUtcTimestamp printOn:Transcript. Transcript cr.
     (Timestamp now asTZTimestamp:(Timestamp utcOffsetFrom:'EST')) printOn:Transcript. Transcript cr.

     tHere := Timestamp now.
     tNewYork := tHere asTZTimestamp:(Timestamp utcOffsetFrom:'EST').
     tHere printOn:Transcript. Transcript cr.
     tNewYork printOn:Transcript. Transcript cr.

     (Timestamp fromSeconds:0) printOn:Transcript. Transcript cr.
     Time now printOn:Transcript. Transcript cr.
     Date today printOn:Transcript. Transcript cr.

     Time now asTimestamp printOn:Transcript. Transcript cr.
     Timestamp now printOn:Transcript. Transcript cr.

     Date today asTimestamp printOn:Transcript. Transcript cr.
     Date today printOn:Transcript. Transcript cr.

printRFC1123FormatOn: aStream

append the RFC1123 representation of the receiver to aStream.
This format is used in HTTP requests and looks like:
'Fri, 04 Jul 2003 15:56:11 GMT'
(always GMT and all names in english)

Usage example(s):

     String streamContents:[:s| Timestamp now printRFC1123FormatOn:s]

printStringRFC1123Format

return the RFC1123 representation of the receiver.
This format is used in HTTP requests and looks like:
'Fri, 04 Jul 2003 15:56:11 GMT'
(always GMT)

Usage example(s):

     Timestamp now printStringRFC1123Format

storeOn: aStream

store the receiver in a format suitable for reconstruction of the
receiver via readFrom:
Use a OS/architecture independent format

storeStringClass

my storeString will ask Timestamp to read the instance

private

additionalPicoseconds

return the additional picoseconds (0..999999999).
These must alwyas be smaller than 1000*1000*1000 (i.e. 1ms),
to avoid overflow into the millis.
These are to be added to any milliseconds

additionalPicoseconds: anInteger

set the additional picoseconds (0..999999999).
These must alwyas be smaller than 1000*1000*1000 (i.e. 1ms),
to avoid overflow into the millis.

computeTimeInfo

fake an info which the OS cannot give me

Usage example(s):

	(Timestamp year:1592 month:7 day:1 hour:12 minute:0 second:0 millisecond:555) computeTimeInfo
	(Timestamp year:4096 month:7 day:1 hour:12 minute:0 second:0 millisecond:555) computeTimeInfo

computeUtcTimeInfo

fake an info which the OS cannot give me

Usage example(s):

	(Timestamp year:1950 month:7 day:1 hour:12 minute:0 second:0) timeInfo
	(Timestamp year:1592 month:7 day:1 hour:12 minute:0 second:0) computeUtcTimeInfo
	(Timestamp year:4096 month:7 day:1 hour:12 minute:0 second:0) computeUtcTimeInfo

fromOSTime: anUninterpretedOSTime

strictly private: set the milliseconds from an OS time (since the epoch).
Notice: timestamps always have millisecond precision (in contrast to Time, where it is optional)

fromOSTimeWithMilliseconds: anUninterpretedOSTime

strictly private: set the milliseconds from an OS time (since the epoch).
Notice: timestamps always have millisecond precision (in contrast to Time, where it is optional)

fromOSTimeWithMilliseconds: anUninterpretedOSTime additionalPicoseconds: picos

strictly private: set the milliseconds and picoSeconds from an OS time (since the epoch)

getMicroseconds

strictly private: return the truncated microseconds (since the epoch) in utc

getMilliseconds

strictly private: return the truncated milliseconds (since the epoch) in utc

getNanoseconds

strictly private: return the truncated nanoseconds (since the epoch) in utc

getSeconds

strictly private: return the (truncated) seconds (since the epoch) in utc

osTime: aTime

set the internal representation of the time

setMicrosecond: aNumber

change the sub-second fractional part only (leaves everything above seconds unchanged)

Usage example(s):

     Timestamp now setMicrosecond:15    - 15 microseconds after the current second's start 
     Timestamp now setMicrosecond:0.1   - 100 nanoseconds after the current second's start

setMillisecond: aNumber

change the sub-second fractional part only (leaves everything above seconds unchanged)

Usage example(s):

     Timestamp now setMillisecond:15    - 15 milliseconds after the current second's start
     Timestamp now setMillisecond:0.05  - 50 microseconds after the current second's start

setMilliseconds: millis

strictly private: set the milliseconds (since the epoch)

setMilliseconds: millis additionalPicoseconds: picos

strictly private: set the milliseconds (since the epoch) and additional picos

setNanosecond: aNumber

change the sub-second fractional part only (leaves everything above seconds unchanged)

Usage example(s):

     Timestamp now setNanosecond:15     - 15 nanoseconds after the current second's start
     Timestamp now setNanosecond:0.1    - 10 picoseconds after the current second's start

setSeconds: secs

strictly private: set the seconds (since whatever)

timeInfo

fake an info which the OS cannot give me

Usage example(s):

	(Timestamp year:1950 month:7 day:1 hour:12 minute:0 second:0) timeInfo
	(UtcTimestamp year:1950 month:7 day:1 hour:12 minute:0 second:0) timeInfo

utcTimeInfo

fake an info which the OS cannot give me

Usage example(s):

	(Timestamp year:1950 month:7 day:1 hour:12 minute:0 second:0) timeInfo
	(Timestamp year:1950 month:7 day:1 hour:12 minute:0 second:0) utcTimeInfo

queries

speciesForCompare: all of my subclass instances can be compared,
because they all hold the UTC time internally

testing

isLocalTimestamp: return true, if I am a local timestamp (i.e. with no TZ info)
isTZTimestamp: return true, if I am a timestamp with TZ info
isTimestamp: return true, if I am a timestamp
isUtcTimestamp: return true, if I am a utc timestamp

visiting

acceptVisitor: aVisitor with: aParameter: dispatch for visitor pattern; send #visitTimestamp:with: to aVisitor.

Private classes:

    TimestampBuilderAbstract
    TimestampISO8601Builder

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 06:34:20 GMT