Time | Documentation
Description: Documentation for Documentation

# Interface Time

A Time represents an instant in time with nanosecond precision.

Programs using times should typically store and pass them as values, not pointers. That is, time variables and struct fields should be of type [time.Time], not *time.Time.

A Time value can be used by multiple goroutines simultaneously except that the methods [Time.GobDecode], [Time.UnmarshalBinary], [Time.UnmarshalJSON] and [Time.UnmarshalText] are not concurrency-safe.

Time instants can be compared using the [Time.Before], [Time.After], and [Time.Equal] methods. The [Time.Sub] method subtracts two instants, producing a [Duration]. The [Time.Add] method adds a Time and a Duration, producing a Time.

The zero value of type Time is January 1, year 1, 00:00:00.000000000 UTC. As this time is unlikely to come up in practice, the [Time.IsZero] method gives a simple way of detecting a time that has not been initialized explicitly.

Each time has an associated [Location]. The methods [Time.Local], [Time.UTC], and Time.In return a Time with a specific Location. Changing the Location of a Time value with these methods does not change the actual instant it represents, only the time zone in which to interpret it.

Representations of a Time value saved by the [Time.GobEncode], [Time.MarshalBinary], [Time.MarshalJSON], and [Time.MarshalText] methods store the [Time.Location]'s offset, but not the location name. They therefore lose information about Daylight Saving Time.

In addition to the required “wall clock” reading, a Time may contain an optional reading of the current process's monotonic clock, to provide additional precision for comparison or subtraction. See the “Monotonic Clocks” section in the package documentation for details.

Note that the Go == operator compares not just the time instant but also the Location and the monotonic clock reading. Therefore, Time values should not be used as map or database keys without first guaranteeing that the identical Location has been set for all values, which can be achieved through use of the UTC or Local method, and that the monotonic clock reading has been stripped by setting t = t.Round(0). In general, prefer t.Equal(u) to t == u, since t.Equal uses the most accurate comparison available and correctly handles the case when only one of its arguments has a monotonic clock reading.

#### Hierarchy

- Time

- Defined in types.d.ts:307
- Defined in types.d.ts:325
- Defined in types.d.ts:332
- Defined in types.d.ts:343
- Defined in types.d.ts:393
- Defined in types.d.ts:395
- Defined in types.d.ts:401
- Defined in types.d.ts:407
- Defined in types.d.ts:414
- Defined in types.d.ts:424
- Defined in types.d.ts:431
- Defined in types.d.ts:437
- Defined in types.d.ts:443
- Defined in types.d.ts:449
- Defined in types.d.ts:455
- Defined in types.d.ts:461
- Defined in types.d.ts:470
- Defined in types.d.ts:476
- Defined in types.d.ts:482
- Defined in types.d.ts:488
- Defined in types.d.ts:494
- Defined in types.d.ts:501
- Defined in types.d.ts:508
- Defined in types.d.ts:514
- Defined in types.d.ts:523
- Defined in types.d.ts:545
- Defined in types.d.ts:551
- Defined in types.d.ts:557
- Defined in types.d.ts:567
- Defined in types.d.ts:573
- Defined in types.d.ts:580
- Defined in types.d.ts:590
- Defined in types.d.ts:601
- Defined in types.d.ts:611
- Defined in types.d.ts:621
- Defined in types.d.ts:632
- Defined in types.d.ts:638
- Defined in types.d.ts:644
- Defined in types.d.ts:650
- Defined in types.d.ts:656
- Defined in types.d.ts:665
- Defined in types.d.ts:672
- Defined in types.d.ts:681
- Defined in types.d.ts:688
- Defined in types.d.ts:694
- Defined in types.d.ts:706

#####
Index

### Methods

Add
AddDate
After
AppendFormat
Before
Clock
Compare
Date
Day
Equal
Format
GoString
GobDecode
GobEncode
Hour
ISOWeek
In
IsDST
IsZero
Local
Location
MarshalBinary
MarshalJSON
MarshalText
Minute
Month
Nanosecond
Round
Second
String
Sub
Truncate
UTC
Unix
UnixMicro
UnixMilli
UnixNano
UnmarshalBinary
UnmarshalJSON
UnmarshalText
Weekday
Year
YearDay
Zone
ZoneBounds

