diff options
Diffstat (limited to 'src/errors/errors.go')
| -rw-r--r-- | src/errors/errors.go | 87 |
1 files changed, 87 insertions, 0 deletions
diff --git a/src/errors/errors.go b/src/errors/errors.go new file mode 100644 index 0000000..9e3860a --- /dev/null +++ b/src/errors/errors.go @@ -0,0 +1,87 @@ +// 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). +// +// [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]. +// +// [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 [*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") |