assert

package
v0.8.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 15, 2022 License: MIT Imports: 7 Imported by: 60

Documentation

Overview

Package assert includes runtime assertion helpers. They follow same practise used in C/C++ development where you can see lines like: 

assert(ptr != NULL)
...
assert(!"not implemented")

With the help of the assert package we can write the same preconditions in Go: 

assert.NotNil(ptr)
...
assert.NotImplemented()

The package offers a convenient way to set preconditions to code which allow us detect programming errors and API violations faster. Still allowing production-time error handling if needed. When used with the err2 package panics can be turned to normal Go's error values by using proper Asserter like P: 

assert.P.True(s != "", "sub-command cannot be empty")

Please see the code examples for more information.

Note. assert.That's performance is equal to the if-statement. Most of the generics-based versions are as fast, but some of them (Equal, SLen, MLen) aren't. If your algorithm is performance-critical please run `make bench` in the err2 repo and decide case by case.

Note. Format string functions need to be own instances because of Go's vet and test tool integration.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// P is a production Asserter that sets panic objects to errors which
	// allows err2 handlers to catch them.
	P = AsserterToError

	// D is a development Asserter that sets panic objects to strings that
	// doesn't by caught by err2 handlers.
	D Asserter = AsserterDebug

	// DefaultAsserter is a default asserter used for package-level functions
	// like assert.That(). It is the same as the production asserter P, which
	// treats assert failures as Go errors, but in addition to that, it formats
	// the assertion message properly. Naturally, only if err2 handlers are
	// found in the call stack, these errors are caught.
	//
	// You are free to set it according to your current preferences. For
	// example, it might be better to panic about every assertion fault during
	// the tests. When in other cases, throw an error.
	DefaultAsserter = AsserterToError | AsserterFormattedCallerInfo
)

Functions

func CNotNil added in v0.8.0 

func CNotNil[T any](c chan T, a ...any)

CNotNil asserts that the channel is not nil. If it is it panics/errors (default Asserter) with the given message.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(c chan byte) (err error) {
		defer err2.Annotate("sample", &err)

		assert.CNotNil(c)
		return err
	}
	var c chan byte
	err := sample(c)
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:90 ExampleCNotNil.func1 channel is nil

func Equal added in v0.8.0 

func Equal[T comparable](val, want T, a ...any)

Equal asserts that the values are equal. If not it panics/errors (current Asserter) with the given message.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Annotate("sample", &err)

		assert.Equal(len(b), 3)
		return err
	}
	err := sample([]byte{1, 2})
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:116 ExampleEqual.func1 got 2, want 3

func MLen added in v0.8.0 

func MLen[T comparable, U any](obj map[T]U, length int, a ...any)

MLen asserts that the length of the map is equal to the given. If not it panics/errors (current Asserter) with the given message. Note! This is reasonably fast but not as fast as 'That' because of lacking inlining for the current implementation of Go's type parametric functions.

func MNotEmpty added in v0.8.3 

func MNotEmpty[T comparable, U any](obj map[T]U, length int, a ...any)

MNotEmpty asserts that the map is not empty. If it is, it panics/errors (current Asserter) with the given message. Note! This is reasonably fast but not as fast as 'That' because of lacking inlining for the current implementation of Go's type parametric functions.

func MNotNil added in v0.8.0 

func MNotNil[T comparable, U any](m map[T]U, a ...any)

MNotNil asserts that the map is not nil. If it is it panics/errors (default Asserter) with the given message.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b map[string]byte) (err error) {
		defer err2.Annotate("sample", &err)

		assert.MNotNil(b)
		return err
	}
	var b map[string]byte
	err := sample(b)
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:77 ExampleMNotNil.func1 map is nil

func NotEmpty added in v0.8.3 

func NotEmpty(obj string, a ...any)

NotEmpty asserts that the string is not empty. If it is, it panics/errors (current Asserter) with the given message.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b string) (err error) {
		defer err2.Annotate("sample", &err)

		assert.NotEmpty(b)
		return err
	}
	err := sample("")
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:193 ExampleNotEmpty.func1 string shouldn't be empty

func NotEqual added in v0.8.0 

func NotEqual[T comparable](val, want T, a ...any)

NotEqual asserts that the values aren't equal. If they are it panics/errors (current Asserter) with the given message.

func NotImplemented added in v0.8.3 

func NotImplemented(a ...any)

NotImplemented always panics with 'not implemented' assertion message.

func NotNil added in v0.8.0 

func NotNil[T any](p *T, a ...any)

NotNil asserts that the value is not nil. If it is it panics/errors (default Asserter) with the given message.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b *byte) (err error) {
		defer err2.Annotate("sample", &err)

		assert.NotNil(b)
		return err
	}
	var b *byte
	err := sample(b)
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:64 ExampleNotNil.func1 pointer is nil

func SLen added in v0.8.0 

func SLen[T any](obj []T, length int, a ...any)

SLen asserts that the length of the slice is equal to the given. If not it panics/errors (current Asserter) with the given message. Note! This is reasonably fast but not as fast as 'That' because of lacking inlining for the current implementation of Go's type parametric functions.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Annotate("sample", &err)

		assert.SLen(b, 3)
		return err
	}
	err := sample([]byte{1, 2})
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:128 ExampleSLen.func1 got 2, want 3

func SNotEmpty added in v0.8.3 

