# std/time/time▲toc

Time represents instants as human readable calendar time.

A `timestd/time/time/time: V` represents an `instantstd/time/instant/instant: V` in time in a given `calendarstd/time/calendar/calendar: V` and `timezonestd/time/calendar/timezone: V` as a “human” calendar time. Months, days etc. are always 1-based.

Represents an instant in time for a certain calendar and timezone.

Add an SI second `durationstd/time/duration/duration: V` to a time.
`(time(2015,12,31,23,59,59,0.5) + duration(1)).show == "2016-01-01T00:00:00.500Z"`
`(time(2016,12,31,23,59,59,0.5) + duration(1)).show == "2016-12-31T23:59:60.500Z"`   (into a leap second).

Subtract an SI second `durationstd/time/duration/duration: V` from a time.
`(time(2016,1,1,0,0,0,0.5) - duration(1)).show == "2015-12-31T23:59:59.500Z"`
`(time(2017,1,1,0,0,0,0.5) - duration(1)).show == "2016-12-31T23:59:60.500Z"`   (into a leap second).

Return the exact SI second duration between to times.
`(time(2016,1,1,0,0,0,0.5) - time(2015,12,31,23,59,59)).show == "1.5s"`
`(time(2017,1,1,0,0,0,0.5) - time(2016,12,31,23,59,59)).show == "2.5s"`   (over a leap second)
`(time(2017,1,1,0,0,0,0.5) - time(2017,1,1,2,59,59,tz=tz-fixedstd/time/calendar/tz-fixed: (hours : int, mins : ?int, name : ?string, abbrv : ?string, hourwidth : ?int) -> timezone(3)).show == "2.5s"`   (GMT+3, and over a leap second).

Add a clock (hours, minutes, seconds) to a time. Takes leap years, leap seconds, etc. into account.

Add a date (years, months, days) and optional clock to a time. Takes leap years, leap seconds, etc. into account.

Add a specified number of days to a calendar time. Takes leap years etc. into account.
`time(2016,12,31,12).add-days(1).show == "2017-01-01T12:00:00Z"`   (over a leap second)
`time(1582,10,4,cal=cal-jg).add-days(1).show == "1582-10-15T00:00:00Z JG"`   (transition from Julian (`cal-julian`) to Gregorian (`cal-gregorianstd/time/calendar/cal-gregorian: calendar`) calendar).

Add a specified number of months to a calendar time.

Add a specified number of weeks to a calendar time.

Add a specified number of years to a calendar time.

Automatically generated. Retrieves the `calendar` constructor field of the `timestd/time/time/time: V` type.

Automatically generated. Retrieves the `clock` constructor field of the `timestd/time/time/time: V` type.

Compare two `timestd/time/time/time: V`s. Compares the actual instants in time and can thus compare across calendars and timezones.
`time(2001,7,2,tz=tz-fixedstd/time/calendar/tz-fixed: (hours : int, mins : ?int, name : ?string, abbrv : ?string, hourwidth : ?int) -> timezone("GMT+1",duration(3600))) > time(2001,7,1,23,30,0)`   (`Falsestd/core/False: bool`!).

Copy a `timestd/time/time/time: V` with optionally changing any of its attributes.
`t.copystd/time/time/copy: (t : time, year : ?int, month : ?int, day : ?int, hours : ?int, minutes : ?int, seconds : ?ddouble, tz : ?timezone, cal : ?calendar, ts : ?timescale) -> time(month=1,day=1,hours=0,minutes=0,seconds=zero)`   (copy to start of the year)
`t.copystd/time/time/copy: (t : time, year : ?int, month : ?int, day : ?int, hours : ?int, minutes : ?int, seconds : ?ddouble, tz : ?timezone, cal : ?calendar, ts : ?timescale) -> time(month=t.month+2,day=t.day+3)`   (add 2 months and 3 days)
`t.copystd/time/time/copy: (t : time, year : ?int, month : ?int, day : ?int, hours : ?int, minutes : ?int, seconds : ?ddouble, tz : ?timezone, cal : ?calendar, ts : ?timescale) -> time(tz=tz-localstd/time/calendar/tz-local: () -> ndet timezone())`   (change to a different time zone).

Copy a `timestd/time/time/time: V` with a new `datestd/time/date/date: V` and optional `clockstd/time/date/clock: V` (=`t.clock`), and optionally a new timezone (=`t.timezone`) and calendar (=`t.calendar`).

Automatically generated. Retrieves the `date` constructor field of the `timestd/time/time/time: V` type.

Return the day of the month of a `timestd/time/time/time: V`. (starting at 1).

Return the day of the year of time `t` (starting at 1).

Return the total days in the month of time `t`.

Return the total days in the year of time `t`.

Return the days between two times. Uses the calendar and timezone of the first time `t1` to determine the date of `t2`.

