Package: golang.org/x/xerrors

package xerrors Import Path golang.org/x/xerrors (on go.dev) Dependency Relation imports 11 packages, and imported by 5 packages

Involved Source Files adaptor.go d doc.go Package xerrors implements functions to manipulate errors. This package is based on the Go 2 proposal for error values: https://go.dev/design/29934-error-values These functions were incorporated into the standard library's errors package in Go 1.13: - Is - As - Unwrap Also, Errorf's %w verb was incorporated into fmt.Errorf. No other features of this package were included in Go 1.13, and at present there are no plans to include any of them. errors.go fmt.go format.go frame.go wrap.go

Code Examples package main import ( "fmt" "time" ) // MyError is an error implementation that includes a time and message. type MyError struct { When time.Time What string } func (e MyError) Error() string { return fmt.Sprintf("%v: %v", e.When, e.What) } func oops() error { return MyError{ time.Date(1989, 3, 15, 22, 30, 0, 0, time.UTC), "the file system has gone away", } } func main() { if err := oops(); err != nil { fmt.Println(err) } } As package main import ( "fmt" "os" "golang.org/x/xerrors" ) func main() { _, err := os.Open("non-existing") if err != nil { var pathError *os.PathError if xerrors.As(err, &pathError) { fmt.Println("Failed at path:", pathError.Path) } } } FormatError package main import ( "fmt" "golang.org/x/xerrors" ) type MyError2 struct { Message string frame xerrors.Frame } func (m *MyError2) Error() string { return m.Message } func (m *MyError2) Format(f fmt.State, c rune) { // implements fmt.Formatter xerrors.FormatError(m, f, c) } func (m *MyError2) FormatError(p xerrors.Printer) error { // implements xerrors.Formatter p.Print(m.Message) if p.Detail() { m.frame.Format(p) } return nil } func main() { err := &MyError2{Message: "oops", frame: xerrors.Caller(1)} fmt.Printf("%v\n", err) fmt.Println() fmt.Printf("%+v\n", err) }

Package-Level Functions (total 8)

func As(err error, target any) bool As finds the first error in err's tree that matches target, and if one is found, sets target to that error value and returns true. Otherwise, it returns false. The tree consists of err itself, followed by the errors obtained by repeatedly calling its Unwrap() error or Unwrap() []error method. When err wraps multiple errors, As examines err followed by a depth-first traversal of its children. 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(any) bool such that As(target) returns true. In the latter case, the As method is responsible for setting target. An error type might provide an As method so it can be treated as if it were 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. Deprecated: As of Go 1.13, this function simply calls [errors.As].

func Caller(skip int) Frame Caller returns a Frame that describes a frame on the caller's stack. The argument skip is the number of frames to skip over. Caller(0) returns the frame for the caller of Caller.

func Errorf(format string, a ...any) error Errorf formats according to a format specifier and returns the string as a value that satisfies error. The returned error includes the file and line number of the caller when formatted with additional detail enabled. If the last argument is an error the returned error's Format method will return it if the format string ends with ": %s", ": %v", or ": %w". If the last argument is an error and the format string ends with ": %w", the returned error implements an Unwrap method returning it. If the format specifier includes a %w verb with an error operand in a position other than at the end, the returned error will still implement an Unwrap method returning the operand, but the error's Format method will not return the wrapped error. It is invalid to include more than one %w verb or to supply it with an operand that does not implement the error interface. The %w verb is otherwise a synonym for %v. Note that as of Go 1.13, the fmt.Errorf function will do error formatting, but it will not capture a stack backtrace.

func FormatError(f Formatter, s fmt.State, verb rune) FormatError calls the FormatError method of f with an errors.Printer configured according to s and verb, and writes the result to s.

func Is(err, target error) bool Is reports whether any error in err's tree matches target. The tree consists of err itself, followed by the errors obtained by repeatedly calling its Unwrap() error or Unwrap() []error method. When err wraps multiple errors, Is examines err followed by a depth-first traversal of its children. 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 == fs.ErrExist } then Is(MyError{}, fs.ErrExist) returns true. See [syscall.Errno.Is] for an example in the standard library. An Is method should only shallowly compare err and the target and not call [Unwrap] on either. Deprecated: As of Go 1.13, this function simply calls [errors.Is].

func New(text string) error New returns an error that formats as the given text. The returned error contains a Frame set to the caller's location and implements Formatter to show this information when printed with details.

func Opaque(err error) error Opaque returns an error with the same error formatting as err but that does not match err and cannot be unwrapped.

func Unwrap(err error) error Unwrap returns the result of calling the Unwrap method on err, if err implements Unwrap. Otherwise, Unwrap returns nil. Unwrap only calls a method of the form "Unwrap() error". In particular Unwrap does not unwrap errors returned by [errors.Join]. Deprecated: As of Go 1.13, this function simply calls [errors.Unwrap].