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

Package:: stx:libbasic

Category:: Magnitude-Time

Version:: rev: 1.129 date: 2010/03/31 09:41:13; user: stefan; 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. 
(typically, from 1st. Jan 1970, 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 these times. 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; 
instances of Timestamp can.

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

Related information:

    Time
    Date
    Delay
    ProcessorScheduler

Class protocol:

Compatibility-Squeak

current

initialization

initialize

instance creation

UTCYear: y month: m day: d hour: h minute: min second: s millisecond: millis: return an instance of the receiver, given individual components.
See also `Timestamp now' and other protocol inherited
from my superclass.
day: d month: m year: y hour: h minutes: min seconds: s: ** 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 an obsolete interface - do not use it (it may vanish in future versions) **
decodeFromLiteralArray: anArray: decode an 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)
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.
newDay: dayInYear year: year: return a new Timestamp, given the year and the day-in-year (starting at 1).
Date protocol compatibility
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 dd-mm-yyyy hh:mm:ss.iii
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.

Notice, that this is not the storeString format and
is different from the format expected by readFrom:.
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.

Notice, that this is not the storeString format and
is different from the format expected by readFrom:.
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.

Notice, that this is not the storeString format and
is different from the format expected by readFrom:.
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 - its the standard.
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 - its the standard.
readRFC1123FormatFrom: rfc1123String onError: exceptionBlock
secondsSince1970: sec: set time from elapsed seconds since 1-1-1970, 0:0:0.
This is the format used in the UNIX world
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.
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.

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 and
is different from the format expected by readFrom:.
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
readIso8601FormatFrom: aStringOrStream yearAlreadyRead: yearOrNil: common helper for read methods.
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 - its the standard.
readIso8601FormatFrom: aStringOrStream yearAlreadyRead: yearOrNil onError: exceptionValue: common helper for read methods.
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 - its the standard.

reading

readISO8601From: stringOrStream

Instance protocol:

accessing

day: return the day-in-month of the receiver (1..31).
For compatibility, use instances of Date for this.
dayInWeek: return the week-day of the receiver - 1 for monday, 7 for sunday
WARNING: different from ANSIs dayOfWeek (which returns 1 for sunday, ... 7 for saturday).
WARNING: does not care for pre-julian dates
(i.e. do not use this for dates before 1752)
dayInYear: return the year-day of the receiver - 1 for Jan, 1st.
hour: return the hour (0..23).
ST-80 Timestamp compatibility (I'd prefer the name #hours, for Time compatibility).
hours: return the hours (0..23)
millisecond: return the millisecond (0..999).
ST-80 Timestamp compatibility (I'd prefer the name #milliseconds).
milliseconds: return the milliseconds (0..999)
minute: return the minute (0..59).
ST-80 Timestamp compatibility (I'd prefer the name #minutes, for Time compatibility).
minutes: return the minutes (0..59)
month: return the month of the receiver (1..12).
For compatibility, use instances of Date for this.
osTime: get the internal representation of the time.
Warning: do not depend on the value (unix vs. win32 - differences)
osTime: aTime: set the internal representation of the time
second: return the second (0..59).
ST-80 Timestamp compatibility (I'd prefer the name #seconds, for Time compatibility).
seconds: return the seconds (0..59)
timeInfo
utcOffset: return the difference between UTC (Greenwich Mean Time) and the local time in seconds.
If daylight saving time applies to ourself, take that into account.

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

If utcOffset is negative, the local timezone is east of Greenwich.
If utcOffset is positive, the local timezone is west of Greenwich.
year: return the year of the receiver i.e. 1992.
For compatibility, use instances of Date for this.

arithmetic

deltaFrom: aTimestamp: return the delta as a timeDuration between 2 timeStamps.
The argument is supposed to be BEFORE the receiver
millisecondDeltaFrom: aTimestamp: return the delta in milliseconds between 2 absolute times.
The argument is supposed to be BEFORE the receiver
secondDeltaFrom: aTimestamp: return the delta in seconds between 2 absolute times.
The argument is supposed to be BEFORE the receiver

comparing

= aTime: return true if the argument, aTime represents the same time
hash: return an integer useful for hashing on times

converting

asAbsoluteTime: deprecated, use #asTimestamp

** This is an obsolete interface - do not use it (it may vanish in future versions) **
asDate: return a Date object from the receiver.
The returned date will only represent the day - not the timeOfDay.
asLocalTimestamp: convert an utc timestamp to local time
asMilliseconds: return the number of milliSeconds elapsed since whatever time the
OperatingSystem bases its time upon. Since this is totally
OS-dependent, do not interpret the value returned by this method.
You can use it to add/subtract milliSeconds or get time deltas, though.
asSeconds: return the number of seconds elapsed since whatever time the
OperatingSystem bases its time upon. Since this is totally
OS-dependent, do not interpret the value returned by this method.
You can use it to add/subtract seconds or get time deltas, though.
asTime: return a Time object from the receiver.
The returned time will only represent the timeOfDay - not the day.
asTimestamp: return an Timestamp object from the receiver - thats the receiver.
asUtcTimestamp: convert a local time timestamp to UTC
literalArrayEncoding: encode myself as an array, from which a copy of the receiver
can be reconstructed with #decodeAsLiteralArray.
The encoding is:
(#Timestamp YYYYMMDDhhmmss.iii)
utcSecondsSince1901: return the number of seconds elapsed since Jan, 1st 1901

printing

printISO8601
printISO8601Compressed
printISO8601CompressedOn: aStream
printISO8601On: aStream

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.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.
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, otherwise add UTC time offset.
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'

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.
The short format is no longer recommended.

If isLocal is true, represent as local time, otherwise add UTC time offset.
printIso8601FormatOn: aStream: append the iso8601 UTC 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.
printOn: aStream: append a user readable representation of the receiver to aStream.
The format is compatible with readFromString:, but not with readFrom:.
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)
printStringIso8601Format: return the Iso8601 representation of the receiver.
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.
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)
storeOn: aStream: store the receiver in a format suitable for reconstruction of the
receiver via readFrom:
Use a OS/architecture independent format

private

fromOSTime: anUninterpretedOSTime: strictly private: set the seconds from an OS time (since whatever)
getMilliseconds: strictly private: return the milliseconds (since whatever)
getSeconds: strictly private: return the seconds (since whatever)
setMilliseconds: millis: strictly private: set the milliseconds (since whatever)
setSeconds: secs: strictly private: set the seconds (since whatever)
utcSecondsSince1970: return the UTC seconds since 1970

visiting

acceptVisitor: aVisitor with: aParameter

Private classes:

    TimestampBuilderAbstract
    TimestampISO8601Builder

ST/X 6.1.1; WebServer 1.620 at exept:8081; Wed, 23 May 2012 21:39:15 GMT