Skip to content

G
go
Commit 5fa18e10 authored by Rob Pike's avatar Rob Pike
Browse files
Options

doc/go1: time 

R=rsc
CC=golang-dev
https://golang.org/cl/5477077
parent f76bd4fe
Show whitespace changes
Inline Side-by-side
Showing with 173 additions and 24 deletions
doc/go1.html
View file @ 5fa18e10
......@@ -417,17 +417,17 @@ As a result, structs and arrays can now be used as map keys:
</p>
<pre><!--{{code "progs/go1.go" `/type Day struct/` `/Printf/`}}
--> // type Day struct {
// long string
// short string
// }
// Christmas := Day{&#34;Christmas&#34;, &#34;XMas&#34;}
// Thanksgiving := Day{&#34;Thanksgiving&#34;, &#34;Turkey&#34;}
// holiday := map[Day]bool {
// Christmas: true,
// Thanksgiving: true,
// }
// fmt.Printf(&#34;Christmas is a holiday: %t\n&#34;, holiday[Christmas])
--> type Day struct {
long string
short string
}
Christmas := Day{&#34;Christmas&#34;, &#34;XMas&#34;}
Thanksgiving := Day{&#34;Thanksgiving&#34;, &#34;Turkey&#34;}
holiday := map[Day]bool{
Christmas: true,
Thanksgiving: true,
}
fmt.Printf(&#34;Christmas is a holiday: %t\n&#34;, holiday[Christmas])
</pre>
<p>
......@@ -626,6 +626,78 @@ rather than <code>syscall</code> and so will be unaffected.
<h3 id="time">Time</h3>
<p>
One of the most sweeping changes in the Go 1 library is the
complete redesign of the
<a href="/pkg/time/"><code>time</code></a> package.
Instead of an integer number of nanoseconds as an <code>int64</code>,
and a separate <code>*time.Time</code> type to deal with human
units such as hours and years,
there are now two fundamental types:
<a href="/pkg/time/#Time"><code>time.Time</code></a>
(a value, so the <code>*</code> is gone), which represents a moment in time;
and <a href="/pkg/time/#Duration"><code>time.Duration</code></a>,
which represents an interval.
Both have nanosecond resolution.
A <code>Time</code> can represent any time into the ancient
past and remote future, while a <code>Duration</code> 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 <code>time.Second</code>.
</p>
<p>
Among the new methods are things like
<a href="/pkg/time/#Time.Add"><code>Time.Add</code></a>,
which adds a <code>Duration</code> to a <code>Time</code>, and
<a href="/pkg/time/#Time.Sub"><code>Time.Sub</code></a>,
which subtracts two <code>Times</code> to yield a <code>Duration</code>.
</p>
<p>
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:
<a href="/pkg/time/#Unix"><code>time.Unix</code></a>
and the <a href="/pkg/time/#Time.Unix"><code>Unix</code></a>
and <a href="/pkg/time/#Time.UnixNano"><code>UnixNano</code></a> methods
of the <code>Time</code> type.
In particular,
<a href="/pkg/time/#Now"><code>time.Now</code></a>
returns a <code>time.Time</code> value rather than, in the old
API, an integer nanosecond count since the Unix epoch.
</p>
<pre><!--{{code "progs/go1.go" `/sleepUntil/` `/^}/`}}
-->// sleepUntil sleeps until the specified time. It returns immediately if it&#39;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(&#34;Sleeping for %.3fs&#34;, delta.Seconds())
time.Sleep(delta)
}
</pre>
<p>
The new types, methods, and constants have been propagated through
all the standard packages that use time, such as <code>os</code> and
its representation of file time stamps.
</p>
<p>
<em>Updating</em>:
Gofix will update many uses of the old <code>time</code> package to use the new
types and methods, although it does not replace values such as <code>1e9</code>
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.
</p>
<h3 id="html">The html package</h3>
<p>
......
doc/go1.tmpl
View file @ 5fa18e10
......@@ -529,6 +529,67 @@ rather than <code>syscall</code> and so will be unaffected.
<h3 id="time">Time</h3>
<p>
One of the most sweeping changes in the Go 1 library is the
complete redesign of the
<a href="/pkg/time/"><code>time</code></a> package.
Instead of an integer number of nanoseconds as an <code>int64</code>,
and a separate <code>*time.Time</code> type to deal with human
units such as hours and years,
there are now two fundamental types:
<a href="/pkg/time/#Time"><code>time.Time</code></a>
(a value, so the <code>*</code> is gone), which represents a moment in time;
and <a href="/pkg/time/#Duration"><code>time.Duration</code></a>,
which represents an interval.
Both have nanosecond resolution.
A <code>Time</code> can represent any time into the ancient
past and remote future, while a <code>Duration</code> 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 <code>time.Second</code>.
</p>
<p>
Among the new methods are things like
<a href="/pkg/time/#Time.Add"><code>Time.Add</code></a>,
which adds a <code>Duration</code> to a <code>Time</code>, and
<a href="/pkg/time/#Time.Sub"><code>Time.Sub</code></a>,
which subtracts two <code>Times</code> to yield a <code>Duration</code>.
</p>
<p>
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:
<a href="/pkg/time/#Unix"><code>time.Unix</code></a>
and the <a href="/pkg/time/#Time.Unix"><code>Unix</code></a>
and <a href="/pkg/time/#Time.UnixNano"><code>UnixNano</code></a> methods
of the <code>Time</code> type.
In particular,
<a href="/pkg/time/#Now"><code>time.Now</code></a>
returns a <code>time.Time</code> value rather than, in the old
API, an integer nanosecond count since the Unix epoch.
</p>
{{code "progs/go1.go" `/sleepUntil/` `/^}/`}}
<p>
The new types, methods, and constants have been propagated through
all the standard packages that use time, such as <code>os</code> and
its representation of file time stamps.
</p>
<p>
<em>Updating</em>:
Gofix will update many uses of the old <code>time</code> package to use the new
types and methods, although it does not replace values such as <code>1e9</code>
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.
</p>
<h3 id="html">The html package</h3>
<p>
......
doc/progs/go1.go
View file @ 5fa18e10
......@@ -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) {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7