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).
Times are seldom used - usually timestamps are better suited.

Creation

Time now => a time

provides the current time of day

Arithmetic

aTime addSeconds: nSeconds => a time

aTime addMinutes: nMinutes => a time

aTime addHours: nHours => a time

to compute times

Accessing

aTime hours => hours (0..24)

aTime minutes => hours (0..59)

aTime seconds => hours (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 => a date

provides the current date

Date tomorrow => a date

provides the date of tomorrow

Date yesterday => a date

provides the date of yesterday

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

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

Arithmetic

aDate addDays: numDays => a date

to compute a date numDays after aDate

aDate subtractDays: numDays => a date

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

aDate subtractDate: date2 => 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 => day (1..31)

aDate month => month (1..12)

aDate year => year

to retrieve date components.

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 => a timestamp

provides the current timestamp (local time)

UTCTimestamp now => a timestamp

provides the current timestamp (UTC time)

TZTimestamp now => a timestamp

provides the current timestamp (in the local timezone)

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 => a timestamp

creates a timestamp from given date and time instances

Timestamp secondsSince1970: anInteger => a timestamp

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

Timestamp secondsSince1900: anInteger => a timestamp

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

Conversion

aTimestamp asUTCTimestamp => a timestamp

convert a timestamp to an UTC timestamp

aTimestamp asLocalTimestamp => a timestamp

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

aTimestamp asTZTimestamp => a timestamp

convert a timestamp to a timestamp for your timezone

aTimestamp asTZTimestamp: utcOffsetInSeconds => a timestamp

convert a timestamp to a timestamp with the given tz offset

aTimestamp asTZTimestampInZone: nameOfTimeZone => a 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 => a date

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

aTimestamp asTime => a 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 (eg. 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.
Eg. " 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.
Eg. " 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.
Eg. " 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