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
13 // A Time represents an instant in time with nanosecond precision.
15 // Programs using times should typically store and pass them as values,
16 // not pointers. That is, time variables and struct fields should be of
17 // type time.Time, not *time.Time. A Time value can be used by
18 // multiple goroutines simultaneously.
20 // Time instants can be compared using the Before, After, and Equal methods.
21 // The Sub method subtracts two instants, producing a Duration.
22 // The Add method adds a Time and a Duration, producing a Time.
24 // The zero value of type Time is January 1, year 1, 00:00:00.000000000 UTC.
25 // As this time is unlikely to come up in practice, the IsZero method gives
26 // a simple way of detecting a time that has not been initialized explicitly.
28 // Each Time has associated with it a Location, consulted when computing the
29 // presentation form of the time, such as in the Format, Hour, and Year methods.
30 // The methods Local, UTC, and In return a Time with a specific location.
31 // Changing the location in this way changes only the presentation; it does not
32 // change the instant in time being denoted and therefore does not affect the
33 // computations described in earlier paragraphs.
35 // Note that the Go == operator compares not just the time instant but also the
36 // Location. Therefore, Time values should not be used as map or database keys
37 // without first guaranteeing that the identical Location has been set for all
38 // values, which can be achieved through use of the UTC or Local method.
41 // sec gives the number of seconds elapsed since
42 // January 1, year 1 00:00:00 UTC.
45 // nsec specifies a non-negative nanosecond
46 // offset within the second named by Seconds.
47 // It must be in the range [0, 999999999].
50 // loc specifies the Location that should be used to
51 // determine the minute, hour, month, day, and year
52 // that correspond to this Time.
53 // The nil location means UTC.
54 // All UTC times are represented with loc==nil, never loc==&utcLoc.
58 func (t
*Time
) setLoc(loc
*Location
) {
65 // After reports whether the time instant t is after u.
66 func (t Time
) After(u Time
) bool {
67 return t
.sec
> u
.sec || t
.sec
== u
.sec
&& t
.nsec
> u
.nsec
70 // Before reports whether the time instant t is before u.
71 func (t Time
) Before(u Time
) bool {
72 return t
.sec
< u
.sec || t
.sec
== u
.sec
&& t
.nsec
< u
.nsec
75 // Equal reports whether t and u represent the same time instant.
76 // Two times can be equal even if they are in different locations.
77 // For example, 6:00 +0200 CEST and 4:00 UTC are Equal.
78 // Do not use == with Time values.
79 func (t Time
) Equal(u Time
) bool {
80 return t
.sec
== u
.sec
&& t
.nsec
== u
.nsec
83 // A Month specifies a month of the year (January = 1, ...).
87 January Month
= 1 + iota
101 var months
= [...]string{
116 // String returns the English name of the month ("January", "February", ...).
117 func (m Month
) String() string {
118 if January
<= m
&& m
<= December
{
121 buf
:= make([]byte, 20)
122 n
:= fmtInt(buf
, uint64(m
))
123 return "%!Month(" + string(buf
[n
:]) + ")"
126 // A Weekday specifies a day of the week (Sunday = 0, ...).
130 Sunday Weekday
= iota
139 var days
= [...]string{
149 // String returns the English name of the day ("Sunday", "Monday", ...).
150 func (d Weekday
) String() string { return days
[d
] }
152 // Computations on time.
154 // The zero value for a Time is defined to be
155 // January 1, year 1, 00:00:00.000000000 UTC
156 // which (1) looks like a zero, or as close as you can get in a date
157 // (1-1-1 00:00:00 UTC), (2) is unlikely enough to arise in practice to
158 // be a suitable "not set" sentinel, unlike Jan 1 1970, and (3) has a
159 // non-negative year even in time zones west of UTC, unlike 1-1-0
160 // 00:00:00 UTC, which would be 12-31-(-1) 19:00:00 in New York.
162 // The zero Time value does not force a specific epoch for the time
163 // representation. For example, to use the Unix epoch internally, we
164 // could define that to distinguish a zero value from Jan 1 1970, that
165 // time would be represented by sec=-1, nsec=1e9. However, it does
166 // suggest a representation, namely using 1-1-1 00:00:00 UTC as the
167 // epoch, and that's what we do.
169 // The Add and Sub computations are oblivious to the choice of epoch.
171 // The presentation computations - year, month, minute, and so on - all
172 // rely heavily on division and modulus by positive constants. For
173 // calendrical calculations we want these divisions to round down, even
174 // for negative values, so that the remainder is always positive, but
175 // Go's division (like most hardware division instructions) rounds to
176 // zero. We can still do those computations and then adjust the result
177 // for a negative numerator, but it's annoying to write the adjustment
178 // over and over. Instead, we can change to a different epoch so long
179 // ago that all the times we care about will be positive, and then round
180 // to zero and round down coincide. These presentation routines already
181 // have to add the zone offset, so adding the translation to the
182 // alternate epoch is cheap. For example, having a non-negative time t
183 // means that we can write
196 // The calendar runs on an exact 400 year cycle: a 400-year calendar
197 // printed for 1970-2469 will apply as well to 2370-2769. Even the days
198 // of the week match up. It simplifies the computations to choose the
199 // cycle boundaries so that the exceptional years are always delayed as
200 // long as possible. That means choosing a year equal to 1 mod 400, so
201 // that the first leap year is the 4th year, the first missed leap year
202 // is the 100th year, and the missed missed leap year is the 400th year.
203 // So we'd prefer instead to print a calendar for 2001-2400 and reuse it
206 // Finally, it's convenient if the delta between the Unix epoch and
207 // long-ago epoch is representable by an int64 constant.
209 // These three considerations—choose an epoch as early as possible, that
210 // uses a year equal to 1 mod 400, and that is no more than 2⁶³ seconds
211 // earlier than 1970—bring us to the year -292277022399. We refer to
212 // this year as the absolute zero year, and to times measured as a uint64
213 // seconds since this year as absolute times.
215 // Times measured as an int64 seconds since the year 1—the representation
216 // used for Time's sec field—are called internal times.
218 // Times measured as an int64 seconds since the year 1970 are called Unix
221 // It is tempting to just use the year 1 as the absolute epoch, defining
222 // that the routines are only valid for years >= 1. However, the
223 // routines would then be invalid when displaying the epoch in time zones
224 // west of UTC, since it is year 0. It doesn't seem tenable to say that
225 // printing the zero time correctly isn't supported in half the time
226 // zones. By comparison, it's reasonable to mishandle some times in
227 // the year -292277022399.
229 // All this is opaque to clients of the API and can be changed if a
230 // better implementation presents itself.
233 // The unsigned zero year for internal calculations.
234 // Must be 1 mod 400, and times before it will not compute correctly,
235 // but otherwise can be changed at will.
236 absoluteZeroYear
= -292277022399
238 // The year of the zero Time.
239 // Assumed by the unixToInternal computation below.
242 // Offsets to convert between internal and absolute or Unix times.
243 absoluteToInternal
int64 = (absoluteZeroYear
- internalYear
) * 365.2425 * secondsPerDay
244 internalToAbsolute
= -absoluteToInternal
246 unixToInternal
int64 = (1969*365 + 1969/4 - 1969/100 + 1969/400) * secondsPerDay
247 internalToUnix
int64 = -unixToInternal
250 // IsZero reports whether t represents the zero time instant,
251 // January 1, year 1, 00:00:00 UTC.
252 func (t Time
) IsZero() bool {
253 return t
.sec
== 0 && t
.nsec
== 0
256 // abs returns the time t as an absolute time, adjusted by the zone offset.
257 // It is called when computing a presentation property like Month or Hour.
258 func (t Time
) abs() uint64 {
260 // Avoid function calls when possible.
261 if l
== nil || l
== &localLoc
{
264 sec
:= t
.sec
+ internalToUnix
266 if l
.cacheZone
!= nil && l
.cacheStart
<= sec
&& sec
< l
.cacheEnd
{
267 sec
+= int64(l
.cacheZone
.offset
)
269 _
, offset
, _
, _
, _
:= l
.lookup(sec
)
273 return uint64(sec
+ (unixToInternal
+ internalToAbsolute
))
276 // locabs is a combination of the Zone and abs methods,
277 // extracting both return values from a single zone lookup.
278 func (t Time
) locabs() (name
string, offset
int, abs
uint64) {
280 if l
== nil || l
== &localLoc
{
283 // Avoid function call if we hit the local time cache.
284 sec
:= t
.sec
+ internalToUnix
286 if l
.cacheZone
!= nil && l
.cacheStart
<= sec
&& sec
< l
.cacheEnd
{
287 name
= l
.cacheZone
.name
288 offset
= l
.cacheZone
.offset
290 name
, offset
, _
, _
, _
= l
.lookup(sec
)
296 abs
= uint64(sec
+ (unixToInternal
+ internalToAbsolute
))
300 // Date returns the year, month, and day in which t occurs.
301 func (t Time
) Date() (year
int, month Month
, day
int) {
302 year
, month
, day
, _
= t
.date(true)
306 // Year returns the year in which t occurs.
307 func (t Time
) Year() int {
308 year
, _
, _
, _
:= t
.date(false)
312 // Month returns the month of the year specified by t.
313 func (t Time
) Month() Month
{
314 _
, month
, _
, _
:= t
.date(true)
318 // Day returns the day of the month specified by t.
319 func (t Time
) Day() int {
320 _
, _
, day
, _
:= t
.date(true)
324 // Weekday returns the day of the week specified by t.
325 func (t Time
) Weekday() Weekday
{
326 return absWeekday(t
.abs())
329 // absWeekday is like Weekday but operates on an absolute time.
330 func absWeekday(abs
uint64) Weekday
{
331 // January 1 of the absolute year, like January 1 of 2001, was a Monday.
332 sec
:= (abs
+ uint64(Monday
)*secondsPerDay
) % secondsPerWeek
333 return Weekday(int(sec
) / secondsPerDay
)
336 // ISOWeek returns the ISO 8601 year and week number in which t occurs.
337 // Week ranges from 1 to 53. Jan 01 to Jan 03 of year n might belong to
338 // week 52 or 53 of year n-1, and Dec 29 to Dec 31 might belong to week 1
340 func (t Time
) ISOWeek() (year
, week
int) {
341 year
, month
, day
, yday
:= t
.date(true)
342 wday
:= int(t
.Weekday()+6) % 7 // weekday but Monday = 0.
353 // Calculate week as number of Mondays in year up to
354 // and including today, plus 1 because the first week is week 0.
355 // Putting the + 1 inside the numerator as a + 7 keeps the
356 // numerator from being negative, which would cause it to
357 // round incorrectly.
358 week
= (yday
- wday
+ 7) / 7
360 // The week number is now correct under the assumption
361 // that the first Monday of the year is in week 1.
362 // If Jan 1 is a Tuesday, Wednesday, or Thursday, the first Monday
363 // is actually in week 2.
364 jan1wday
:= (wday
- yday
+ 7*53) % 7
365 if Tue
<= jan1wday
&& jan1wday
<= Thu
{
369 // If the week number is still 0, we're in early January but in
370 // the last week of last year.
374 // A year has 53 weeks when Jan 1 or Dec 31 is a Thursday,
375 // meaning Jan 1 of the next year is a Friday
376 // or it was a leap year and Jan 1 of the next year is a Saturday.
377 if jan1wday
== Fri ||
(jan1wday
== Sat
&& isLeap(year
)) {
382 // December 29 to 31 are in week 1 of next year if
383 // they are after the last Thursday of the year and
384 // December 31 is a Monday, Tuesday, or Wednesday.
385 if month
== December
&& day
>= 29 && wday
< Thu
{
386 if dec31wday
:= (wday
+ 31 - day
) % 7; Mon
<= dec31wday
&& dec31wday
<= Wed
{
395 // Clock returns the hour, minute, and second within the day specified by t.
396 func (t Time
) Clock() (hour
, min
, sec
int) {
397 return absClock(t
.abs())
400 // absClock is like clock but operates on an absolute time.
401 func absClock(abs
uint64) (hour
, min
, sec
int) {
402 sec
= int(abs
% secondsPerDay
)
403 hour
= sec
/ secondsPerHour
404 sec
-= hour
* secondsPerHour
405 min
= sec
/ secondsPerMinute
406 sec
-= min
* secondsPerMinute
410 // Hour returns the hour within the day specified by t, in the range [0, 23].
411 func (t Time
) Hour() int {
412 return int(t
.abs()%secondsPerDay
) / secondsPerHour
415 // Minute returns the minute offset within the hour specified by t, in the range [0, 59].
416 func (t Time
) Minute() int {
417 return int(t
.abs()%secondsPerHour
) / secondsPerMinute
420 // Second returns the second offset within the minute specified by t, in the range [0, 59].
421 func (t Time
) Second() int {
422 return int(t
.abs() % secondsPerMinute
)
425 // Nanosecond returns the nanosecond offset within the second specified by t,
426 // in the range [0, 999999999].
427 func (t Time
) Nanosecond() int {
431 // YearDay returns the day of the year specified by t, in the range [1,365] for non-leap years,
432 // and [1,366] in leap years.
433 func (t Time
) YearDay() int {
434 _
, _
, _
, yday
:= t
.date(false)
438 // A Duration represents the elapsed time between two instants
439 // as an int64 nanosecond count. The representation limits the
440 // largest representable duration to approximately 290 years.
444 minDuration Duration
= -1 << 63
445 maxDuration Duration
= 1<<63 - 1
448 // Common durations. There is no definition for units of Day or larger
449 // to avoid confusion across daylight savings time zone transitions.
451 // To count the number of units in a Duration, divide:
452 // second := time.Second
453 // fmt.Print(int64(second/time.Millisecond)) // prints 1000
455 // To convert an integer number of units to a Duration, multiply:
457 // fmt.Print(time.Duration(seconds)*time.Second) // prints 10s
460 Nanosecond Duration
= 1
461 Microsecond
= 1000 * Nanosecond
462 Millisecond
= 1000 * Microsecond
463 Second
= 1000 * Millisecond
468 // String returns a string representing the duration in the form "72h3m0.5s".
469 // Leading zero units are omitted. As a special case, durations less than one
470 // second format use a smaller unit (milli-, micro-, or nanoseconds) to ensure
471 // that the leading digit is non-zero. The zero duration formats as 0s.
472 func (d Duration
) String() string {
473 // Largest time is 2540400h10m10.000000000s
483 if u
< uint64(Second
) {
484 // Special case: if duration is smaller than a second,
485 // use smaller units, like 1.2ms
493 case u
< uint64(Microsecond
):
497 case u
< uint64(Millisecond
):
498 // print microseconds
500 // U+00B5 'µ' micro sign == 0xC2 0xB5
501 w
-- // Need room for two bytes.
504 // print milliseconds
508 w
, u
= fmtFrac(buf
[:w
], u
, prec
)
509 w
= fmtInt(buf
[:w
], u
)
514 w
, u
= fmtFrac(buf
[:w
], u
, 9)
516 // u is now integer seconds
517 w
= fmtInt(buf
[:w
], u%60
)
520 // u is now integer minutes
524 w
= fmtInt(buf
[:w
], u%60
)
527 // u is now integer hours
528 // Stop at hours because days can be different lengths.
532 w
= fmtInt(buf
[:w
], u
)
542 return string(buf
[w
:])
545 // fmtFrac formats the fraction of v/10**prec (e.g., ".12345") into the
546 // tail of buf, omitting trailing zeros. it omits the decimal
547 // point too when the fraction is 0. It returns the index where the
548 // output bytes begin and the value v/10**prec.
549 func fmtFrac(buf
[]byte, v
uint64, prec
int) (nw
int, nv
uint64) {
550 // Omit trailing zeros up to and including decimal point.
553 for i
:= 0; i
< prec
; i
++ {
555 print = print || digit
!= 0
558 buf
[w
] = byte(digit
) + '0'
569 // fmtInt formats v into the tail of buf.
570 // It returns the index where the output begins.
571 func fmtInt(buf
[]byte, v
uint64) int {
579 buf
[w
] = byte(v%10
) + '0'
586 // Nanoseconds returns the duration as an integer nanosecond count.
587 func (d Duration
) Nanoseconds() int64 { return int64(d
) }
589 // These methods return float64 because the dominant
590 // use case is for printing a floating point number like 1.5s, and
591 // a truncation to integer would make them not useful in those cases.
592 // Splitting the integer and fraction ourselves guarantees that
593 // converting the returned float64 to an integer rounds the same
594 // way that a pure integer conversion would have, even in cases
595 // where, say, float64(d.Nanoseconds())/1e9 would have rounded
598 // Seconds returns the duration as a floating point number of seconds.
599 func (d Duration
) Seconds() float64 {
602 return float64(sec
) + float64(nsec
)/1e9
605 // Minutes returns the duration as a floating point number of minutes.
606 func (d Duration
) Minutes() float64 {
609 return float64(min
) + float64(nsec
)/(60*1e9
)
612 // Hours returns the duration as a floating point number of hours.
613 func (d Duration
) Hours() float64 {
616 return float64(hour
) + float64(nsec
)/(60*60*1e9
)
619 // Add returns the time t+d.
620 func (t Time
) Add(d Duration
) Time
{
621 t
.sec
+= int64(d
/ 1e9
)
622 nsec
:= t
.nsec
+ int32(d%1e9
)
634 // Sub returns the duration t-u. If the result exceeds the maximum (or minimum)
635 // value that can be stored in a Duration, the maximum (or minimum) duration
637 // To compute t-d for a duration d, use t.Add(-d).
638 func (t Time
) Sub(u Time
) Duration
{
639 d
:= Duration(t
.sec
-u
.sec
)*Second
+ Duration(t
.nsec
-u
.nsec
)
640 // Check for overflow or underflow.
642 case u
.Add(d
).Equal(t
):
643 return d
// d is correct
645 return minDuration
// t - u is negative out of range
647 return maxDuration
// t - u is positive out of range
651 // Since returns the time elapsed since t.
652 // It is shorthand for time.Now().Sub(t).
653 func Since(t Time
) Duration
{
657 // Until returns the duration until t.
658 // It is shorthand for t.Sub(time.Now()).
659 func Until(t Time
) Duration
{
663 // AddDate returns the time corresponding to adding the
664 // given number of years, months, and days to t.
665 // For example, AddDate(-1, 2, 3) applied to January 1, 2011
666 // returns March 4, 2010.
668 // AddDate normalizes its result in the same way that Date does,
669 // so, for example, adding one month to October 31 yields
670 // December 1, the normalized form for November 31.
671 func (t Time
) AddDate(years
int, months
int, days
int) Time
{
672 year
, month
, day
:= t
.Date()
673 hour
, min
, sec
:= t
.Clock()
674 return Date(year
+years
, month
+Month(months
), day
+days
, hour
, min
, sec
, int(t
.nsec
), t
.Location())
678 secondsPerMinute
= 60
679 secondsPerHour
= 60 * 60
680 secondsPerDay
= 24 * secondsPerHour
681 secondsPerWeek
= 7 * secondsPerDay
682 daysPer400Years
= 365*400 + 97
683 daysPer100Years
= 365*100 + 24
684 daysPer4Years
= 365*4 + 1
687 // date computes the year, day of year, and when full=true,
688 // the month and day in which t occurs.
689 func (t Time
) date(full
bool) (year
int, month Month
, day
int, yday
int) {
690 return absDate(t
.abs(), full
)
693 // absDate is like date but operates on an absolute time.
694 func absDate(abs
uint64, full
bool) (year
int, month Month
, day
int, yday
int) {
695 // Split into time and day.
696 d
:= abs
/ secondsPerDay
698 // Account for 400 year cycles.
699 n
:= d
/ daysPer400Years
701 d
-= daysPer400Years
* n
703 // Cut off 100-year cycles.
704 // The last cycle has one extra leap year, so on the last day
705 // of that year, day / daysPer100Years will be 4 instead of 3.
706 // Cut it back down to 3 by subtracting n>>2.
707 n
= d
/ daysPer100Years
710 d
-= daysPer100Years
* n
712 // Cut off 4-year cycles.
713 // The last cycle has a missing leap year, which does not
714 // affect the computation.
715 n
= d
/ daysPer4Years
717 d
-= daysPer4Years
* n
719 // Cut off years within a 4-year cycle.
720 // The last year is a leap year, so on the last day of that year,
721 // day / 365 will be 4 instead of 3. Cut it back down to 3
722 // by subtracting n>>2.
728 year
= int(int64(y
) + absoluteZeroYear
)
740 // After leap day; pretend it wasn't there.
750 // Estimate month on assumption that every month has 31 days.
751 // The estimate may be too low by at most one month, so adjust.
752 month
= Month(day
/ 31)
753 end
:= int(daysBefore
[month
+1])
759 begin
= int(daysBefore
[month
])
762 month
++ // because January is 1
763 day
= day
- begin
+ 1
767 // daysBefore[m] counts the number of days in a non-leap year
768 // before month m begins. There is an entry for m=12, counting
769 // the number of days before January of next year (365).
770 var daysBefore
= [...]int32{
776 31 + 28 + 31 + 30 + 31,
777 31 + 28 + 31 + 30 + 31 + 30,
778 31 + 28 + 31 + 30 + 31 + 30 + 31,
779 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31,
780 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30,
781 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31,
782 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30,
783 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30 + 31,
786 func daysIn(m Month
, year
int) int {
787 if m
== February
&& isLeap(year
) {
790 return int(daysBefore
[m
] - daysBefore
[m
-1])
793 // Provided by package runtime.
794 func now() (sec
int64, nsec
int32)
796 // Now returns the current local time.
799 return Time
{sec
+ unixToInternal
, nsec
, Local
}
802 // UTC returns t with the location set to UTC.
803 func (t Time
) UTC() Time
{
808 // Local returns t with the location set to local time.
809 func (t Time
) Local() Time
{
814 // In returns t with the location information set to loc.
816 // In panics if loc is nil.
817 func (t Time
) In(loc
*Location
) Time
{
819 panic("time: missing Location in call to Time.In")
825 // Location returns the time zone information associated with t.
826 func (t Time
) Location() *Location
{
834 // Zone computes the time zone in effect at time t, returning the abbreviated
835 // name of the zone (such as "CET") and its offset in seconds east of UTC.
836 func (t Time
) Zone() (name
string, offset
int) {
837 name
, offset
, _
, _
, _
= t
.loc
.lookup(t
.sec
+ internalToUnix
)
841 // Unix returns t as a Unix time, the number of seconds elapsed
842 // since January 1, 1970 UTC.
843 func (t Time
) Unix() int64 {
844 return t
.sec
+ internalToUnix
847 // UnixNano returns t as a Unix time, the number of nanoseconds elapsed
848 // since January 1, 1970 UTC. The result is undefined if the Unix time
849 // in nanoseconds cannot be represented by an int64 (a date before the year
850 // 1678 or after 2262). Note that this means the result of calling UnixNano
851 // on the zero Time is undefined.
852 func (t Time
) UnixNano() int64 {
853 return (t
.sec
+internalToUnix
)*1e9
+ int64(t
.nsec
)
856 const timeBinaryVersion
byte = 1
858 // MarshalBinary implements the encoding.BinaryMarshaler interface.
859 func (t Time
) MarshalBinary() ([]byte, error
) {
860 var offsetMin
int16 // minutes east of UTC. -1 is UTC.
862 if t
.Location() == UTC
{
865 _
, offset
:= t
.Zone()
867 return nil, errors
.New("Time.MarshalBinary: zone offset has fractional minute")
870 if offset
< -32768 || offset
== -1 || offset
> 32767 {
871 return nil, errors
.New("Time.MarshalBinary: unexpected zone offset")
873 offsetMin
= int16(offset
)
877 timeBinaryVersion
, // byte 0 : version
878 byte(t
.sec
>> 56), // bytes 1-8: seconds
886 byte(t
.nsec
>> 24), // bytes 9-12: nanoseconds
890 byte(offsetMin
>> 8), // bytes 13-14: zone offset in minutes
897 // UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.
898 func (t
*Time
) UnmarshalBinary(data
[]byte) error
{
901 return errors
.New("Time.UnmarshalBinary: no data")
904 if buf
[0] != timeBinaryVersion
{
905 return errors
.New("Time.UnmarshalBinary: unsupported version")
908 if len(buf
) != /*version*/ 1+ /*sec*/ 8+ /*nsec*/ 4+ /*zone offset*/ 2 {
909 return errors
.New("Time.UnmarshalBinary: invalid length")
913 t
.sec
= int64(buf
[7]) |
int64(buf
[6])<<8 |
int64(buf
[5])<<16 |
int64(buf
[4])<<24 |
914 int64(buf
[3])<<32 |
int64(buf
[2])<<40 |
int64(buf
[1])<<48 |
int64(buf
[0])<<56
917 t
.nsec
= int32(buf
[3]) |
int32(buf
[2])<<8 |
int32(buf
[1])<<16 |
int32(buf
[0])<<24
920 offset
:= int(int16(buf
[1])|
int16(buf
[0])<<8) * 60
924 } else if _
, localoff
, _
, _
, _
:= Local
.lookup(t
.sec
+ internalToUnix
); offset
== localoff
{
927 t
.setLoc(FixedZone("", offset
))
933 // TODO(rsc): Remove GobEncoder, GobDecoder, MarshalJSON, UnmarshalJSON in Go 2.
934 // The same semantics will be provided by the generic MarshalBinary, MarshalText,
935 // UnmarshalBinary, UnmarshalText.
937 // GobEncode implements the gob.GobEncoder interface.
938 func (t Time
) GobEncode() ([]byte, error
) {
939 return t
.MarshalBinary()
942 // GobDecode implements the gob.GobDecoder interface.
943 func (t
*Time
) GobDecode(data
[]byte) error
{
944 return t
.UnmarshalBinary(data
)
947 // MarshalJSON implements the json.Marshaler interface.
948 // The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
949 func (t Time
) MarshalJSON() ([]byte, error
) {
950 if y
:= t
.Year(); y
< 0 || y
>= 10000 {
951 // RFC 3339 is clear that years are 4 digits exactly.
952 // See golang.org/issue/4556#c15 for more discussion.
953 return nil, errors
.New("Time.MarshalJSON: year outside of range [0,9999]")
956 b
:= make([]byte, 0, len(RFC3339Nano
)+2)
958 b
= t
.AppendFormat(b
, RFC3339Nano
)
963 // UnmarshalJSON implements the json.Unmarshaler interface.
964 // The time is expected to be a quoted string in RFC 3339 format.
965 func (t
*Time
) UnmarshalJSON(data
[]byte) error
{
966 // Ignore null, like in the main JSON package.
967 if string(data
) == "null" {
970 // Fractional seconds are handled implicitly by Parse.
972 *t
, err
= Parse(`"`+RFC3339
+`"`, string(data
))
976 // MarshalText implements the encoding.TextMarshaler interface.
977 // The time is formatted in RFC 3339 format, with sub-second precision added if present.
978 func (t Time
) MarshalText() ([]byte, error
) {
979 if y
:= t
.Year(); y
< 0 || y
>= 10000 {
980 return nil, errors
.New("Time.MarshalText: year outside of range [0,9999]")
983 b
:= make([]byte, 0, len(RFC3339Nano
))
984 return t
.AppendFormat(b
, RFC3339Nano
), nil
987 // UnmarshalText implements the encoding.TextUnmarshaler interface.
988 // The time is expected to be in RFC 3339 format.
989 func (t
*Time
) UnmarshalText(data
[]byte) error
{
990 // Fractional seconds are handled implicitly by Parse.
992 *t
, err
= Parse(RFC3339
, string(data
))
996 // Unix returns the local Time corresponding to the given Unix time,
997 // sec seconds and nsec nanoseconds since January 1, 1970 UTC.
998 // It is valid to pass nsec outside the range [0, 999999999].
999 // Not all sec values have a corresponding time value. One such
1000 // value is 1<<63-1 (the largest int64 value).
1001 func Unix(sec
int64, nsec
int64) Time
{
1002 if nsec
< 0 || nsec
>= 1e9
{
1011 return Time
{sec
+ unixToInternal
, int32(nsec
), Local
}
1014 func isLeap(year
int) bool {
1015 return year%4
== 0 && (year%100
!= 0 || year%400
== 0)
1018 // norm returns nhi, nlo such that
1019 // hi * base + lo == nhi * base + nlo
1021 func norm(hi
, lo
, base
int) (nhi
, nlo
int) {
1023 n
:= (-lo
-1)/base
+ 1
1035 // Date returns the Time corresponding to
1036 // yyyy-mm-dd hh:mm:ss + nsec nanoseconds
1037 // in the appropriate zone for that time in the given location.
1039 // The month, day, hour, min, sec, and nsec values may be outside
1040 // their usual ranges and will be normalized during the conversion.
1041 // For example, October 32 converts to November 1.
1043 // A daylight savings time transition skips or repeats times.
1044 // For example, in the United States, March 13, 2011 2:15am never occurred,
1045 // while November 6, 2011 1:15am occurred twice. In such cases, the
1046 // choice of time zone, and therefore the time, is not well-defined.
1047 // Date returns a time that is correct in one of the two zones involved
1048 // in the transition, but it does not guarantee which.
1050 // Date panics if loc is nil.
1051 func Date(year
int, month Month
, day
, hour
, min
, sec
, nsec
int, loc
*Location
) Time
{
1053 panic("time: missing Location in call to Date")
1056 // Normalize month, overflowing into year.
1058 year
, m
= norm(year
, m
, 12)
1059 month
= Month(m
) + 1
1061 // Normalize nsec, sec, min, hour, overflowing into day.
1062 sec
, nsec
= norm(sec
, nsec
, 1e9
)
1063 min
, sec
= norm(min
, sec
, 60)
1064 hour
, min
= norm(hour
, min
, 60)
1065 day
, hour
= norm(day
, hour
, 24)
1067 y
:= uint64(int64(year
) - absoluteZeroYear
)
1069 // Compute days since the absolute epoch.
1071 // Add in days from 400-year cycles.
1074 d
:= daysPer400Years
* n
1076 // Add in 100-year cycles.
1079 d
+= daysPer100Years
* n
1081 // Add in 4-year cycles.
1084 d
+= daysPer4Years
* n
1086 // Add in non-leap years.
1090 // Add in days before this month.
1091 d
+= uint64(daysBefore
[month
-1])
1092 if isLeap(year
) && month
>= March
{
1096 // Add in days before today.
1097 d
+= uint64(day
- 1)
1099 // Add in time elapsed today.
1100 abs
:= d
* secondsPerDay
1101 abs
+= uint64(hour
*secondsPerHour
+ min
*secondsPerMinute
+ sec
)
1103 unix
:= int64(abs
) + (absoluteToInternal
+ internalToUnix
)
1105 // Look for zone offset for t, so we can adjust to UTC.
1106 // The lookup function expects UTC, so we pass t in the
1107 // hope that it will not be too close to a zone transition,
1108 // and then adjust if it is.
1109 _
, offset
, _
, start
, end
:= loc
.lookup(unix
)
1111 switch utc
:= unix
- int64(offset
); {
1113 _
, offset
, _
, _
, _
= loc
.lookup(start
- 1)
1115 _
, offset
, _
, _
, _
= loc
.lookup(end
)
1117 unix
-= int64(offset
)
1120 t
:= Time
{unix
+ unixToInternal
, int32(nsec
), nil}
1125 // Truncate returns the result of rounding t down to a multiple of d (since the zero time).
1126 // If d <= 0, Truncate returns t unchanged.
1128 // Truncate operates on the time as an absolute duration since the
1129 // zero time; it does not operate on the presentation form of the
1130 // time. Thus, Truncate(Hour) may return a time with a non-zero
1131 // minute, depending on the time's Location.
1132 func (t Time
) Truncate(d Duration
) Time
{
1140 // Round returns the result of rounding t to the nearest multiple of d (since the zero time).
1141 // The rounding behavior for halfway values is to round up.
1142 // If d <= 0, Round returns t unchanged.
1144 // Round operates on the time as an absolute duration since the
1145 // zero time; it does not operate on the presentation form of the
1146 // time. Thus, Round(Hour) may return a time with a non-zero
1147 // minute, depending on the time's Location.
1148 func (t Time
) Round(d Duration
) Time
{
1159 // div divides t by d and returns the quotient parity and remainder.
1160 // We don't use the quotient parity anymore (round half up instead of round to even)
1161 // but it's still here in case we change our minds.
1162 func div(t Time
, d Duration
) (qmod2
int, r Duration
) {
1166 // Operate on absolute value.
1172 t
.sec
-- // t.sec >= 1 before the -- so safe
1177 // Special case: 2d divides 1 second.
1178 case d
< Second
&& Second
%(d
+d
) == 0:
1179 qmod2
= int(nsec
/int32(d
)) & 1
1180 r
= Duration(nsec
% int32(d
))
1182 // Special case: d is a multiple of 1 second.
1184 d1
:= int64(d
/ Second
)
1185 qmod2
= int(t
.sec
/d1
) & 1
1186 r
= Duration(t
.sec%d
1)*Second
+ Duration(nsec
)
1189 // This could be faster if more cleverness were applied,
1190 // but it's really only here to avoid special case restrictions in the API.
1191 // No one will care about these cases.
1193 // Compute nanoseconds as 128-bit number.
1194 sec
:= uint64(t
.sec
)
1195 tmp
:= (sec
>> 32) * 1e9
1198 tmp
= (sec
& 0xFFFFFFFF) * 1e9
1199 u0x
, u0
:= u0
, u0
+tmp
1203 u0x
, u0
= u0
, u0
+uint64(nsec
)
1208 // Compute remainder by subtracting r<<k for decreasing k.
1209 // Quotient parity is whether we subtract on last round.
1217 if u1
> d1 || u1
== d1
&& u0
>= d0
{
1226 if d1
== 0 && d0
== uint64(d
) {
1230 d0 |
= (d1
& 1) << 63
1237 // If input was negative and not an exact multiple of d, we computed q, r such that
1239 // But the right answers are given by -(q-1), d-r:
1242 // -(q-1)*d + (d - r) = t