## Methods

### Add

- Add(d): Time

- Add returns the time t+d.

  #### Parameters

  - ##### d: Duration

  #### Returns Time

  - Defined in types.d.ts:512

### AddDate

- AddDate(years, months, days): Time

- AddDate returns the time corresponding to adding the given number of years, months, and days to t. For example, AddDate(-1, 2, 3) applied to January 1, 2011 returns March 4, 2010.

  Note that dates are fundamentally coupled to timezones, and calendrical periods like days don't have fixed durations. AddDate uses the Location of the Time value to determine these durations. That means that the same AddDate arguments can produce a different shift in absolute time depending on the base Time value and its Location. For example, AddDate(0, 0, 1) applied to 12:00 on March 27 always returns 12:00 on March 28. At some locations and in some years this is a 24 hour shift. In others it's a 23 hour shift due to daylight savings time transitions.

  AddDate normalizes its result in the same way that Date does, so, for example, adding one month to October 31 yields December 1, the normalized form for November 31.

  #### Parameters

  - ##### years: number

  - ##### months: number

  - ##### days: number

  #### Returns Time

  - Defined in types.d.ts:543

### After

- After(u): boolean

- After reports whether the time instant t is after u.

  #### Parameters

  - ##### u: Time

  #### Returns boolean

  - Defined in types.d.ts:399

### AppendFormat

- AppendFormat(b, layout): string | number[]

- AppendFormat is like [Time.Format] but appends the textual representation to b and returns the extended buffer.

  #### Parameters

  - ##### b: string | number[]

  - ##### layout: string

  #### Returns string | number[]

  - Defined in types.d.ts:348

### Before

- Before(u): boolean

- Before reports whether the time instant t is before u.

  #### Parameters

  - ##### u: Time

  #### Returns boolean

  - Defined in types.d.ts:405

### Clock

- Clock(): [number, number, number]

- Clock returns the hour, minute, and second within the day specified by t.

  #### Returns [number, number, number]

  - Defined in types.d.ts:474

### Compare

- Compare(u): number

- Compare compares the time instant t with u. If t is before u, it returns -1; if t is after u, it returns +1; if they're the same, it returns 0.

  #### Parameters

  - ##### u: Time

  #### Returns number

  - Defined in types.d.ts:412

### Date

- Date(): [number, Month, number]

- Date returns the year, month, and day in which t occurs.

  #### Returns [number, Month, number]

  - Defined in types.d.ts:435

### Day

- Day(): number

- Day returns the day of the month specified by t.

  #### Returns number

  - Defined in types.d.ts:453

### Equal

- Equal(u): boolean

- Equal reports whether t and u represent the same time instant. Two times can be equal even if they are in different locations. For example, 6:00 +0200 and 4:00 UTC are Equal. See the documentation on the Time type for the pitfalls of using == with Time values; most code should use Equal instead.

  #### Parameters

  - ##### u: Time

  #### Returns boolean

  - Defined in types.d.ts:422

### Format

- Format(layout): string

- Format returns a textual representation of the time value formatted according to the layout defined by the argument. See the documentation for the constant called [Layout] to see how to represent the layout format.

  The executable example for [Time.Format] demonstrates the working of the layout string in detail and is a good reference.

  #### Parameters

  - ##### layout: string

  #### Returns string

  - Defined in types.d.ts:341

### GoString

- GoString(): string

- GoString implements [fmt.GoStringer] and formats t to be printed in Go source code.

  #### Returns string

  - Defined in types.d.ts:330

### GobDecode

- GobDecode(data): void

- GobDecode implements the gob.GobDecoder interface.

  #### Parameters

  - ##### data: string | number[]

  #### Returns void

  - Defined in types.d.ts:654

### GobEncode

- GobEncode(): string | number[]

- GobEncode implements the gob.GobEncoder interface.

  #### Returns string | number[]

  - Defined in types.d.ts:648

### Hour

- Hour(): number

- Hour returns the hour within the day specified by t, in the range [0, 23].

  #### Returns number

  - Defined in types.d.ts:480

