must

Documentation

Overview

Package must implements assertions.

Index

• Variables
• func Check(err error) error
• func CheckAll(errs ...error)
• func Checkf(err error, format string, args ...any) error
• func Equal[T comparable](a T, b T) bool
• func Equalf[T comparable](a T, b T, format string, args ...any) bool
• func Func[X any](f func() (X, error)) func() X
• func Never()
• func Neverf(format string, args ...any)
• func Nil(v any) bool
• func Nilf(v any, format string, args ...any) bool
• func Not(q bool) bool
• func NotNil(v any) bool
• func NotNilf(v any, format string, args ...any) bool
• func Notf(q bool, format string, args ...any) bool
• func Ok[T any](t T, ok bool) T
• func Okf[T any](t T, ok bool, format string, args ...any) T
• func Result[T any](t T, err error) T
• func Resultf[T any](t T, err error, format string, args ...any) T
• func True(q bool) bool
• func Truef(q bool, format string, args ...any) bool
• func Try[X any](f func() X) func() (x X, err error)
• type CheckError
  • func (e CheckError) Error() string
  • func (e CheckError) Unwrap() error
• type CompareError
  • func (e CompareError[T]) Error() string
  • func (e CompareError[T]) Unwrap() error
• type NeverError
  • func (e NeverError) Error() string
  • func (e NeverError) Unwrap() error
• type OkError
  • func (e OkError[T]) Error() string
  • func (e OkError[T]) Unwrap() error
• type ResultError
  • func (e ResultError[T]) Error() string
  • func (e ResultError[T]) Unwrap() error
• type ValueError
  • func (e ValueError[T]) Error() string
  • func (e ValueError[T]) Value() any

Variables

var False = Not

False is an alias of Not.

var Falsef = Notf

Falsef is an alias of Notf.

Functions

func Check

func Check(err error) error

Check panics if the error is not nil. Otherwise, it returns a nil error (so that it is convenient to chain). The raised non-nil error is wrapped in a CheckError before panicking.

func CheckAll

func CheckAll(errs ...error)

CheckAll panics at the first non-nil error. The raised non-nil error is wrapped in a CheckError before panicking.

func Checkf

func Checkf(err error, format string, args ...any) error

Checkf panics if the error is not nil. Otherwise, it always returns a nil error (so that it is convenient to chain).

