| // Copyright 2011 The Go Authors. All rights reserved. | |
| // Use of this source code is governed by a BSD-style | |
| // 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. | |
| // | |
| // An error e wraps another error if e's type has one of the methods | |
| // | |
| // Unwrap() error | |
| // Unwrap() []error | |
| // | |
| // If e.Unwrap() returns a non-nil error w or a slice containing w, | |
| // then we say that e wraps w. A nil error returned from e.Unwrap() | |
| // indicates that e does not wrap any error. It is invalid for an | |
| // Unwrap method to return an []error containing a nil error value. | |
| // | |
| // An easy way to create wrapped errors is to call [fmt.Errorf] and apply | |
| // the %w verb to the error argument: | |
| // | |
| // wrapsErr := fmt.Errorf("... %w ...", ..., err, ...) | |
| // | |
| // Successive unwrapping of an error creates a tree. The [Is] and [As] | |
| // functions inspect an error's tree by examining first the error | |
| // itself followed by the tree of each of its children in turn | |
| // (pre-order, depth-first traversal). | |
| // | |
| // See https://go.dev/blog/go1.13-errors for a deeper discussion of the | |
| // philosophy of wrapping and when to wrap. | |
| // | |
| // [Is] examines the tree of its first argument 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, fs.ErrExist) | |
| // | |
| // is preferable to | |
| // | |
| // if err == fs.ErrExist | |
| // | |
| // because the former will succeed if err wraps [io/fs.ErrExist]. | |
| // | |
| // [AsType] examines the tree of its argument looking for an error whose | |
| // type matches its type argument. If it succeeds, it returns the | |
| // corresponding value of that type and true. Otherwise, it returns the | |
| // zero value of that type and false. The form | |
| // | |
| // if perr, ok := errors.AsType[*fs.PathError](err); ok { | |
| // fmt.Println(perr.Path) | |
| // } | |
| // | |
| // is preferable to | |
| // | |
| // if perr, ok := err.(*fs.PathError); ok { | |
| // fmt.Println(perr.Path) | |
| // } | |
| // | |
| // because the former will succeed if err wraps an [*io/fs.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} | |
| } | |
| // errorString is a trivial implementation of error. | |
| type errorString struct { | |
| s string | |
| } | |
| func (e *errorString) Error() string { | |
| return e.s | |
| } | |
| // ErrUnsupported indicates that a requested operation cannot be performed, | |
| // because it is unsupported. For example, a call to [os.Link] when using a | |
| // file system that does not support hard links. | |
| // | |
| // Functions and methods should not return this error but should instead | |
| // return an error including appropriate context that satisfies | |
| // | |
| // errors.Is(err, errors.ErrUnsupported) | |
| // | |
| // either by directly wrapping ErrUnsupported or by implementing an [Is] method. | |
| // | |
| // Functions and methods should document the cases in which an error | |
| // wrapping this will be returned. | |
| var ErrUnsupported = New("unsupported operation") | |