Smalltalk/X Webserver

Documentation of class 'Timestamp':

Class: Timestamp

Inheritance
Description
Related information
Class protocol
Instance protocol
Private classes

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

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

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

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)

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

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.

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

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

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'

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

getDate
( an extension from the stx:libjavascript package )

return the day of the month (1..31)

usage example(s):

     JavaScriptParser
	evaluate:'Date.now.getDate;'

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

getFullYear
( an extension from the stx:libjavascript package )

return the year

usage example(s):

     JavaScriptParser
	evaluate:'Date.now.getFullYear;'

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

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!

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!

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!

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!

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!

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.

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

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

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

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

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
floorSecond: return a timestamp truncated to the last full second
microsecondDeltaFrom: aTimestamp: return the delta in (truncated) microseconds between 2 timestamps.
The argument is supposed to be BEFORE the receiver,
computes self - aTimestamp
millisecondDeltaFrom: aTimestamp: return the delta in (truncated) milliseconds between 2 timestamps.
The argument is supposed to be BEFORE the receiver,
computes self - aTimestamp
roundedToSecond: return a timestamp which represents the time rounded to the nearest full second
secondDeltaFrom: aTimestamp: return the delta in (truncated) seconds between 2 timestamps.
The argument is supposed to be BEFORE the receiver,
computes self - aTimestamp

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

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

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

utcSecondsSince1901

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

usage example(s):

     Timestamp now utcSecondsSince1901

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

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

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'

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

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

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

utcSecondsSince1970

return the UTC seconds since 1970

usage example(s):

     Timestamp now utcSecondsSince1970

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.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Fri, 08 Dec 2023 03:41:41 GMT

Smalltalk/X Webserver

Documentation of class 'Timestamp':

Class: Timestamp

Inheritance:

Description:

Related information:

Class protocol:

Instance protocol:

Private classes: