Time

Usage

use Time;

or

import Time;

Support for routines related to measuring the passing of time.

This module provides support for querying local wall time or UTC time, and structures for manipulating dates and times. Note that timezone-naive local and UTC time querying methods will produce different results if the local time is not UTC, including potentially different calendar dates.

It also implements a record stopwatch that can measure the execution time of sections of a program. The stopwatch has the potential for microsecond resolution and is intended to be useful for performance testing.

enum TimeUnits { microseconds, milliseconds, seconds, minutes, hours }

Warning

The ‘TimeUnits’ type is deprecated. Please specify times in seconds in this module.

Specifies the units to be used when certain functions return a time

enum constant microseconds
enum constant milliseconds
enum constant seconds
enum constant minutes
enum constant hours
config param cIsoDayOfWeek = false

Controls whether dayOfWeek starts with Monday = 0 or Monday = 1.

  • If true, dayOfWeek represents Monday as day 1.

  • If false, dayOfWeek represents Monday as day 0. This behavior is deprecated and will be removed in an upcoming release.

The deprecated behavior is on by default. To opt-in to the new behavior, recompile your program with -scIsoDayOfWeek=true.

enum dayOfWeek { Monday = firstDayOfWeekNum, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday }

Days in the week, starting with Monday. Monday is represented as 0 when cIsoDayOfWeek is false (deprecated), or 1 otherwise (future default).

Warning

In an upcoming release ‘dayOfWeek’ will represent Monday as 1 instead of 0 by default. During the deprecation period this behavior can be controlled with cIsoDayOfWeek.

enum constant Monday = firstDayOfWeekNum
enum constant Tuesday
enum constant Wednesday
enum constant Thursday
enum constant Friday
enum constant Saturday
enum constant Sunday
enum Day { sunday = 0, monday, tuesday, wednesday, thursday, friday, saturday }

Warning

enum ‘Day’ is deprecated. Please use day instead

enum constant sunday = 0
enum constant monday
enum constant tuesday
enum constant wednesday
enum constant thursday
enum constant friday
enum constant saturday
enum day { sunday = 0, monday, tuesday, wednesday, thursday, friday, saturday }

Warning

enum ‘day’ is deprecated. Please use dayOfWeek instead

Specifies the day of the week

enum constant sunday = 0
enum constant monday
enum constant tuesday
enum constant wednesday
enum constant thursday
enum constant friday
enum constant saturday
enum isoDayOfWeek { Monday = 1, Tuesday = 2, Wednesday = 3, Thursday = 4, Friday = 5, Saturday = 6, Sunday = 7 }

Warning

enum ‘isoDayOfWeek’ is deprecated. Please use dayOfWeek instead

Days in the week, starting with Monday = 1

enum constant Monday = 1
enum constant Tuesday = 2
enum constant Wednesday = 3
enum constant Thursday = 4
enum constant Friday = 5
enum constant Saturday = 6
enum constant Sunday = 7
param MINYEAR = 1

Warning

‘MINYEAR’ is deprecated; use date.min.year instead

The minimum year allowed in date objects

param MAXYEAR = 9999

Warning

‘MAXYEAR’ is deprecated; use date.max.year instead

The maximum year allowed in date objects

const unixEpoch = new dateTime(1970, 1, 1)

The Unix Epoch date and time

proc timeSinceEpoch(): timeDelta

Get the time since Unix Epoch in seconds

proc isLeapYear(year: int): bool

Return true if year is a leap year

proc daysInMonth(year: int, month: int): int throws

Return the number of days in month month during the year year. The number for a month can change from year to year due to leap years.

Throws

IllegalArgumentError – Thrown if month is out of range.

record date: serializable

A record representing a date

proc year: int

The year represented by this date value

proc month: int

The month represented by this date value

proc day: int

The day represented by this date value

proc type min: date

The minimum representable date

proc type max: date

The maximum representable date

proc type resolution: timeDelta

The minimum non-zero difference between two dates

proc date.init(year: int, month: int, day: int)

Initialize a new date value from a year, month, and day. All three arguments are required and must be in valid ranges. The valid ranges are:

1 <= year <= 9999

1 <= month <= 12

1 <= day <= the number of days in the given month and year

proc type date.today(): date

A date object representing the current day, using naive local time

proc type date.utcToday(): date

A date object representing the current day, using naive UTC time

proc type date.fromTimestamp(timestamp): date

Warning

‘date.fromTimestamp’ is deprecated, please use ‘dateTime.createUtcFromTimestamp().getDate()’ instead

proc type date.createFromTimestamp(timestamp: real): date

Warning

