Documentation
¶
Overview ¶
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).
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 fs.ErrExist.
As examines the tree of its first argument looking for an error that can be assigned to its second argument, which must be a pointer. If it succeeds, it performs the assignment and returns true. Otherwise, it returns false. The form
var perr *fs.PathError
if errors.As(err, &perr) {
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 *fs.PathError.
Example ¶
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)
}
}
Output: 1989-03-15 22:30:00 +0000 UTC: the file system has gone away
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Join ¶
Join returns an error that wraps the given errors. Any nil error values are discarded. Join returns nil if errs contains no non-nil values. The error formats as the concatenation of the strings obtained by calling the Error method of each element of errs, with a newline between each string.
Example ¶
package main
import (
"errors"
"fmt"
)
func main() {
err1 := errors.New("err1")
err2 := errors.New("err2")
err := errors.Join(err1, err2)
fmt.Println(err)
if errors.Is(err, err1) {
fmt.Println("err is err1")
}
if errors.Is(err, err2) {
fmt.Println("err is err2")
}
}
Output: err1 err2 err is err1 err is err2
func New ¶
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.
Example ¶
package main
import (
"errors"
"fmt"
)
func main() {
err := errors.New("emit macho dwarf: elf header corrupted")
if err != nil {
fmt.Print(err)
}
}
Output: emit macho dwarf: elf header corrupted
Example (Errorf) ¶
The fmt package's Errorf function lets us use the package's formatting features to create descriptive error messages.
package main
import (
"fmt"
)
func main() {
const name, id = "bimmler", 17
err := fmt.Errorf("user %q (id %d) not found", name, id)
if err != nil {
fmt.Print(err)
}
}
Output: user "bimmler" (id 17) not found
Types ¶
This section is empty.
Source Files
Directories