assert

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Mar 16, 2022 License: MIT Imports: 4 Imported by: 60

Documentation

Overview

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

assert(ptr != NULL)

or 

assert(!"not implemented")

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

assert.NotNil(ptr)

or 

assert.NoImplementation()

The package offers a convenient way to set preconditions to code which allow us detect programming errors and API usage violations faster. Still allowing proper path to 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! 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 types panic objects to errors which
	// allows err2 handlers to catch them.
	P = AsserterToError

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

	// DefaultAsserter is a default asserter used for package level functions.
	// If not changed it is the same as P the production asserter that treats
	// assert failures as Go errors, i.e. if err2 handlers are found in the
	// callstack these errors are caught.
	DefaultAsserter = AsserterToError
)

Functions

func CNotNil added in v0.8.0 

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

CNotNil asserts that value in not nil. If it is it panics/errors (default Asserter) with the given msg.

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: channel is nil

func Equal added in v0.8.0 

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

Equal asserts that values 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.Equal(len(b), 3)
		return err
	}
	err := sample([]byte{1, 2})
	fmt.Printf("%v", err)
}

Output:

sample: 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 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.

func MNotNil added in v0.8.0 

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

MNotNil asserts that value in not nil. If it is it panics/errors (default Asserter) with the given msg.

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: map is nil

func NotEqual added in v0.8.0 

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

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

func NotNil added in v0.8.0 

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

NotNil asserts that value in not nil. If it is it panics/errors (default 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.NotNil(b)
		return err
	}
	var b *byte
	err := sample(b)
	fmt.Printf("%v", err)
}

Output:

sample: pointer is nil

func SLen added in v0.8.0 

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

SLen 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.SLen(b, 3)
		return err
	}
	err := sample([]byte{1, 2})
	fmt.Printf("%v", err)
}

Output:

sample: got 2, want 3

func SNotNil added in v0.8.0 

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

SNotNil asserts that value in not nil. If it is it panics/errors (default 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.SNotNil(b)
		return err
	}
	var b []byte
	err := sample(b)
	fmt.Printf("%v", err)
}

Output:

sample: slice is nil

func That added in v0.8.0 

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

That asserts that term is true. If not it panics with the given formatting string. Note! That is the most performant of all the assertion functions.

Types

type Asserter 

type Asserter uint32

Asserter is type for asserter object guided by its flags. 

const (
	// 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
)

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.