‘date.createFromTimestamp’ is deprecated, please use ‘dateTime.createUtcFromTimestamp().getDate()’ instead

The date that is timestamp seconds from the epoch

proc type date.fromOrdinal(ord): date

Warning

‘date.fromOrdinal’ is deprecated, please use ‘date.createFromOrdinal’ instead

proc type date.createFromOrdinal(ordinal: int): date

The date that is ordinal days from 1-1-0001

proc date.replace(year = -1, month = -1, day = -1): date

Get a new date based on this one, optionally with the year, month and/or day replaced.

proc date.timetuple(): tm

Warning

‘date.timetuple’ is unstable

Return a filled record matching the C struct tm type for the given date

proc date.toOrdinal(): int

Return the number of days since 1-1-0001 this date represents

proc date.weekday(): dayOfWeek  where cIsoDayOfWeek

Return the day of the week.

proc date.weekday(): dayOfWeek  where !cIsoDayOfWeek

Warning

The version of ‘date.weekday’ returning a dayOfWeek starting with Monday = 0 is deprecated. Recompile with -sCIsoDayOfWeek=true to opt in to the new behavior of Monday = 1

proc date.isoWeekday(): isoDayOfWeek

Warning

‘date.isoWeekday’ is deprecated; use date.weekday instead

Return the day of the week as an isoDayOfWeek. Monday == 1, Sunday == 7

proc date.isoWeekDate(): (int, int, int)

Return the ISO week date as a tuple containing the ISO week-numbering year, ISO week number, and ISO weekday number.

proc date.isoCalendar(): (int, int, int)

Warning

date.isoCalendar is deprecated; use date.isoWeekDate instead

Return the ISO week date as a tuple containing the ISO week-numbering year, ISO week number, and ISO weekday number.

operator date.:(x: date, type t: string)

Get a string representation of this date in ISO format YYYY-MM-DD.

proc date.isoFormat(): string

Warning

date.isoFormat is deprecated; use cast to string instead

Return the date as a string in ISO 8601 format: “YYYY-MM-DD”

proc date.ctime(): string

Warning

‘date.ctime’ is unstable

Return a string representing the date

proc date.strftime(fmt: string): string

Warning

‘date.strftime’ is unstable

Return a formatted string matching the format argument and the date

proc date.serialize(writer, ref serializer) throws

Writes this date formatted as YYYY-MM-DD

proc ref date.deserialize(reader, ref deserializer) throws

Reads this date with the same format used by date.serialize

record time: serializable

A record representing a time

proc hour: int

The hour represented by this time value

proc minute: int

The minute represented by this time value

proc second: int

The second represented by this time value

proc microsecond: int

The microsecond represented by this time value

proc timezone: shared Timezone?

Warning

timezone is unstable

The timezone represented by this time value

proc type min: time

The minimum representable time

proc type max: time

The maximum representable time

proc type resolution: timeDelta

The minimum non-zero difference between two times

proc time.init(hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0, in tz: shared Timezone?)

Warning

tz is unstable; its type may change in the future

Initialize a new time value from the given hour, minute, second, microsecond, and timezone. All arguments are optional

proc time.init(hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0)

Initialize a new time value from the given hour, minute, second, microsecond. All arguments are optional

proc time.replace(hour = -1, minute = -1, second = -1, microsecond = -1): time

Get a new time based on this one, optionally with the hour minute, second, and/or microsecond replaced.

proc time.replace(hour = -1, minute = -1, second = -1, microsecond = -1, in tz): time

Warning

tz is unstable; its type may change in the future

Get a new time based on this one, optionally with the hour minute, second, microsecond and/or tz replaced.

operator time.:(x: time, type t: string)

Get a string representation of this time in ISO format hh:mm:ss.ssssss, followed by ±hh:mm if a timezone is specified.

proc time.isoFormat(): string

Warning

time.isoFormat is deprecated; use cast to string instead

proc time.utcOffset(): timeDelta

Warning

‘utcOffset’ is unstable

Return the offset from UTC

proc time.dst(): timeDelta

Warning

‘dst’ is unstable

Return the daylight saving time offset

proc time.tzname(): string

Warning

‘tzname’ is unstable

Return the name of the timezone for this time value

proc time.strftime(fmt: string): string

Warning

‘time.strftime’ is unstable

Return a string matching the format argument for this time

proc time.serialize(writer, ref serializer) throws

Writes this time formatted as hh:mm:ss.ssssss, followed by ±hh:mm if a timezone is specified

proc ref time.deserialize(reader, ref deserializer) throws

Reads this time with the same format used by time.serialize

type datetime = dateTime

Warning

