Time

Usage

use Time;

or

import Time;

Support for routines related to measuring the passing of time.

This module provides support for querying wall time in the local timezone and 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 }

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

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

Specifies the day of the week

enum dayOfWeek { Monday = 0, Tuesday = 1, Wednesday = 2, Thursday = 3, Friday = 4, Saturday = 5, Sunday = 6 }

Days in the week, starting with Monday = 0

enum isoDayOfWeek { Monday = 1, Tuesday = 2, Wednesday = 3, Thursday = 4, Friday = 5, Saturday = 6, Sunday = 7 }

Days in the week, starting with Monday = 1

param MINYEAR = 1

The minimum year allowed in date objects

param MAXYEAR = 9999

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)

Return true if year is a leap year

proc daysInMonth(year: int, month: 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

A record representing a date

proc year

The year represented by this date value

proc month

The month represented by this date value

proc day

The day represented by this date value

proc type min

The minimum representable date

proc type max

The maximum representable date

proc type resolution

The minimum non-zero difference between two dates

proc date.init(year, month, day)

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

A date object representing the current day

proc type date.fromTimestamp(timestamp)

The date that is timestamp seconds from the epoch

proc type date.fromOrdinal(ord)

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

proc date.replace(year = 0, month = 0, day = 0)

Replace the year, month and/or day in a date to create a new date

proc date.timetuple()

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

proc date.toOrdinal()

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

proc date.weekday()

Return the day of the week as a dayOfWeek. Monday == 0, Sunday == 6

proc date.isoWeekday()

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

proc date.isoCalendar()

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

proc date.isoFormat()

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

proc date.ctime()

Return a string representing the date

proc date.strftime(fmt: string)

Return a formatted string matching the format argument and the date

proc date.writeThis(f) throws

Writes this date in ISO 8601 format: YYYY-MM-DD

proc date.readThis(f) throws

Reads this date from ISO 8601 format: YYYY-MM-DD

record time

A record representing a time

proc hour

The hour represented by this time value

proc minute

The minute represented by this time value

proc second

The second represented by this time value

proc microsecond

The microsecond represented by this time value

proc timezone

The timezone represented by this time value

proc type min

The minimum representable time

proc type max

The maximum representable time

proc type resolution

The minimum non-zero difference between two times

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

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

Warning

tz is unstable; its type may change in the future

proc time.init(hour = 0, minute = 0, second = 0, microsecond = 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)

Replace the hour, minute, second, microsecond in a time to create a new time. All arguments are optional.

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

Replace the hour, minute, second, microsecond and tz in a time to create a new time. All arguments are optional.

Warning

tz is unstable; its type may change in the future

proc time.isoFormat()

Return a string representing the time in ISO format

proc time.utcOffset()

Return the offset from UTC

proc time.dst()

Return the daylight saving time offset

proc time.tzname()

Return the name of the timezone for this time value

proc time.strftime(fmt: string)

Return a string matching the format argument for this time

proc time.writeThis(f) throws

Writes this time in ISO format: hh:mm:ss.sss

proc time.readThis(f) throws

Reads this time from ISO format: hh:mm:ss.sss

record datetime

A record representing a combined date and time

proc type min

The minimum representable date and time

proc type max

The maximum representable date and time

proc type resolution

The minimum non-zero difference between two datetimes

proc year

The year represented by this datetime value

proc month

The month represented by this datetime value

proc day

The day represented by this datetime value

proc hour

The hour represented by this datetime value

proc minute

The minute represented by this datetime value

proc second

The second represented by this datetime value

proc microsecond

The microsecond represented by this datetime value

proc timezone

The timezone represented by this datetime value

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

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.

Warning

tz is unstable; its type may change in the future

proc datetime.init(year, month, day, hour = 0, minute = 0, second = 0, microsecond = 0)

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(d: date, t: time)

Initialize a new datetime value from the given date and time

proc type datetime.now()

Return a datetime value representing the current time and date

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

Return a datetime value representing the current time and date

proc type datetime.utcNow()

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

proc type datetime.fromTimestamp(timestamp: real)

The datetime that is timestamp seconds from the epoch

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

The datetime that is timestamp seconds from the epoch

Warning

tz is unstable; its type may change in the future

proc type datetime.utcFromTimestamp(timestamp)

The datetime that is timestamp seconds from the epoch in UTC

proc type datetime.fromOrdinal(ordinal)

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

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

Form a datetime value from a given date and time

proc datetime.getdate()

Get the date portion of the datetime value

proc datetime.gettime()

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

proc datetime.timetz()

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, in tz = this.timezone)

Replace the year, month, day, hour, minute, second, microsecond, or tz to form a new datetime object. All arguments are optional.

proc datetime.astimezone(in tz: shared Timezone)

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

Warning

tz is unstable; its type may change in the future

proc datetime.utcOffset()

Return the offset from UTC

proc datetime.dst()

Return the daylight saving time offset

proc datetime.tzname()

Return the name of the timezone for this datetime value

proc datetime.timetuple()

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

proc datetime.utctimetuple()

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

proc datetime.toOrdinal()

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

proc datetime.weekday()

Return the day of the week as a dayOfWeek. Monday == 0, Sunday == 6

proc datetime.isoWeekday()

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

proc datetime.isoCalendar()

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

proc datetime.isoFormat(sep = "T")

Return the datetime as a string in ISO format

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

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)

Create a string from a datetime matching the format string

proc datetime.ctime()

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

proc datetime.writeThis(f) throws

Writes this datetime in ISO format: YYYY-MM-DDThh:mm:ss.sss

proc datetime.readThis(f) throws

Reads this datetime from ISO format: YYYY-MM-DDThh:mm:ss.sss

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

The number of days this timedelta represents

proc seconds

The number of seconds this timedelta represents

proc microseconds

The number of microseconds this timedelta represents

proc type min

Return the minimum representable timedelta object.

proc type max

Return the maximum representable timedelta object.

proc type resolution

Return the smallest positive value representable by a timedelta object.

proc timedelta.init(days = 0, seconds = 0, microseconds = 0, milliseconds = 0, minutes = 0, hours = 0, weeks = 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 abs(t: timedelta)

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

class Timezone

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

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)

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

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

Returns

The current day of the week

Return type

Day

proc sleep(t: real, unit: TimeUnits = TimeUnits.seconds): void

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

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 clear(): void

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

proc start(): void

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

proc stop(): void

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

proc reset()

Clear the elapsed time and ensure the stopwatch is stopped

proc restart()

Clear the elapsed time and ensure the stopwatch is running

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

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)

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 start(): void

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

proc stop(): void

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

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

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)