Date and Time API Functions

This document lists most useful (and most often needed) functions. Be aware, that there are many more to be found in either the class references or via the builtin class browser.

Reference: Date Time Timestamp TimeDuration

Back to Useful API Functions

Time

Time instances represent a time-of-day (i.e. "hh:mm:ss" within a single day).
Be aware that time represents times modulo 24 h. Thus they are not useful for arithmetic, and therefore are seldom used. See Timestamps below, which are better suited.

Creation

Time now => Time

provides the current time of day (with seconds precision).

When printed, this will present itself as 'HH:MM:SS' (or 'HH:MM:SS am/pm' in US locale)

Time nowWithMilliseconds => Time

ditto with millisecond precision.

When printed, this will present itself as 'HH:MM:SS.mmm'

Time utcNow => Time

Time utcNowWithMilliseconds => Time

provide the current time in UTC

Time hours: hrs minutes: mins seconds: secs => Time

returns a Time instance with given hours, minutes and seconds.

Time readFrom: aStringOrStream onError: [...] => Time

to convert a string into a Time instance.

Arithmetic

aTime addSeconds: nSeconds => Time

aTime addMinutes: nMinutes => Time

aTime addHours: nHours => Time

to compute times

aTime + nSeconds => Time

aTime - nSeconds => Time

if the argument is numeric, it is interpreted as seconds.

Thus "Time now + 3600" represents a time one hour after the current time (but beware of mod 24h behavior).

Such code is considered bad style; see alternative below.

aTime + aTimeDuration => Time

aTime - aTimeDuration => Time

better use a timeDuration as argument, to make the behavior explicit.

E.g. "Time now + 3600 seconds" or "Time now + 60 minutes" or "Time now + 1 hours" all return the same result.

Accessing

aTime hours => Integer (0..24)

aTime minutes => Integer (0..59)

aTime seconds => Integer (0..59)

aTime milliseconds => Integer (0..999)

to retrieve the hour, minute, second and millisecond components

Conversion

aTime asTimestamp

returns a timestamp of aTime in today (in unspecified timezone)

aTime asUTCTimestamp

returns a timestamp of aTime in today (in UTC)

aTime asTZTimestamp

returns a timestamp of aTime in today (in local timezone)

Date

Date instances represent a date (i.e. "dd-mm-yyyy").
Dates are seldom used - usually timestamps are better suited. However, there are a number of useful query function provided on the class side.

Creation

Date today => Date

provides the current date

Date tomorrow => Date

provides the date of tomorrow

Date yesterday => Date

provides the date of yesterday

Date year: yearNr month: monthNr day: dayNr => Date

for example, "(Date year:2025 month:4 day:20)" generates 20-04-2025 (i.e. 20th April 2025)

Date readFrom: aString onError: replacementBlock => Date

reads a date from a string. Tries to be smart detecting the format. Be aware that there is a difference in the order between US and European formats: US uses MM/DD/YY, whereas the European format is DD-MM-YY. We recommend using formats like YYYY-MM-DD or YYYYMMDD (both ISO 8601), which have the advantage of being both unambiguous and sortable as strings.

Arithmetic

aDate addDays: numDays => Date

to compute a date numDays after aDate

aDate subtractDays: numDays => Date

to compute a date numDays before aDate; for example: "(Date today subtractDays:7)"

aDate subtractDate: date2 => Integer (nr of days)

to compute the number of days since 1.1.1900, use: "(Date today subtractDate:(Date year:1900 month:1 day:1))"

Accessing

aDate day => Integer (1..31)

aDate month => Integer (1..12)

aDate year => Integer

to retrieve date components.

Useful Queries

The class side provides information which is not related to any particular date (i.e. static functions in C or Java nomenclature)

Date dayNamesForLanguage: langCode => Collection of Strings

Date abbreviatedDayNamesForLanguage: langCode => Collection of Strings

returns day names / abbreviated day names in various languages (ISO language code as argument: en, de, fr, it, es, ...).

Example:

 Date abbreviatedDayNamesForLanguage: 'en'
   => #('mon' 'tue' 'wed' 'thu' 'fri' 'sat' 'sun')
 Date abbreviatedDayNamesForLanguage: 'de'
   => #('Mo' 'Di' 'Mi' 'Do' 'Fr' 'Sa' 'So')
 Date dsyNamesForLanguage: 'fr'
   => #('lundi' 'mardi' 'mercredi' 'vendredi' 'jeudi' 'samedi' 'dimanche')

Date nameOfDay: dayIndex language: langCode=> String

Date nameOfDay: dayIndex => String

Date abbreviatedNameOfDay: dayIndex language: langCode => String

Date abbreviatedNameOfDay: dayIndex => String

returns the day name / abbreviated day name of the given day (1=Monday). Without langCode argument, the name is returned in the current user language.