‘datetime’ is deprecated, please use dateTime instead

record dateTime: serializable

A record representing a combined date and time

proc type min: dateTime

The minimum representable date and time

proc type max: dateTime

The maximum representable date and time

proc type resolution: timeDelta

The minimum non-zero difference between two dateTimes

proc year: int

The year represented by this dateTime value

proc month: int

The month represented by this dateTime value

proc day: int

The day represented by this dateTime value

proc hour: int

The hour represented by this dateTime value

proc minute: int

The minute represented by this dateTime value

proc second: int

The second represented by this dateTime value

proc microsecond: int

The microsecond represented by this dateTime value

proc timezone: shared Timezone?

Warning

timezone is unstable

The timezone represented by this dateTime value

proc dateTime.init(year: int, month: int, day: int, hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0, in tz)

Warning

tz is unstable; its type may change in the future

Initialize a new dateTime value from the given year, month, day, hour, minute, second, microsecond and timezone. The year, month, and day arguments are required, the rest are optional.

proc dateTime.init(year: int, month: int, day: int, hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0)

Initialize a new dateTime value from the given year, month, day, hour, minute, second, and microsecond. The year, month, and day arguments are required, the rest are optional.

proc dateTime.init(d: date, t: time = new time())

Initialize a new dateTime value from the given date and time

proc type dateTime.now(): dateTime

Return a dateTime value representing the current time and date, in naive local time.

proc type dateTime.now(in tz: shared Timezone?): dateTime

Warning

tz is unstable; its type may change in the future

Return a dateTime value representing the current time and date

proc type dateTime.utcNow(): dateTime

Return a dateTime value representing the current time and date in UTC

proc type dateTime.fromTimestamp(timestamp: real): dateTime

Warning

‘dateTime.fromTimestamp’ is deprecated, please use ‘dateTime.createFromTimestamp’ instead

proc type dateTime.fromTimestamp(timestamp: real, in tz: shared Timezone?): dateTime

Warning

‘dateTime.fromTimestamp’ is deprecated, please use ‘dateTime.createFromTimestamp’ instead

proc type dateTime.createFromTimestamp(timestamp: real): dateTime

The dateTime that is timestamp seconds from the epoch, in naive local time.

proc type dateTime.createFromTimestamp(timestamp: real, in tz: shared Timezone?): dateTime

Warning

tz is unstable; its type may change in the future

The dateTime that is timestamp seconds from the epoch

proc type dateTime.utcFromTimestamp(timestamp): dateTime

Warning

‘dateTime.utcFromTimestamp’ is deprecated, please use ‘dateTime.createUtcFromTimestamp’ instead

proc type dateTime.createUtcFromTimestamp(timestamp): dateTime

The dateTime that is timestamp seconds from the epoch in UTC

proc type dateTime.fromOrdinal(ordinal): dateTime

Warning

‘dateTime.fromOrdinal’ is deprecated, please use ‘new dateTime(date.createFromOrdinal(ordinal))’ instead

proc type dateTime.createFromOrdinal(ordinal: int): dateTime

Warning

‘dateTime.createFromOrdinal’ is deprecated; use ‘new dateTime(date.createFromOrdinal(ordinal))’ instead

The dateTime that is ordinal days from 1-1-0001

proc type dateTime.combine(d: date, t: time): dateTime

Warning

dateTime.combine is deprecated; use new dateTime taking a date and time argument instead

Form a dateTime value from a given date and time

proc dateTime.getdate(): date

Warning

‘dateTime.getdate’ is deprecated. Please use dateTime.getDate instead

Methods on dateTime values

proc dateTime.getDate(): date

Get the date portion of the dateTime value

proc dateTime.gettime(): time

Warning

‘dateTime.gettime’ is deprecated. Please use dateTime.getTime instead

proc dateTime.getTime(): time

Get the time portion of the dateTime value, with tz = nil

proc dateTime.timetz(): time

Warning

tz is unstable; its type may change in the future

Get the time portion of the dateTime value including the tz field

proc dateTime.replace(year = -1, month = -1, day = -1, hour = -1, minute = -1, second = -1, microsecond = -1): dateTime

Get a new time based on this one, optionally with the year, month, day, hour minute, second, and/or microsecond replaced.

proc dateTime.replace(year = -1, month = -1, day = -1, hour = -1, minute = -1, second = -1, microsecond = -1, in tz = this.timezone): dateTime

Warning

tz is unstable; its type may change in the future

Get a new time based on this one, optionally with the year, month, day, hour minute, second, microsecond and/or tz replaced.

proc dateTime.astimezone(in tz: shared Timezone): dateTime

Warning

tz is unstable; its type may change in the future