The fmt.Sprintf -style format string and with optional arguments are used to format the error message raised in the panic. The original non-nil input error, and the formatted error message, are joined (see errors.Join and wrapped in CheckError before panicking.

func Equal

func Equal[T comparable](a T, b T) bool

Equal panics if the provided comparable values are not equal. Otherwise, returns true.

func Equalf

func Equalf[T comparable](a T, b T, format string, args ...any) bool

Equalf panics if the provided comparable values are not equal. Otherwise, returns true.

The fmt.Sprintf -style format string and with optional arguments are used to format the error message. The formatted error message is wrapped in CompareError before panicking.

func Func

func Func[X any](
	f func() (X, error),
) func() X

Func takes a function f() => (x, error), and returns a function f() => x that may panic in the event of error.

Any raised error is wrapped in ResultError.

func Never

func Never()

Never signifies code that should never be reached. It raises a panic when called.

func Neverf

func Neverf(format string, args ...any)

Neverf signifies code that should never be reached. It raises a panic when called.

The args parameter defines an optional fmt.Sprintf-style format string and arguments.

func Nil

func Nil(v any) bool

Nil returns true if v is (untyped) nil. Otherwise, panics.

func Nilf

func Nilf(v any, format string, args ...any) bool

Nilf returns true if v is (untyped) nil. Otherwise, panics.

The fmt.Sprintf -style format string and with optional arguments are used to format the error message. The formatted error message is wrapped in CompareError before panicking.

func Not

func Not(q bool) bool

Not is the equivalent of Equal with a false value.

func NotNil

func NotNil(v any) bool

NotNil returns true if v is not (untyped) nil. Otherwise, panics.

func NotNilf

func NotNilf(v any, format string, args ...any) bool

NotNilf returns true if v is not (untyped) nil. Otherwise, panics.

The fmt.Sprintf -style format string and with optional arguments are used to format the error message. The formatted error message is wrapped in CompareError before panicking.

func Notf

func Notf(q bool, format string, args ...any) bool

Notf is the equivalent of Equalf with a false value.

func Ok

func Ok[T any](t T, ok bool) T

Ok accepts a (value, ok) tuple as input and panics if ok is false, otherwise returns value.

func Okf

func Okf[T any](t T, ok bool, format string, args ...any) T

Okf accepts a (value, ok) tuple, and a fmt.Sprintf -style format string with optional arguments, as input and panics if ok is false. Otherwise, returns value. The formatted error message is wrapped in OkError before panicking.

func Result

func Result[T any](t T, err error) T

Result accepts a (value, err) tuple as input and panics if err != nil, otherwise returns value. The non-nil input error is wrapped in ResultError before panicking.

For example, must.Result(os.Open("doesnotexist")) may panic with an error such as "error in must.Result[*os.File]: open doesnotexist: no such file or directory", or, on success, return *os.File.

func Resultf

func Resultf[T any](t T, err error, format string, args ...any) T

Resultf accepts a (value, err) tuple, and a fmt.Sprintf -style format string with optional arguments, as input and panics if err != nil. Otherwise, returns value. The original non-nil input error, and the formatted error message, are joined (see errors.Join and wrapped in ResultError before panicking.

func True

func True(q bool) bool

True is the equivalent of Equal with a true value.

func Truef

func Truef(q bool, format string, args ...any) bool

Truef is the equivalent of Equalf with a true value.

func Try

func Try[X any](f func() X) func() (x X, err error)

Try takes a function f() => x that may panic, and instead returns a function f() => (x, error).

If the raised panic is of type error, it is returned directly. Otherwise, it is wrapped in a ValueError.

Types

type CheckError

type CheckError struct {
	// contains filtered or unexported fields
}

CheckError is the type of error that may be returned by a check function such as Check, CheckAll, and Checkf.

func (CheckError) Error

func (e CheckError) Error() string

Error implements the standard error interface.

func (CheckError) Unwrap

func (e CheckError) Unwrap() error

Unwrap (for use with errors.Is, etc.) the original error caught by a check function, or the original error and the formatted error message received by formatting variant of a check function (one ending in "f"), in which case the returned error implements `[]Unwrap()`.

type CompareError

type CompareError[T comparable] struct {
	// contains filtered or unexported fields
}

CompareError is the type of error that may be returned by a comparison function such as True or Equal, or a formating variant of a comparison function (one ending in "f").

func (CompareError[T]) Error

func (e CompareError[T]) Error() string

Error implements the standard error interface.

func (CompareError[T]) Unwrap

func (e CompareError[T]) Unwrap() error

Unwrap (for use with errors.Is, etc.) returns nil for an error returned by a comparison function, or the formatted error message received by a formating variant of a comparison function (one ending in "f").

type NeverError

type NeverError struct {
	// contains filtered or unexported fields
}

NeverError is the type of error that may be returned by Never, and represents an event that should never happen.

func (NeverError) Error

func (e NeverError) Error() string

Error implements the standard error interface.

func (NeverError) Unwrap

func (e NeverError) Unwrap() error

Unwrap (for use with errors.Is, etc.) returns nil for an error returned by Never, or the formatted error message received by Neverf.

type OkError

type OkError[T any] struct {
	// contains filtered or unexported fields
}

OkError is the type of error that may be returned by Ok or Okf.

It is generic in order to capture the information about the type of the hoped result without having to allocate memory at the error creation time.

func (OkError[T]) Error

func (e OkError[T]) Error() string

Error implements the standard error interface.

func (OkError[T]) Unwrap

func (e OkError[T]) Unwrap() error

Unwrap (for use with errors.Is, etc.) returns nil for an error returned by Ok, or the formatted error message received by Okf.

type ResultError

type ResultError[T any] struct {
	// contains filtered or unexported fields
}

ResultError is the type of error that may be returned by Result or Resultf.

It is generic in order to capture the information about the type of the hoped result without having to allocate memory at the error creation time.

func (ResultError[T]) Error

func (e ResultError[T]) Error() string

Error implements the standard error interface.

func (ResultError[T]) Unwrap

func (e ResultError[T]) Unwrap() error

Unwrap (for use with errors.Is, etc.) the original error caught by Result, or the original error and the formatted error message received by Resultf, in which case the returned error implements `[]Unwrap()`.

type ValueError

type ValueError[T any] struct {
	// contains filtered or unexported fields
}

ValueError is the type of error that may hold a value, for example a non-error value recovered from a panic in Try.

It is generic in order to capture the information about the type of the hoped result without having to allocate memory at the error creation time.

Note that the value itself is type `any`, not one that matches the generic type constraint.

func (ValueError[T]) Error

func (e ValueError[T]) Error() string

Error implements the standard error interface.

func (ValueError[T]) Value

func (e ValueError[T]) Value() any