Date monthNamesForLanguage: langCode => Collection of Strings

Date abbreviatedMonthNamesForLanguage: langCode => Collection of Strings

Date nameOfMonth: monthIndex language: langCode => String

Date nameOfMonth: monthIndex => String

Date abbreviatedNameOfMonth: monthIndex language: langCode => String

Date abbreviatedNameOfMonth: monthIndex => String

same for month names

Date dayOfWeek: dayName language: langCode => Integer

Date dayOfWeek: dayName => Integer

the reverse operation: given a string containing a day name, return the day-in-week number (1..7). Without a langCode argument, the current user language is tried first, then English. If the string is invalid, a 0 is returned.

Date indexOfMonth: monthString language: langCode

Date indexOfMonth: monthString

same for months: given a string containing a month name, return the month number (1..12). Without a langCode argument, the current user language is tried first, then English. If the string is invalid, a 0 is returned.

Date leapYear: yearInteger => Boolean

returns true if yearInteger is leap year.

Timestamp

Timestamp instances represent a particular point in time. (i.e. "dd-mm-yyyy hh:mm:ss"). Conceptionally, they combine Date and Time with a higher resolution into one object. Timestamps can be created from strings or acquired from the operating system. OS-timestamp precision varies among operating systems; some may only provide millisecond resolution, others provide nanosecond resolution.

In contrast to the operating system's time information, Timestamps can represent times before 1970/1900 and after 2036. Thus expecco has no problem representing the year 2525 or 1400 as a timestamp.

However, there is currently no specific support for pre-Gregorian dates, which means that dates before Gregor are simply extrapolated printed as if they were Gregorian (very unlikely, that you are affected by this, unless you are testing an application dealing with historic dates).

Timestamps can be either local timestamps, UTC timestamps or timezone-specific timestamps, and are then instances of one of the classes Timestamp, UTCTimestamp or TZTimestamp, which can be converted into each other as required.

Local timestamps (instances of Timestamp) do not carry along any timezone information; they can be used to measure time deltas or if the timezone is irrelevant or if it is provided by another information source.

UTC timestamps are explicitly marked as being universal time zone based.

TZTimestamps carry their offset relative to UTC with them.

Creation

Timestamp now => Timestamp

provides the current timestamp (local time); millisecond resolution bz default

Timestamp nowWithMicroseconds => Timestamp

ditto with microsecond precision

UTCTimestamp now => UTCTimestamp

provides the current timestamp (UTC time)

TZTimestamp now => TZTimestamp

provides the current timestamp (in the local timezone)

TZTimestamp nowInTimeZone: tzName => TZTimestamp

provides the current timestamp in the given timezone.

E.g. "TZTimestamp nowInTimeZone:'JST'" returns the current time in Japan Standard Time. A list of timezones is returned by "TimeZone timeZones".

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

provides a new local timestamp for the given date and time.
Same protocol can be used to get UTCTimestamps and TZTimestamps

Timestamp fromDate:' aDate ándTime: aTime => Timestamp

creates a timestamp from given date and time instances

Timestamp secondsSince1970: anInteger => Timestamp

creates a timestamp from the given number of seconds. Useful to convert UNIX timestamps.

Timestamp secondsSince1900: anInteger => Timestamp

creates a timestamp from the given number of seconds. Useful to convert NTP timestamps.

Conversion

aTimestamp asUTCTimestamp => Timestamp

convert a timestamp to an UTC timestamp

aTimestamp asLocalTimestamp => Timestamp

convert a timestamp to a local timestamp (i.e. no timezone info)

aTimestamp asTZTimestamp => Timestamp

convert a timestamp to a timestamp for your timezone

aTimestamp asTZTimestamp: utcOffsetInSeconds => Timestamp

convert a timestamp to a timestamp with the given tz offset

aTimestamp asTZTimestampInZone: nameOfTimeZone => Timestamp

convert a timestamp to a timestamp in the given timezone.

for example to get the current time in NewYork, use " Timestamp now asTZTimestampInZone:'EST' "
and to get the time in Stuttgart, use " Timestamp now asTZTimestampInZone:'MEZ' "

aTimestamp asDate => Date

convert a timestamp to a date (i.e. forgets the time information). Mainly useful for printing.

aTimestamp asTime => Time

convert a timestamp to a time (i.e. forgets the date information). Mainly useful for printing.

Accessing

aTimestamp day => Integer

the day in month (1 .. 31)

aTimestamp month => Integer

the month in year (1 .. 12)

aTimestamp year => Integer

the year

aTimestamp hours => Integer

the hour within the day (0..23)

aTimestamp minutes => Integer

the minutes within the hour (0 .. 59)

aTimestamp seconds => Integer

the seconds within the minute (0 .. 59)

aTimestamp milliSeconds => Integer

the truncated milliseconds within the second (0 .. 999)