### ISOWeek

- ISOWeek(): [number, number]

- ISOWeek returns the ISO 8601 year and week number in which t occurs. Week ranges from 1 to 53. Jan 01 to Jan 03 of year n might belong to week 52 or 53 of year n-1, and Dec 29 to Dec 31 might belong to week 1 of year n+1.

  #### Returns [number, number]

  - Defined in types.d.ts:468

### In

- In(loc): Time

- In returns a copy of t representing the same time instant, but with the copy's location information set to loc for display purposes.

  In panics if loc is nil.

  #### Parameters

  - ##### loc: Location

  #### Returns Time

  - Defined in types.d.ts:565

### IsDST

- IsDST(): boolean

- IsDST reports whether the time in the configured location is in Daylight Savings Time.

  #### Returns boolean

  - Defined in types.d.ts:692

### IsZero

- IsZero(): boolean

- IsZero reports whether t represents the zero time instant, January 1, year 1, 00:00:00 UTC.

  #### Returns boolean

  - Defined in types.d.ts:429

### Local

- Local(): Time

- Local returns t with the location set to local time.

  #### Returns Time

  - Defined in types.d.ts:555

### Location

- Location(): Location

- Location returns the time zone information associated with t.

  #### Returns Location

  - Defined in types.d.ts:571

### MarshalBinary

- MarshalBinary(): string | number[]

- MarshalBinary implements the encoding.BinaryMarshaler interface.

  #### Returns string | number[]

  - Defined in types.d.ts:636

### MarshalJSON

- MarshalJSON(): string | number[]

- MarshalJSON implements the [json.Marshaler] interface. The time is a quoted string in the RFC 3339 format with sub-second precision. If the timestamp cannot be represented as valid RFC 3339 (e.g., the year is out of range), then an error is reported.

  #### Returns string | number[]

  - Defined in types.d.ts:663

### MarshalText

- MarshalText(): string | number[]

- MarshalText implements the [encoding.TextMarshaler] interface. The time is formatted in RFC 3339 format with sub-second precision. If the timestamp cannot be represented as valid RFC 3339 (e.g., the year is out of range), then an error is reported.

  #### Returns string | number[]

  - Defined in types.d.ts:679

### Minute

- Minute(): number

- Minute returns the minute offset within the hour specified by t, in the range [0, 59].

  #### Returns number

  - Defined in types.d.ts:486

### Month

- Month(): Month

- Month returns the month of the year specified by t.

  #### Returns Month

  - Defined in types.d.ts:447

### Nanosecond

- Nanosecond(): number

- Nanosecond returns the nanosecond offset within the second specified by t, in the range [0, 999999999].

  #### Returns number

  - Defined in types.d.ts:499

### Round

- Round(d): Time

- Round returns the result of rounding t to the nearest multiple of d (since the zero time). The rounding behavior for halfway values is to round up. If d <= 0, Round returns t stripped of any monotonic clock reading but otherwise unchanged.

  Round operates on the time as an absolute duration since the zero time; it does not operate on the presentation form of the time. Thus, Round(Hour) may return a time with a non-zero minute, depending on the time's Location.

  #### Parameters

  - ##### d: Duration

  #### Returns Time

  - Defined in types.d.ts:717

### Second

- Second(): number

- Second returns the second offset within the minute specified by t, in the range [0, 59].

  #### Returns number

  - Defined in types.d.ts:492

### String

- String(): string

- String returns the time formatted using the format string

          "2006-01-02 15:04:05.999999999 -0700 MST"

  If the time has a monotonic clock reading, the returned string includes a final field "m=±", where value is the monotonic clock reading formatted as a decimal number of seconds.

  The returned string is meant for debugging; for a stable serialized representation, use t.MarshalText, t.MarshalBinary, or t.Format with an explicit format string.

  #### Returns string

  - Defined in types.d.ts:323

### Sub

- Sub(u): Duration

- Sub returns the duration t-u. If the result exceeds the maximum (or minimum) value that can be stored in a [Duration], the maximum (or minimum) duration will be returned. To compute t-d for a duration d, use t.Add(-d).

  #### Parameters

  - ##### u: Time

  #### Returns Duration

  - Defined in types.d.ts:521