```days-until( time(2000,1,1), time(2000,1,1) ) == 0
days-until( time(2000,1,1), time(2000,1,2) ) == 1
days-until( time(2000,1,1), time(2000,1,2,tz=tz-fixed(1)) ) == 0
days-until( time(2000,1,1), time(2000,3,1) ) == 60
days-until( time(2000,2,1), time(2000,1,1) ) == -1
days-until( time(2000,1,1), time(2000,1,1) ) == 0
days-until( time(2000,1,1), time(2000,1,2) ) == 1
days-until( time(2000,1,1), time(2000,1,2,tz=tz-fixedstd/time/calendar/tz-fixed: (hours : int, mins : ?int, name : ?string, abbrv : ?string, hourwidth : ?int) -> timezone(1)) ) == 0
days-until( time(2000,1,1), time(2000,3,1) ) == 60
days-until( time(2000,2,1), time(2000,1,1) ) == -1
```
.

Return the whole hours of a `timestd/time/time/time: V`.

Automatically generated. Retrieves the `instant` constructor field of the `timestd/time/time/time: V` type.

Return the Julian date (JD) number for a given `timestd/time/time/time: V` `t`. This interprets the Julian date in the calendar of `t` with the timezone of `t` applied.
`time(-4713,11,24,12,cal=cal-tt).jd == "0"`
`time(1972,1,2,tz=tz-fixedstd/time/calendar/tz-fixed: (hours : int, mins : ?int, name : ?string, abbrv : ?string, hourwidth : ?int) -> timezone(1)).jd == "2441318.5"`
`time(1972,1,2,tz=tz-fixedstd/time/calendar/tz-fixed: (hours : int, mins : ?int, name : ?string, abbrv : ?string, hourwidth : ?int) -> timezone(1)).instant.jd(ts-tistd/time/utc/ts-ti: timescale).show(9) == "2441318.458333333"`

Takes leap seconds into account when calculating the fraction of the day, see `mjd` for examples.

Return the last week day of the month of time `t`.
`time(2016,10,10).last-weekday-of-monthstd/time/time/last-weekday-of-month: (t : time, wd : weekday) -> time(Sunstd/time/date/Sun: weekday).date`   (2016-10-30, Last Sunday of October 2016).

Convert a `timestd/time/time/time: V` `t` to a new `timestd/time/time/time: V` value in the local time zone in an optional calendar (=`t.calendar` by default).

Return the current time in the local timezone and optional calendar (=`cal-isostd/time/calendar/cal-iso: calendar`).

Return the current time in the local timezone and optional calendar (=`cal-isostd/time/calendar/cal-iso: calendar`).

Convert an `instantstd/time/instant/instant: V` to a `timestd/time/time/time: V` value in the local timezone, in an optional calendar (=`cal-isostd/time/calendar/cal-iso: calendar` by default).

Return the `timestd/time/time/time: V` value for a given date and clock in the local timezone interpreted by calendar `cal` (=`cal-isostd/time/calendar/cal-iso: calendar`). See `instant` for roll-over behaviour.

Return the `timestd/time/time/time: V` value for a given date and clock in the local timezone interpreted by calendar `cal` (=`cal-isostd/time/calendar/cal-iso: calendar`). See `instant` for roll-over behaviour.

Return the `timestd/time/time/time: V` value for a given `datestd/time/date/date: V` and `clockstd/time/date/clock: V` (=`clock0std/time/date/clock0: clock`) in the local timezone interpreted by calendar `cal` (=`cal-isostd/time/calendar/cal-iso: calendar`).

Return the `timestd/time/time/time: V` value for a given `datestd/time/date/date: V` and `clockstd/time/date/clock: V` (=`clock0std/time/date/clock0: clock`) in the local timezone interpreted by calendar `cal` (=`cal-isostd/time/calendar/cal-iso: calendar`).

The maximum of two times (as by their actual instant in time).

The minimum of two times (as by their actual instant in time).

Return the whole minutes of a `timestd/time/time/time: V`.

Return the modified Julian date (MJD) number for a given `timestd/time/time/time: V`. This interprets the Modified Julian Date in the calendar system of `t` with the timezone applied.
`time(1972,1,2,tz=tz-fixedstd/time/calendar/tz-fixed: (hours : int, mins : ?int, name : ?string, abbrv : ?string, hourwidth : ?int) -> timezone(1)).mjd == "41318"`
`time(1972,1,2,tz=tz-fixedstd/time/calendar/tz-fixed: (hours : int, mins : ?int, name : ?string, abbrv : ?string, hourwidth : ?int) -> timezone(1)).instant.mjd(ts-utc).show == "41317.958333335"`   (one hour earlier)
Also takes leap seconds into account:
`time(2015,12,31,12,0,0).mjd.show == "57387.5"`   (exactly mid-day)
`time(2016,12,31,12,0,0).mjd.show(9) == "57753.499994213"`   (this day has a leap second, so it is just before the real middle of the day)
`time(2016,12,31,12,0,0,0.5).mjd.show == "57753.5"`   (real middle of the day).

