Documentation
¶
Overview ¶
Package errors provides basic utilities to manipulate errors with a useful stacktrace. It combines the benefits of errors.New and fmt.Errorf world into a single package. It is an improved and minimal version of the popular https://github.com/pkg/errors (archived) package allowing reliable wrapping of errors with stacktrace. Unfortunately, the standard library recommended error wrapping using `%+w` is prone to errors and does not support stacktraces.
Index ¶
- func As(err error, target interface{}) bool
- func Cause(err error) error
- func Is(err, target error) bool
- func New(message string) error
- func Newf(format string, args ...interface{}) error
- func Unwrap(err error) error
- func Wrap(cause error, message string) error
- func Wrapf(cause error, format string, args ...interface{}) error
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func As ¶
As is a wrapper of built-in errors.As. It finds the first error in err's chain that matches target, and if one is found, sets target to that error value and returns true. Otherwise, it returns false.
func Cause ¶
Cause returns the result of repeatedly calling the Unwrap method on err, if err's type implements an Unwrap method. Otherwise, Cause returns the last encountered error. The difference between Unwrap and Cause is the first one performs unwrapping of one level but Cause returns the last err (whether it's nil or not) where it failed to assert the interface containing the Unwrap method. This is a replacement of errors.Cause without the causer interface from pkg/errors which actually can be sufficed through the errors.Is function. But considering some use cases where we need to peel off all the external layers applied through errors.Wrap family, it is useful ( where external SDK doesn't use errors.Is internally).
func Is ¶
Is is a wrapper of built-in errors.Is. It reports whether any error in err's chain matches target. The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.
func New ¶
New returns a new error with a stacktrace of recent call frames. Each call to New returns a distinct error value even if the text is identical. An alternative of the errors.New function from github.com/pkg/errors.
func Newf ¶
Newf is like New, but it formats input according to a format specifier. An alternative of the fmt.Errorf function.
If no args have been passed, it is same as `New` function without formatting. Character like '%' still has to be escaped in that scenario.
func Unwrap ¶
Unwrap is a wrapper of built-in errors.Unwrap. Unwrap returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning error. Otherwise, Unwrap returns nil.
func Wrap ¶
Wrap returns a new error, which wraps another error with a stacktrace containing recent call frames.
If cause is nil, it does not produce the error, similar to errors.Wrap from github.com/pkg/errors was doing. Still, avoid `errors.Wrap(nil, "...") patterns as it can lead to inefficiencies while constructing arguments to format as well readability issues. We keep this behaviour to make sure it's a drop-in replacement.
Example ¶
package main
import (
"fmt"
"github.com/efficientgo/core/errors"
)
func main() {
if err := func() error {
// Do something...
return errors.New("error!")
}(); err != nil {
wrapped := errors.Wrap(err, "doing something")
fmt.Println(wrapped)
}
}
Output: doing something: error!
func Wrapf ¶
Wrapf is like Wrap but the message is formatted with the supplied format specifier.
If no args have been passed, it is same as `Wrap` function without formatting. Character like '%' still has to be escaped in that scenario.
Example ¶
package main
import (
"fmt"
"github.com/efficientgo/core/errors"
)
func main() {
if err := func() error {
// Do something...
return errors.Newf("I am surprised %d + %d equals %v", 2, 3, 5)
}(); err != nil {
wrapped := errors.Wrapf(err, "doing some math %v times", 10)
fmt.Println(wrapped)
}
}
Output: doing some math 10 times: I am surprised 2 + 3 equals 5
Types ¶
This section is empty.
Source Files