### Truncate

- Truncate(d): Time

- Truncate returns the result of rounding t down to a multiple of d (since the zero time). If d <= 0, Truncate returns t stripped of any monotonic clock reading but otherwise unchanged.

  Truncate operates on the time as an absolute duration since the zero time; it does not operate on the presentation form of the time. Thus, Truncate(Hour) may return a time with a non-zero minute, depending on the time's Location.

  #### Parameters

  - ##### d: Duration

  #### Returns Time

  - Defined in types.d.ts:704

### UTC

- UTC(): Time

- UTC returns t with the location set to UTC.

  #### Returns Time

  - Defined in types.d.ts:549

### Unix

- Unix(): number

- Unix returns t as a Unix time, the number of seconds elapsed since January 1, 1970 UTC. The result does not depend on the location associated with t. Unix-like operating systems often record time as a 32-bit count of seconds, but since the method here returns a 64-bit value it is valid for billions of years into the past or future.

  #### Returns number

  - Defined in types.d.ts:599

### UnixMicro

- UnixMicro(): number

- UnixMicro returns t as a Unix time, the number of microseconds elapsed since January 1, 1970 UTC. The result is undefined if the Unix time in microseconds cannot be represented by an int64 (a date before year -290307 or after year 294246). The result does not depend on the location associated with t.

  #### Returns number

  - Defined in types.d.ts:619

### UnixMilli

- UnixMilli(): number

- UnixMilli returns t as a Unix time, the number of milliseconds elapsed since January 1, 1970 UTC. The result is undefined if the Unix time in milliseconds cannot be represented by an int64 (a date more than 292 million years before or after 1970). The result does not depend on the location associated with t.

  #### Returns number

  - Defined in types.d.ts:609

### UnixNano

- UnixNano(): number

- UnixNano returns t as a Unix time, the number of nanoseconds elapsed since January 1, 1970 UTC. The result is undefined if the Unix time in nanoseconds cannot be represented by an int64 (a date before the year 1678 or after 2262). Note that this means the result of calling UnixNano on the zero Time is undefined. The result does not depend on the location associated with t.

  #### Returns number

  - Defined in types.d.ts:630

### UnmarshalBinary

- UnmarshalBinary(data): void

- UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

  #### Parameters

  - ##### data: string | number[]

  #### Returns void

  - Defined in types.d.ts:642

### UnmarshalJSON

- UnmarshalJSON(data): void

- UnmarshalJSON implements the [json.Unmarshaler] interface. The time must be a quoted string in the RFC 3339 format.

  #### Parameters

  - ##### data: string | number[]

  #### Returns void

  - Defined in types.d.ts:670

### UnmarshalText

- UnmarshalText(data): void

- UnmarshalText implements the [encoding.TextUnmarshaler] interface. The time must be in the RFC 3339 format.

  #### Parameters

  - ##### data: string | number[]

  #### Returns void

  - Defined in types.d.ts:686

### Weekday

- Weekday(): Weekday

- Weekday returns the day of the week specified by t.

  #### Returns Weekday

  - Defined in types.d.ts:459

### Year

- Year(): number

- Year returns the year in which t occurs.

  #### Returns number

  - Defined in types.d.ts:441

### YearDay

- YearDay(): number

- YearDay returns the day of the year specified by t, in the range [1,365] for non-leap years, and [1,366] in leap years.

  #### Returns number

  - Defined in types.d.ts:506

### Zone

- Zone(): [string, number]

- Zone computes the time zone in effect at time t, returning the abbreviated name of the zone (such as "CET") and its offset in seconds east of UTC.

  #### Returns [string, number]

  - Defined in types.d.ts:578

### ZoneBounds

- ZoneBounds(): [Time, Time]

- ZoneBounds returns the bounds of the time zone in effect at time t. The zone begins at start and the next zone begins at end. If the zone begins at the beginning of time, start will be returned as a zero Time. If the zone goes on forever, end will be returned as a zero Time. The Location of the returned times will be the same as t.

  #### Returns [Time, Time]

  - Defined in types.d.ts:588

Generated using TypeDoc