diff options
author | Jonathan Amsterdam <jba@google.com> | 2019-08-05 10:14:40 -0400 |
---|---|---|
committer | Jonathan Amsterdam <jba@google.com> | 2019-08-05 23:12:39 +0000 |
commit | a4c825156d0a3817377a2b7e5b30ab50e11440ab (patch) | |
tree | 3aa40ea71e70592c04987ddcdd2a5d2ccf5e0540 | |
parent | d1338ec30e8c611395a6b253b441734adb9635de (diff) | |
download | go-a4c825156d0a3817377a2b7e5b30ab50e11440ab.tar.gz go-a4c825156d0a3817377a2b7e5b30ab50e11440ab.zip |
doc/go1.13.html: describe error-value additions
A brief description at the top the Standard Library section of the
changes to support error wrapping.
Fixes #33365.
Change-Id: Id5a3b2fe148d9bfb949f2cfc9e5d8a1613a0e219
Reviewed-on: https://go-review.googlesource.com/c/go/+/188798
Reviewed-by: Ian Lance Taylor <iant@golang.org>
-rw-r--r-- | doc/go1.13.html | 34 |
1 files changed, 33 insertions, 1 deletions
diff --git a/doc/go1.13.html b/doc/go1.13.html index bc44531133..f38474b327 100644 --- a/doc/go1.13.html +++ b/doc/go1.13.html @@ -525,6 +525,37 @@ godoc <code>crypto/ed25519</code> when used with Go 1.13+. </p> +<h3 id="error_wrapping">Error wrapping</h3> + +<p><!-- CL 163558, 176998 --> + Go 1.13 contains support for error wrapping, as first proposed in + the <a href="https://go.googlesource.com/proposal/+/master/design/29934-error-values.md"> + Error Values proposal</a> and discussed on <a href="https://golang.org/issue/29934">the + associated issue</a>. +</p> +<p> + An error <code>e</code> can <em>wrap</em> another error <code>w</code> by providing + an <code>Unwrap</code> method that returns <code>w</code>. Both <code>e</code> + and <code>w</code> are available to programs, allowing <code>e</code> to provide + additional context to <code>w</code> or to reinterpret it while still allowing + programs to make decisions based on <code>w</code>. +</p> +<p> + To support wrapping, <a href="#fmt"><code>fmt.Errorf</code></a> now has a <code>%w</code> + verb for creating wrapped errors, and three new functions in + the <a href="#errors"><code>errors</code></a> package ( + <a href="/pkg/errors#Unwrap"><code>errors.Unwrap</code></a>, + <a href="/pkg/errors#Is"><code>errors.Is</code></a> and + <a href="/pkg/errors#As"><code>errors.As</code></a>) simplify unwrapping + and inspecting wrapped errors. +</p> +<p> + For more information, read the <a href="/pkg/errors/"><code>errors</code> package + documentation</a>, or see + the <a href="https://golang.org/wiki/ErrorValueFAQ">Error Value FAQ</a>. + There will soon be a blog post as well. +</p> + <h3 id="minor_library_changes">Minor changes to the library</h3> <p> @@ -612,7 +643,8 @@ godoc <dd> <!-- CL 163558 --> <p> - The new function <a href="/pkg/errors/#As"><code>As</code></a> finds the first error in a given error’s chain + The new function <a href="/pkg/errors/#As"><code>As</code></a> finds the first + error in a given error’s chain (sequence of wrapped errors) that matches a given target’s type, and if so, sets the target to that error value. </p> <p> |