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.
12 // A Time represents an instant in time with nanosecond precision.
14 // Programs using times should typically store and pass them as values,
15 // not pointers. That is, time variables and struct fields should be of
16 // type time.Time, not *time.Time. A Time value can be used by
17 // multiple goroutines simultaneously.
19 // Time instants can be compared using the Before, After, and Equal methods.
20 // The Sub method subtracts two instants, producing a Duration.
21 // The Add method adds a Time and a Duration, producing a Time.
23 // The zero value of type Time is January 1, year 1, 00:00:00.000000000 UTC.
24 // As this time is unlikely to come up in practice, the IsZero method gives
25 // a simple way of detecting a time that has not been initialized explicitly.
27 // Each Time has associated with it a Location, consulted when computing the
28 // presentation form of the time, such as in the Format, Hour, and Year methods.
29 // The methods Local, UTC, and In return a Time with a specific location.
30 // Changing the location in this way changes only the presentation; it does not
31 // change the instant in time being denoted and therefore does not affect the
32 // computations described in earlier paragraphs.
35 // sec gives the number of seconds elapsed since
36 // January 1, year 1 00:00:00 UTC.
39 // nsec specifies a non-negative nanosecond
40 // offset within the second named by Seconds.
41 // It must be in the range [0, 999999999].
43 // It is declared as uintptr instead of int32 or uint32
44 // to avoid garbage collector aliasing in the case where
45 // on a 64-bit system the int32 or uint32 field is written
46 // over the low half of a pointer, creating another pointer.
47 // TODO(rsc): When the garbage collector is completely
48 // precise, change back to int32.
51 // loc specifies the Location that should be used to
52 // determine the minute, hour, month, day, and year
53 // that correspond to this Time.
54 // Only the zero Time has a nil Location.
55 // In that case it is interpreted to mean UTC.
59 // After reports whether the time instant t is after u.
60 func (t Time
) After(u Time
) bool {
61 return t
.sec
> u
.sec || t
.sec
== u
.sec
&& t
.nsec
> u
.nsec
64 // Before reports whether the time instant t is before u.
65 func (t Time
) Before(u Time
) bool {
66 return t
.sec
< u
.sec || t
.sec
== u
.sec
&& t
.nsec
< u
.nsec
69 // Equal reports whether t and u represent the same time instant.
70 // Two times can be equal even if they are in different locations.
71 // For example, 6:00 +0200 CEST and 4:00 UTC are Equal.
72 // This comparison is different from using t == u, which also compares
74 func (t Time
) Equal(u Time
) bool {
75 return t
.sec
== u
.sec
&& t
.nsec
== u
.nsec
78 // A Month specifies a month of the year (January = 1, ...).
82 January Month
= 1 + iota
96 var months
= [...]string{
111 // String returns the English name of the month ("January", "February", ...).
112 func (m Month
) String() string { return months
[m
-1] }
114 // A Weekday specifies a day of the week (Sunday = 0, ...).
118 Sunday Weekday
= iota
127 var days
= [...]string{
137 // String returns the English name of the day ("Sunday", "Monday", ...).
138 func (d Weekday
) String() string { return days
[d
] }
140 // Computations on time.
142 // The zero value for a Time is defined to be
143 // January 1, year 1, 00:00:00.000000000 UTC
144 // which (1) looks like a zero, or as close as you can get in a date
145 // (1-1-1 00:00:00 UTC), (2) is unlikely enough to arise in practice to
146 // be a suitable "not set" sentinel, unlike Jan 1 1970, and (3) has a
147 // non-negative year even in time zones west of UTC, unlike 1-1-0
148 // 00:00:00 UTC, which would be 12-31-(-1) 19:00:00 in New York.
150 // The zero Time value does not force a specific epoch for the time
151 // representation. For example, to use the Unix epoch internally, we
152 // could define that to distinguish a zero value from Jan 1 1970, that
153 // time would be represented by sec=-1, nsec=1e9. However, it does
154 // suggest a representation, namely using 1-1-1 00:00:00 UTC as the
155 // epoch, and that's what we do.
157 // The Add and Sub computations are oblivious to the choice of epoch.
159 // The presentation computations - year, month, minute, and so on - all
160 // rely heavily on division and modulus by positive constants. For
161 // calendrical calculations we want these divisions to round down, even
162 // for negative values, so that the remainder is always positive, but
163 // Go's division (like most hardware division instructions) rounds to
164 // zero. We can still do those computations and then adjust the result
165 // for a negative numerator, but it's annoying to write the adjustment
166 // over and over. Instead, we can change to a different epoch so long
167 // ago that all the times we care about will be positive, and then round
168 // to zero and round down coincide. These presentation routines already
169 // have to add the zone offset, so adding the translation to the
170 // alternate epoch is cheap. For example, having a non-negative time t
171 // means that we can write
184 // The calendar runs on an exact 400 year cycle: a 400-year calendar
185 // printed for 1970-2469 will apply as well to 2470-2869. Even the days
186 // of the week match up. It simplifies the computations to choose the
187 // cycle boundaries so that the exceptional years are always delayed as
188 // long as possible. That means choosing a year equal to 1 mod 400, so
189 // that the first leap year is the 4th year, the first missed leap year
190 // is the 100th year, and the missed missed leap year is the 400th year.
191 // So we'd prefer instead to print a calendar for 2001-2400 and reuse it
194 // Finally, it's convenient if the delta between the Unix epoch and
195 // long-ago epoch is representable by an int64 constant.
197 // These three considerations—choose an epoch as early as possible, that
198 // uses a year equal to 1 mod 400, and that is no more than 2⁶³ seconds
199 // earlier than 1970—bring us to the year -292277022399. We refer to
200 // this year as the absolute zero year, and to times measured as a uint64
201 // seconds since this year as absolute times.
203 // Times measured as an int64 seconds since the year 1—the representation
204 // used for Time's sec field—are called internal times.
206 // Times measured as an int64 seconds since the year 1970 are called Unix
209 // It is tempting to just use the year 1 as the absolute epoch, defining
210 // that the routines are only valid for years >= 1. However, the
211 // routines would then be invalid when displaying the epoch in time zones
212 // west of UTC, since it is year 0. It doesn't seem tenable to say that
213 // printing the zero time correctly isn't supported in half the time
214 // zones. By comparison, it's reasonable to mishandle some times in
215 // the year -292277022399.
217 // All this is opaque to clients of the API and can be changed if a
218 // better implementation presents itself.
221 // The unsigned zero year for internal calculations.
222 // Must be 1 mod 400, and times before it will not compute correctly,
223 // but otherwise can be changed at will.
224 absoluteZeroYear
= -292277022399
226 // The year of the zero Time.
227 // Assumed by the unixToInternal computation below.
230 // The year of the zero Unix time.
233 // Offsets to convert between internal and absolute or Unix times.
234 absoluteToInternal
int64 = (absoluteZeroYear
- internalYear
) * 365.2425 * secondsPerDay
235 internalToAbsolute
= -absoluteToInternal
237 unixToInternal
int64 = (1969*365 + 1969/4 - 1969/100 + 1969/400) * secondsPerDay
238 internalToUnix
int64 = -unixToInternal
241 // IsZero reports whether t represents the zero time instant,
242 // January 1, year 1, 00:00:00 UTC.
243 func (t Time
) IsZero() bool {
244 return t
.sec
== 0 && t
.nsec
== 0
247 // abs returns the time t as an absolute time, adjusted by the zone offset.
248 // It is called when computing a presentation property like Month or Hour.
249 func (t Time
) abs() uint64 {
251 // Avoid function calls when possible.
252 if l
== nil || l
== &localLoc
{
255 sec
:= t
.sec
+ internalToUnix
257 if l
.cacheZone
!= nil && l
.cacheStart
<= sec
&& sec
< l
.cacheEnd
{
258 sec
+= int64(l
.cacheZone
.offset
)
260 _
, offset
, _
, _
, _
:= l
.lookup(sec
)
264 return uint64(sec
+ (unixToInternal
+ internalToAbsolute
))
267 // locabs is a combination of the Zone and abs methods,
268 // extracting both return values from a single zone lookup.
269 func (t Time
) locabs() (name
string, offset
int, abs
uint64) {
271 if l
== nil || l
== &localLoc
{
274 // Avoid function call if we hit the local time cache.
275 sec
:= t
.sec
+ internalToUnix
277 if l
.cacheZone
!= nil && l
.cacheStart
<= sec
&& sec
< l
.cacheEnd
{
278 name
= l
.cacheZone
.name
279 offset
= l
.cacheZone
.offset
281 name
, offset
, _
, _
, _
= l
.lookup(sec
)
287 abs
= uint64(sec
+ (unixToInternal
+ internalToAbsolute
))
291 // Date returns the year, month, and day in which t occurs.
292 func (t Time
) Date() (year
int, month Month
, day
int) {
293 year
, month
, day
, _
= t
.date(true)
297 // Year returns the year in which t occurs.
298 func (t Time
) Year() int {
299 year
, _
, _
, _
:= t
.date(false)
303 // Month returns the month of the year specified by t.
304 func (t Time
) Month() Month
{
305 _
, month
, _
, _
:= t
.date(true)
309 // Day returns the day of the month specified by t.
310 func (t Time
) Day() int {
311 _
, _
, day
, _
:= t
.date(true)
315 // Weekday returns the day of the week specified by t.
316 func (t Time
) Weekday() Weekday
{
317 return absWeekday(t
.abs())
320 // absWeekday is like Weekday but operates on an absolute time.
321 func absWeekday(abs
uint64) Weekday
{
322 // January 1 of the absolute year, like January 1 of 2001, was a Monday.
323 sec
:= (abs
+ uint64(Monday
)*secondsPerDay
) % secondsPerWeek
324 return Weekday(int(sec
) / secondsPerDay
)
327 // ISOWeek returns the ISO 8601 year and week number in which t occurs.
328 // Week ranges from 1 to 53. Jan 01 to Jan 03 of year n might belong to
329 // week 52 or 53 of year n-1, and Dec 29 to Dec 31 might belong to week 1
331 func (t Time
) ISOWeek() (year
, week
int) {
332 year
, month
, day
, yday
:= t
.date(true)
333 wday
:= int(t
.Weekday()+6) % 7 // weekday but Monday = 0.
344 // Calculate week as number of Mondays in year up to
345 // and including today, plus 1 because the first week is week 0.
346 // Putting the + 1 inside the numerator as a + 7 keeps the
347 // numerator from being negative, which would cause it to
348 // round incorrectly.
349 week
= (yday
- wday
+ 7) / 7
351 // The week number is now correct under the assumption
352 // that the first Monday of the year is in week 1.
353 // If Jan 1 is a Tuesday, Wednesday, or Thursday, the first Monday
354 // is actually in week 2.
355 jan1wday
:= (wday
- yday
+ 7*53) % 7
356 if Tue
<= jan1wday
&& jan1wday
<= Thu
{
360 // If the week number is still 0, we're in early January but in
361 // the last week of last year.
365 // A year has 53 weeks when Jan 1 or Dec 31 is a Thursday,
366 // meaning Jan 1 of the next year is a Friday
367 // or it was a leap year and Jan 1 of the next year is a Saturday.
368 if jan1wday
== Fri ||
(jan1wday
== Sat
&& isLeap(year
)) {
373 // December 29 to 31 are in week 1 of next year if
374 // they are after the last Thursday of the year and
375 // December 31 is a Monday, Tuesday, or Wednesday.
376 if month
== December
&& day
>= 29 && wday
< Thu
{
377 if dec31wday
:= (wday
+ 31 - day
) % 7; Mon
<= dec31wday
&& dec31wday
<= Wed
{
386 // Clock returns the hour, minute, and second within the day specified by t.
387 func (t Time
) Clock() (hour
, min
, sec
int) {
388 return absClock(t
.abs())
391 // absClock is like clock but operates on an absolute time.
392 func absClock(abs
uint64) (hour
, min
, sec
int) {
393 sec
= int(abs
% secondsPerDay
)
394 hour
= sec
/ secondsPerHour
395 sec
-= hour
* secondsPerHour
396 min
= sec
/ secondsPerMinute
397 sec
-= min
* secondsPerMinute
401 // Hour returns the hour within the day specified by t, in the range [0, 23].
402 func (t Time
) Hour() int {
403 return int(t
.abs()%secondsPerDay
) / secondsPerHour
406 // Minute returns the minute offset within the hour specified by t, in the range [0, 59].
407 func (t Time
) Minute() int {
408 return int(t
.abs()%secondsPerHour
) / secondsPerMinute
411 // Second returns the second offset within the minute specified by t, in the range [0, 59].
412 func (t Time
) Second() int {
413 return int(t
.abs() % secondsPerMinute
)
416 // Nanosecond returns the nanosecond offset within the second specified by t,
417 // in the range [0, 999999999].
418 func (t Time
) Nanosecond() int {
422 // YearDay returns the day of the year specified by t, in the range [1,365] for non-leap years,
423 // and [1,366] in leap years.
424 func (t Time
) YearDay() int {
425 _
, _
, _
, yday
:= t
.date(false)
429 // A Duration represents the elapsed time between two instants
430 // as an int64 nanosecond count. The representation limits the
431 // largest representable duration to approximately 290 years.
435 minDuration Duration
= -1 << 63
436 maxDuration Duration
= 1<<63 - 1
439 // Common durations. There is no definition for units of Day or larger
440 // to avoid confusion across daylight savings time zone transitions.
442 // To count the number of units in a Duration, divide:
443 // second := time.Second
444 // fmt.Print(int64(second/time.Millisecond)) // prints 1000
446 // To convert an integer number of units to a Duration, multiply:
448 // fmt.Print(time.Duration(seconds)*time.Second) // prints 10s
451 Nanosecond Duration
= 1
452 Microsecond
= 1000 * Nanosecond
453 Millisecond
= 1000 * Microsecond
454 Second
= 1000 * Millisecond
459 // String returns a string representing the duration in the form "72h3m0.5s".
460 // Leading zero units are omitted. As a special case, durations less than one
461 // second format use a smaller unit (milli-, micro-, or nanoseconds) to ensure
462 // that the leading digit is non-zero. The zero duration formats as 0,
464 func (d Duration
) String() string {
465 // Largest time is 2540400h10m10.000000000s
475 if u
< uint64(Second
) {
476 // Special case: if duration is smaller than a second,
477 // use smaller units, like 1.2ms
485 case u
< uint64(Microsecond
):
489 case u
< uint64(Millisecond
):
490 // print microseconds
494 // print milliseconds
501 w
, u
= fmtFrac(buf
[:w
], u
, prec
)
502 w
= fmtInt(buf
[:w
], u
)
507 w
, u
= fmtFrac(buf
[:w
], u
, 9)
509 // u is now integer seconds
510 w
= fmtInt(buf
[:w
], u%60
)
513 // u is now integer minutes
517 w
= fmtInt(buf
[:w
], u%60
)
520 // u is now integer hours
521 // Stop at hours because days can be different lengths.
525 w
= fmtInt(buf
[:w
], u
)
535 return string(buf
[w
:])
538 // fmtFrac formats the fraction of v/10**prec (e.g., ".12345") into the
539 // tail of buf, omitting trailing zeros. it omits the decimal
540 // point too when the fraction is 0. It returns the index where the
541 // output bytes begin and the value v/10**prec.
542 func fmtFrac(buf
[]byte, v
uint64, prec
int) (nw
int, nv
uint64) {
543 // Omit trailing zeros up to and including decimal point.
546 for i
:= 0; i
< prec
; i
++ {
548 print = print || digit
!= 0
551 buf
[w
] = byte(digit
) + '0'
562 // fmtInt formats v into the tail of buf.
563 // It returns the index where the output begins.
564 func fmtInt(buf
[]byte, v
uint64) int {
572 buf
[w
] = byte(v%10
) + '0'
579 // Nanoseconds returns the duration as an integer nanosecond count.
580 func (d Duration
) Nanoseconds() int64 { return int64(d
) }
582 // These methods return float64 because the dominant
583 // use case is for printing a floating point number like 1.5s, and
584 // a truncation to integer would make them not useful in those cases.
585 // Splitting the integer and fraction ourselves guarantees that
586 // converting the returned float64 to an integer rounds the same
587 // way that a pure integer conversion would have, even in cases
588 // where, say, float64(d.Nanoseconds())/1e9 would have rounded
591 // Seconds returns the duration as a floating point number of seconds.
592 func (d Duration
) Seconds() float64 {
595 return float64(sec
) + float64(nsec
)*1e-9
598 // Minutes returns the duration as a floating point number of minutes.
599 func (d Duration
) Minutes() float64 {
602 return float64(min
) + float64(nsec
)*(1e-9/60)
605 // Hours returns the duration as a floating point number of hours.
606 func (d Duration
) Hours() float64 {
609 return float64(hour
) + float64(nsec
)*(1e-9/60/60)
612 // Add returns the time t+d.
613 func (t Time
) Add(d Duration
) Time
{
614 t
.sec
+= int64(d
/ 1e9
)
615 nsec
:= int32(t
.nsec
) + int32(d%1e9
)
623 t
.nsec
= uintptr(nsec
)
627 // Sub returns the duration t-u. If the result exceeds the maximum (or minimum)
628 // value that can be stored in a Duration, the maximum (or minimum) duration
630 // To compute t-d for a duration d, use t.Add(-d).
631 func (t Time
) Sub(u Time
) Duration
{
632 d
:= Duration(t
.sec
-u
.sec
)*Second
+ Duration(int32(t
.nsec
)-int32(u
.nsec
))
633 // Check for overflow or underflow.
635 case u
.Add(d
).Equal(t
):
636 return d
// d is correct
638 return minDuration
// t - u is negative out of range
640 return maxDuration
// t - u is positive out of range
644 // Since returns the time elapsed since t.
645 // It is shorthand for time.Now().Sub(t).
646 func Since(t Time
) Duration
{
650 // AddDate returns the time corresponding to adding the
651 // given number of years, months, and days to t.
652 // For example, AddDate(-1, 2, 3) applied to January 1, 2011
653 // returns March 4, 2010.
655 // AddDate normalizes its result in the same way that Date does,
656 // so, for example, adding one month to October 31 yields
657 // December 1, the normalized form for November 31.
658 func (t Time
) AddDate(years
int, months
int, days
int) Time
{
659 year
, month
, day
:= t
.Date()
660 hour
, min
, sec
:= t
.Clock()
661 return Date(year
+years
, month
+Month(months
), day
+days
, hour
, min
, sec
, int(t
.nsec
), t
.loc
)
665 secondsPerMinute
= 60
666 secondsPerHour
= 60 * 60
667 secondsPerDay
= 24 * secondsPerHour
668 secondsPerWeek
= 7 * secondsPerDay
669 daysPer400Years
= 365*400 + 97
670 daysPer100Years
= 365*100 + 24
671 daysPer4Years
= 365*4 + 1
674 // date computes the year, day of year, and when full=true,
675 // the month and day in which t occurs.
676 func (t Time
) date(full
bool) (year
int, month Month
, day
int, yday
int) {
677 return absDate(t
.abs(), full
)
680 // absDate is like date but operates on an absolute time.
681 func absDate(abs
uint64, full
bool) (year
int, month Month
, day
int, yday
int) {
682 // Split into time and day.
683 d
:= abs
/ secondsPerDay
685 // Account for 400 year cycles.
686 n
:= d
/ daysPer400Years
688 d
-= daysPer400Years
* n
690 // Cut off 100-year cycles.
691 // The last cycle has one extra leap year, so on the last day
692 // of that year, day / daysPer100Years will be 4 instead of 3.
693 // Cut it back down to 3 by subtracting n>>2.
694 n
= d
/ daysPer100Years
697 d
-= daysPer100Years
* n
699 // Cut off 4-year cycles.
700 // The last cycle has a missing leap year, which does not
701 // affect the computation.
702 n
= d
/ daysPer4Years
704 d
-= daysPer4Years
* n
706 // Cut off years within a 4-year cycle.
707 // The last year is a leap year, so on the last day of that year,
708 // day / 365 will be 4 instead of 3. Cut it back down to 3
709 // by subtracting n>>2.
715 year
= int(int64(y
) + absoluteZeroYear
)
727 // After leap day; pretend it wasn't there.
737 // Estimate month on assumption that every month has 31 days.
738 // The estimate may be too low by at most one month, so adjust.
739 month
= Month(day
/ 31)
740 end
:= int(daysBefore
[month
+1])
746 begin
= int(daysBefore
[month
])
749 month
++ // because January is 1
750 day
= day
- begin
+ 1
754 // daysBefore[m] counts the number of days in a non-leap year
755 // before month m begins. There is an entry for m=12, counting
756 // the number of days before January of next year (365).
757 var daysBefore
= [...]int32{
763 31 + 28 + 31 + 30 + 31,
764 31 + 28 + 31 + 30 + 31 + 30,
765 31 + 28 + 31 + 30 + 31 + 30 + 31,
766 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31,
767 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30,
768 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31,
769 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30,
770 31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30 + 31,
773 func daysIn(m Month
, year
int) int {
774 if m
== February
&& isLeap(year
) {
777 return int(daysBefore
[m
] - daysBefore
[m
-1])
780 // Provided by package runtime.
781 func now() (sec
int64, nsec
int32)
783 // Now returns the current local time.
786 return Time
{sec
+ unixToInternal
, uintptr(nsec
), Local
}
789 // UTC returns t with the location set to UTC.
790 func (t Time
) UTC() Time
{
795 // Local returns t with the location set to local time.
796 func (t Time
) Local() Time
{
801 // In returns t with the location information set to loc.
803 // In panics if loc is nil.
804 func (t Time
) In(loc
*Location
) Time
{
806 panic("time: missing Location in call to Time.In")
812 // Location returns the time zone information associated with t.
813 func (t Time
) Location() *Location
{
821 // Zone computes the time zone in effect at time t, returning the abbreviated
822 // name of the zone (such as "CET") and its offset in seconds east of UTC.
823 func (t Time
) Zone() (name
string, offset
int) {
824 name
, offset
, _
, _
, _
= t
.loc
.lookup(t
.sec
+ internalToUnix
)
828 // Unix returns t as a Unix time, the number of seconds elapsed
829 // since January 1, 1970 UTC.
830 func (t Time
) Unix() int64 {
831 return t
.sec
+ internalToUnix
834 // UnixNano returns t as a Unix time, the number of nanoseconds elapsed
835 // since January 1, 1970 UTC. The result is undefined if the Unix time
836 // in nanoseconds cannot be represented by an int64. Note that this
837 // means the result of calling UnixNano on the zero Time is undefined.
838 func (t Time
) UnixNano() int64 {
839 return (t
.sec
+internalToUnix
)*1e9
+ int64(t
.nsec
)
842 const timeBinaryVersion
byte = 1
844 // MarshalBinary implements the encoding.BinaryMarshaler interface.
845 func (t Time
) MarshalBinary() ([]byte, error
) {
846 var offsetMin
int16 // minutes east of UTC. -1 is UTC.
848 if t
.Location() == &utcLoc
{
851 _
, offset
:= t
.Zone()
853 return nil, errors
.New("Time.MarshalBinary: zone offset has fractional minute")
856 if offset
< -32768 || offset
== -1 || offset
> 32767 {
857 return nil, errors
.New("Time.MarshalBinary: unexpected zone offset")
859 offsetMin
= int16(offset
)
863 timeBinaryVersion
, // byte 0 : version
864 byte(t
.sec
>> 56), // bytes 1-8: seconds
872 byte(t
.nsec
>> 24), // bytes 9-12: nanoseconds
876 byte(offsetMin
>> 8), // bytes 13-14: zone offset in minutes
883 // UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.
884 func (t
*Time
) UnmarshalBinary(data
[]byte) error
{
887 return errors
.New("Time.UnmarshalBinary: no data")
890 if buf
[0] != timeBinaryVersion
{
891 return errors
.New("Time.UnmarshalBinary: unsupported version")
894 if len(buf
) != /*version*/ 1+ /*sec*/ 8+ /*nsec*/ 4+ /*zone offset*/ 2 {
895 return errors
.New("Time.UnmarshalBinary: invalid length")
899 t
.sec
= int64(buf
[7]) |
int64(buf
[6])<<8 |
int64(buf
[5])<<16 |
int64(buf
[4])<<24 |
900 int64(buf
[3])<<32 |
int64(buf
[2])<<40 |
int64(buf
[1])<<48 |
int64(buf
[0])<<56
903 t
.nsec
= uintptr(int32(buf
[3]) |
int32(buf
[2])<<8 |
int32(buf
[1])<<16 |
int32(buf
[0])<<24)
906 offset
:= int(int16(buf
[1])|
int16(buf
[0])<<8) * 60
910 } else if _
, localoff
, _
, _
, _
:= Local
.lookup(t
.sec
+ internalToUnix
); offset
== localoff
{
913 t
.loc
= FixedZone("", offset
)
919 // TODO(rsc): Remove GobEncoder, GobDecoder, MarshalJSON, UnmarshalJSON in Go 2.
920 // The same semantics will be provided by the generic MarshalBinary, MarshalText,
921 // UnmarshalBinary, UnmarshalText.
923 // GobEncode implements the gob.GobEncoder interface.
924 func (t Time
) GobEncode() ([]byte, error
) {
925 return t
.MarshalBinary()
928 // GobDecode implements the gob.GobDecoder interface.
929 func (t
*Time
) GobDecode(data
[]byte) error
{
930 return t
.UnmarshalBinary(data
)
933 // MarshalJSON implements the json.Marshaler interface.
934 // The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
935 func (t Time
) MarshalJSON() ([]byte, error
) {
936 if y
:= t
.Year(); y
< 0 || y
>= 10000 {
937 return nil, errors
.New("Time.MarshalJSON: year outside of range [0,9999]")
939 return []byte(t
.Format(`"` + RFC3339Nano
+ `"`)), nil
942 // UnmarshalJSON implements the json.Unmarshaler interface.
943 // The time is expected to be a quoted string in RFC 3339 format.
944 func (t
*Time
) UnmarshalJSON(data
[]byte) (err error
) {
945 // Fractional seconds are handled implicitly by Parse.
946 *t
, err
= Parse(`"`+RFC3339
+`"`, string(data
))
950 // MarshalText implements the encoding.TextMarshaler interface.
951 // The time is formatted in RFC 3339 format, with sub-second precision added if present.
952 func (t Time
) MarshalText() ([]byte, error
) {
953 if y
:= t
.Year(); y
< 0 || y
>= 10000 {
954 return nil, errors
.New("Time.MarshalText: year outside of range [0,9999]")
956 return []byte(t
.Format(RFC3339Nano
)), nil
959 // UnmarshalText implements the encoding.TextUnmarshaler interface.
960 // The time is expected to be in RFC 3339 format.
961 func (t
*Time
) UnmarshalText(data
[]byte) (err error
) {
962 // Fractional seconds are handled implicitly by Parse.
963 *t
, err
= Parse(RFC3339
, string(data
))
967 // Unix returns the local Time corresponding to the given Unix time,
968 // sec seconds and nsec nanoseconds since January 1, 1970 UTC.
969 // It is valid to pass nsec outside the range [0, 999999999].
970 func Unix(sec
int64, nsec
int64) Time
{
971 if nsec
< 0 || nsec
>= 1e9
{
980 return Time
{sec
+ unixToInternal
, uintptr(nsec
), Local
}
983 func isLeap(year
int) bool {
984 return year%4
== 0 && (year%100
!= 0 || year%400
== 0)
987 // norm returns nhi, nlo such that
988 // hi * base + lo == nhi * base + nlo
990 func norm(hi
, lo
, base
int) (nhi
, nlo
int) {
992 n
:= (-lo
-1)/base
+ 1
1004 // Date returns the Time corresponding to
1005 // yyyy-mm-dd hh:mm:ss + nsec nanoseconds
1006 // in the appropriate zone for that time in the given location.
1008 // The month, day, hour, min, sec, and nsec values may be outside
1009 // their usual ranges and will be normalized during the conversion.
1010 // For example, October 32 converts to November 1.
1012 // A daylight savings time transition skips or repeats times.
1013 // For example, in the United States, March 13, 2011 2:15am never occurred,
1014 // while November 6, 2011 1:15am occurred twice. In such cases, the
1015 // choice of time zone, and therefore the time, is not well-defined.
1016 // Date returns a time that is correct in one of the two zones involved
1017 // in the transition, but it does not guarantee which.
1019 // Date panics if loc is nil.
1020 func Date(year
int, month Month
, day
, hour
, min
, sec
, nsec
int, loc
*Location
) Time
{
1022 panic("time: missing Location in call to Date")
1025 // Normalize month, overflowing into year.
1027 year
, m
= norm(year
, m
, 12)
1028 month
= Month(m
) + 1
1030 // Normalize nsec, sec, min, hour, overflowing into day.
1031 sec
, nsec
= norm(sec
, nsec
, 1e9
)
1032 min
, sec
= norm(min
, sec
, 60)
1033 hour
, min
= norm(hour
, min
, 60)
1034 day
, hour
= norm(day
, hour
, 24)
1036 y
:= uint64(int64(year
) - absoluteZeroYear
)
1038 // Compute days since the absolute epoch.
1040 // Add in days from 400-year cycles.
1043 d
:= daysPer400Years
* n
1045 // Add in 100-year cycles.
1048 d
+= daysPer100Years
* n
1050 // Add in 4-year cycles.
1053 d
+= daysPer4Years
* n
1055 // Add in non-leap years.
1059 // Add in days before this month.
1060 d
+= uint64(daysBefore
[month
-1])
1061 if isLeap(year
) && month
>= March
{
1065 // Add in days before today.
1066 d
+= uint64(day
- 1)
1068 // Add in time elapsed today.
1069 abs
:= d
* secondsPerDay
1070 abs
+= uint64(hour
*secondsPerHour
+ min
*secondsPerMinute
+ sec
)
1072 unix
:= int64(abs
) + (absoluteToInternal
+ internalToUnix
)
1074 // Look for zone offset for t, so we can adjust to UTC.
1075 // The lookup function expects UTC, so we pass t in the
1076 // hope that it will not be too close to a zone transition,
1077 // and then adjust if it is.
1078 _
, offset
, _
, start
, end
:= loc
.lookup(unix
)
1080 switch utc
:= unix
- int64(offset
); {
1082 _
, offset
, _
, _
, _
= loc
.lookup(start
- 1)
1084 _
, offset
, _
, _
, _
= loc
.lookup(end
)
1086 unix
-= int64(offset
)
1089 return Time
{unix
+ unixToInternal
, uintptr(nsec
), loc
}
1092 // Truncate returns the result of rounding t down to a multiple of d (since the zero time).
1093 // If d <= 0, Truncate returns t unchanged.
1094 func (t Time
) Truncate(d Duration
) Time
{
1102 // Round returns the result of rounding t to the nearest multiple of d (since the zero time).
1103 // The rounding behavior for halfway values is to round up.
1104 // If d <= 0, Round returns t unchanged.
1105 func (t Time
) Round(d Duration
) Time
{
1116 // div divides t by d and returns the quotient parity and remainder.
1117 // We don't use the quotient parity anymore (round half up instead of round to even)
1118 // but it's still here in case we change our minds.
1119 func div(t Time
, d Duration
) (qmod2
int, r Duration
) {
1121 nsec
:= int32(t
.nsec
)
1123 // Operate on absolute value.
1129 t
.sec
-- // t.sec >= 1 before the -- so safe
1134 // Special case: 2d divides 1 second.
1135 case d
< Second
&& Second
%(d
+d
) == 0:
1136 qmod2
= int(nsec
/int32(d
)) & 1
1137 r
= Duration(nsec
% int32(d
))
1139 // Special case: d is a multiple of 1 second.
1141 d1
:= int64(d
/ Second
)
1142 qmod2
= int(t
.sec
/d1
) & 1
1143 r
= Duration(t
.sec%d
1)*Second
+ Duration(nsec
)
1146 // This could be faster if more cleverness were applied,
1147 // but it's really only here to avoid special case restrictions in the API.
1148 // No one will care about these cases.
1150 // Compute nanoseconds as 128-bit number.
1151 sec
:= uint64(t
.sec
)
1152 tmp
:= (sec
>> 32) * 1e9
1155 tmp
= uint64(sec
&0xFFFFFFFF) * 1e9
1156 u0x
, u0
:= u0
, u0
+tmp
1160 u0x
, u0
= u0
, u0
+uint64(nsec
)
1165 // Compute remainder by subtracting r<<k for decreasing k.
1166 // Quotient parity is whether we subtract on last round.
1174 if u1
> d1 || u1
== d1
&& u0
>= d0
{
1183 if d1
== 0 && d0
== uint64(d
) {
1187 d0 |
= (d1
& 1) << 63
1194 // If input was negative and not an exact multiple of d, we computed q, r such that
1196 // But the right answers are given by -(q-1), d-r:
1199 // -(q-1)*d + (d - r) = t