Return the date and time converted into the timezone in the argument

proc dateTime.utcOffset(): timeDelta

Warning

‘utcOffset’ is unstable

Return the offset from UTC

proc dateTime.dst(): timeDelta

Warning

‘dst’ is unstable

Return the daylight saving time offset

proc dateTime.tzname(): string

Warning

‘tzname’ is unstable

Return the name of the timezone for this dateTime value

proc dateTime.timetuple(): tm

Warning

‘dateTime.timetuple’ is unstable

Return a filled record matching the C struct tm type for the given dateTime

proc dateTime.utctimetuple(): tm

Warning

‘dateTime.utctimetuple’ is unstable

Return a filled record matching the C struct tm type for the given dateTime in UTC

proc dateTime.toOrdinal(): int

Warning

dateTime.toOrdinal is deprecated; use dateTime.getDate().toOrdinal() instead

Return the number of days since 1-1-0001 this dateTime represents

proc dateTime.weekday(): dayOfWeek  where cIsoDayOfWeek

Warning

dateTime.weekday is deprecated; use dateTime.getDate().weekday() instead

Return the day of the week.

proc dateTime.weekday(): dayOfWeek  where !cIsoDayOfWeek

Warning

The version of ‘dateTime.weekday’ returning a dayOfWeek starting with Monday = 0 is deprecated. Recompile with -sCIsoDayOfWeek=true to opt in to the new behavior of Monday = 1

proc dateTime.isoWeekday(): isoDayOfWeek

Warning

dateTime.isoWeekday is deprecated; use dateTime.getDate().weekday() instead

Return the day of the week as an isoDayOfWeek. Monday == 1, Sunday == 7

proc dateTime.isoCalendar(): (int, int, int)

Warning

dateTime.isoCalendar is deprecated; use dateTime.getDate().isoWeekDate() instead

Return the ISO date as a tuple containing the ISO year, ISO week number, and ISO day of the week

operator dateTime.:(x: dateTime, type t: string)

Get a string representation of this dateTime in ISO format YYYY-MM-DDThh:mm:ss.ssssss, followed by ±hh:mm if a timezone is specified

proc dateTime.isoFormat(sep = "T"): string

Warning

dateTime.isoFormat is deprecated; use cast to string instead

Return the dateTime as a string in ISO format

proc type dateTime.strptime(date_string: string, format: string): dateTime

Warning

‘dateTime.strptime’ is unstable

Create a dateTime as described by the date_string and format string. Note that this routine currently only supports the format strings of C’s strptime().

proc dateTime.strftime(fmt: string): string

Warning

‘dateTime.strftime’ is unstable

Create a string from a dateTime matching the format string

proc dateTime.ctime(): string

Warning

‘dateTime.ctime’ is unstable

Return a string from a dateTime in the form: Wed Dec 4 20:30:40 2002

proc dateTime.serialize(writer, ref serializer) throws

Writes this dateTime formatted as YYYY-MM-DDThh:mm:ss.ssssss, followed by ±hh:mm if a timezone is specified

proc ref dateTime.deserialize(reader, ref deserializer) throws

Reads this dateTime with the same format used by dateTime.serialize

type timedelta = timeDelta

Warning

‘timedelta’ is deprecated. Please use timeDelta instead

record timeDelta

A record representing an amount of time. A timeDelta has fields representing days, seconds, and microseconds. These fields are always kept within the following ranges:

0 <= microseconds < 1000000

0 <= seconds < 60*60*24

-999999999 <= days <= 999999999

It is an overflow error if days is outside the given range.

proc days: int

The number of days this timeDelta represents

proc seconds: int

The number of seconds this timeDelta represents

proc microseconds: int

The number of microseconds this timeDelta represents

proc type min: timeDelta

Return the minimum representable timeDelta object.

proc type max: timeDelta

Return the maximum representable timeDelta object.

proc type resolution: timeDelta

Return the smallest positive value representable by a timeDelta object.

proc timeDelta.init(days: int = 0, seconds: int = 0, microseconds: int = 0, milliseconds: int = 0, minutes: int = 0, hours: int = 0, weeks: int = 0)

Initialize a timeDelta object. All arguments are optional and default to 0. Since only days, seconds and microseconds are stored, the other arguments are converted to days, seconds and microseconds.

proc timeDelta.init(timestamp: real)

Create a timeDelta from a given number of seconds

proc timeDelta.totalSeconds(): real

Return the total number of seconds represented by this object

proc timeDelta.abs(): timeDelta

Return the absolute value of this timeDelta. If is negative, then returns its negation, else returns it as-is.

