1 // Copyright 2009 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
5 // Package time provides functionality for measuring and displaying time.
7 // The calendrical calculations always assume a Gregorian calendar, with
12 // Operating systems provide both a “wall clock,” which is subject to
13 // changes for clock synchronization, and a “monotonic clock,” which is
14 // not. The general rule is that the wall clock is for telling time and
15 // the monotonic clock is for measuring time. Rather than split the API,
16 // in this package the Time returned by time.Now contains both a wall
17 // clock reading and a monotonic clock reading; later time-telling
18 // operations use the wall clock reading, but later time-measuring
19 // operations, specifically comparisons and subtractions, use the
20 // monotonic clock reading.
22 // For example, this code always computes a positive elapsed time of
23 // approximately 20 milliseconds, even if the wall clock is changed during
24 // the operation being timed:
26 // start := time.Now()
27 // ... operation that takes 20 milliseconds ...
29 // elapsed := t.Sub(start)
31 // Other idioms, such as time.Since(start), time.Until(deadline), and
32 // time.Now().Before(deadline), are similarly robust against wall clock
35 // The rest of this section gives the precise details of how operations
36 // use monotonic clocks, but understanding those details is not required
37 // to use this package.
39 // The Time returned by time.Now contains a monotonic clock reading.
40 // If Time t has a monotonic clock reading, t.Add adds the same duration to
41 // both the wall clock and monotonic clock readings to compute the result.
42 // Because t.AddDate(y, m, d), t.Round(d), and t.Truncate(d) are wall time
43 // computations, they always strip any monotonic clock reading from their results.
44 // Because t.In, t.Local, and t.UTC are used for their effect on the interpretation
45 // of the wall time, they also strip any monotonic clock reading from their results.
46 // The canonical way to strip a monotonic clock reading is to use t = t.Round(0).
48 // If Times t and u both contain monotonic clock readings, the operations
49 // t.After(u), t.Before(u), t.Equal(u), and t.Sub(u) are carried out
50 // using the monotonic clock readings alone, ignoring the wall clock
51 // readings. If either t or u contains no monotonic clock reading, these
52 // operations fall back to using the wall clock readings.
54 // On some systems the monotonic clock will stop if the computer goes to sleep.
55 // On such a system, t.Sub(u) may not accurately reflect the actual
56 // time that passed between t and u.
58 // Because the monotonic clock reading has no meaning outside
59 // the current process, the serialized forms generated by t.GobEncode,
60 // t.MarshalBinary, t.MarshalJSON, and t.MarshalText omit the monotonic
61 // clock reading, and t.Format provides no format for it. Similarly, the
62 // constructors time.Date, time.Parse, time.ParseInLocation, and time.Unix,
63 // as well as the unmarshalers t.GobDecode, t.UnmarshalBinary.
64 // t.UnmarshalJSON, and t.UnmarshalText always create times with
65 // no monotonic clock reading.
67 // Note that the Go == operator compares not just the time instant but
68 // also the Location and the monotonic clock reading. See the
69 // documentation for the Time type for a discussion of equality
70 // testing for Time values.
72 // For debugging, the result of t.String does include the monotonic
73 // clock reading if present. If t != u because of different monotonic clock readings,
74 // that difference will be visible when printing t.String() and u.String().
80 _
"unsafe" // for go:linkname
83 // A Time represents an instant in time with nanosecond precision.
85 // Programs using times should typically store and pass them as values,
86 // not pointers. That is, time variables and struct fields should be of
87 // type time.Time, not *time.Time.
89 // A Time value can be used by multiple goroutines simultaneously except
90 // that the methods GobDecode, UnmarshalBinary, UnmarshalJSON and
91 // UnmarshalText are not concurrency-safe.
93 // Time instants can be compared using the Before, After, and Equal methods.
94 // The Sub method subtracts two instants, producing a Duration.
95 // The Add method adds a Time and a Duration, producing a Time.
97 // The zero value of type Time is January 1, year 1, 00:00:00.000000000 UTC.
98 // As this time is unlikely to come up in practice, the IsZero method gives
99 // a simple way of detecting a time that has not been initialized explicitly.
101 // Each Time has associated with it a Location, consulted when computing the
102 // presentation form of the time, such as in the Format, Hour, and Year methods.
103 // The methods Local, UTC, and In return a Time with a specific location.
104 // Changing the location in this way changes only the presentation; it does not
105 // change the instant in time being denoted and therefore does not affect the
106 // computations described in earlier paragraphs.
108 // Representations of a Time value saved by the GobEncode, MarshalBinary,
109 // MarshalJSON, and MarshalText methods store the Time.Location's offset, but not
110 // the location name. They therefore lose information about Daylight Saving Time.
112 // In addition to the required “wall clock” reading, a Time may contain an optional
113 // reading of the current process's monotonic clock, to provide additional precision
114 // for comparison or subtraction.
115 // See the “Monotonic Clocks” section in the package documentation for details.
117 // Note that the Go == operator compares not just the time instant but also the
118 // Location and the monotonic clock reading. Therefore, Time values should not
119 // be used as map or database keys without first guaranteeing that the
120 // identical Location has been set for all values, which can be achieved
121 // through use of the UTC or Local method, and that the monotonic clock reading
122 // has been stripped by setting t = t.Round(0). In general, prefer t.Equal(u)
123 // to t == u, since t.Equal uses the most accurate comparison available and
124 // correctly handles the case when only one of its arguments has a monotonic
128 // wall and ext encode the wall time seconds, wall time nanoseconds,
129 // and optional monotonic clock reading in nanoseconds.
131 // From high to low bit position, wall encodes a 1-bit flag (hasMonotonic),
132 // a 33-bit seconds field, and a 30-bit wall time nanoseconds field.
133 // The nanoseconds field is in the range [0, 999999999].
134 // If the hasMonotonic bit is 0, then the 33-bit field must be zero
135 // and the full signed 64-bit wall seconds since Jan 1 year 1 is stored in ext.
136 // If the hasMonotonic bit is 1, then the 33-bit field holds a 33-bit
137 // unsigned wall seconds since Jan 1 year 1885, and ext holds a
138 // signed 64-bit monotonic clock reading, nanoseconds since process start.
142 // loc specifies the Location that should be used to
143 // determine the minute, hour, month, day, and year
144 // that correspond to this Time.
145 // The nil location means UTC.
146 // All UTC times are represented with loc==nil, never loc==&utcLoc.
151 hasMonotonic
= 1 << 63
152 maxWall
= wallToInternal
+ (1<<33 - 1) // year 2157
153 minWall
= wallToInternal
// year 1885
158 // These helpers for manipulating the wall and monotonic clock readings
159 // take pointer receivers, even when they don't modify the time,
160 // to make them cheaper to call.
162 // nsec returns the time's nanoseconds.
163 func (t
*Time
) nsec() int32 {
164 return int32(t
.wall
& nsecMask
)
167 // sec returns the time's seconds since Jan 1 year 1.
168 func (t
*Time
) sec() int64 {
169 if t
.wall
&hasMonotonic
!= 0 {
170 return wallToInternal
+ int64(t
.wall
<<1>>(nsecShift
+1))
175 // unixSec returns the time's seconds since Jan 1 1970 (Unix time).
176 func (t
*Time
) unixSec() int64 { return t
.sec() + internalToUnix
}
178 // addSec adds d seconds to the time.
179 func (t
*Time
) addSec(d
int64) {
180 if t
.wall
&hasMonotonic
!= 0 {
181 sec
:= int64(t
.wall
<< 1 >> (nsecShift
+ 1))
183 if 0 <= dsec
&& dsec
<= 1<<33-1 {
184 t
.wall
= t
.wall
&nsecMask |
uint64(dsec
)<<nsecShift | hasMonotonic
187 // Wall second now out of range for packed field.
192 // TODO: Check for overflow.
196 // setLoc sets the location associated with the time.
197 func (t
*Time
) setLoc(loc
*Location
) {
205 // stripMono strips the monotonic clock reading in t.
206 func (t
*Time
) stripMono() {
207 if t
.wall
&hasMonotonic
!= 0 {
213 // setMono sets the monotonic clock reading in t.
214 // If t cannot hold a monotonic clock reading,
215 // because its wall time is too large,
216 // setMono is a no-op.
217 func (t
*Time
) setMono(m
int64) {
218 if t
.wall
&hasMonotonic
== 0 {
220 if sec
< minWall || maxWall
< sec
{
223 t
.wall |
= hasMonotonic |
uint64(sec
-minWall
)<<nsecShift
228 // mono returns t's monotonic clock reading.
229 // It returns 0 for a missing reading.
230 // This function is used only for testing,
231 // so it's OK that technically 0 is a valid
232 // monotonic clock reading as well.
233 func (t
*Time
) mono() int64 {
234 if t
.wall
&hasMonotonic
== 0 {
240 // After reports whether the time instant t is after u.
241 func (t Time
) After(u Time
) bool {
242 if t
.wall
&u
.wall
&hasMonotonic
!= 0 {
247 return ts
> us || ts
== us
&& t
.nsec() > u
.nsec()
250 // Before reports whether the time instant t is before u.
251 func (t Time
) Before(u Time
) bool {
252 if t
.wall
&u
.wall
&hasMonotonic
!= 0 {
255 return t
.sec() < u
.sec() || t
.sec() == u
.sec() && t
.nsec() < u
.nsec()
258 // Equal reports whether t and u represent the same time instant.
259 // Two times can be equal even if they are in different locations.
260 // For example, 6:00 +0200 and 4:00 UTC are Equal.
261 // See the documentation on the Time type for the pitfalls of using == with
262 // Time values; most code should use Equal instead.
263 func (t Time
) Equal(u Time
) bool {
264 if t
.wall
&u
.wall
&hasMonotonic
!= 0 {
265 return t
.ext
== u
.ext
267 return t
.sec() == u
.sec() && t
.nsec() == u
.nsec()
270 // A Month specifies a month of the year (January = 1, ...).
274 January Month
= 1 + iota
288 var months
= [...]string{
303 // String returns the English name of the month ("January", "February", ...).
304 func (m Month
) String() string {
305 if January
<= m
&& m
<= December
{
308 buf
:= make([]byte, 20)
309 n
:= fmtInt(buf
, uint64(m
))
310 return "%!Month(" + string(buf
[n
:]) + ")"
313 // A Weekday specifies a day of the week (Sunday = 0, ...).
317 Sunday Weekday
= iota
326 var days
= [...]string{
336 // String returns the English name of the day ("Sunday", "Monday", ...).
337 func (d Weekday
) String() string {
338 if Sunday
<= d
&& d
<= Saturday
{
341 buf
:= make([]byte, 20)
342 n
:= fmtInt(buf
, uint64(d
))
343 return "%!Weekday(" + string(buf
[n
:]) + ")"
346 // Computations on time.
348 // The zero value for a Time is defined to be
349 // January 1, year 1, 00:00:00.000000000 UTC
350 // which (1) looks like a zero, or as close as you can get in a date
351 // (1-1-1 00:00:00 UTC), (2) is unlikely enough to arise in practice to
352 // be a suitable "not set" sentinel, unlike Jan 1 1970, and (3) has a
353 // non-negative year even in time zones west of UTC, unlike 1-1-0
354 // 00:00:00 UTC, which would be 12-31-(-1) 19:00:00 in New York.
356 // The zero Time value does not force a specific epoch for the time
357 // representation. For example, to use the Unix epoch internally, we
358 // could define that to distinguish a zero value from Jan 1 1970, that
359 // time would be represented by sec=-1, nsec=1e9. However, it does
360 // suggest a representation, namely using 1-1-1 00:00:00 UTC as the
361 // epoch, and that's what we do.
363 // The Add and Sub computations are oblivious to the choice of epoch.
365 // The presentation computations - year, month, minute, and so on - all
366 // rely heavily on division and modulus by positive constants. For
367 // calendrical calculations we want these divisions to round down, even
368 // for negative values, so that the remainder is always positive, but
369 // Go's division (like most hardware division instructions) rounds to
370 // zero. We can still do those computations and then adjust the result
371 // for a negative numerator, but it's annoying to write the adjustment
372 // over and over. Instead, we can change to a different epoch so long
373 // ago that all the times we care about will be positive, and then round
374 // to zero and round down coincide. These presentation routines already
375 // have to add the zone offset, so adding the translation to the
376 // alternate epoch is cheap. For example, having a non-negative time t
377 // means that we can write
390 // The calendar runs on an exact 400 year cycle: a 400-year calendar
391 // printed for 1970-2369 will apply as well to 2370-2769. Even the days
392 // of the week match up. It simplifies the computations to choose the
393 // cycle boundaries so that the exceptional years are always delayed as
394 // long as possible. That means choosing a year equal to 1 mod 400, so
395 // that the first leap year is the 4th year, the first missed leap year
396 // is the 100th year, and the missed missed leap year is the 400th year.
397 // So we'd prefer instead to print a calendar for 2001-2400 and reuse it
400 // Finally, it's convenient if the delta between the Unix epoch and
401 // long-ago epoch is representable by an int64 constant.
403 // These three considerations—choose an epoch as early as possible, that
404 // uses a year equal to 1 mod 400, and that is no more than 2⁶³ seconds
405 // earlier than 1970—bring us to the year -292277022399. We refer to
406 // this year as the absolute zero year, and to times measured as a uint64
407 // seconds since this year as absolute times.
409 // Times measured as an int64 seconds since the year 1—the representation
410 // used for Time's sec field—are called internal times.
412 // Times measured as an int64 seconds since the year 1970 are called Unix
415 // It is tempting to just use the year 1 as the absolute epoch, defining
416 // that the routines are only valid for years >= 1. However, the
417 // routines would then be invalid when displaying the epoch in time zones
418 // west of UTC, since it is year 0. It doesn't seem tenable to say that
419 // printing the zero time correctly isn't supported in half the time
420 // zones. By comparison, it's reasonable to mishandle some times in
421 // the year -292277022399.
423 // All this is opaque to clients of the API and can be changed if a
424 // better implementation presents itself.
427 // The unsigned zero year for internal calculations.
428 // Must be 1 mod 400, and times before it will not compute correctly,
429 // but otherwise can be changed at will.
430 absoluteZeroYear
= -292277022399
432 // The year of the zero Time.
433 // Assumed by the unixToInternal computation below.
436 // Offsets to convert between internal and absolute or Unix times.
437 absoluteToInternal
int64 = (absoluteZeroYear
- internalYear
) * 365.2425 * secondsPerDay
438 internalToAbsolute
= -absoluteToInternal
440 unixToInternal
int64 = (1969*365 + 1969/4 - 1969/100 + 1969/400) * secondsPerDay
441 internalToUnix
int64 = -unixToInternal
443 wallToInternal
int64 = (1884*365 + 1884/4 - 1884/100 + 1884/400) * secondsPerDay
444 internalToWall
int64 = -wallToInternal
447 // IsZero reports whether t represents the zero time instant,
448 // January 1, year 1, 00:00:00 UTC.
449 func (t Time
) IsZero() bool {
450 return t
.sec() == 0 && t
.nsec() == 0
453 // abs returns the time t as an absolute time, adjusted by the zone offset.
454 // It is called when computing a presentation property like Month or Hour.
455 func (t Time
) abs() uint64 {
457 // Avoid function calls when possible.
458 if l
== nil || l
== &localLoc
{
463 if l
.cacheZone
!= nil && l
.cacheStart
<= sec
&& sec
< l
.cacheEnd
{
464 sec
+= int64(l
.cacheZone
.offset
)
466 _
, offset
, _
, _
:= l
.lookup(sec
)
470 return uint64(sec
+ (unixToInternal
+ internalToAbsolute
))
473 // locabs is a combination of the Zone and abs methods,
474 // extracting both return values from a single zone lookup.
475 func (t Time
) locabs() (name
string, offset
int, abs
uint64) {
477 if l
== nil || l
== &localLoc
{
480 // Avoid function call if we hit the local time cache.
483 if l
.cacheZone
!= nil && l
.cacheStart
<= sec
&& sec
< l
.cacheEnd
{
484 name
= l
.cacheZone
.name
485 offset
= l
.cacheZone
.offset
487 name
, offset
, _
, _
= l
.lookup(sec
)
493 abs
= uint64(sec
+ (unixToInternal
+ internalToAbsolute
))
497 // Date returns the year, month, and day in which t occurs.
498 func (t Time
) Date() (year
int, month Month
, day
int) {
499 year
, month
, day
, _
= t
.date(true)
503 // Year returns the year in which t occurs.
504 func (t Time
) Year() int {
505 year
, _
, _
, _
:= t
.date(false)
509 // Month returns the month of the year specified by t.
510 func (t Time
) Month() Month
{
511 _
, month
, _
, _
:= t
.date(true)
515 // Day returns the day of the month specified by t.
516 func (t Time
) Day() int {
517 _
, _
, day
, _
:= t
.date(true)
521 // Weekday returns the day of the week specified by t.
522 func (t Time
) Weekday() Weekday
{
523 return absWeekday(t
.abs())
526 // absWeekday is like Weekday but operates on an absolute time.
527 func absWeekday(abs
uint64) Weekday
{
528 // January 1 of the absolute year, like January 1 of 2001, was a Monday.
529 sec
:= (abs
+ uint64(Monday
)*secondsPerDay
) % secondsPerWeek
530 return Weekday(int(sec
) / secondsPerDay
)
533 // ISOWeek returns the ISO 8601 year and week number in which t occurs.
534 // Week ranges from 1 to 53. Jan 01 to Jan 03 of year n might belong to
535 // week 52 or 53 of year n-1, and Dec 29 to Dec 31 might belong to week 1
537 func (t Time
) ISOWeek() (year
, week
int) {
538 year
, month
, day
, yday
:= t
.date(true)
539 wday
:= int(t
.Weekday()+6) % 7 // weekday but Monday = 0.
550 // Calculate week as number of Mondays in year up to
551 // and including today, plus 1 because the first week is week 0.
552 // Putting the + 1 inside the numerator as a + 7 keeps the
553 // numerator from being negative, which would cause it to
554 // round incorrectly.
555 week
= (yday
- wday
+ 7) / 7
557 // The week number is now correct under the assumption
558 // that the first Monday of the year is in week 1.
559 // If Jan 1 is a Tuesday, Wednesday, or Thursday, the first Monday
560 // is actually in week 2.
561 jan1wday
:= (wday
- yday
+ 7*53) % 7
562 if Tue
<= jan1wday
&& jan1wday
<= Thu
{
566 // If the week number is still 0, we're in early January but in
567 // the last week of last year.
571 // A year has 53 weeks when Jan 1 or Dec 31 is a Thursday,
572 // meaning Jan 1 of the next year is a Friday
573 // or it was a leap year and Jan 1 of the next year is a Saturday.
574 if jan1wday
== Fri ||
(jan1wday
== Sat
&& isLeap(year
)) {
579 // December 29 to 31 are in week 1 of next year if
580 // they are after the last Thursday of the year and
581 // December 31 is a Monday, Tuesday, or Wednesday.
582 if month
== December
&& day
>= 29 && wday
< Thu
{
583 if dec31wday
:= (wday
+ 31 - day
) % 7; Mon
<= dec31wday
&& dec31wday
<= Wed
{
592 // Clock returns the hour, minute, and second within the day specified by t.
593 func (t Time
) Clock() (hour
, min
, sec
int) {
594 return absClock(t
.abs())
597 // absClock is like clock but operates on an absolute time.
598 func absClock(abs
uint64) (hour
, min
, sec
int) {
599 sec
= int(abs
% secondsPerDay
)
600 hour
= sec
/ secondsPerHour
601 sec
-= hour
* secondsPerHour
602 min
= sec
/ secondsPerMinute
603 sec
-= min
* secondsPerMinute
607 // Hour returns the hour within the day specified by t, in the range [0, 23].
608 func (t Time
) Hour() int {
609 return int(t
.abs()%secondsPerDay
) / secondsPerHour
612 // Minute returns the minute offset within the hour specified by t, in the range [0, 59].
613 func (t Time
) Minute() int {
614 return int(t
.abs()%secondsPerHour
) / secondsPerMinute
617 // Second returns the second offset within the minute specified by t, in the range [0, 59].
618 func (t Time
) Second() int {
619 return int(t
.abs() % secondsPerMinute
)
622 // Nanosecond returns the nanosecond offset within the second specified by t,
623 // in the range [0, 999999999].
624 func (t Time
) Nanosecond() int {
628 // YearDay returns the day of the year specified by t, in the range [1,365] for non-leap years,
629 // and [1,366] in leap years.
630 func (t Time
) YearDay() int {
631 _
, _
, _
, yday
:= t
.date(false)
635 // A Duration represents the elapsed time between two instants
636 // as an int64 nanosecond count. The representation limits the
637 // largest representable duration to approximately 290 years.
641 minDuration Duration
= -1 << 63
642 maxDuration Duration
= 1<<63 - 1
645 // Common durations. There is no definition for units of Day or larger
646 // to avoid confusion across daylight savings time zone transitions.
648 // To count the number of units in a Duration, divide:
649 // second := time.Second
650 // fmt.Print(int64(second/time.Millisecond)) // prints 1000
652 // To convert an integer number of units to a Duration, multiply:
654 // fmt.Print(time.Duration(seconds)*time.Second) // prints 10s
657 Nanosecond Duration
= 1
658 Microsecond
= 1000 * Nanosecond
659 Millisecond
= 1000 * Microsecond
660 Second
= 1000 * Millisecond
665 // String returns a string representing the duration in the form "72h3m0.5s".
666 // Leading zero units are omitted. As a special case, durations less than one
667 // second format use a smaller unit (milli-, micro-, or nanoseconds) to ensure
668 // that the leading digit is non-zero. The zero duration formats as 0s.
669 func (d Duration
) String() string {
670 // Largest time is 2540400h10m10.000000000s
680 if u
< uint64(Second
) {
681 // Special case: if duration is smaller than a second,
682 // use smaller units, like 1.2ms
690 case u
< uint64(Microsecond
):
694 case u
< uint64(Millisecond
):
695 // print microseconds
697 // U+00B5 'µ' micro sign == 0xC2 0xB5
698 w
-- // Need room for two bytes.
701 // print milliseconds
705 w
, u
= fmtFrac(buf
[:w
], u
, prec
)
706 w
= fmtInt(buf
[:w
], u
)
711 w
, u
= fmtFrac(buf
[:w
], u
, 9)
713 // u is now integer seconds
714 w
= fmtInt(buf
[:w
], u%60
)
717 // u is now integer minutes
721 w
= fmtInt(buf
[:w
], u%60
)
724 // u is now integer hours
725 // Stop at hours because days can be different lengths.
729 w
= fmtInt(buf
[:w
], u
)
739 return string(buf
[w
:])
742 // fmtFrac formats the fraction of v/10**prec (e.g., ".12345") into the
743 // tail of buf, omitting trailing zeros. It omits the decimal
744 // point too when the fraction is 0. It returns the index where the
745 // output bytes begin and the value v/10**prec.
746 func fmtFrac(buf
[]byte, v
uint64, prec
int) (nw
int, nv
uint64) {
747 // Omit trailing zeros up to and including decimal point.
750 for i
:= 0; i
< prec
; i
++ {
752 print = print || digit
!= 0
755 buf
[w
] = byte(digit
) + '0'
766 // fmtInt formats v into the tail of buf.
767 // It returns the index where the output begins.
768 func fmtInt(buf
[]byte, v
uint64) int {
776 buf
[w
] = byte(v%10
) + '0'
783 // Nanoseconds returns the duration as an integer nanosecond count.
784 func (d Duration
) Nanoseconds() int64 { return int64(d
) }
786 // Microseconds returns the duration as an integer microsecond count.
787 func (d Duration
) Microseconds() int64 { return int64(d
) / 1e3
}
789 // Milliseconds returns the duration as an integer millisecond count.
790 func (d Duration
) Milliseconds() int64 { return int64(d
) / 1e6
}
792 // These methods return float64 because the dominant
793 // use case is for printing a floating point number like 1.5s, and
794 // a truncation to integer would make them not useful in those cases.
795 // Splitting the integer and fraction ourselves guarantees that
796 // converting the returned float64 to an integer rounds the same
797 // way that a pure integer conversion would have, even in cases
798 // where, say, float64(d.Nanoseconds())/1e9 would have rounded
801 // Seconds returns the duration as a floating point number of seconds.
802 func (d Duration
) Seconds() float64 {
805 return float64(sec
) + float64(nsec
)/1e9
808 // Minutes returns the duration as a floating point number of minutes.
809 func (d Duration
) Minutes() float64 {
812 return float64(min
) + float64(nsec
)/(60*1e9
)
815 // Hours returns the duration as a floating point number of hours.
816 func (d Duration
) Hours() float64 {
819 return float64(hour
) + float64(nsec
)/(60*60*1e9
)
822 // Truncate returns the result of rounding d toward zero to a multiple of m.
823 // If m <= 0, Truncate returns d unchanged.
824 func (d Duration
) Truncate(m Duration
) Duration
{
831 // lessThanHalf reports whether x+x < y but avoids overflow,
832 // assuming x and y are both positive (Duration is signed).
833 func lessThanHalf(x
, y Duration
) bool {
834 return uint64(x
)+uint64(x
) < uint64(y
)
837 // Round returns the result of rounding d to the nearest multiple of m.
838 // The rounding behavior for halfway values is to round away from zero.
839 // If the result exceeds the maximum (or minimum)
840 // value that can be stored in a Duration,
841 // Round returns the maximum (or minimum) duration.
842 // If m <= 0, Round returns d unchanged.
843 func (d Duration
) Round(m Duration
) Duration
{
850 if lessThanHalf(r
, m
) {
853 if d1
:= d
- m
+ r
; d1
< d
{
856 return minDuration
// overflow
858 if lessThanHalf(r
, m
) {
861 if d1
:= d
+ m
- r
; d1
> d
{
864 return maxDuration
// overflow
867 // Add returns the time t+d.
868 func (t Time
) Add(d Duration
) Time
{
869 dsec
:= int64(d
/ 1e9
)
870 nsec
:= t
.nsec() + int32(d%1e9
)
878 t
.wall
= t
.wall
&^nsecMask |
uint64(nsec
) // update nsec
880 if t
.wall
&hasMonotonic
!= 0 {
881 te
:= t
.ext
+ int64(d
)
882 if d
< 0 && te
> t
.ext || d
> 0 && te
< t
.ext
{
883 // Monotonic clock reading now out of range; degrade to wall-only.
892 // Sub returns the duration t-u. If the result exceeds the maximum (or minimum)
893 // value that can be stored in a Duration, the maximum (or minimum) duration
895 // To compute t-d for a duration d, use t.Add(-d).
896 func (t Time
) Sub(u Time
) Duration
{
897 if t
.wall
&u
.wall
&hasMonotonic
!= 0 {
900 d
:= Duration(te
- ue
)
901 if d
< 0 && te
> ue
{
902 return maxDuration
// t - u is positive out of range
904 if d
> 0 && te
< ue
{
905 return minDuration
// t - u is negative out of range
909 d
:= Duration(t
.sec()-u
.sec())*Second
+ Duration(t
.nsec()-u
.nsec())
910 // Check for overflow or underflow.
912 case u
.Add(d
).Equal(t
):
913 return d
// d is correct
915 return minDuration
// t - u is negative out of range
917 return maxDuration
// t - u is positive out of range
921 // Since returns the time elapsed since t.
922 // It is shorthand for time.Now().Sub(t).
923 func Since(t Time
) Duration
{
925 if t
.wall
&hasMonotonic
!= 0 {
926 // Common case optimization: if t has monotonic time, then Sub will use only it.
927 now
= Time
{hasMonotonic
, runtimeNano() - startNano
, nil}
934 // Until returns the duration until t.
935 // It is shorthand for t.Sub(time.Now()).
936 func Until(t Time
) Duration
{
938 if t
.wall
&hasMonotonic
!= 0 {
939 // Common case optimization: if t has monotonic time, then Sub will use only it.
940 now
= Time
{hasMonotonic
, runtimeNano() - startNano
, nil}
947 // AddDate returns the time corresponding to adding the
948 // given number of years, months, and days to t.
949 // For example, AddDate(-1, 2, 3) applied to January 1, 2011
950 // returns March 4, 2010.
952 // AddDate normalizes its result in the same way that Date does,
953 // so, for example, adding one month to October 31 yields
954 // December 1, the normalized form for November 31.
955 func (t Time
) AddDate(years
int, months
int, days
int) Time
{
956 year
, month
, day
:= t
.Date()
957 hour
, min
, sec
:= t
.Clock()
958 return Date(year
+years
, month
+Month(months
), day
+days
, hour
, min
, sec
, int(t
.nsec()), t
.Location())
962 secondsPerMinute
= 60
963 secondsPerHour
= 60 * secondsPerMinute
964 secondsPerDay
= 24 * secondsPerHour
965 secondsPerWeek
= 7 * secondsPerDay
966 daysPer400Years
= 365*400 + 97
967 daysPer100Years
= 365*100 + 24
968 daysPer4Years
= 365*4 + 1
971 // date computes the year, day of year, and when full=true,
972 // the month and day in which t occurs.
973 func (t Time
) date(full
bool) (year
int, month Month
, day
int, yday
int) {
974 return absDate(t
.abs(), full
)
977 // absDate is like date but operates on an absolute time.
978 func absDate(abs
uint64, full
bool) (year
int, month Month
, day
int, yday
int) {
979 // Split into time and day.
980 d
:= abs
/ secondsPerDay
982 // Account for 400 year cycles.
983 n
:= d
/ daysPer400Years
985 d
-= daysPer400Years
* n
987 // Cut off 100-year cycles.
988 // The last cycle has one extra leap year, so on the last day
989 // of that year, day / daysPer100Years will be 4 instead of 3.
990 // Cut it back down to 3 by subtracting n>>2.
991 n
= d
/ daysPer100Years
994 d
-= daysPer100Years
* n
996 // Cut off 4-year cycles.
997 // The last cycle has a missing leap year, which does not
998 // affect the computation.
999 n
= d
/ daysPer4Years
1001 d
-= daysPer4Years
* n
1003 // Cut off years within a 4-year cycle.
1004 // The last year is a leap year, so on the last day of that year,
1005 // day / 365 will be 4 instead of 3. Cut it back down to 3
1006 // by subtracting n>>2.
1012 year
= int(int64(y
) + absoluteZeroYear
)
1024 // After leap day; pretend it wasn't there.
1026 case day
== 31+29-1:
1034 // Estimate month on assumption that every month has 31 days.
1035 // The estimate may be too low by at most one month, so adjust.
1036 month
= Month(day
/ 31)
1037 end
:= int(daysBefore
[month
+1])
1043 begin
= int(daysBefore
[month
])
1046 month
++ // because January is 1
1047 day
= day
- begin
+ 1
1051 // daysBefore[m] counts the number of days in a non-leap year
1052 // before month m begins. There is an entry for m=12, counting
1053 // the number of days before January of next year (365).
1054 var daysBefore
= [...]int32{
1060 31 + 28 + 31 + 30 + 31,
1061 31 + 28 + 31 + 30 + 31 + 30,
1062 31 + 28 + 31 + 30 + 31 + 30 + 31,
1063 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31,
1064 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30,
1065 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31,
1066 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30,
1067 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30 + 31,
1070 func daysIn(m Month
, year
int) int {
1071 if m
== February
&& isLeap(year
) {
1074 return int(daysBefore
[m
] - daysBefore
[m
-1])
1077 // Provided by package runtime.
1078 func now() (sec
int64, nsec
int32, mono
int64)
1080 // runtimeNano returns the current value of the runtime clock in nanoseconds.
1081 //go:linkname runtimeNano runtime.nanotime
1082 func runtimeNano() int64
1084 // Monotonic times are reported as offsets from startNano.
1085 // We initialize startNano to runtimeNano() - 1 so that on systems where
1086 // monotonic time resolution is fairly low (e.g. Windows 2008
1087 // which appears to have a default resolution of 15ms),
1088 // we avoid ever reporting a monotonic time of 0.
1089 // (Callers may want to use 0 as "time not set".)
1090 var startNano
int64 = runtimeNano() - 1
1092 // Now returns the current local time.
1094 sec
, nsec
, mono
:= now()
1096 sec
+= unixToInternal
- minWall
1097 if uint64(sec
)>>33 != 0 {
1098 return Time
{uint64(nsec
), sec
+ minWall
, Local
}
1100 return Time
{hasMonotonic |
uint64(sec
)<<nsecShift |
uint64(nsec
), mono
, Local
}
1103 func unixTime(sec
int64, nsec
int32) Time
{
1104 return Time
{uint64(nsec
), sec
+ unixToInternal
, Local
}
1107 // UTC returns t with the location set to UTC.
1108 func (t Time
) UTC() Time
{
1113 // Local returns t with the location set to local time.
1114 func (t Time
) Local() Time
{
1119 // In returns a copy of t representing the same time instant, but
1120 // with the copy's location information set to loc for display
1123 // In panics if loc is nil.
1124 func (t Time
) In(loc
*Location
) Time
{
1126 panic("time: missing Location in call to Time.In")
1132 // Location returns the time zone information associated with t.
1133 func (t Time
) Location() *Location
{
1141 // Zone computes the time zone in effect at time t, returning the abbreviated
1142 // name of the zone (such as "CET") and its offset in seconds east of UTC.
1143 func (t Time
) Zone() (name
string, offset
int) {
1144 name
, offset
, _
, _
= t
.loc
.lookup(t
.unixSec())
1148 // Unix returns t as a Unix time, the number of seconds elapsed
1149 // since January 1, 1970 UTC. The result does not depend on the
1150 // location associated with t.
1151 func (t Time
) Unix() int64 {
1155 // UnixNano returns t as a Unix time, the number of nanoseconds elapsed
1156 // since January 1, 1970 UTC. The result is undefined if the Unix time
1157 // in nanoseconds cannot be represented by an int64 (a date before the year
1158 // 1678 or after 2262). Note that this means the result of calling UnixNano
1159 // on the zero Time is undefined. The result does not depend on the
1160 // location associated with t.
1161 func (t Time
) UnixNano() int64 {
1162 return (t
.unixSec())*1e9
+ int64(t
.nsec())
1165 const timeBinaryVersion
byte = 1
1167 // MarshalBinary implements the encoding.BinaryMarshaler interface.
1168 func (t Time
) MarshalBinary() ([]byte, error
) {
1169 var offsetMin
int16 // minutes east of UTC. -1 is UTC.
1171 if t
.Location() == UTC
{
1174 _
, offset
:= t
.Zone()
1176 return nil, errors
.New("Time.MarshalBinary: zone offset has fractional minute")
1179 if offset
< -32768 || offset
== -1 || offset
> 32767 {
1180 return nil, errors
.New("Time.MarshalBinary: unexpected zone offset")
1182 offsetMin
= int16(offset
)
1188 timeBinaryVersion
, // byte 0 : version
1189 byte(sec
>> 56), // bytes 1-8: seconds
1197 byte(nsec
>> 24), // bytes 9-12: nanoseconds
1201 byte(offsetMin
>> 8), // bytes 13-14: zone offset in minutes
1208 // UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.
1209 func (t
*Time
) UnmarshalBinary(data
[]byte) error
{
1212 return errors
.New("Time.UnmarshalBinary: no data")
1215 if buf
[0] != timeBinaryVersion
{
1216 return errors
.New("Time.UnmarshalBinary: unsupported version")
1219 if len(buf
) != /*version*/ 1+ /*sec*/ 8+ /*nsec*/ 4+ /*zone offset*/ 2 {
1220 return errors
.New("Time.UnmarshalBinary: invalid length")
1224 sec
:= int64(buf
[7]) |
int64(buf
[6])<<8 |
int64(buf
[5])<<16 |
int64(buf
[4])<<24 |
1225 int64(buf
[3])<<32 |
int64(buf
[2])<<40 |
int64(buf
[1])<<48 |
int64(buf
[0])<<56
1228 nsec
:= int32(buf
[3]) |
int32(buf
[2])<<8 |
int32(buf
[1])<<16 |
int32(buf
[0])<<24
1231 offset
:= int(int16(buf
[1])|
int16(buf
[0])<<8) * 60
1234 t
.wall
= uint64(nsec
)
1237 if offset
== -1*60 {
1239 } else if _
, localoff
, _
, _
:= Local
.lookup(t
.unixSec()); offset
== localoff
{
1242 t
.setLoc(FixedZone("", offset
))
1248 // TODO(rsc): Remove GobEncoder, GobDecoder, MarshalJSON, UnmarshalJSON in Go 2.
1249 // The same semantics will be provided by the generic MarshalBinary, MarshalText,
1250 // UnmarshalBinary, UnmarshalText.
1252 // GobEncode implements the gob.GobEncoder interface.
1253 func (t Time
) GobEncode() ([]byte, error
) {
1254 return t
.MarshalBinary()
1257 // GobDecode implements the gob.GobDecoder interface.
1258 func (t
*Time
) GobDecode(data
[]byte) error
{
1259 return t
.UnmarshalBinary(data
)
1262 // MarshalJSON implements the json.Marshaler interface.
1263 // The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
1264 func (t Time
) MarshalJSON() ([]byte, error
) {
1265 if y
:= t
.Year(); y
< 0 || y
>= 10000 {
1266 // RFC 3339 is clear that years are 4 digits exactly.
1267 // See golang.org/issue/4556#c15 for more discussion.
1268 return nil, errors
.New("Time.MarshalJSON: year outside of range [0,9999]")
1271 b
:= make([]byte, 0, len(RFC3339Nano
)+2)
1273 b
= t
.AppendFormat(b
, RFC3339Nano
)
1278 // UnmarshalJSON implements the json.Unmarshaler interface.
1279 // The time is expected to be a quoted string in RFC 3339 format.
1280 func (t
*Time
) UnmarshalJSON(data
[]byte) error
{
1281 // Ignore null, like in the main JSON package.
1282 if string(data
) == "null" {
1285 // Fractional seconds are handled implicitly by Parse.
1287 *t
, err
= Parse(`"`+RFC3339
+`"`, string(data
))
1291 // MarshalText implements the encoding.TextMarshaler interface.
1292 // The time is formatted in RFC 3339 format, with sub-second precision added if present.
1293 func (t Time
) MarshalText() ([]byte, error
) {
1294 if y
:= t
.Year(); y
< 0 || y
>= 10000 {
1295 return nil, errors
.New("Time.MarshalText: year outside of range [0,9999]")
1298 b
:= make([]byte, 0, len(RFC3339Nano
))
1299 return t
.AppendFormat(b
, RFC3339Nano
), nil
1302 // UnmarshalText implements the encoding.TextUnmarshaler interface.
1303 // The time is expected to be in RFC 3339 format.
1304 func (t
*Time
) UnmarshalText(data
[]byte) error
{
1305 // Fractional seconds are handled implicitly by Parse.
1307 *t
, err
= Parse(RFC3339
, string(data
))
1311 // Unix returns the local Time corresponding to the given Unix time,
1312 // sec seconds and nsec nanoseconds since January 1, 1970 UTC.
1313 // It is valid to pass nsec outside the range [0, 999999999].
1314 // Not all sec values have a corresponding time value. One such
1315 // value is 1<<63-1 (the largest int64 value).
1316 func Unix(sec
int64, nsec
int64) Time
{
1317 if nsec
< 0 || nsec
>= 1e9
{
1326 return unixTime(sec
, int32(nsec
))
1329 func isLeap(year
int) bool {
1330 return year%4
== 0 && (year%100
!= 0 || year%400
== 0)
1333 // norm returns nhi, nlo such that
1334 // hi * base + lo == nhi * base + nlo
1336 func norm(hi
, lo
, base
int) (nhi
, nlo
int) {
1338 n
:= (-lo
-1)/base
+ 1
1350 // Date returns the Time corresponding to
1351 // yyyy-mm-dd hh:mm:ss + nsec nanoseconds
1352 // in the appropriate zone for that time in the given location.
1354 // The month, day, hour, min, sec, and nsec values may be outside
1355 // their usual ranges and will be normalized during the conversion.
1356 // For example, October 32 converts to November 1.
1358 // A daylight savings time transition skips or repeats times.
1359 // For example, in the United States, March 13, 2011 2:15am never occurred,
1360 // while November 6, 2011 1:15am occurred twice. In such cases, the
1361 // choice of time zone, and therefore the time, is not well-defined.
1362 // Date returns a time that is correct in one of the two zones involved
1363 // in the transition, but it does not guarantee which.
1365 // Date panics if loc is nil.
1366 func Date(year
int, month Month
, day
, hour
, min
, sec
, nsec
int, loc
*Location
) Time
{
1368 panic("time: missing Location in call to Date")
1371 // Normalize month, overflowing into year.
1373 year
, m
= norm(year
, m
, 12)
1374 month
= Month(m
) + 1
1376 // Normalize nsec, sec, min, hour, overflowing into day.
1377 sec
, nsec
= norm(sec
, nsec
, 1e9
)
1378 min
, sec
= norm(min
, sec
, 60)
1379 hour
, min
= norm(hour
, min
, 60)
1380 day
, hour
= norm(day
, hour
, 24)
1382 y
:= uint64(int64(year
) - absoluteZeroYear
)
1384 // Compute days since the absolute epoch.
1386 // Add in days from 400-year cycles.
1389 d
:= daysPer400Years
* n
1391 // Add in 100-year cycles.
1394 d
+= daysPer100Years
* n
1396 // Add in 4-year cycles.
1399 d
+= daysPer4Years
* n
1401 // Add in non-leap years.
1405 // Add in days before this month.
1406 d
+= uint64(daysBefore
[month
-1])
1407 if isLeap(year
) && month
>= March
{
1411 // Add in days before today.
1412 d
+= uint64(day
- 1)
1414 // Add in time elapsed today.
1415 abs
:= d
* secondsPerDay
1416 abs
+= uint64(hour
*secondsPerHour
+ min
*secondsPerMinute
+ sec
)
1418 unix
:= int64(abs
) + (absoluteToInternal
+ internalToUnix
)
1420 // Look for zone offset for t, so we can adjust to UTC.
1421 // The lookup function expects UTC, so we pass t in the
1422 // hope that it will not be too close to a zone transition,
1423 // and then adjust if it is.
1424 _
, offset
, start
, end
:= loc
.lookup(unix
)
1426 switch utc
:= unix
- int64(offset
); {
1428 _
, offset
, _
, _
= loc
.lookup(start
- 1)
1430 _
, offset
, _
, _
= loc
.lookup(end
)
1432 unix
-= int64(offset
)
1435 t
:= unixTime(unix
, int32(nsec
))
1440 // Truncate returns the result of rounding t down to a multiple of d (since the zero time).
1441 // If d <= 0, Truncate returns t stripped of any monotonic clock reading but otherwise unchanged.
1443 // Truncate operates on the time as an absolute duration since the
1444 // zero time; it does not operate on the presentation form of the
1445 // time. Thus, Truncate(Hour) may return a time with a non-zero
1446 // minute, depending on the time's Location.
1447 func (t Time
) Truncate(d Duration
) Time
{
1456 // Round returns the result of rounding t to the nearest multiple of d (since the zero time).
1457 // The rounding behavior for halfway values is to round up.
1458 // If d <= 0, Round returns t stripped of any monotonic clock reading but otherwise unchanged.
1460 // Round operates on the time as an absolute duration since the
1461 // zero time; it does not operate on the presentation form of the
1462 // time. Thus, Round(Hour) may return a time with a non-zero
1463 // minute, depending on the time's Location.
1464 func (t Time
) Round(d Duration
) Time
{
1470 if lessThanHalf(r
, d
) {
1476 // div divides t by d and returns the quotient parity and remainder.
1477 // We don't use the quotient parity anymore (round half up instead of round to even)
1478 // but it's still here in case we change our minds.
1479 func div(t Time
, d Duration
) (qmod2
int, r Duration
) {
1484 // Operate on absolute value.
1490 sec
-- // sec >= 1 before the -- so safe
1495 // Special case: 2d divides 1 second.
1496 case d
< Second
&& Second
%(d
+d
) == 0:
1497 qmod2
= int(nsec
/int32(d
)) & 1
1498 r
= Duration(nsec
% int32(d
))
1500 // Special case: d is a multiple of 1 second.
1502 d1
:= int64(d
/ Second
)
1503 qmod2
= int(sec
/d1
) & 1
1504 r
= Duration(sec%d
1)*Second
+ Duration(nsec
)
1507 // This could be faster if more cleverness were applied,
1508 // but it's really only here to avoid special case restrictions in the API.
1509 // No one will care about these cases.
1511 // Compute nanoseconds as 128-bit number.
1513 tmp
:= (sec
>> 32) * 1e9
1516 tmp
= (sec
& 0xFFFFFFFF) * 1e9
1517 u0x
, u0
:= u0
, u0
+tmp
1521 u0x
, u0
= u0
, u0
+uint64(nsec
)
1526 // Compute remainder by subtracting r<<k for decreasing k.
1527 // Quotient parity is whether we subtract on last round.
1535 if u1
> d1 || u1
== d1
&& u0
>= d0
{
1544 if d1
== 0 && d0
== uint64(d
) {
1548 d0 |
= (d1
& 1) << 63
1555 // If input was negative and not an exact multiple of d, we computed q, r such that
1557 // But the right answers are given by -(q-1), d-r:
1560 // -(q-1)*d + (d - r) = t