From 5fa18e10618d609ce2c272026e460c47ec864250 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Mon, 12 Dec 2011 21:08:03 -0800 Subject: [PATCH] doc/go1: time R=rsc CC=golang-dev https://golang.org/cl/5477077 --- doc/go1.html | 94 ++++++++++++++++++++++++++++++++++++++++++------ doc/go1.tmpl | 61 +++++++++++++++++++++++++++++++ doc/progs/go1.go | 42 +++++++++++++++------- 3 files changed, 173 insertions(+), 24 deletions(-) diff --git a/doc/go1.html b/doc/go1.html index 420cae4de13..f362fe970a6 100644 --- a/doc/go1.html +++ b/doc/go1.html @@ -417,17 +417,17 @@ As a result, structs and arrays can now be used as map keys: 

    //    type Day struct {
-    //        long string
-    //        short string
-    //    }
-    //    Christmas := Day{"Christmas", "XMas"}
-    //    Thanksgiving := Day{"Thanksgiving", "Turkey"}
-    //    holiday := map[Day]bool {
-    //        Christmas: true,
-    //        Thanksgiving: true,
-    //    }
-    //    fmt.Printf("Christmas is a holiday: %t\n", holiday[Christmas])
+-->    type Day struct {
+        long  string
+        short string
+    }
+    Christmas := Day{"Christmas", "XMas"}
+    Thanksgiving := Day{"Thanksgiving", "Turkey"}
+    holiday := map[Day]bool{
+        Christmas:    true,
+        Thanksgiving: true,
+    }
+    fmt.Printf("Christmas is a holiday: %t\n", holiday[Christmas])

@@ -626,6 +626,78 @@ rather than syscall and so will be unaffected.

Time

+

+One of the most sweeping changes in the Go 1 library is the +complete redesign of the +time package. +Instead of an integer number of nanoseconds as an int64, +and a separate *time.Time type to deal with human +units such as hours and years, +there are now two fundamental types: +time.Time +(a value, so the * is gone), which represents a moment in time; +and time.Duration, +which represents an interval. +Both have nanosecond resolution. +A Time can represent any time into the ancient +past and remote future, while a Duration can +span plus or minus only about 290 years. +There are methods on these types, plus a number of helpful +predefined constant durations such as time.Second. +

+ +

+Among the new methods are things like +Time.Add, +which adds a Duration to a Time, and +Time.Sub, +which subtracts two Times to yield a Duration. +

+ +

+The most important semantic change is that the Unix epoch (Jan 1, 1970) is now +relevant only for those functions and methods that mention Unix: +time.Unix +and the Unix +and UnixNano methods +of the Time type. +In particular, +time.Now +returns a time.Time value rather than, in the old +API, an integer nanosecond count since the Unix epoch. +

+ +
// sleepUntil sleeps until the specified time. It returns immediately if it's too late.
+func sleepUntil(wakeup time.Time) {
+    now := time.Now() // A Time.
+    if !wakeup.After(now) {
+        return
+    }
+    delta := wakeup.Sub(now) // A Duration.
+    log.Printf("Sleeping for %.3fs", delta.Seconds())
+    time.Sleep(delta)
+}
+
+ +

+The new types, methods, and constants have been propagated through +all the standard packages that use time, such as os and +its representation of file time stamps. +

+ +

+Updating: +Gofix will update many uses of the old time package to use the new +types and methods, although it does not replace values such as 1e9 +representing nanoseconds per second. +Also, because of type changes in some of the values that arise, +some of the expressions rewritten by gofix may require +further hand editing; in such cases the rewrite will include +the correct function or method for the old functionality, but +may have the wrong type or require further analysis. +

+

The html package

diff --git a/doc/go1.tmpl b/doc/go1.tmpl index 77eeebaf53d..d224e8ba0ef 100644 --- a/doc/go1.tmpl +++ b/doc/go1.tmpl @@ -529,6 +529,67 @@ rather than syscall and so will be unaffected.

Time

+

+One of the most sweeping changes in the Go 1 library is the +complete redesign of the +time package. +Instead of an integer number of nanoseconds as an int64, +and a separate *time.Time type to deal with human +units such as hours and years, +there are now two fundamental types: +time.Time +(a value, so the * is gone), which represents a moment in time; +and time.Duration, +which represents an interval. +Both have nanosecond resolution. +A Time can represent any time into the ancient +past and remote future, while a Duration can +span plus or minus only about 290 years. +There are methods on these types, plus a number of helpful +predefined constant durations such as time.Second. +

+ +

+Among the new methods are things like +Time.Add, +which adds a Duration to a Time, and +Time.Sub, +which subtracts two Times to yield a Duration. +

+ +

+The most important semantic change is that the Unix epoch (Jan 1, 1970) is now +relevant only for those functions and methods that mention Unix: +time.Unix +and the Unix +and UnixNano methods +of the Time type. +In particular, +time.Now +returns a time.Time value rather than, in the old +API, an integer nanosecond count since the Unix epoch. +

+ +{{code "progs/go1.go" `/sleepUntil/` `/^}/`}} + +

+The new types, methods, and constants have been propagated through +all the standard packages that use time, such as os and +its representation of file time stamps. +

+ +

+Updating: +Gofix will update many uses of the old time package to use the new +types and methods, although it does not replace values such as 1e9 +representing nanoseconds per second. +Also, because of type changes in some of the values that arise, +some of the expressions rewritten by gofix may require +further hand editing; in such cases the rewrite will include +the correct function or method for the old functionality, but +may have the wrong type or require further analysis. +

+

The html package

diff --git a/doc/progs/go1.go b/doc/progs/go1.go index 54b7d206674..b1bcc43f615 100644 --- a/doc/progs/go1.go +++ b/doc/progs/go1.go @@ -10,6 +10,7 @@ import ( "errors" "fmt" "log" + "time" "unicode" ) @@ -22,6 +23,7 @@ func main() { compositeLiterals() runeType() errorExample() + timePackage() } func mapDelete() { @@ -50,6 +52,9 @@ func mapIteration() { } } +func f(string, int) { +} + func assert(t bool) { if !t { log.Panic("assertion fail") @@ -74,18 +79,17 @@ func multipleAssignment() { } func structEquality() { - // Feature not net in repo. - // type Day struct { - // long string - // short string - // } - // Christmas := Day{"Christmas", "XMas"} - // Thanksgiving := Day{"Thanksgiving", "Turkey"} - // holiday := map[Day]bool { - // Christmas: true, - // Thanksgiving: true, - // } - // fmt.Printf("Christmas is a holiday: %t\n", holiday[Christmas]) + type Day struct { + long string + short string + } + Christmas := Day{"Christmas", "XMas"} + Thanksgiving := Day{"Thanksgiving", "Turkey"} + holiday := map[Day]bool{ + Christmas: true, + Thanksgiving: true, + } + fmt.Printf("Christmas is a holiday: %t\n", holiday[Christmas]) } func compositeLiterals() { @@ -156,7 +160,19 @@ func errorExample() { } } -func f(string, int) { +// sleepUntil sleeps until the specified time. It returns immediately if it's too late. +func sleepUntil(wakeup time.Time) { + now := time.Now() // A Time. + if !wakeup.After(now) { + return + } + delta := wakeup.Sub(now) // A Duration. + log.Printf("Sleeping for %.3fs", delta.Seconds()) + time.Sleep(delta) +} + +func timePackage() { + sleepUntil(time.Now().Add(123 * time.Millisecond)) } func initializationFunction(c chan int) {