ks

Documentation

Overview

Package ks ("kitchen sink") implements assorted helpful things that don't fit anywhere else.

Index

• func Assert(q bool, args ...interface{})
• func FirstNonZero[T comparable](args ...T) T
• func Identity[X any](x X) X
• func IfThenElse[X any](q bool, ifTrue X, ifFalse X) X
• func IfThenElseLazy[X any](q bool, ifTrue func() X, ifFalse func() X) X
• func In[X comparable](x X, xs ...X) bool
• func MaybeFunc[V any](f func() (V, bool)) func() Maybe[V]
• func Never(args ...interface{})
• func Range[K comparable, V any, R Rangeable[K, V]](f func(K, V) error, r R) (K, error)
• func ResultFunc[V any](f func() (V, error)) func() Result[V]
• func TestCompletes(t *testing.T, duration time.Duration, f func(), args ...interface{})
• func WithCloser[T io.Closer](opener func() (T, error), do func(v T) error) error
• func WrapBlock(message string, columns int) string
• func Zero[T any]() T
• type Item
• type Maybe
• type Pair
• type Rangeable
• type Result

Examples

• Zero

Functions

func Assert

func Assert(q bool, args ...interface{})

Assert panics if the value is not true. Optionally, follow with a printf-style format string and arguments.

func FirstNonZero

func FirstNonZero[T comparable](args ...T) T

FirstNonZero returns the first argument that isn't equal to the zero value of T, or otherwise the zero value.

func Identity

func Identity[X any](x X) X

Identity implements the function f(x) => x.

func IfThenElse

func IfThenElse[X any](
	q bool,
	ifTrue X,
	ifFalse X,
) X

IfThenElse returns a value based on a boolean condition, q. Iff q is true, returns the ifTrue. Iff q is false, returns ifFalse. This IfThenElse expression (as distinct from If-Then-Else statements) is much like the ternary operator in some other languages, however it is not short-circuited and both arguments are evaluated.

For a lazily-evaluated version, see IfThenElseLazy.

func IfThenElseLazy

func IfThenElseLazy[X any](
	q bool,
	ifTrue func() X,
	ifFalse func() X,
) X

IfThenElseLazy returns a lazily-evaluated value based on a boolean condition, q. Iff q is true, returns the return value of ifTrue(). Iff q is false, returns the return value of ifFalse(). This IfThenElse expression (as distinct from If-Then-Else statements) is much like the ternary operator in some other languages.

For a non-lazy version, see IfThenElse.

func In

func In[X comparable](x X, xs ...X) bool

In returns true if x equals any of the following arguments.

func MaybeFunc

func MaybeFunc[V any](f func() (V, bool)) func() Maybe[V]

MaybeFunc accepts a function that returns a naked (value, exists) and returns a function that returns a Maybe{value, exists} instead.

func Never

func Never(args ...interface{})

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

Deprecated: use must.Never instead.

func Range

func Range[K comparable, V any, R Rangeable[K, V]](
	f func(K, V) error,
	r R,
) (K, error)

Range calls some function f(k, v) => err over any Rangeable of (K, V)s. If the return value of f is not nil, the iteration stops immediately, and returns (k, err) for the given k. Otherwise, returns (zero, nil).

Caution: invalid key types will panic at runtime. The key type must be int for any type other than a map. See Rangeable for details. In a channel, the key is always zero.

func ResultFunc

func ResultFunc[V any](f func() (V, error)) func() Result[V]

ResultFunc accepts a function that returns a naked (value, error) and returns a function that returns a Result{value, error} instead.

func TestCompletes

func TestCompletes(t *testing.T, duration time.Duration, f func(), args ...interface{})

TestCompletes executes f (in a goroutine), and blocks until either f returns, or the provided duration has elapsed. In the latter case, calls t.Errorf to fail the test. Provide optional format string and arguments to add context to the test error message.

func WithCloser

func WithCloser[T io.Closer](opener func() (T, error), do func(v T) error) error

WithCloser calls a function on a resource that can be opened and closed. The resource if automatically closed as soon as that function returns. Checks for errors opening the resource, checks for errors returned by the provided function, and checks for errors closing the resource.

For example:

opener := func(name) func() (*os.File, error) { return os.Open(name) }
err := With(opener("example.txt"), func(f *os.File) error {
   ...
   return nil
}) // calls .Close() automatically

func WrapBlock

func WrapBlock(message string, columns int) string

WrapBlock word-wraps a whitespace-delimited string to a given number of columns. The column length is given in runes (Unicode code points), not bytes.

This is a simple implementation without any configuration options, designed for circumstances such as quickly wrapping a single error message for display.

Save for bug fixes, the output of this function for any given input is frozen and will not be changed in future. This means you can reliably test against the return value of this function without your tests being brittle.

Caveat: Single words longer than the column length will be truncated.

Caveat: all whitespace, including existing new lines, is collapsed. An input consisting of multiple paragraphs will be wrapped into a single word-wrapped paragraph.

Caveat: assumes all runes in the input string represent a glyph of length one. Whether this is true or not depends on how the display and font treats different runes. For example, some runes where [Unicode.IsGraphic] returns false might still be displayed as a special escaped character. Some letters might be displayed wider than usual, even in a monospaced font.

func Zero

func Zero[T any]() T

Zero returns the zero value for any type.

Example

package main

import (
	"fmt"

	"github.com/tawesoft/golib/v2/ks"
)

func main() {

	type thing struct {
		number int
		phrase string
	}

	fmt.Printf("The zero value is %+v\n", ks.Zero[thing]())
	fmt.Printf("The zero value is %+v\n", ks.Zero[int32]())

}

Output:

The zero value is {number:0 phrase:}
The zero value is 0

Types

type Item

type Item[K comparable, V any] struct {
	Key   K
	Value V
}

Item is any Key, Value pair. Type K is any type that would be suitable as a KeyType in a Go [builtin.map].

A downstream package should use this to define its own number type (e.g. type Item[K comparable, V any] ks.Item[K, V]) rather than use the type directly from here in its exported interface.

type Maybe

type Maybe[V any] struct {
	Value V
	Ok    bool
}

Maybe is a (value, ok) "sum type" that has a value only when Ok is true.

Note that in many cases, it is more idiomatic for a function to return a naked (value, ok). The Maybe type is more useful in iterators.

type Pair

type Pair[K comparable, V any] struct {
	Key   K
	Value V
}

Pair is any Key, Value pair. Type K is any type that would be suitable as a KeyType in a Go [builtin.map].

type Rangeable

type Rangeable[K comparable, V any] interface {
	~string | ~map[K]V | ~[]V | chan V
}

Rangeable defines any type of value x where it is possible to range over using "for k, v := range x" or "v := range x" (in the case of a channel, only "v := range x" is permitted). For every Rangeable other than a map, K must always be int.

type Result

type Result[V any] struct {
	Value V
	Error error
}

Result is a (value, error) "sum type" that has a value only when Error is nil.

Note that in many cases, it is more idiomatic for a function to return a naked (value, error). The Result type is more useful in iterators.