diff options
author | Jonathan Amsterdam <jba@google.com> | 2019-08-22 12:29:29 -0400 |
---|---|---|
committer | Jonathan Amsterdam <jba@google.com> | 2019-08-27 16:51:42 +0000 |
commit | fc4663d56f2ac550c0deca6ed0261d894be49465 (patch) | |
tree | 8ac032955b0ac2023f982418e9da5a68e2cf4798 /src/errors | |
parent | 95c3c43072a3d613429ff5eb80b5fcf212dd9998 (diff) | |
download | go-fc4663d56f2ac550c0deca6ed0261d894be49465.tar.gz go-fc4663d56f2ac550c0deca6ed0261d894be49465.zip |
errors: document Is and As methods
Add brief descriptions of why one might implement
an Is or As method.
Fixes #33364.
Change-Id: I81a091bf564c654ddb9ef3997e780451a01efb7a
Reviewed-on: https://go-review.googlesource.com/c/go/+/191338
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Diffstat (limited to 'src/errors')
-rw-r--r-- | src/errors/wrap.go | 13 |
1 files changed, 12 insertions, 1 deletions
diff --git a/src/errors/wrap.go b/src/errors/wrap.go index 240da37c29..65e6c44853 100644 --- a/src/errors/wrap.go +++ b/src/errors/wrap.go @@ -28,6 +28,14 @@ func Unwrap(err error) error { // // 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. +// +// An error type might provide an Is method so it can be treated as equivalent +// to an existing error. For example, if MyError defines +// +// func (m MyError) Is(target error) bool { return target == os.ErrExist } +// +// then Is(MyError{}, os.ErrExist) returns true. See syscall.Errno.Is for +// an example in the standard library. func Is(err, target error) bool { if target == nil { return err == target @@ -61,7 +69,10 @@ func Is(err, target error) bool { // As(target) returns true. In the latter case, the As method is responsible for // setting target. // -// As will panic if target is not a non-nil pointer to either a type that implements +// An error type might provide an As method so it can be treated as if it were a +// a different error type. +// +// As panics if target is not a non-nil pointer to either a type that implements // error, or to any interface type. As returns false if err is nil. func As(err error, target interface{}) bool { if target == nil { |