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)

to retrieve the hour, minute and second component:

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 os not related to any particular date (as 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 (although the precision varies among Operating systems - some will 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. However, there is currently no support for pre-Gregorian 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.

Creation

Timestamp now => Timestamp

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

Timestamp nowWithMicroseconds => Timestamp

ditto with microsecond precision

UTCTimestamp now => Timestamp

provides the current timestamp (UTC time)

TZTimestamp now => Timestamp

provides the current timestamp (in the local timezone)

TZTimestamp nowInTimeZone: tzName

provides the current timestamp in the given timezone. E.g. TZTimestamp nowInTimeZone:'JST' returns the current time in Japan standard time.

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.

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

---

Copyright © 2014-2024 eXept Software AG