errors

func As ¶

func As(err error, target interface{}) bool

As finds the first error in err's chain that matches target, and if so, sets target to that error value and returns true. Otherwise, it returns false.

The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.

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(interface{}) 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.

package main

import (
	"fmt"
	"os"

	"github.com/go-faster/errors"
)

func main() {
	_, err := os.Open("non-existing")
	if err != nil {
		var pathError *os.PathError
		if errors.As(err, &pathError) {
			fmt.Println("Failed at path:", pathError.Path)
		}
	}

}

Output:

Failed at path: non-existing

func DisableTrace ¶

func DisableTrace()

DisableTrace disables capturing caller frames.

func Errorf ¶

func Errorf(format string, a ...interface{}) error

Errorf creates new error with format.

func FormatError ¶

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.

package main

import (
	"fmt"

	"github.com/go-faster/errors"
)

type MyError2 struct {
	Message string
	frame   errors.Frame
}

func (m *MyError2) Error() string {
	return m.Message
}

func (m *MyError2) Format(f fmt.State, c rune) { // implements fmt.Formatter
	errors.FormatError(m, f, c)
}

func (m *MyError2) FormatError(p errors.Printer) error { // implements errors.Formatter
	p.Print(m.Message)
	if p.Detail() {
		m.frame.Format(p)
	}
	return nil
}

func main() {
	err := &MyError2{Message: "oops", frame: errors.Caller(1)}
	fmt.Printf("%v\n", err)
	fmt.Println()
	fmt.Printf("%+v\n", err)
}

Output:

func Into ¶ added in v0.6.0

func Into[T error](err error) (val T, ok bool)

Into finds the first error in err's chain that matches target type T, and if so, returns it.

Into is type-safe alternative to As.

package main

import (
	"fmt"
	"os"

	"github.com/go-faster/errors"
)

func main() {
	_, err := os.Open("non-existing")
	if err != nil {
		if pathError, ok := errors.Into[*os.PathError](err); ok {
			fmt.Println("Failed at path:", pathError.Path)
		}
	}

}

Output:

Failed at path: non-existing

func Is ¶

func Is(err, target error) bool

Is 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.

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.

func Join ¶ added in v0.7.0

func Join(errs ...error) error

Join returns an error that wraps the given errors. Any nil error values are discarded. Join returns nil if every value in errs is nil. 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.

A non-nil error returned by Join implements the Unwrap() []error method.

Available only for go 1.20 or superior.

func Must ¶ added in v0.6.0

func Must[T any](val T, err error) T

Must is a generic helper, like template.Must, that wraps a call to a function returning (T, error) and panics if the error is non-nil.

package main

import (
	"fmt"
	"net/url"

	"github.com/go-faster/errors"
)

func main() {
	r := errors.Must(url.Parse(`https://google.com`))
	fmt.Println(r.String())

}

Output:

https://google.com

func New ¶

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.

package main

import (
	"fmt"

	"github.com/go-faster/errors"
)

func main() {
	err := errors.New("emit macho dwarf: elf header corrupted")
	if err != nil {
		fmt.Print(err)
	}
}

Output:

emit macho dwarf: elf header corrupted

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

func Opaque ¶

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 Trace ¶

func Trace() bool

Trace reports whether caller stack capture is enabled.

func Unwrap ¶

func Unwrap(err error) error

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 ¶

func Wrap(err error, message string) error

Wrap error with message and caller.

func Wrapf ¶

func Wrapf(err error, format string, a ...interface{}) error

Wrapf wraps error with formatted message and caller.