Source file src/errors/wrap.go
1 // Copyright 2018 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 package errors 6 7 import ( 8 "internal/reflectlite" 9 ) 10 11 // Unwrap returns the result of calling the Unwrap method on err, if err's 12 // type contains an Unwrap method returning error. 13 // Otherwise, Unwrap returns nil. 14 // 15 // Unwrap only calls a method of the form "Unwrap() error". 16 // In particular Unwrap does not unwrap errors returned by [Join]. 17 func Unwrap(err error) error { 18 u, ok := err.(interface { 19 Unwrap() error 20 }) 21 if !ok { 22 return nil 23 } 24 return u.Unwrap() 25 } 26 27 // Is reports whether any error in err's tree matches target. 28 // 29 // The tree consists of err itself, followed by the errors obtained by repeatedly 30 // calling Unwrap. When err wraps multiple errors, Is examines err followed by a 31 // depth-first traversal of its children. 32 // 33 // An error is considered to match a target if it is equal to that target or if 34 // it implements a method Is(error) bool such that Is(target) returns true. 35 // 36 // An error type might provide an Is method so it can be treated as equivalent 37 // to an existing error. For example, if MyError defines 38 // 39 // func (m MyError) Is(target error) bool { return target == fs.ErrExist } 40 // 41 // then Is(MyError{}, fs.ErrExist) returns true. See [syscall.Errno.Is] for 42 // an example in the standard library. An Is method should only shallowly 43 // compare err and the target and not call Unwrap on either. 44 func Is(err, target error) bool { 45 if target == nil { 46 return err == target 47 } 48 49 isComparable := reflectlite.TypeOf(target).Comparable() 50 for { 51 if isComparable && err == target { 52 return true 53 } 54 if x, ok := err.(interface{ Is(error) bool }); ok && x.Is(target) { 55 return true 56 } 57 switch x := err.(type) { 58 case interface{ Unwrap() error }: 59 err = x.Unwrap() 60 if err == nil { 61 return false 62 } 63 case interface{ Unwrap() []error }: 64 for _, err := range x.Unwrap() { 65 if Is(err, target) { 66 return true 67 } 68 } 69 return false 70 default: 71 return false 72 } 73 } 74 } 75 76 // As finds the first error in err's tree that matches target, and if one is found, sets 77 // target to that error value and returns true. Otherwise, it returns false. 78 // 79 // The tree consists of err itself, followed by the errors obtained by repeatedly 80 // calling Unwrap. When err wraps multiple errors, As examines err followed by a 81 // depth-first traversal of its children. 82 // 83 // An error matches target if the error's concrete value is assignable to the value 84 // pointed to by target, or if the error has a method As(interface{}) bool such that 85 // As(target) returns true. In the latter case, the As method is responsible for 86 // setting target. 87 // 88 // An error type might provide an As method so it can be treated as if it were a 89 // different error type. 90 // 91 // As panics if target is not a non-nil pointer to either a type that implements 92 // error, or to any interface type. 93 func As(err error, target any) bool { 94 if err == nil { 95 return false 96 } 97 if target == nil { 98 panic("errors: target cannot be nil") 99 } 100 val := reflectlite.ValueOf(target) 101 typ := val.Type() 102 if typ.Kind() != reflectlite.Ptr || val.IsNil() { 103 panic("errors: target must be a non-nil pointer") 104 } 105 targetType := typ.Elem() 106 if targetType.Kind() != reflectlite.Interface && !targetType.Implements(errorType) { 107 panic("errors: *target must be interface or implement error") 108 } 109 for { 110 if reflectlite.TypeOf(err).AssignableTo(targetType) { 111 val.Elem().Set(reflectlite.ValueOf(err)) 112 return true 113 } 114 if x, ok := err.(interface{ As(any) bool }); ok && x.As(target) { 115 return true 116 } 117 switch x := err.(type) { 118 case interface{ Unwrap() error }: 119 err = x.Unwrap() 120 if err == nil { 121 return false 122 } 123 case interface{ Unwrap() []error }: 124 for _, err := range x.Unwrap() { 125 if As(err, target) { 126 return true 127 } 128 } 129 return false 130 default: 131 return false 132 } 133 } 134 } 135 136 var errorType = reflectlite.TypeOf((*error)(nil)).Elem() 137