Black Lives Matter. Support the Equal Justice Initiative.

Source file src/errors/wrap.go

Documentation: errors

     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  func Unwrap(err error) error {
    15  	u, ok := err.(interface {
    16  		Unwrap() error
    17  	})
    18  	if !ok {
    19  		return nil
    20  	}
    21  	return u.Unwrap()
    22  }
    23  
    24  // Is reports whether any error in err's chain matches target.
    25  //
    26  // The chain consists of err itself followed by the sequence of errors obtained by
    27  // repeatedly calling Unwrap.
    28  //
    29  // An error is considered to match a target if it is equal to that target or if
    30  // it implements a method Is(error) bool such that Is(target) returns true.
    31  //
    32  // An error type might provide an Is method so it can be treated as equivalent
    33  // to an existing error. For example, if MyError defines
    34  //
    35  //	func (m MyError) Is(target error) bool { return target == os.ErrExist }
    36  //
    37  // then Is(MyError{}, os.ErrExist) returns true. See syscall.Errno.Is for
    38  // an example in the standard library.
    39  func Is(err, target error) bool {
    40  	if target == nil {
    41  		return err == target
    42  	}
    43  
    44  	isComparable := reflectlite.TypeOf(target).Comparable()
    45  	for {
    46  		if isComparable && err == target {
    47  			return true
    48  		}
    49  		if x, ok := err.(interface{ Is(error) bool }); ok && x.Is(target) {
    50  			return true
    51  		}
    52  		// TODO: consider supporting target.Is(err). This would allow
    53  		// user-definable predicates, but also may allow for coping with sloppy
    54  		// APIs, thereby making it easier to get away with them.
    55  		if err = Unwrap(err); err == nil {
    56  			return false
    57  		}
    58  	}
    59  }
    60  
    61  // As finds the first error in err's chain that matches target, and if so, sets
    62  // target to that error value and returns true. Otherwise, it returns false.
    63  //
    64  // The chain consists of err itself followed by the sequence of errors obtained by
    65  // repeatedly calling Unwrap.
    66  //
    67  // An error matches target if the error's concrete value is assignable to the value
    68  // pointed to by target, or if the error has a method As(interface{}) bool such that
    69  // As(target) returns true. In the latter case, the As method is responsible for
    70  // setting target.
    71  //
    72  // An error type might provide an As method so it can be treated as if it were a
    73  // different error type.
    74  //
    75  // As panics if target is not a non-nil pointer to either a type that implements
    76  // error, or to any interface type.
    77  func As(err error, target interface{}) bool {
    78  	if target == nil {
    79  		panic("errors: target cannot be nil")
    80  	}
    81  	val := reflectlite.ValueOf(target)
    82  	typ := val.Type()
    83  	if typ.Kind() != reflectlite.Ptr || val.IsNil() {
    84  		panic("errors: target must be a non-nil pointer")
    85  	}
    86  	if e := typ.Elem(); e.Kind() != reflectlite.Interface && !e.Implements(errorType) {
    87  		panic("errors: *target must be interface or implement error")
    88  	}
    89  	targetType := typ.Elem()
    90  	for err != nil {
    91  		if reflectlite.TypeOf(err).AssignableTo(targetType) {
    92  			val.Elem().Set(reflectlite.ValueOf(err))
    93  			return true
    94  		}
    95  		if x, ok := err.(interface{ As(interface{}) bool }); ok && x.As(target) {
    96  			return true
    97  		}
    98  		err = Unwrap(err)
    99  	}
   100  	return false
   101  }
   102  
   103  var errorType = reflectlite.TypeOf((*error)(nil)).Elem()
   104  

View as plain text