aTimestamp microSeconds => Integer

the truncated microseconds within the second (0 .. 999999). If the timestamp was acquired from an operating system which does not provide that precision, these will be the milliseconds * 1000.

aTimestamp nanoSeconds => Integer

the truncated nanoseconds within the second (0 .. 999999999). Will be microseconds * 1000 if the source did not provide the precision.

aTimestamp picoSeconds => Integer

the picoseconds within the second (0 .. 999999999999). Will be nanoseconds * 1000 if the source did not provide the precision

aTimestamp exactMilliSeconds => Number

the exact milliseconds within the second as integer (0 .. 999) or fixed point number (0 .. 999.xxx)

aTimestamp exactMicroSeconds => Number

the exact microseconds within the second

aTimestamp exactNanoSeconds => Number

the exact nanoseconds within the second

aTimestamp dayInWeek => Integer

the weekday in European numbering (1=Monday)

aTimestamp dayOfWeek => Integer

the weekday in US numbering (1=Sunday)

aTimestamp dayInYear => Integer

the day within the year (1=1st January)

aTimestamp weekInYear => Integer

the week-number within the year. The returned week number starts with 1 for the first week which has a thursday in it (see DIN 1355-1/ISO 8601). Be prepared: by definition this can lead to the 1st week starting in the old year!

Queries

aTimestamp utcSecondsSince1900 => Integer

the number of seconds since 1.1.1900; timestamps are often represented as such in communication protocols (e.g. NTP and OSC)

aTimestamp utcSecondsSince1901 => Integer

the number of seconds since 1.1.1901; timestamps are sometimes represented as such in communication protocols

aTimestamp utcSecondsSince1970 => Integer

the number of seconds since 1.1.1970; UNIX timestamps are represented as such in communication protocols

Printing

aTimestamp printStringRFC1123Format => String

a string representation as in RFC1123.
For example, " 'Wed, 05 Jan 2022 19:41:31 GMT' "

aTimestamp printRFC1123FormatOn: aStream => void

append the RFC1123 representation to a stream.
E.g. "Timestamp now printRFC1123FormatOn: Transcript".

aTimestamp printStringIso8601 => String

generates a string representation as defined in Iso8601.
For example, " '2022-01-05T20:43:55.068' "

aTimestamp printIso8601FormatOn: aStream => void

append the Iso8601 representation to a stream.
E.g. "Timestamp now printIso8601FormatOn: Transcript".

aTimestamp printStringIso8601Compressed => String

generates a compressed string representation as defined in Iso8601.
For example, " 20220105T204544.828 "

aTimestamp printIso8601CompressedOn: aStream => void

append the compressed Iso8601 representation to a stream.
E.g. "Timestamp now printIso8601CompressedOn: Transcript".

aTimestamp printStringFormat: formatString => String

generates a string representation as specified in formatString.
For example, " Timestamp now printStringFormat:'%h:%m:%s' " might generate a string like " '20:48:47' "
Valid format characters are:

"%h" (hour 24 padded),"%m" (minutes),"%s" (seconds),"%i" (millis),"%j" (micros),
"%(day)" (day-nr in month), "%(month)" (month-nr), "%(year)" (year),
"%H" (hour 24 unpadded), "%M" (minutes unpadded), "%S" (seconds unpadded),
"%(milli)" (millis), "%(milli1)" (millis, 1 digit), "%(milli3)" (millis, 3 digits),
"%(micro)" (micros), "%(micro6)" (micros, 6 digits),
"%(nano)" (nanos), "%(nano9)" (nanos, 9 digits),
"%(pico)" (picos), "%(pico12)" (picos, 12 digits),
"%(weekDay)" (1 to 7), "%(dayName)" (in current language), "%(monthName)" (in current language), "%(shortDayName)" (in current language), "%(shortMonthName)" (in current language).

For a full list, see the AbstractTime class documentation, or look into the source in the class browser.

aTimestamp printOn: aStream format: formatString => void

same as above, but the string is sent to aStream.

TimeDuration

TimeDuration instances represent a time-delta. (i.e. seconds + fractional seconds). TimeDurations are typically returned when timestamps are subtracted. They provide a protocol similar to the above described Time protocol (albeit with a higher resolution).

TimeDurations can be either created via constructor messages to the TimeDuration class, by arithmetic on Timestamps, or by some special messages to numbers:

Creation (Constructors)

TimeDuration hours: h minutes: m seconds: s

TimeDuration hours: h minutes: m seconds: s milliseconds: ms

TimeDuration days: d hours: h minutes: m seconds: s nanoSeconds: n

Creation (In Number)

aNumber hours. => TimeDuration

aNumber minutes. => TimeDuration

aNumber seconds. => TimeDuration

aNumber milliseconds.=> TimeDuration

aNumber microseconds => TimeDuration

