code review 5392041: time: new Time, Duration, ZoneInfo types

src/pkg/time/time.go

 // Copyright 2009 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 // Package time provides functionality for measuring and displaying time.
 //
 // The calendrical calculations always assume a Gregorian calendar.
 package time
 
 // A Time represents an instant in time with nanosecond precision.
 //
 // Programs using times should typically store and pass them as values,
 // not pointers.  That is, time variables and struct fields should be of
 // type time.Time, not *time.Time.
 //
 // Time instants can be compared using the Before, After, and Equal methods.
 // The Sub method subtracts two instants, producing a Duration.
 // The Add method adds a Time and a Duration, producing a Time.
 //
 // The zero value of type Time is January 1, year 1, 00:00:00.000000000 UTC.
-// As this time is unlikely to come up in practice, the IsZero method
-// gives a simple way of detecting an uninitialized time.
+// As this time is unlikely to come up in practice, the IsZero method gives
+// a simple way of detecting a time that has not been initialized explicitly.
 //
 // Each Time has associated with it a Location, consulted when computing the
 // presentation form of the time, such as in the Format, Hour, and Year methods.
-// The methods Local, UTC, and In return a Time with a specific zone.
-// Changing the zone in this way changes only the presentation; it does not
+// The methods Local, UTC, and In return a Time with a specific location.
+// Changing the location in this way changes only the presentation; it does not
 // change the instant in time being denoted and therefore does not affect the
 // computations described in earlier paragraphs.
 //
 type Time struct {
         // sec gives the number of seconds elapsed since
         // January 1, year 1 00:00:00 UTC.
         sec int64
 
         // nsec specifies a non-negative nanosecond
         // offset within the second named by Seconds.
@@ skipping 12 matching lines @@
 func (t Time) After(u Time) bool {
         return t.sec > u.sec || t.sec == u.sec && t.nsec > u.nsec
 }
 
 // Before reports whether the time instant t is before u.
 func (t Time) Before(u Time) bool {
         return t.sec < u.sec || t.sec == u.sec && t.nsec < u.nsec
 }
 
 // Equal reports whether t and u represent the same time instant.
-// Two times can be equal even if they are in different time zones.
-// For example, 1:00 +0200 CEST and 2:00 +0100 CET are Equal.
+// Two times can be equal even if they are in different locations.
+// For example, 6:00 +0200 CEST and 4:00 UTC are Equal.
 // This comparison is different from using t == u, which also compares
 // the locations.
 func (t Time) Equal(u Time) bool {
         return t.sec == u.sec && t.nsec == u.nsec
 }
 
 // A Month specifies a month of the year (January = 1, ...).
 type Month int
 
 const (
         January Month = 1 + iota
         February
         March
         April
         May
         June
         July
         August
         September
         October
         November
         December
 )
 
-var months = []string{
+var months = [...]string{
         "January",
         "February",
         "March",
         "April",
         "May",
         "June",
         "July",
         "August",
         "September",
         "October",
@@ skipping 10 matching lines @@
 const (
         Sunday Weekday = iota
         Monday
         Tuesday
         Wednesday
         Thursday
         Friday
         Saturday
 )
 
-var days = []string{
+var days = [...]string{
         "Sunday",
         "Monday",
         "Tuesday",
         "Wednesday",
         "Thursday",
         "Friday",
         "Saturday",
 }
 
 // String returns the English name of the day ("Sunday", "Monday", ...).
@@ skipping 112 matching lines @@
         l := t.loc
         if l == nil {
                 l = &utcLoc
         }
         // Avoid function call if we hit the local time cache.
         sec := t.sec + internalToUnix
         if l != &utcLoc {
                 if l.cacheZone != nil && l.cacheStart <= sec && sec < l.cacheEnd {
                         sec += int64(l.cacheZone.offset)
                 } else {
-                        _, offset, _, _, _ := l.Lookup(sec)
+                        _, offset, _, _, _ := l.lookup(sec)
                         sec += int64(offset)
                 }
         }
         return uint64(sec + (unixToInternal + internalToAbsolute))
 }
 
 // Date returns the year, month, and day in which t occurs.
 func (t Time) Date() (year int, month Month, day int) {
         year, month, day, _ = t.date(true)
         return
@@ skipping 112 matching lines @@
 // in the range [0, 999999999].
 func (t Time) Nanosecond() int {
         return int(t.nsec)
 }
 
 // A Duration represents the elapsed time between two instants
 // as an int64 nanosecond count.  The representation limits the
 // largest representable duration to approximately 290 years.
 type Duration int64
 
+// Common durations.  There is no definition for units of Day or larger
+// to avoid confusion across daylight savings time zone transitions.
 const (
         Nanosecond  Duration = 1
         Microsecond          = 1000 * Nanosecond
         Millisecond          = 1000 * Microsecond
         Second               = 1000 * Millisecond
         Minute               = 60 * Second
         Hour                 = 60 * Minute
 )
 
 // Duration returns a string representing the duration in the form "72h3m0.5s".
 // Leading zero units are omitted.  As a special case, durations less than one
-// second format use a smaller unit—milli-, micro-, or nanoseconds—to ensure
+// second format use a smaller unit (milli-, micro-, or nanoseconds) to ensure
 // that the leading digit is non-zero.  The zero duration formats as 0,
 // with no unit.
 func (d Duration) String() string {
         // Largest time is 2540400h10m10.000000000s
         var buf [32]byte
         w := len(buf)
 
         u := uint64(d)
         neg := d < 0
         if neg {
@@ skipping 80 matching lines @@
                 }
                 v /= 10
         }
         if print {
                 w--
                 buf[w] = '.'
         }
         return w, v
 }
 
-// fmtInt formats v into the tail of buf[:w].
+// fmtInt formats v into the tail of buf.
 // It returns the index where the output begins.
 func fmtInt(buf []byte, v uint64) int {
         w := len(buf)
         if v == 0 {
                 w--
                 buf[w] = '0'
         } else {
                 for v > 0 {
                         w--
                         buf[w] = byte(v%10) + '0'
                         v /= 10
                 }
         }
         return w
 }
 
 // Nanoseconds returns the duration as an integer nanosecond count.
 func (d Duration) Nanoseconds() int64 { return int64(d) }
 
-// REVIEW NOTE: The use of float64 for these methods was not
-// my first choice, but in practice everyone who would have called
-// Seconds was instead writing float64(d.Nanoseconds())/1e9 in
-// order to have sub-second precision.

[r, 2011/11/18 17:37:37]

delete at least the phrase "REVIEW NOTE" and remove yourself from the comment.
there's information here worth keeping, so don't delete the whole thing

[rsc, 2011/11/18 18:21:36]

Done:

// These methods return float64 because the dominant
// use case is for printing a floating point number like 1.5s, and
// a truncation to integer would make them not useful in those cases.
// Splitting the integer and fraction ourselves guarantees that
// converting the returned float64 to an integer rounds the same
// way that a pure integer conversion would have, even in cases
// where, say, float64(d.Nanoseconds())/1e9 would have rounded
// differently.

and updated Minutes and Hours to do that too.

+// These methods return float64 because the dominant
+// use case is for printing a floating point number like 1.5s, and
+// a truncation to integer would make them not useful in those cases.
+// Splitting the integer and fraction ourselves guarantees that
+// converting the returned float64 to an integer rounds the same
+// way that a pure integer conversion would have, even in cases
+// where, say, float64(d.Nanoseconds())/1e9 would have rounded
+// differently.
 
 // Seconds returns the duration as a floating point number of seconds.
 func (d Duration) Seconds() float64 {
-        // Splitting the second vs nsec ourselves guarantees
-        // that int64(d.Seconds()) == d.Nanoseconds()p/1e9

[r, 2011/11/18 17:37:37]

s/p//

[rsc, 2011/11/18 18:21:36]

Done.

-        // even in cases where float64(d) / 1e9 would have

[r, 2011/11/18 17:37:37]

s; / ;/;

[rsc, 2011/11/18 18:21:36]

Done.

-        // rounded differently.
         sec := d / Second
         nsec := d % Second
         return float64(sec) + float64(nsec)*1e-9
 }
 
-// REVIEW NOTE: There are no uses of Minutes or Hours in the tree.
-// Are these worth having?  Days and Years are out because those
-// units do not have fixed lengths.

[r, 2011/11/18 17:37:37]

delete

[rsc, 2011/11/18 18:21:36]

Done.

-
 // Minutes returns the duration as a floating point number of minutes.
-func (d Duration) Minutes() float64 { return float64(d) / float64(Minute) }
+func (d Duration) Minutes() float64 {
+        min := d / Minute
+        nsec := d % Minute
+        return float64(min) + float64(nsec)*(1e-9/60)
+}
 
 // Hours returns the duration as a floating point number of hours.
-func (d Duration) Hours() float64 { return float64(d) / float64(Hour) }
+func (d Duration) Hours() float64 {
+        hour := d / Hour
+        nsec := d % Hour
+        return float64(hour) + float64(nsec)*(1e-9/60/60)
+}
 
 // Add returns the time t+d.
 func (t Time) Add(d Duration) Time {
         t.sec += int64(d / 1e9)
         t.nsec += int32(d % 1e9)
         if t.nsec > 1e9 {
                 t.sec++
                 t.nsec -= 1e9
         } else if t.nsec < 0 {
                 t.sec--
@@ skipping 103 matching lines @@
         31 + 28,
         31 + 28 + 31,
         31 + 28 + 31 + 30,
         31 + 28 + 31 + 30 + 31,
         31 + 28 + 31 + 30 + 31 + 30,
         31 + 28 + 31 + 30 + 31 + 30 + 31,
         31 + 28 + 31 + 30 + 31 + 30 + 31 + 31,
         31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30,
         31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31,
         31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30,
         31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30 + 31,

[r, 2011/11/18 17:37:37]

there's an optical illusion here, making this line look like it curves upwards

 }
 
+func daysIn(m Month, year int) int {
+        if m == February && isLeap(year) {
+                return 29
+        }
+        return int(daysBefore[m+1] - daysBefore[m])
+}
+
 // Provided by package runtime.
 func now() (sec int64, nsec int32)
 
 // Now returns the current local time.
 func Now() Time {
         sec, nsec := now()
         return Time{sec + unixToInternal, nsec, Local}
 }
 
 // UTC returns t with the location set to UTC.
 func (t Time) UTC() Time {
         t.loc = UTC
         return t
 }
 
 // Local returns t with the location set to local time.
 func (t Time) Local() Time {
         t.loc = Local
         return t
 }
 
 // In returns t with the location information set to loc.

[r, 2011/11/18 17:37:37]

// It panics if loc is nil.
(or you could say nil is UTC and avoid the panic)

[rsc, 2011/11/18 18:21:36]

I added the comment.  I have been trying to force callers to be 
explicit about saying time.Local or time.UTC instead of 'nil',
since it is a point on which there was confusion.

Separately, I am also trying to preserve the property mentioned
in the Time definition that only the zero Time has loc == nil.
If we ever do need to change the internal representation, that will
be a convenient way to detect the zero time.  This does not
imply that the API must reject nil, of course (it could rewrite
to UTC on the way in), but it still seems best to be explicit.

+//
+// In panics if loc is nil.
 func (t Time) In(loc *Location) Time {
         if loc == nil {
                 panic("time: missing Location in call to Time.In")
         }
         t.loc = loc
         return t
 }
 
 // Location returns the time zone information associated with t.
 func (t Time) Location() *Location {
         l := t.loc
         if l == nil {
                 l = UTC
         }
         return l
 }
 
 // Zone computes the time zone in effect at time t, returning the abbreviated
 // name of the zone (such as "CET") and its offset in seconds east of UTC.
 func (t Time) Zone() (name string, offset int) {
-        name, offset, _, _, _ = t.loc.Lookup(t.sec + internalToUnix)
+        name, offset, _, _, _ = t.loc.lookup(t.sec + internalToUnix)
         return
 }
 
-// Unix returns the Unix time, the number of seconds since January 1, 1970 UTC.
+// Unix returns the Unix time, the number of seconds elapsed
+// since January 1, 1970 UTC.
 func (t Time) Unix() int64 {
         return t.sec + internalToUnix
 }
 
-// UnixNano returns the Unix time, the number of nanoseconds since January 1, 1970 UTC.
+// UnixNano returns the Unix time, the number of nanoseconds elapsed
+// since January 1, 1970 UTC.
 func (t Time) UnixNano() int64 {
         return (t.sec+internalToUnix)*1e9 + int64(t.nsec)
 }
 
 // Unix returns the local Time corresponding to the given Unix time,
 // sec seconds and nsec nanoseconds since January 1, 1970 UTC.
 // It is valid to pass nsec outside the range [0, 999999999].
 func Unix(sec int64, nsec int64) Time {
         if nsec < 0 || nsec >= 1e9 {
                 n := nsec / 1e9
@@ skipping 27 matching lines @@
         }
         return hi, lo
 }
 
 // Date returns the Time corresponding to
 //      yyyy-mm-dd hh:mm:ss + nsec nanoseconds
 // in the appropriate zone for that time in the given location.
 //
 // The month, day, hour, min, sec, and nsec values may be outside
 // their usual ranges and will be normalized during the conversion.
-// For example, October 42 converts to November 11.

[r, 2011/11/18 17:37:37]

easier to understand
For example, October 32 is November 1.

[rsc, 2011/11/18 18:21:36]

Done.

+// For example, October 32 converts to November 1.
 //
 // A daylight savings time transition skips or repeats times.
 // For example, in the United States, March 13, 2011 2:15am never occurred,
 // while November 6, 2011 1:15am occurred twice.  In such cases, the
 // choice of time zone, and therefore the time, is not well-defined.
-// Date guarantees to return a time correct in one of the two zones
-// involved in the transition, but it does not guarantee which.
+// Date returns a time that is correct in one of the two zones involved
+// in the transition, but it does not guarantee which.
+//
+// Date panics if loc is nil.
 func Date(year int, month Month, day, hour, min, sec, nsec int, loc *Location) Time {
         if loc == nil {
                 panic("time: missing Location in call to Date")

[r, 2011/11/18 17:37:37]

utc?

[rsc, 2011/11/18 18:21:36]

Added panic to doc comment.

         }
 
         // Normalize month, overflowing into year.
         m := int(month) - 1
         year, m = norm(year, m, 12)
         month = Month(m) + 1
 
         // Normalize nsec, sec, min, hour, overflowing into day.
         sec, nsec = norm(sec, nsec, 1e9)
         min, sec = norm(min, sec, 60)
@@ skipping 32 matching lines @@
         // Add in days before today.
         d += uint64(day - 1)
 
         // Add in time elapsed today.
         abs := d * secondsPerDay
         abs += uint64(hour*secondsPerHour + min*secondsPerMinute + sec)
 
         unix := int64(abs) + (absoluteToInternal + internalToUnix)
 
         // Look for zone offset for t, so we can adjust to UTC.
-        // The Lookup function expects UTC, so we pass t in the
+        // The lookup function expects UTC, so we pass t in the
         // hope that it will not be too close to a zone transition,
         // and then adjust if it is.
-        _, offset, _, start, end := loc.Lookup(unix)
+        _, offset, _, start, end := loc.lookup(unix)
         if offset != 0 {
                 switch utc := unix - int64(offset); {
                 case utc < start:
-                        _, offset, _, _, _ = loc.Lookup(start - 1)
+                        _, offset, _, _, _ = loc.lookup(start - 1)
                 case utc >= end:
-                        _, offset, _, _, _ = loc.Lookup(end)
+                        _, offset, _, _, _ = loc.lookup(end)
                 }
                 unix -= int64(offset)
         }
 
         return Time{unix + unixToInternal, int32(nsec), loc}
 }