Documentation
¶
Index ¶
- Constants
- Variables
- func As(err error, target any) bool
- func ErrorMessage(err error) string
- func ErrorOr(err error, fn func() error) error
- func Is(err, target error) bool
- func JoinErrors(errs []error) error
- func NewF(format string, args ...any) error
- func Try(fn func() error) error
- func Unwrap(target error) error
- type ErrBadParam
- type ErrJoined
- type ErrPanic
- type ErrPool
- type ErrString
Constants ¶
const ( // DEFAULT_ERR_MSG is the error message used for when errors returns // empty messages. DEFAULT_ERR_MSG string = "something went wrong" )
Variables ¶
var ( // ErrUnsupported indicates that a requested operation cannot be // performed, because it is unsupported. Functions and methods should // not return this error but should instead return an error including // an appropriate context that satisfies the following: // // errors.Is(err, errors.ErrUnsupported) // // This can be done either by directly wrapping [ErrUnsupported] or // by implementing an `Is(error) bool` method. Functions and methods // should document the cases in which an error wrapping this will be // returned. // // Format: // "unsupported operation" ErrUnsupported error = New("unsupported operation") // ErrNilReceiver occurs when methods are called on receivers that // were not expected to be `nil`. // // Format: // "receiver must not be nil" ErrNilReceiver error = New("receiver must not be nil") // ErrOutOfBounds occurs when operations are performed on values // whose result would be out of bounds. // // Format: // "value is out of bounds" ErrOutOfBounds error = New("value is out of bounds") // ErrSizeExceeded occurs when slices are found to be longer than // the maximum allowed size, that is, the maximum slice size. // // Format: // "max slice size exceeded" ErrSizeExceeded error = New("max slice size exceeded") )
Functions ¶
func As ¶
As finds the first error in the err's tree that matches the target. If one is found, it sets the target to that error value and yields `true`. Otherwise, it yields `false`. However, it panics if the target is not a non-`nil` pointer to either a type that implements error, or to any interface type. Finally, if either the target or the error is `nil`, As yields `false`.
The tree consists of err itself, followed by the errors obtained by repeatedly calling its `Unwrap() error` or `Unwrap() []error` methods. When err wraps multiple errors, As examines err followed by a DFS traversal of its children.
An error is defined to match the target if its concrete value is assignable to the value pointed to by target, or if the error has a method `As(any) bool` such that `As(target)` yields `true`. In the latter case, the method is responsible for setting target.
Error types might provide an `As(any) bool` method so that they can be treated as if it were a different error type.
Parameters:
- err: The error to search in.
- target: The value to set if a match is found.
Returns:
- bool: `true` if a match is found, `false` otherwise.
func ErrorMessage ¶
ErrorMessage returns the error message for the given error. If the error is `nil` or its error message is empty, then DEFAULT_ERR_MSG is returned.
Parameters:
- err: The error to get the error message for.
Returns:
- string: The error message for the given error. It is never empty.
func ErrorOr ¶ added in v1.0.2
ErrorOr returns the first error that is not nil.
Parameters:
- err: The second error to check.
- fn: The function to call to get the first error.
Returns:
- error: The first error that is not nil.
func Is ¶
Is reports whether any error in the err's tree matches the target. If either err or the target is `nil`, Is yields `false`.
The tree consists of err itself, followed by the errors obtained by repeatedly calling its `Unwrap() error` or `Unwrap() []error` methods. When err wraps multiple errors, Is examines err followed by a DFS traversal of its children.
An error is defined to match the target if it is equal to that target or if it implements a method `Is(error) bool` such that it yields `true`.
Error types might provide an `Is(error) bool` method so that they can be treated as if it were equivalent to an existing error. This method should only shallowly compare err and the target and not call any unwrap methods on either.
Parameters:
- err: The error to search in.
- target: The error to match.
Returns:
- bool: `true` if a match is found, `false` otherwise.
func JoinErrors ¶ added in v1.0.2
JoinErrors joins the errors in errs together into a single error, rejecting any `nil` errors. If there are no non-`nil` errors, no error is returned
If there is exactly one non-`nil` error, it is returned as is. Otherwise, an new joined error is returned.
Lastly, if there are more than common.MAX_SLICE_SIZE non-`nil` errors, the result is truncated.
Parameters:
- errs: The errors to join together.
Returns:
- error: An error that wraps the given errors.
Errors:
- ErrJoined: If there is more than one non-`nil` error in the list.
- any other error: If there is only one non-`nil` error in the list.
Format:
"<error 1>\n<error 2>\n...\n<error n>"
Due to implementation details, the error messages are sorted in alphabetical order and duplicate messages are removed.
func NewF ¶ added in v1.0.1
NewF creates a new error with the given format and arguments.
Parameters:
- format: The format string.
- args: The arguments to the format string.
Returns:
- error: The newly created error. It is never `nil`.
func Try ¶ added in v1.0.0
Try is a control flow function that catches the error returned by the function and returns it. If the function panics, Try returns the panic value.
Does nothing if no function is provided.
Parameters:
- fn: The function to call.
Returns:
- error: The error returned by the function.
Errors:
- ErrString: If the function panics with a string message.
- ErrPanic: If the function panics with any non-`error` value.
- any other error: If the function panics with an `error` value or returns an error.
Types ¶
type ErrBadParam ¶ added in v0.1.6
type ErrBadParam struct {
// contains filtered or unexported fields
}
ErrBadParam is the error type for errors that occur when functions (or methods) are called with parameters that are not valid (i.e., not as said functions (or methods) were expecting).
func NewErrBadParam ¶ added in v0.1.6
func NewErrBadParam(name, reason string) *ErrBadParam
NewErrBadParam creates a new ErrBadParam error with the given parameter name and reason.
Parameters:
- name: The name of the parameter that is not valid.
- reason: The message explaining why the parameter is not valid.
Returns:
- *ErrBadParam: The newly created error. It is never `nil`.
Format:
"parameter (<name>) <reason>"
Where:
- <name> is the name of the parameter that is not valid.
- <reason> is the message explaining why the parameter is not valid. Defaults to "is not valid" if empty.
If <name> is empty, then the error message is as follows:
"parameter <reason>"
Where, <reason> is the message explaining why the parameter is not valid. Defaults to "is not valid" if empty.
func NewErrNilParam ¶ added in v0.1.6
func NewErrNilParam(name string) *ErrBadParam
NewErrNilParam is a convenience function that creates a new ErrBadParam with the given parameter name for when `nil` parameters are passed to functions (or methods) that were expecting non-`nil` parameters.
Parameters:
- name: The parameter that was `nil`.
Returns:
- *ErrBadParam: The newly created error. It is never `nil`.
Format:
"parameter (<name>) must not be nil"
Where, <name> is the name of the parameter that was `nil`.
If <name> is empty, then the error message is as follows:
"parameter must not be nil"
func (ErrBadParam) Error ¶ added in v0.1.6
func (ebp ErrBadParam) Error() string
Error implements error.
func (ErrBadParam) Name ¶ added in v0.1.6
func (ebp ErrBadParam) Name() string
Name returns the name of the parameter that is not valid.
Returns:
- string: The name of the parameter that is not valid.
type ErrJoined ¶ added in v1.0.2
type ErrJoined struct {
// contains filtered or unexported fields
}
ErrJoined is the error type used for joining multiple errors together.
type ErrPanic ¶ added in v1.0.0
type ErrPanic struct {
// contains filtered or unexported fields
}
ErrPanic is the error type for panics.
type ErrPool ¶ added in v1.0.2
type ErrPool struct {
// contains filtered or unexported fields
}
ErrPool is a pool-like accumulator for errors. While this data structure can be involved in operations that make use of concurrency, ErrPool itself is not thread-safe.
This data structure is used inside operations that, despite involving multiple sub components (e.g., concurrency, I/O, etc.), a failure by one component does not require to stop execution of the remaining components.
func NewErrPool ¶ added in v1.0.2
func NewErrPool() *ErrPool
NewErrPool creates a new ErrPool.
Returns:
- *ErrPool: The newly created ErrPool. It is never `nil`.
func (*ErrPool) Capture ¶ added in v1.0.2
Capture captures errors from a receive-only channel in a more efficient way than calling the [Put] multiple times.
If the channel is `nil` or closed, no error is captured. Same goes for when the pool is full.
Like with [Put], `nil` errors are ignored. However, unlike with [Put], as soon as an assert.ErrAssert is encountered, [Capture] throws it up.
Parameters:
- err_ch: The channel to capture errors from.
Returns:
- error: An error if capturing the errors from the channel fails.
Errors:
- ErrNilReceiver: If the receiver is nil.
func (*ErrPool) Err ¶ added in v1.0.2
Err returns the result of the pool by joining all the errors that were inserted into the pool. If the receiver is `nil` or the pool is empty, no error is returned.
As a special case, if the pool contains only one error, it is returned as is. In any other case, errors are joined together with the common.Join function.
Returns:
- error: The result of the pool.
func (*ErrPool) Grow ¶ added in v1.0.2
Grow allows to optimize the performance of pooling errors by pre-allocating the underlying slice.
If amount is 0, the pool is returned as is. But, if it is greater than common.MAX_SLICE_SIZE, the size is capped to this upper limit.
Parameters:
- amount: The number of elements to grow the pool by.
Returns:
- error: An error if growing the pool fails.
Errors:
- ErrNilReceiver: If the receiver is nil.
type ErrString ¶
type ErrString struct {
// contains filtered or unexported fields
}
ErrString is the most basic implementation of the error interface.
func New ¶
New creates a new ErrString with the given message.
Parameters:
- message: The error message.
Returns:
- *ErrString: The newly created ErrString. It is never `nil`.
Format:
"<message>"
Where, <message> is the error message. It defaults to DEFAULT_ERR_MSG if the message is empty.
Source Files