proc abs(t: timeDelta): timeDelta

Warning

abs as a free function is deprecated; use timeDelta.abs instead

Return the absolute value of t. If t is negative, then returns -t, else returns t.

class Timezone

Warning

Timezone functionality is unstable and may change in the future

Abstract base class for time zones. This class should not be used directly, but concrete implementations of time zones should be derived from it.

proc utcOffset(dt: dateTime): timeDelta

The offset from UTC this class represents

proc dst(dt: dateTime): timeDelta

The timeDelta for daylight saving time

proc tzname(dt: dateTime): string

Warning

‘tzname’ is unstable

The name of this time zone

proc fromUtc(dt: dateTime): dateTime

Convert a time in UTC to this time zone

proc getCurrentTime(unit: TimeUnits = TimeUnits.seconds): real(64)

Warning

‘getCurrentTime()’ is deprecated please use ‘timeSinceEpoch().totalSeconds()’ instead

Arguments

unit : TimeUnits – The units for the returned value

Returns

The elapsed time since midnight, local time, in the units specified

Return type

real(64)

proc getCurrentDate(): (int, int, int)

Warning

‘getCurrentDate’ is deprecated; access the individual fields of ‘date.utcToday()’ as needed instead, or use ‘date.today()’ for local wall time

Returns

(year, month, day) as a tuple of 3 ints

The month is in the range 1 to 12. The day is in the range 1 to 31

proc getCurrentDayOfWeek(): day

Warning

‘getCurrentDayOfWeek’ is deprecated; please use ‘date.utcToday().weekday()’ instead, or ‘date.today().weekday()’ for local wall time

Returns

The current day of the week, calculated from UTC time.

Return type

day

proc sleep(t: real, unit: TimeUnits): void

Warning

‘sleep’ with a ‘TimeUnits’ argument is deprecated. Please use ‘sleep’ with a time in seconds

Delay a task for a duration in the units specified. This function will return without sleeping and emit a warning if the duration is negative.

Arguments
  • t : real – The duration for the time to sleep

  • unit : TimeUnits – The units for the duration

proc sleep(t: real): void

Delay a task for a duration specified in seconds. This function will return without sleeping and emit a warning if the duration is negative.

Arguments

t : real – The duration for the time to sleep

record stopwatch

Implements basic stopwatch behavior with a potential resolution of microseconds if supported by the runtime platform.

The stopwatch can be started, stopped, and cleared. A stopwatch is either running or stopped.

proc ref clear(): void

Clears the elapsed time. If the timer is running then it is restarted otherwise it remains in the stopped state.

proc ref start(): void

Starts the timer. A warning is emitted if the timer is already running.

proc ref stop(): void

Stops the timer. A warning is emitted if the timer is not running.

proc ref reset(): void

Clear the elapsed time and ensure the stopwatch is stopped

proc ref restart(): void

Clear the elapsed time and ensure the stopwatch is running

proc elapsed(unit: TimeUnits): real

Warning

‘stopwatch.elapsed’ with a ‘TimeUnits’ argument is deprecated. Please call ‘stopwatch.elapsed’ without an argument and assume it returns a time in seconds.

Returns the cumulative elapsed time, in the units specified, between all pairs of calls to start and stop since the timer was created or the last call to clear. If the timer is running, the elapsed time since the last call to start is added to the return value.

Arguments

unit : TimeUnits – The units for the returned value

Returns

The elapsed time in the units specified

Return type

real(64)

proc elapsed(): real

Returns the cumulative elapsed time, in seconds, between all pairs of calls to start and stop since the timer was created or the last call to clear. If the timer is running, the elapsed time since the last call to start is added to the return value.

Returns

The elapsed time in seconds

Return type

real(64)

record Timer

Warning

‘Timer’ is deprecated, please use ‘stopwatch’ instead

proc clear(): void

Clears the elapsed time. If the timer is running then it is restarted otherwise it remains in the stopped state.

proc ref start(): void

Starts the timer. A warning is emitted if the timer is already running.

proc ref stop(): void

Stops the timer. A warning is emitted if the timer is not running.

proc elapsed(unit: TimeUnits = TimeUnits.seconds): real

Warning

‘Timer.elapsed’ with a ‘TimeUnits’ argument is deprecated. Please call ‘stopwatch.elapsed’ without an argument and assume it returns a time in seconds.

Returns the cumulative elapsed time, in the units specified, between all pairs of calls to start and stop since the timer was created or the last call to clear. If the timer is running, the elapsed time since the last call to start is added to the return value.

Arguments

unit : TimeUnits – The units for the returned value

Returns

The elapsed time in the units specified

Return type

real(64)