eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Timestamp':

Home

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

Class: Timestamp


Inheritance:

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

Package:
stx:libbasic
Category:
Magnitude-Time
Version:
rev: 1.271 date: 2019/07/08 16:08:57
user: alkurz
file: Timestamp.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

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 UNIX, 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 will have no problem when 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).


Related information:

    UtcTimestamp
    Time
    Date
    Delay
    ProcessorScheduler

Class protocol:

Compatibility-Squeak
o  current

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

o  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

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

o  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
o  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
o  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
o  initialize
(comment from inherited method)
called only once - initialize signals

instance creation
o  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

o  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

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

o  epoch
the epoch is based to 0 for 1970-01-01 00:00:00.
However, we allow negative values to represent timestamps before that

o  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

o  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

o  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

o  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

o  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

o  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

o  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

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

     Timestamp secondsSince1970:3600
     Timestamp secondsSince1970:3600*24

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

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

o  utcNow
return now as utc timestamp

usage example(s):

     Timestamp now
     Timestamp utcNow

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

o  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 

o  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

o  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

o  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

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

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

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

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

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

o  readIso8601FormatFrom: aStringOrStream yearAlreadyRead: yearOrNil onError: exceptionValue
common helper for read methods.

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

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

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

o  readGeneralizedFrom: aStringOrStream onError: exceptionBlock
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:.

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

o  readISO8601From: aStringOrStream
obsoleted due to uc/lc confusion

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

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

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

o  readIso8601FormatFrom: aStringOrStream onError: exceptionValue
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.

o  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

o  timezoneInfo
return a table containing timezone information.
This may or may not be correct by the time you read this.
It is recommended to add explicit information in the form of +hh:mm to a printed
representation, instead of using names.

As this is searched for when reverse converting from utcOffset to TZName

o  utcOffsetFrom: aStringOrStream
return the utcOffset (in seconds) for a given time-zone name.
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'
     self utcOffsetFrom:'+0130'
     self utcOffsetFrom:'+01:30'
     self utcOffsetFrom:'+1:30'
     self utcOffsetFrom:'+01'

o  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
o  getDate
( an extension from the stx:libjavascript package )
return the day of the month (1..31)

usage example(s):

     JavaScriptParser
	evaluate:'Date.now.getDate;'

o  getDay
( an extension from the stx:libjavascript package )
return the day of the week (0..6); Sunday is 0

usage example(s):

     JavaScriptParser
	evaluate:'Date.now.getDay;'

o  getFullYear
( an extension from the stx:libjavascript package )
return the year

usage example(s):

     JavaScriptParser
	evaluate:'Date.now.getFullYear;'

o  getMonth
( an extension from the stx:libjavascript package )
return the day of the month (1..12)

usage example(s):

     JavaScriptParser
	evaluate:'Date.now.getMonth;'

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

o  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

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

usage example(s):

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

o  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

o  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

o  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

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

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

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

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

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

o  hours
return the hours (0..23)

usage example(s):

     Timestamp now hours

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

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

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

usage example(s):

     Timestamp now milliseconds

o  minutes
return the minutes (0..59)

usage example(s):

     Timestamp now minutes

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

usage example(s):

     Timestamp now month

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

usage example(s):

     Timestamp now monthIndex

o  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

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

o  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

o  seconds
return the truncated seconds (0..59)

usage example(s):

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

usage example(s):

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

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

usage example(s):

     Timestamp now timeZoneName
     UtcTimestamp now timeZoneName

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

o  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

o  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

o  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

o  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

o  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
o  ceilingSecond
return a timestamp which represents the next full second

o  floorSecond
return a timestamp truncated to the last full second

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

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

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

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

comparing
o  hash
return an integer useful for hashing on time stamps

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

o  asLocalTimestamp
represent myself as a timestamp in the local timezone

usage example(s):

     Timestamp now asUtcTimestamp
     Timestamp now asUtcTimestamp asLocalTimestamp

o  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

o  asTZTimestamp: utcOffset
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'

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

o  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

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

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

o  asUTC
Timestamp now
Timestamp now asUTC

o  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

o  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

o  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

o  utcSecondsSince1901
return the number of seconds elapsed since Jan, 1st 1901

usage example(s):

     Timestamp now utcSecondsSince1901

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

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

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

o  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

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

o  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

o  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
o  inspectorExtraAttributes
( an extension from the stx:libtool package )
extra (pseudo instvar) entries to be shown in an inspector.

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

printing & storing
o  addPrintBindingsTo: dict language: languageOrNil
private print support: add bindings for printing to aDictionary
languageOrNil can only be #en or nil for the current language.

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

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

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

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

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

o  printISO8601CompressedOn: aStream
obsoleted due to uc/lc confusion

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

o  printISO8601On: aStream
obsoleted due to uc/lc confusion

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

o  printIso8601CompressedOn: aStream
print in a format like 20141017T170939Z on aStream

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

o  printIso8601FormatOn: aStream compressed: compact timeSeparator: sepChar
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 printStringIso8601Format.

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

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

o  printIso8601FormatOn: aStream timeSeparator: sepChar
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 printStringIso8601Format.

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

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

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

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

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

o  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

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

o  storeStringClass

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

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

o  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

o  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

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

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

o  fromOSTimeWithMilliseconds: anUninterpretedOSTime additionalPicoseconds: picos
strictly private: set the milliseconds and picoSeconds from an OS time (since the epoch)

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

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

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

o  osTime: aTime
set the internal representation of the time

o  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 

o  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

o  setMilliseconds: millis
strictly private: set the milliseconds (since the epoch)

o  setMilliseconds: millis additionalPicoseconds: picos
strictly private: set the milliseconds (since the epoch) and additional picos

o  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

o  setSeconds: secs
strictly private: set the seconds (since whatever)

o  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

o  utcSecondsSince1970
return the UTC seconds since 1970

usage example(s):

     Timestamp now utcSecondsSince1970

o  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
o  speciesForCompare
all of my subclass instances can be compared,
because they all hold the UTC time internally

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

o  isTZTimestamp
return true, if I am a timestamp with TZ info

o  isTimestamp
return true, if I am a timestamp

o  isUtcTimestamp
return true, if I am a utc timestamp

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


Private classes:

    TimestampBuilderAbstract
    TimestampISO8601Builder


ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Fri, 16 Apr 2021 12:19:54 GMT