Class: TimestampISO8601Builder (private in Timestamp

• Inheritance
• Description
• Related information
• Class protocol
  • printing
  • printing - basic
  • public parsing
• Instance protocol
  • accessing
  • private-reading
  • public processing
  • reading
• Examples

Inheritance:

   Object
   |
   +--Timestamp::TimestampBuilderAbstract
      |
      +--Timestamp::TimestampISO8601Builder

Package:

stx:libbasic

Category:

Kernel-Chronology

Owner:

Timestamp

Author:

Martin Dvorak (masca@volny.cz)

Description:

TimestampISO8601Builder is designed to read any (almost) format of ISO 8601 encoded timestamp.
Also, class methods can be used to print but the main reading job is done in instance protocol.
It has been written because of insufficient abilities of Timestamp #readIso8601FormatFrom: method
(which was now changed to call this as well).

It produces timestamps, i.e. when the string (or stream) contains only a time, an error will result
(it may also pass in some cases but with the time undestood as date). It survives incomplete dates,
broken years, incomplete times and timezones. All times read with timezone difference are recomputed
to UTC before the timestamp is created (even passing across new year boundary is handled correctly).
Unknown offsets (usually local) are considered UTC - this may be wrong and more work is probably needed.
All data is checked for validity (including leap years, leap seconds,...) during reading and as soon as
possible.
For an example of what the builder can read, see the examples method and ISO 8601 itself.


[instance variables:]
    stream          A stream the builder operates on. Assigned on each call to instance method #read:,
                    so the builder instance can be reused (by at most one thread).
    year            Current timestamp year. No default value, date must be present.
    month           Current timestamp month. May change during parsing. Defaults to 1.
    day             Current timestamp day. Defaults to 1.
    hour            Current timestamp hour. Defaults to 0.
    minute          Current timestamp minute. Defaults to 0.
    second          Current timestamp second. Defaults to 0.
    millisecond     Current timestamp millisecond. Defaults to 0.

Related information:

    Timestamp

Class protocol:

 print: aTimestamp

Returns the printString of the given timestamp in general ISO8601 format,
such as '2014-11-06T11:48:09Z'.
The time is printed as UTC time

Usage example(s):

self print:(Timestamp now)

 print: aTimestamp asLocal: asLocal on: aStream

Print the given timestamp in general ISO8601 format,
such as '2014-11-06T11:48:09Z'.
The time is always printed as UTC time

Usage example(s):

self print:(Timestamp now) on:Transcript

 print: aTimeOrTimestamp compact: compact asLocal: asLocal asUTC: asUTC withMicoseconds: withMicros timeSeparator: tSep timeOnly: timeOnly on: aStream

Print the given timestamp in general ISO8601 format,
such as '2014-11-06T11:48:09Z'.
compact: if true, the compact format (without separating dashes and colons is generated)
asLocal: if true, generates a localtime string (without any timezone info)
asUTC: if true, generates a utc string
if both are false:
generate a string depending on the type of timestamp:
if local: generate a local timezone string
if utc: generate a utc string
otherwise it is a timestamp from another timezone (TZTimestamp), then print in its timezone
withMilliseconds: if false, no milliseconds are generated.
if timeOnly is true, only the time is printed.
Warning: this has a feature (a bug) of implicitly suppressing fractional seconds, if the millis are zero.
this is strange, but for backward compatibility, left as is
(in case some printout depends on it)

Usage example(s):

self print:(Timestamp now) on:Transcript self print:(Time now) on:Transcript self printAsLocalTime:(Timestamp now) on:Transcript self printAsLocalTime:(Timestamp now asTZTimestamp:-7200) on:Transcript

 print: aTimestamp compact: compact asLocal: asLocal asUTC: asUTC withMilliseconds: withMillis on: aStream

Print the given timestamp in general ISO8601 format,
such as '2014-11-06T11:48:09Z'.
compact: if true, the compact format (without separating dashes and colons is generated)
asLocal: if true, generates a localtime string (with the machine's current timezone setting)
asUTC: if true, generates a utc string
if both are false:
generate a string depending on the type of timestamp:
if local: generate a local timezone string
if utc: generate a utc string
otherwise it is a timestamp from another timezone (TZTimestamp), then print in its timezone
withMilliseconds: if false, no milliseconds are generated

Usage example(s):

self print:(Timestamp now) on:Transcript self printAsLocalTime:(Timestamp now) on:Transcript self printAsLocalTime:(Timestamp now asTZTimestamp:-7200) on:Transcript

 print: aTimestamp compact: compact asLocal: asLocal asUTC: asUTC withMilliseconds: withMillis timeSeparator: tSep on: aStream

Print the given timestamp in general ISO8601 format,
such as '2014-11-06T11:48:09Z'.
compact: if true, the compact format (without separating dashes and colons is generated)
asLocal: if true, generates a localtime string (without any timezone info)
asUTC: if true, generates a utc string
if both are false:
generate a string depending on the type of timestamp:
if local: generate a local timezone string
if utc: generate a utc string
otherwise it is a timestamp from another timezone (TZTimestamp), then print in its timezone
withMilliseconds: if false, no milliseconds are generated

Usage example(s):

self print:(Timestamp now) on:Transcript self printAsLocalTime:(Timestamp now) on:Transcript self printAsLocalTime:(Timestamp now asTZTimestamp:-7200) on:Transcript

 print: aTimeOrTimestamp compact: compact asLocal: asLocal asUTC: asUTC withMilliseconds: withMillis timeSeparator: tSep timeOnly: timeOnly on: aStream

Print the given timestamp in general ISO8601 format,
such as '2014-11-06T11:48:09Z'.
compact: if true, the compact format (without separating dashes and colons is generated)
asLocal: if true, generates a localtime string (without any timezone info)
asUTC: if true, generates a utc string
if both are false:
generate a string depending on the type of timestamp:
if local: generate a local timezone string
if utc: generate a utc string
otherwise it is a timestamp from another timezone (TZTimestamp), then print in its timezone
withMilliseconds: if false, no milliseconds are generated.
if timeOnly is true, only the time is printed.
Warning: this has a feature (a bug) of implicitly suppressing fractional seconds, if the millis are zero.
this is strange, but for backward compatibility, left as is
(in case some printout depends on it)

Usage example(s):

self print:(Timestamp now) on:Transcript self print:(Time now) on:Transcript self printAsLocalTime:(Timestamp now) on:Transcript self printAsLocalTime:(Timestamp now asTZTimestamp:-7200) on:Transcript

 print: aTimestamp on: aStream

Print the given timestamp in general ISO8601 format,
such as '2014-11-06T11:48:09Z'.
The time is printed as UTC time

Usage example(s):

self print:(Timestamp now) on:Transcript. Transcript cr. self print:(Time now) on:Transcript. Transcript cr. self print:(Time nowWithMilliseconds) on:Transcript. Transcript cr.

 printAsLocalTime: aTimestamp on: aStream

Print the given timestamp in general ISO8601 format,
such as '2014-11-06T11:48:09+01'.
The time is printed as local time

Usage example(s):

self printAsLocalTime:(Timestamp now) on:Transcript

 printCompressed: aTimestamp

Return a printString in compressed format such as '20141106T114636Z'.
(for example, for timestamp interchange with mobile devices).
The time is printed as UTC time

Usage example(s):

self printCompressed:(Timestamp now)

 printCompressed: aTimestamp asLocal: asLocal on: aStream

generates a compressed string representation,
(optionally as localtime) such as '20141106T114636Z'

Usage example(s):

self printCompressed:(Timestamp now) on:Transcript

 printCompressed: aTimestamp on: aStream

generates a compressed string representation, such as '20141106T114636Z'.
The time is printed as UTC time

Usage example(s):

self printCompressed:(Timestamp now) on:Transcript

 printCompressedAsLocalTime: aTimestamp on: aStream

generates a compressed string representation, such as '20141106T114636Z'.
The time is printed as local time

 printTime: aTimeOrTimestamp on: aStream

Print the given time in general ISO8601 format,
such as 'T11:48:09Z'.
The time is printed as UTC time.
No date is printed.

Usage example(s):

self print:(Time nowWithMilliseconds) on:Transcript. Transcript cr. self printTime:(Time nowWithMilliseconds) on:Transcript. Transcript cr.

 printTimeZone: tzOffsetArg on: aStream

Print the timezone delta

 print: aTimeOrTimestamp compact: compact asLocal: asLocal asUTC: asUTC subSecondDigits: numDigits suppressZeroSubSecondDigits: suppressZeroSubSecondDigits timeSeparator: tSep timeOnly: timeOnly on: aStream

Print the given timestamp in general ISO8601 format,
such as '2014-11-06T11:48:09Z'.
compact: if true, the compact format (without separating dashes and colons is generated)
asLocal: if true, generates a localtime string (without any timezone info)
asUTC: if true, generates a utc string
if both are false:
generate a string depending on the type of timestamp:
if local: generate a local timezone string
if utc: generate a utc string
otherwise it is a timestamp from another timezone (TZTimestamp), then print in its timezone
numDigits: nr of post-second fractional part
i.e. 3 for millis, 6 for micros, 0 for none,
#variable for as-required;
#variable3 multiples of 3 as-required;
suppressZeroSubSecondDigits: to suppress zeros (i.e. the old behavior).
if timeOnly is true, only the time is printed.

Usage example(s):

Transcript cr. self print:(Timestamp nowWithMicroseconds) compact:false asLocal:false asUTC:true subSecondDigits:3 suppressZeroSubSecondDigits:false timeSeparator:$T timeOnly:false on:Transcript Transcript cr. self print:(Timestamp nowWithMicroseconds) compact:false asLocal:false asUTC:true subSecondDigits:6 suppressZeroSubSecondDigits:false timeSeparator:$T timeOnly:false on:Transcript Transcript cr. self print:(Timestamp nowWithMicroseconds) compact:false asLocal:false asUTC:true subSecondDigits:#variable suppressZeroSubSecondDigits:false timeSeparator:$T timeOnly:false on:Transcript Transcript cr. self print:(Timestamp now) compact:false asLocal:false asUTC:true subSecondDigits:#variable suppressZeroSubSecondDigits:false timeSeparator:$T timeOnly:false on:Transcript Transcript cr. self print:(Timestamp now) compact:false asLocal:false asUTC:true subSecondDigits:1 suppressZeroSubSecondDigits:false timeSeparator:$T timeOnly:false on:Transcript Transcript cr. self print:(Timestamp now) compact:false asLocal:false asUTC:true subSecondDigits:0 suppressZeroSubSecondDigits:false timeSeparator:$T timeOnly:false on:Transcript

 read: stringOrStream withClass: timestampClass

 read: stringOrStream withClass: timestampClass yearAlreadyReadAs: yearArg

support for readers which may have already preread the year

Instance protocol:

 stream: something

 nextDigit

 nextDigitOrError

 nextDigits: anInteger

 nextDigitsAtLeast: minCount atMost: maxCount

 read: stringOrStream withClass: timestampClass

Read the year. This will read and swallow up to four year digits.

 readFraction

Read an arbitrary number of digits representing a fraction.

 readMilliseconds

Read an arbitrary number of digits representing the fractional part
(used to be milliseconds, but now we can represent anything down to pico seconds

 readMonthOrDay

Read month number, optionally followed by day, or absolute day number (three digit).

 readTime

Date already read, don't mind it.
Read only the time value.

 readTimezone

Read time zone information. There are three possibilities of what can occur.
If there is nothing more to read, the offset is unknown - this is treated as
Zulu time as this may not be true.

 readTimezoneOffset

Read time zone offset as an array of hours and minutes.
Generally, there should be hours only,
but as the format introduces minutes in offsets, we must accept them.
(actually: there are countries with half-hour offsets!)

 readWeekNumber

Read week number. It is always two digits long.

 readYear

Read YYYY or :Y (broken decade) from the stream. Also handles correctly YY- and YYY-.

Examples:

See the unit tests in stx/goodies:regression >> RegressionTests::timeAndDateTest
It covers the main features this builder has.

Just to introduce some coding examples, try:
    Timestamp readISO8601From: (TimestampISO8601Builder print: Timestamp now).
    UtcTimestamp readISO8601From: (TimestampISO8601Builder print: UtcTimestamp now).
    Timestamp readISO8601From: (TimestampISO8601Builder print: UtcTimestamp now).
    Timestamp readISO8601From: (TimestampISO8601Builder print: TZTimestamp now).

Timestamp readISO8601From:'fooBar' onError:[ Timestamp now ].