aboutsummaryrefslogtreecommitdiff
path: root/libgo/go/errors
diff options
context:
space:
mode:
authorIan Lance Taylor <ian@gcc.gnu.org>2019-09-12 23:22:53 +0000
committerIan Lance Taylor <ian@gcc.gnu.org>2019-09-12 23:22:53 +0000
commit656297e1fec9a127ff742df16958ee279ccacec5 (patch)
tree24347a35dacea36ce742c32c17420f3e31f17e3d /libgo/go/errors
parentd6ecb707cc5a58816d27908a7aa324c4b0bc67bb (diff)
downloadgcc-656297e1fec9a127ff742df16958ee279ccacec5.zip
gcc-656297e1fec9a127ff742df16958ee279ccacec5.tar.gz
gcc-656297e1fec9a127ff742df16958ee279ccacec5.tar.bz2
libgo: update to Go1.13
Reviewed-on: https://go-review.googlesource.com/c/gofrontend/+/194698 From-SVN: r275691
Diffstat (limited to 'libgo/go/errors')
-rw-r--r--libgo/go/errors/errors.go49
-rw-r--r--libgo/go/errors/wrap.go6
2 files changed, 55 insertions, 0 deletions
diff --git a/libgo/go/errors/errors.go b/libgo/go/errors/errors.go
index b8a4692..85d4260 100644
--- a/libgo/go/errors/errors.go
+++ b/libgo/go/errors/errors.go
@@ -3,9 +3,58 @@
// license that can be found in the LICENSE file.
// Package errors implements functions to manipulate errors.
+//
+// The New function creates errors whose only content is a text message.
+//
+// The Unwrap, Is and As functions work on errors that may wrap other errors.
+// An error wraps another error if its type has the method
+//
+// Unwrap() error
+//
+// If e.Unwrap() returns a non-nil error w, then we say that e wraps w.
+//
+// A simple way to create wrapped errors is to call fmt.Errorf and apply the %w verb
+// to the error argument:
+//
+// fmt.Errorf("... %w ...", ..., err, ...).Unwrap()
+//
+// returns err.
+//
+// Unwrap unpacks wrapped errors. If its argument's type has an
+// Unwrap method, it calls the method once. Otherwise, it returns nil.
+//
+// Is unwraps its first argument sequentially looking for an error that matches the
+// second. It reports whether it finds a match. It should be used in preference to
+// simple equality checks:
+//
+// if errors.Is(err, os.ErrExist)
+//
+// is preferable to
+//
+// if err == os.ErrExist
+//
+// because the former will succeed if err wraps os.ErrExist.
+//
+// As unwraps its first argument sequentially looking for an error that can be
+// assigned to its second argument, which must be a pointer. If it succeeds, it
+// performs the assignment and returns true. Otherwise, it returns false. The form
+//
+// var perr *os.PathError
+// if errors.As(err, &perr) {
+// fmt.Println(perr.Path)
+// }
+//
+// is preferable to
+//
+// if perr, ok := err.(*os.PathError); ok {
+// fmt.Println(perr.Path)
+// }
+//
+// because the former will succeed if err wraps an *os.PathError.
package errors
// New returns an error that formats as the given text.
+// Each call to New returns a distinct error value even if the text is identical.
func New(text string) error {
return &errorString{text}
}
diff --git a/libgo/go/errors/wrap.go b/libgo/go/errors/wrap.go
index 666d1ff..240da37 100644
--- a/libgo/go/errors/wrap.go
+++ b/libgo/go/errors/wrap.go
@@ -23,6 +23,9 @@ func Unwrap(err error) error {
// Is reports whether any error in err's chain matches target.
//
+// The chain consists of err itself followed by the sequence of errors obtained by
+// repeatedly calling Unwrap.
+//
// An error is considered to match a target if it is equal to that target or if
// it implements a method Is(error) bool such that Is(target) returns true.
func Is(err, target error) bool {
@@ -50,6 +53,9 @@ func Is(err, target error) bool {
// As finds the first error in err's chain that matches target, and if so, sets
// target to that error value and returns true.
//
+// The chain consists of err itself followed by the sequence of errors obtained by
+// repeatedly calling Unwrap.
+//
// An error matches target if the error's concrete value is assignable to the value
// pointed to by target, or if the error has a method As(interface{}) bool such that
// As(target) returns true. In the latter case, the As method is responsible for