lang

README

Golang language extensions for APItalist

This repository provides common useful extensions for the Go language, such as the Must* functions.

Import

You can import this library by typing:

go get github.com/apitalist/lang

Documentation

For documentation please see pkg.go.dev/github.com/apitalist/lang.

License

APItalist is licensed under the Unlicense and released under public domain.

Documentation

Index

• func Must(err error)
• func Must2[T any](value T, err error) T
• func Must3[T any, K any](value1 T, value2 K, err error) (T, K)
• func Must4[T any, K any, L any](value1 T, value2 K, value3 L, err error) (T, K, L)
• func Safe(f func()) (err error)
• type Comparable
• type Equals
• type Number
• type Ordered
• type SafeNotErrorPanic
  • func (s SafeNotErrorPanic) Cause() any
  • func (s SafeNotErrorPanic) Error() string

Examples

• Comparable
• Equals
• Must
• Must2
• Must3
• Must4
• Ordered
• Safe

Functions

func Must

func Must(err error)

Must provides error-to-panic conversion on return values.

Example

package main

import (
	"fmt"

	"github.com/apitalist/lang"
)

func main() {
	funcReturningError := func() error {
		return nil
	}

	// If funcReturningError returns an error, lang.Must will throw a panic.
	lang.Must(funcReturningError())
	fmt.Println("No panic thrown.")

}

Output:

No panic thrown.

func Must2

func Must2[T any](value T, err error) T

Must2 provides error-to-panic conversion with one return value.

Example

package main

import (
	"fmt"

	"github.com/apitalist/lang"
)

func main() {
	funcReturningError := func() (string, error) {
		return "Hello world!", nil
	}

	// If funcReturningError returns an error, lang.Must2 will throw a panic.
	message := lang.Must2(funcReturningError())
	fmt.Println(message)

}

Output:

Hello world!

func Must3

func Must3[T any, K any](value1 T, value2 K, err error) (T, K)

Must3 provides error-to-panic conversion with two return values.

Example

package main

import (
	"fmt"

	"github.com/apitalist/lang"
)

func main() {
	funcReturningError := func() (string, string, error) {
		return "Hello", "world!", nil
	}

	// If funcReturningError returns an error, lang.Must3 will throw a panic.
	message1, message2 := lang.Must3(funcReturningError())
	fmt.Println(message1, message2)

}

Output:

Hello world!

func Must4

func Must4[T any, K any, L any](value1 T, value2 K, value3 L, err error) (T, K, L)

Must4 provides error-to-panic conversion with three return values.

Example

package main

import (
	"fmt"

	"github.com/apitalist/lang"
)

func main() {
	funcReturningError := func() (string, string, string, error) {
		return "Hello", "world", "!", nil
	}

	// If funcReturningError returns an error, lang.Must4 will throw a panic.
	message1, message2, message3 := lang.Must4(funcReturningError())
	fmt.Println(message1, message2, message3)

}

Output:

Hello world !

func Safe

func Safe(f func()) (err error)

Safe runs the specified function and, if a panic occurs with an error, returns the error. If a panic happens with a non-error type, the panic is wrapped in a SafeNotErrorPanic

Example

package main

import (
	"errors"
	"fmt"

	"github.com/apitalist/lang"
)

func main() {
	err := lang.Safe(
		func() {
			panic("oh no")
		},
	)
	if err != nil {
		var t lang.SafeNotErrorPanic
		if errors.As(err, &t) {
			fmt.Printf("An error happened: %v", t.Cause())
		}
	}

}

Output:

An error happened: oh no

Types

type Comparable

type Comparable[T any] interface {
	// Compare compares the current object to the other object and returns a negative number if the current object is
	// smaller than the other, a positive number if it is larger, and 0 if it is equal.
	Compare(other T) int
}

Comparable declares that a type can be compared to another using the Compare method.

Example

package main

import "fmt"

type comparableComplexObject struct {
	data int
}

func (o comparableComplexObject) Compare(b *comparableComplexObject) int {
	return o.data - b.data
}

func main() {
	var a, b *comparableComplexObject
	a = &comparableComplexObject{
		1,
	}
	b = &comparableComplexObject{
		2,
	}

	comparison := a.Compare(b)
	if comparison < 0 {
		fmt.Println("A is smaller than B")
	} else if comparison > 0 {
		fmt.Println("B is smaller than A")
	} else {
		fmt.Println("A and B are equal")
	}

}

Output:

A is smaller than B

type Equals

type Equals[T any] interface {
	// Equals compares the current object with the passed other object and returns true if the two objects are logically
	// equal.
	Equals(other T) bool
}

Equals defines the Equals method to compare the current object to another object. It does not, however, give you the ability to compare two objects with the equals (=) operator, which will always compare by value.

Example

package main

import "fmt"

type complexObject struct {
	number int
}

func (c *complexObject) Equals(other *complexObject) bool {
	return c.number == other.number
}

func main() {
	var a, b *complexObject
	a = &complexObject{
		1,
	}
	b = &complexObject{
		2,
	}

	if a.Equals(b) {
		fmt.Println("A equals B")
	} else {
		fmt.Println("A does not equal B")
	}

}

Output:

A does not equal B

type Number

type Number interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr | ~float32 | ~float64
}

Number is an interface that represents all the ordered number types.

type Ordered

type Ordered interface {
	Number | ~string
}

Ordered is an interface that collects all primitives that can be ordered. This is typically helpful when creating Go 1.18 generic definitions:

func compare[T lang.Ordered](a, b T) int {
}

In the example above, a and b can be compared with the smaller than (<) and larger than (>) operators despite not knowing their types. Ideally, Golang will, at some point, add a native interface for this and we will deprecate this extension.

Example

package main

import (
	"fmt"

	"github.com/apitalist/lang"
)

func compare[T lang.Ordered](a, b T) int {
	if a < b {
		return -1
	} else if a > b {
		return 1
	} else {
		return 0
	}
}

func main() {
	a := 1
	b := 2
	if compare(a, b) < 0 {
		fmt.Println("A is smaller than B")
	} else if compare(a, b) > 0 {
		fmt.Println("B is smaller than A")
	} else {
		fmt.Println("A and B are equal")
	}

}

Output:

A is smaller than B

type SafeNotErrorPanic

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

SafeNotErrorPanic is an error type that is returned if a Safe function catches a non-error panic.

func (SafeNotErrorPanic) Cause

func (s SafeNotErrorPanic) Cause() any

Cause returns the originally caught panic.

func (SafeNotErrorPanic) Error

func (s SafeNotErrorPanic) Error() string

Error returns the text with the panic.