aNumber nanoseconds => TimeDuration

aNumber picoseconds. => TimeDuration

aNumber weeks => TimeDuration

aNumber months => TimeDuration

aNumber years => TimeDuration

each returns a corresponding time duration.

E.g. "10 days" gives you a time duration object representing 10*24 hours or 10*24*3600 seconds

Creation (from Timestamps)

"timestamp1 - timestamp2 => TimeDuration

the difference between two timestamps; notice that the result may be negative

Arithmetic

timeDuration1 + timeDuration2 => TimeDuration

a longer time duration.

E.g. "1 days + 10 hours"

timeDuration1 - timeDuration2 => TimeDuration

a shorter time duration. Result may bring you back in time (i.e. be negative)

timeDuration1 * number => TimeDuration

a multiple

E.g. "10 minutes * 10" => 100 minutes

TimeZone

TimeZone instances associate an UTC-offset to a timezone name. The class can be asked for known timezones with "TimeZone timeZones".

Due to the bad fact that zone names are NOT unambiguous ('IST', 'CST' and others), it is highly recommended to NOT use them when printing timestamps or other geographic time information. Instead use the '+/-UTCoffset' notation. The default print function use the ISO recommendations, which do so. The same is true for DST info. Grazy politicians seem to have no idea, what the cost of populistic changes in the switching dates/times are, and we do not carry with us a historic table of when and where DST was in effect, and by how much.
If your test needs that, refer to the timezone database which can be downloaded from the internet.

Class Queries

TimeZone timeZones => Dictionary

Returns a map, associating names to wellknown timezones. Notice that a reverse mapping is not in general possible, as there are usually multiple names (given by individual countries) referring to the same zone, and also both daylight saving and standard times are in this list (e.g. an utcOffset of -540 can be any of 'AKST', 'YST' or 'HDT').

Also be careful, as some countries (brainlessly) use conflicting names: 'IST' is used (locally) as 'Irish Standard', 'Israel Standard' or 'India Standard' time; and 'CST' could be any of 'China Standard', 'Central Standard' or 'Cuba' time. Sigh!

The table returns 'India' for 'IST' and 'Chicago-Central' for 'CST'. Consult the table to make sure it delivers what you expected.

Instance Creation

TimeZone name: nameOfZone => TimeZone

For example, "TimeZone name:'JST'" or "TimeZone name:'EDT'" 'Wed, 05 Jan 2022 19:41:31 GMT'

Instance Queries

aTimeZone utcOffset => Integer

the offset from UTC in seconds. Negative means EAST of Greenwich, positive WEST.

Notice that "GMT" is a timezone whereas "UTC" is the coordinated universal time. However, both have the same UTC offset of 0 (zero).

aTimeZone abbreviation => String

the abbreviated name, which is also the 'official' name-key in the timeZones list.

Typical are 'EDT', 'CET' or 'JST', but also the military names 'A' through 'Z', with 'Z' being the same as 'UTC'.

aTimeZone name => String

the name spelled out.

E.g. "(TimeZone name:'EDT') name" gives 'eastern daylight' and "(TimeZone name:'B') name" gives 'bravo'.

aTimeZone isDST => Boolean

true if this timeZone is a daylight saving time.

Examples

Printed on a machine in Germany with DST in effect.

    TZTimestamp nowInTimeZone:'CEST'   => 2023-07-07 14:58:06.329+02
    TZTimestamp nowInTimeZone:'EET'    => 2023-07-07 14:58:10.883+02
    TZTimestamp nowInTimeZone:'EEST'   => 2023-07-07 15:58:24.235+03

    TZTimestamp now                    => 2023-07-07 14:58:33.203+02
    Timestamp now                      => 2023-07-07 14:58:46.155
    UtcTimestamp now                   => 2023-07-07 12:58:52.851Z
    Timestamp now asTZTimestampInZone:'JST'  => 2023-07-07 21:58:54.341+09

    UtcTimestamp now printStringIso8601 => '2023-07-07T16:07:27.977Z'
    TZTimestamp now printStringIso8601  => '2023-07-07T18:08:07.644+02'
    Timestamp now printStringIso8601    => '2023-07-07T18:08:35.425'

    Time now                           => 14:59:00
    Date today                         => 07-07-2023

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

    Timestamp readFrom:'2023-07-07T16:07:27.977Z'   => (UtcTimestamp 2023-07-07 16:07:27.977Z)
    Timestamp readFrom:'2023-07-07T18:08:07.644+02' => (TZTimestamp 2023-07-07 18:08:07.644+02)
    Timestamp readFrom:'2023-07-07T18:08:07.644'    => (Timestamp 2023-07-07 18:08:07.644)

    Timestamp now + 10 days             => 2023-07-17 18:13:31.514

---

Copyright © 2014-2024 eXept Software AG