mathutil

Documentation

Overview

Package mathutil offers some useful utility functions which are missing from the standard packages.

Index

• Constants
• func AlmostEqual(a, b, epsilon float64) bool
• func BitsInType(v any) int
• func Digits[T constraints.Signed](v T) int
• func DigitsInBase[T constraints.Signed](v T, b uint) int
• func DigitsInBaseUnsigned[T constraints.Unsigned](v T, b uint) int
• func DigitsUnsigned[T constraints.Unsigned](v T) int
• func FmtValsForSigFigs[T constraints.Float](sf uint8, v T) (width, precision int)
• func FmtValsForSigFigsMulti[T constraints.Float](sf uint8, v T, vals ...T) (width, precision int)
• func MaxOf[F constraints.Float](vals ...F) F
• func MaxOfInt[I constraints.Integer](vals ...I) I
• func MinOf[F constraints.Float](vals ...F) F
• func MinOfInt[I constraints.Integer](vals ...I) I
• func Roughly[F constraints.Float](v, accuracy F) F
• func WithinNPercent(a, b, epsilon float64) bool
• type Rational
  • func RationalApproximation(v, accuracy float64) (Rational, error)
  • func RationalApproximationByFareysAlgo(v, accuracy float64) (Rational, error)
  • func SetRational(intPart float64, n, d, sign int64) (Rational, error)
  • func (r Rational) AsFloat64() float64
  • func (r Rational) Invert() Rational
  • func (r Rational) Proximity(v float64) float64
  • func (r Rational) String() string

Constants

const MaxFareyTrials = 100

MaxFareyTrials is the maximum number of attempts that will be made to find a Rational Approximation by taking entries in the Farey Sequence. If no approximation within the accuracy threshold has been found by this point an error is returned indicating that the Farey sequence converges too slowly. Conversion can be very slow for values, for instance, with fractional parts very close to the ends of the interval [0,1].

Functions

func AlmostEqual

func AlmostEqual(a, b, epsilon float64) bool

AlmostEqual returns true if a and b are within epsilon of one another regardless of sign.

func BitsInType

func BitsInType(v any) int

BitsInType returns the number of bits needed to store this type

func Digits

func Digits[T constraints.Signed](v T) int

Digits returns the characters needed to print the value (the number of digits plus potentially a sign marker)

func DigitsInBase

func DigitsInBase[T constraints.Signed](v T, b uint) int

DigitsInBase returns the characters needed to print the value v in base b. Note that the base must be 2 or more; if not a panic is generated.

func DigitsInBaseUnsigned

func DigitsInBaseUnsigned[T constraints.Unsigned](v T, b uint) int

DigitsInBaseUnsigned returns the characters needed to print the value v (of an unsigned integer type) in base b. Note that the base must be 2 or more; if not a panic is generated.

func DigitsUnsigned

func DigitsUnsigned[T constraints.Unsigned](v T) int

DigitsUnsigned returns the characters needed to print the value

func FmtValsForSigFigs

func FmtValsForSigFigs[T constraints.Float](sf uint8, v T) (
	width, precision int,
)

FmtValsForSigFigs returns the width and precision needed to print v to at least sf significant figures. Note that sf must be greater than 0, a panic is generated if not.

There are several caveats to the use of this function: 1, it will only generate precision down to 9 digits; 2, for values very close to negative powers of 10 the results may appear incorrect and either too many or too few digits will be shown. This last caveat is as a result of the way floating point numbers are represented by computers and how Go handles constants. For instance 0.1*0.1 is not equal to 0.01.

func FmtValsForSigFigsMulti

func FmtValsForSigFigsMulti[T constraints.Float](sf uint8, v T, vals ...T) (
	width, precision int,
)

FmtValsForSigFigsMulti returns the width and precision suitable to display all the values to at least sf significant figures. For instance 3 significant figures for the pair 100.0 and 0.1 would require 3 digits before the point and 3 digits after the point, with a width of 7 and a precision of 3. Note that sf must be greater than 0, a panic is generated if not.

func MaxOf

func MaxOf[F constraints.Float](vals ...F) F

MaxOf returns the greater of the slice of values; it will panic if the slice is empty

func MaxOfInt

func MaxOfInt[I constraints.Integer](vals ...I) I

MaxOfInt returns the greater of the slice of values; it will panic if the slice is empty

func MinOf

func MinOf[F constraints.Float](vals ...F) F

MinOf returns the lesser of the slice of values; it will panic if the slice is empty

func MinOfInt

func MinOfInt[I constraints.Integer](vals ...I) I

MinOfInt returns the lesser of the slice of values; it will panic if the slice is empty

func Roughly

func Roughly[F constraints.Float](v, accuracy F) F

Roughly converts v to a value that is "roughly" the same but closer to some multiple of five or ten. It will never be more than accuracy percent from the original value. The accuracy must be less than 100 and greater than zero.

func WithinNPercent

func WithinNPercent(a, b, epsilon float64) bool

WithinNPercent returns true if a and b are within epsilon percent of one another. Strictly speaking the test is for whether the difference between a and b as a proportion of the larger value is less than epsilon. So an epsilon of 10 will test for numbers within 10% of each other. Numbers with differing sign are always considered different regardless of proximity.

Types

type Rational

type Rational struct {
	N int64
	D int64
}

Rational represents a rational number. It is used as the return value of the RationalApproximation functions.

func RationalApproximation

func RationalApproximation(v, accuracy float64) (Rational, error)

RationalApproximation returns a Rational value (a numerator N and denominator D) and an error. The values are such that the supplied value v will lie within accuracy percent of N/D. It uses continued fractions to generate the rational coefficients. Various float64 values cannot be represented in this way (including values that are too big) and a non-nil error is returned in this case.

The accuracy must be less than 100 and greater than zero.

This may generate different approximations from the RationalApproximationByFareysAlgo func.

func RationalApproximationByFareysAlgo

func RationalApproximationByFareysAlgo(v, accuracy float64) (Rational, error)

RationalApproximationByFareysAlgo returns a Rational approximation for v. Various float64 values cannot be represented in this way (including values that are too big) and a non-nil error is returned in this case. It uses Farey's algorithm to generate a sequence of rational approximations.

The accuracy must be less than 100 and greater than zero.

This may generate different approximations from the RationalApproximation func.

Note that this will try at most MaxFareyTrials times before giving up. It can be very slow to converge to certain values, particularly those close to zero or one. If an error is returned the

func SetRational

func SetRational(intPart float64, n, d, sign int64) (Rational, error)

SetRational constructs a Rational from the passed values, checks for overflows and returns it along with any error

func (Rational) AsFloat64

func (r Rational) AsFloat64() float64

AsFloat64 returns the float64 equivalent of the Rational

func (Rational) Invert

func (r Rational) Invert() Rational

Invert returns 1/r

func (Rational) Proximity

func (r Rational) Proximity(v float64) float64

Proximity returns the absolute difference between the rational value and the supplied value as a proportion of the supplied value

func (Rational) String

func (r Rational) String() string

String returns a string value for the Rational