ks

Documentation

Overview

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

Index

• func Catch[X any](f func() X) (x X, err error)
• func CheckedRange[K comparable, V any, R Rangeable[K, V]](fn func(k K, v V) error, r R) (K, V, error)
• func CheckedRangeValue[K comparable, V any, R Rangeable[K, V]](fn func(v V) error, r R) (V, error)
• func FirstNonZero[T comparable](args ...T) T
• func IfThenElse[X any](q bool, ifTrue X, ifFalse X) X
• func Must[T any](t T, err error) T
• func MustFunc[X any, Y any](f func(x X) (Y, error)) func(x X) Y
• func MustInit[K any](f func() (value K, err error), d K) K
• func Never()
• func Range[K comparable, V any, R Rangeable[K, V]](f func(K, V) bool, r R)
• func WrapBlock(message string, columns int) string
• func Zero[T any]() T
• type Item
• type Rangeable

Examples

• Zero

Functions

func Catch

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

Catch calls the input function f. If successful, Catch passes on the return value from f and also returns a nil error. If f panics, Catch recovers from the panic and returns a non-nil error.

If the panic raised by f contains is of type error, the returned error is wrapped once.

The opposite of Catch is Must: Catch(Must(os.Open(""))

func CheckedRange

func CheckedRange[K comparable, V any, R Rangeable[K, V]](
	fn func(k K, v V) error,
	r R,
) (K, V, error)

CheckedRange calls fn(k, v) => error for each key, value in the input slice, but halts if an error is returned at any point. If so, it returns the key and value being examined at the time of the error, and the encountered error, or a nil error otherwise.

func CheckedRangeValue

func CheckedRangeValue[K comparable, V any, R Rangeable[K, V]](
	fn func(v V) error,
	r R,
) (V, error)

CheckedRangeValue is like CheckedRange, but calls fn(value), not fn(key, value), and returns only (value, error), not (key, value, error).

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 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 [lazy.IfThenElse].

func Must

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

Must accepts a (value, err) tuple as input and panics if err != nil, otherwise returns value. The error raised by panic is wrapped in another error.

For example, Must(os.Open("doesnotexist")) panics with an error like "unexpected error in Must[*os.File]: open doesnotexist: no such file or directory". Must(os.Open("filethatexists")) returns a pointer to an os.File.

The opposite of Must is Catch: Catch(Must(os.Open(""))

func MustFunc

func MustFunc[X any, Y any](
	f func(x X) (Y, error),
) func(x X) Y

MustFunc accepts a function that takes an input of type X, where that function then returns a (value Y, err) tuple. Must then returns a function that panics if the returned err != nil, otherwise returns value Y. The returned error is wrapped in another error.

For example, MustFunc(os.Open) returns a function (call this f). f("doesnotexist") panics with an error (like Must), and f("filethatexists") returns a pointer to an os.File.

func MustInit

func MustInit[K any](f func() (value K, err error), d K) K

MustInit calls f, a function that returns a (value, error) tuple. If the error is nil, returns the value. Otherwise, returns the default value d. Intended to be used to initialise package-level constants.

func Never

func Never()

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

func Range

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

Range calls some function f(k, v) => bool over any Rangeable. If the return value of f is false, the iteration stops.

This is roughly equivalent to "k, v := range(x); if !f(x) { break }".

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