Documentation
¶
Overview ¶
Package errors implements functions to manipulate errors.
The New function creates errors whose contents consist of a textual description of the error and contextual information. This contextual information can be used to trace back the source of the error. The Trace function can be used to write traceback information to an io.Writer in a human-friendly format.
Errors are frequently caused by other errors. To account for this, the New function takes two sets of parameters: one representing a textual description of the error and one representing its parent error.
Package developers may choose to predefine certain errors, such as the io.EOF error:
var EOF = errors.New(nil, "EOF")
However, the context of this error is the line on which it is declared. To update the contextual information, the Raise function can be invoked when intending to raise a predefined error from a current context, like so:
errors.Raise(EOF)
A function which handles errors from multiple concurrently executing processes should, in most cases, return the first error it receives:
func f() error { errs := make(chan error) for i := 0; i < 5; i++ { go g(errs) } for err := range errs { if err != nil { return err } } return nil }
Alternatively, if the developer's intent is to return all received errors, the Join function is provided to return all errors as one. However, this removes the context behind the combined errors.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Has ¶
Has reports whether the textual error description of err or any of its parent errors match the textual error description of target.
func Is ¶
Is reports whether the textual error description of err matches the textual error description of target.
func Join ¶
Join returns an error that combines the given errs. Any nil error values are discarded. Join returns nil if errs contains no non-nil values. The resultant error is formatted as a concatenation of the textual error descriptions of all given errs, with a comma and space between each description.
An error can only have one parent, so the resultant error has nil parent.
func New ¶
New returns an error whose textual error description is given by fmt.Sprintf(format, a...) and whose parent error is err. If the new error has no parent, err should be given as nil.
The current filename, line, program counter, and parent function name are stored within the error interface. Each call to New returns a distinct error value even if text is identical.
To avoid writing New(err, ""), a call to Wrap(err) accomplishes the same task.
func Raise ¶
Raise returns the error equivalent to err whose program origin details (file, name line number, etc.) are overridden with those of the caller of Raise.
Types ¶
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error represents an error. The Error type holds a textual description of the error and contextual information describing the source of the error. It also holds a copy of its parent error, if one exists.
Contextual information held in an Error can be used to trace back the source of an error, and can be returned to the user through functions such as errors.Trace
Error implements the error interface. It only be used indirectly via functions in this package, never directly.