func SNotEmpty[T any](obj []T, a ...any)

SNotEmpty asserts that the slice is not empty. If it is, it panics/errors (current Asserter) with the given message. Note! This is reasonably fast but not as fast as 'That' because of lacking inlining for the current implementation of Go's type parametric functions.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Annotate("sample", &err)

		assert.SNotEmpty(b)
		return err
	}
	err := sample([]byte{})
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:181 ExampleSNotEmpty.func1 slice shouldn't be empty

func SNotNil added in v0.8.0 

func SNotNil[T any](s []T, a ...any)

SNotNil asserts that the slice is not nil. If it is it panics/errors (default Asserter) with the given message.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Annotate("sample", &err)

		assert.SNotNil(b)
		return err
	}
	var b []byte
	err := sample(b)
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:103 ExampleSNotNil.func1 slice is nil

func That added in v0.8.0 

func That(term bool, a ...any)

That asserts that the term is true. If not it panics with the given formatting string. Thanks to inlining, the performance penalty is equal to a single 'if-statement' that is almost nothing.

Types

type Asserter 

type Asserter uint32

Asserter is type for asserter object guided by its flags. 

const (
	// AsserterDebug is the default mode where all asserts are treaded as
	// panics
	AsserterDebug Asserter = 0

	// AsserterToError is Asserter flag to guide asserter to use Go's error
	// type for panics.
	AsserterToError Asserter = 1 << iota

	// AsserterStackTrace is Asserter flag to print call stack to stdout.
	AsserterStackTrace

	// AsserterCallerInfo is an asserter flag to add info of the function
	// asserting. It includes filename, line number and function name.
	AsserterCallerInfo

	// AsserterFormattedCallerInfo is an asserter flag to add info of the function
	// asserting. It includes filename, line number and function name in
	// multi-line formatted string output.
	AsserterFormattedCallerInfo
)

func (Asserter) Empty 

func (asserter Asserter) Empty(obj any, msg ...any)

Empty asserts that length of the object is zero. If not it panics with the given formatting string. Note! This is slow.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Annotate("sample", &err)

		assert.P.Empty(b)
		return err
	}
	err := sample([]byte{1, 2})
	fmt.Printf("%v", err)
}

Output:

sample: got 2, want == 0

func (Asserter) EqualInt 

func (asserter Asserter) EqualInt(val, want int, a ...any)

EqualInt asserts that integers are equal. If not it panics/errors (current Asserter) with the given msg.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Annotate("sample", &err)

		assert.P.EqualInt(len(b), 3)
		return err
	}
	err := sample([]byte{1, 2})
	fmt.Printf("%v", err)
}

Output:

sample: got 2, want 3

func (Asserter) Len 

func (asserter Asserter) Len(obj any, length int, a ...any)

Len asserts that length of the object is equal to given. If not it panics/errors (current Asserter) with the given msg. Note! This is very slow (before we have generics). If you need performance use EqualInt. It's not so convenient, though.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Annotate("sample", &err)

		assert.P.Len(b, 3)
		return err
	}
	err := sample([]byte{1, 2})
	fmt.Printf("%v", err)
}

Output:

sample: got 2, want 3

func (Asserter) Lenf 

func (asserter Asserter) Lenf(obj any, length int, format string, a ...any)

Lenf asserts that length of the object is equal to given. If not it panics/errors (current Asserter) with the given msg. Note! This is very slow (before we have generics). If you need performance use EqualInt. It's not so convenient, though.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Annotate("sample", &err)

		assert.P.Lenf(b, 3, "actual len = %d", len(b))
		return err
	}
	err := sample([]byte{1, 2})
	fmt.Printf("%v", err)
}

Output:

sample: actual len = 2

func (Asserter) NoImplementation 

func (asserter Asserter) NoImplementation(a ...any)

NoImplementation always fails with no implementation.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(m int) (err error) {
		defer err2.Annotate("sample", &err)

		switch m {
		case 1:
			return nil
		default:
			assert.P.NoImplementation()
		}
		return err
	}
	err := sample(0)
	fmt.Printf("%v", err)
}

Output:

sample: not implemented

func (Asserter) NotEmpty 

func (asserter Asserter) NotEmpty(obj any, msg ...any)

NotEmpty asserts that length of the object greater than zero. If not it panics with the given formatting string. Note! This is slow.

func (Asserter) NotEmptyf 

func (asserter Asserter) NotEmptyf(obj any, format string, msg ...any)

NotEmptyf asserts that length of the object greater than zero. If not it panics with the given formatting string. Note! This is slow.

func (Asserter) True 

func (asserter Asserter) True(term bool, a ...any)

True asserts that term is true. If not it panics with the given formatting string. Note! This and Truef are the most performant of all the assertion functions.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func() (err error) {
		defer err2.Annotate("sample", &err)

		assert.P.True(false, "assertion test")
		return err
	}
	err := sample()
	fmt.Printf("%v", err)
}

Output:

sample: assertion test

func (Asserter) Truef 

func (asserter Asserter) Truef(term bool, format string, a ...any)

Truef asserts that term is true. If not it panics with the given formatting string.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func() (err error) {
		defer err2.Annotate("sample", &err)

		assert.P.Truef(false, "assertion test %d", 2)
		return err
	}
	err := sample()
	fmt.Printf("%v", err)
}

Output:

sample: assertion test 2

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.