Return the month of a `timestd/time/time/time: V`. (starting at 1).

Return the total months in the year of time `t`. For Gregorian calendars this is always 12 but some calendars have a varying number of months per year.

Return the `n`th week day following (and including) time `t`. Use `n = 1` for the first week day `wd` following `t`; Use `0` for the last occurence of week day `wd` before `t`.
`time(2016,10,10).nth-weekdaystd/time/time/nth-weekday: (t : time, n : int, wd : weekday) -> time(1,Sunstd/time/date/Sun: weekday)`   (2016-10-13, first Sunday following October 10, 2016) `time(2016,11,16).start-of-monthstd/time/time/start-of-month: (t : time) -> time.nth-weekdaystd/time/time/nth-weekday: (t : time, n : int, wd : weekday) -> time(0,Wedstd/time/date/Wed: weekday)`   (2016-10-26, the last Wednesday before 2016-11-01).

Return the `n`th week day since the beginning of the month of time `t`.
`time(2016,10,10).nth-weekday-of-monthstd/time/time/nth-weekday-of-month: (t : time, n : int, wd : weekday) -> time(2,Sunstd/time/date/Sun: weekday).date`   (2016-10-09, Second Sunday of October 2016)
`time(2016,10,10).nth-weekday-of-monthstd/time/time/nth-weekday-of-month: (t : time, n : int, wd : weekday) -> time(60,Sunstd/time/date/Sun: weekday).date`   (2017-11-19, 60th Sunday since Octorber 1, 2016).

Round a time to a specified second precision.

Return the fractional seconds of a `timestd/time/time/time: V`.

Show a `timestd/time/time/time: V` in ISO 8601 format.

Return the time at the start of the day of time `t`.

Return the time at the start of the month of time `t`.

Return the time at the start of the week (Monday) of time `t`.

Return the time at the start of the year of time `t`.

Convert an `instantstd/time/instant/instant: V` to a `timestd/time/time/time: V` value in a given timezone `tz` (=`tz-utcstd/time/calendar/tz-utc: timezone` by default) and calendar (=`cal-isostd/time/calendar/cal-iso: calendar` by default).

Return the current time in an optional timezone (=`tz-utcstd/time/calendar/tz-utc: timezone`) and optional calendar (=`cal-isostd/time/calendar/cal-iso: calendar`).

Return the current time in an optional timezone (=`tz-utcstd/time/calendar/tz-utc: timezone`) and optional calendar (=`cal-isostd/time/calendar/cal-iso: calendar`).

Convert a `timestd/time/time/time: V` `t` to a new `timestd/time/time/time: V` value in a potentially different timezone `tz` (=`t.timezone` by default) and calendar (=`t.calendar` by default).

Return the `timestd/time/time/time: V` value for a given date and clock in a timezone `tz` (=`tz-utcstd/time/calendar/tz-utc: timezone` by default) interpreted by calendar `cal` (=`cal-isostd/time/calendar/cal-iso: calendar`).

The `month`, `day`, `hour`, `minutes` may be outside their usual ranges and will be normalized during the conversion. For example, January 33 converts to February 2. This makes it very easy to add- or subtract days or months to an existing time.

When the `seconds` or fraction of seconds `frac` add up over 60 though, those extra seconds are interpreted as leap seconds.

Due to timezone transitions, or leap seconds, it is possible to specify dates that never happened (as it was skipped by a timezone change), or ambigious times (as a timezone springs back). In such cases, the time is always interpreted in the earlier timezone.

Return the `timestd/time/time/time: V` value for a given `datestd/time/date/date: V` and `clockstd/time/date/clock: V` (=`clock0std/time/date/clock0: clock`) in a timezone `tz` (=`tz-utcstd/time/calendar/tz-utc: timezone` by default) interpreted by calendar `cal` (=`cal-isostd/time/calendar/cal-iso: calendar`).

The `timescalestd/time/instant/timescale: V` of the time.

Automatically generated. Retrieves the `timezone` constructor field of the `timestd/time/time/time: V` type.

Automatically generated. Retrieves the `tzabbrvstd/time/time/tzabbrv: (time : time) -> string` constructor field of the `timestd/time/time/time: V` type.

Automatically generated. Retrieves the `tzdeltastd/time/time/tzdelta: (time : time) -> duration` constructor field of the `timestd/time/time/time: V` type.

Return the weekday of a given time `t`.

Return the year of a `timestd/time/time/time: V`.

Return a `timestd/time/time/time: V` as a fractional year.
`year-fracstd/time/time/year-frac: (t : time) -> ddouble(time(2000,7,2)) == fixed(2000.5)`.

Show a time zone delta. Optional `utcstd/time/utc/utc: () -> utc timescale` for displaying a zero timezone delta (=`"Z"`). Optional `hmsep` for the hour-minute separator (=`":"`). Optional `hrwidth` to give the minimal width of the hour field (=`2`).