fx

README

fx int64 based binary fixed point

Documentation

Overview

Package fx provides binary fixed point numbers based on int64s.

The fixed point numbers support multiplication, division, float64 conversion, Sin, Cos, Tan, Atan, const Pi, Sqrt, const Sqrt2

Build flags may be used to define different q's (number of fractional bits), and a generator program generates the necessary constants for more options of q values.

Using Fixed Point Numbers

Using fixed point numbers effectively requires some getting used to. They are generally used in media and hardware in contexts where the exact number of bits required to accomplish some task has been pre-calculated. In such contexts, they can be very effective and offer nice benefits.

fixed point numbers are not so well suited as general purpose fixed-number-of words number types. When the assumptions about the required bits for an application go out the window, fixed point numbers are not as robust as floats.

In summary, fixed point numbers offer the following avantages as compared to floats.

• uniform precision
• replicability across platforms
• built-in addition, subtraction, bit manipulation
• precise power of two multiplication/division by bit shifting
• possibility to choose a q with greater precision than float64s.

with the following costs as compared to floats.

• reduced dynamic range
• slower multiplication (5 native multiplies + shifts and adds)
• even slower division
• slower trigonometric functions (based on Cordic rotation currently)
• less generally available math support.

History and Status

Package fx was developed primarily in support of an application which needed replicability accross platforms and programming languages of some trigonometric functions and which also targeted implementability in hardware without FPU, or perhaps even without soft floats.

To date, most emphasis has been on clarity, precision, and correctness. Optimisations for speed will be added on-demand, or on-offer of contributions.

The package has a decently thorough test suite, is based on standard numerical algorithms, and is in use, but as of this writing (06/2018), it is brand new.

Index

• Constants
• func SinCos(a T) (T, T)
• type T
  • func Atan(a T) T
  • func Atan2(x, y T) T
  • func Cos(a T) T
  • func Float64(f float64) T
  • func Int(i int) T
  • func Sin(a T) T
  • func Sqrt(a T) T
  • func Tan(a T) T
  • func Uint(i uint) T
  • func (a T) Abs() T
  • func (a T) Div(b T) T
  • func (t T) Float64() float64
  • func (a T) Frac() T
  • func (a T) Int() T
  • func (a T) Inv() T
  • func (a T) Mul(b T) T
  • func (a T) Round() int64
  • func (t T) String() string

Constants

const (
	Pi    = 14148475504056880
	E     = 12242053029736146
	Sqrt2 = 6369051672525774
)

const (
	Sign = -1
	Zero = 0
	One  = 1 << FrBits
	Iota = 1
	Max  = iMask | frMask
)

const (
	FrBits = 52
)

Functions

func SinCos

func SinCos(a T) (T, T)

SinCos computes sin(a), cos(a)

a must be in the range

[-2*Pi..2*Pi]

or SinCos panics

Types

type T

type T int64

func Atan

func Atan(a T) T

Atan computes the arc-tangent of a, ie the angle w for which sin(w)/cos(w) = a.

func Atan2

func Atan2(x, y T) T

Atan2 computes the arctangent of x/y

Atan2 distinguishes the result based on the signs of both x and y.

func Cos

func Cos(a T) T

Cos computes cos(a)

a must be in the range

[-2*Pi..2*Pi]

or Cos panics

func Float64

func Float64(f float64) T

func Int

func Int(i int) T

func Sin

func Sin(a T) T

Sin computes sin(a).

a must be in the range

[-2*Pi..2*Pi]

or Sin panics

func Sqrt

func Sqrt(a T) T

Sqrt computes the square root of a. If a is negative Sqrt panics.

func Tan

func Tan(a T) T

Tan computes the tangent of a.

a must be in the range

[-2*Pi..2*Pi]

or Tan panics

func Uint

func Uint(i uint) T

func (T) Abs

func (a T) Abs() T

Abs returns the absolute value of a.

func (T) Div

func (a T) Div(b T) T

Div computes division. Note if b is a power of 2, then you can just shift.

func (T) Float64

func (t T) Float64() float64

func (T) Frac

func (a T) Frac() T

Frac returns the fractional part of a.

func (T) Int

func (a T) Int() T

Int returns the int part of a.

func (T) Inv

func (a T) Inv() T

Inv computes and returns 1/a.

func (T) Mul

func (a T) Mul(b T) T

Mul computes multiplication of a*b.

func (T) Round

func (a T) Round() int64

Round returns a rounded to the nearest integer as an int64.

func (T) String

func (t T) String() string