fixed

README

fixed

fixed implements a fixed-point number, where both mantissa and exponent are stored in a single number. Can be used to represent currency rates with up to 16 digits of precision.

Installation

$ go get github.com/avdva/fixed

Representation

Value is a positive fixed-point number. It currently uses a uint64 value as a data type, where 8 bits are used for exponent and 56 for mantissa.

   63      55                                                     0
   ________|_______________________________________________________
   mmmmmmmmeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee

Value can be useful for representing numbers like prices in financial services. Negative numbers aren't currently supported.

Usage

To get a value use one of From{Uint64, String, Float, MantAndExp} :

	v, err := fixed.FromString("1.23456")
	if err != nil {
		panic(err)
	}

See value_example_test.go for more examples.

Documentation

Overview

package fixed implements a fixed-point number, where both mantissa and exponent are stored in a single number. Can be used to represent currency rates with up to 16 digits of precision.

Index

• Constants
• Variables
• type Value
  • func FromFloat64(v float64) (Value, error)
  • func FromMantAndExp(mant uint64, exp int8) (Value, error)
  • func FromString(s string) (Value, error)
  • func FromUint64(v uint64) (Value, error)
  • func (v Value) Cmp(other Value) int
  • func (v Value) Eq(other Value) bool
  • func (v Value) Float64() float64
  • func (v Value) GoString() string
  • func (v Value) MantUint64() uint64
  • func (v Value) MarshalJSON() ([]byte, error)
  • func (v Value) Normalized() Value
  • func (v Value) String() string
  • func (v Value) ToExp(exp int) Value
  • func (v Value) Uint64() uint64
  • func (v *Value) UnmarshalJSON(data []byte) error

Examples

• Value

Constants

const (
	// JSONModeString produces values as strings, like `"1234.5678"`
	JSONModeString = iota
	// JSONModeFloat marshals values as floats, like `1234.5678`.
	JSONModeFloat
	// JSONModeME marshals values with mantissa and exponent, like `{"m":123,"e":-5}`.
	JSONModeME
	// JSONModeCompact will choose the shortest form between JSONModeString and JSONModeME.
	JSONModeCompact
)

const (
	// Max is the maximum possible fixed-point value.
	Max = Value(number(maxExponent)<<mantBits | (maxMantissa & mantMask))
	// Min is the minimum possible fixed-point value.
	Min = Value(number((1<<(expBits-1)+1))<<mantBits | minMantissa)
)

Variables

var (
	// JSONMode defines the way all values are marshaled into json, see JSONMode* constants.
	// This variable is not thread-safe, so this should be changed on program start.
	JSONMode = JSONModeCompact
)

Types

type Value

type Value number

Value is a positive fixed-point number. It currently uses a uint64 value as a data type, where 8 bits are used for exponent and 56 for mantissa.

63      55                                                     0
________|_______________________________________________________
mmmmmmmmeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee

Negative numbers aren't currently supported. Value can be useful for representing numbers like prices in financial services.

Example

v1, err := FromString("1.23456")
if err != nil {
	panic(err)
}
fmt.Printf("v1 as a float = %v, mantissa = %v, uint64 = %v\n", v1.Float64(), v1.MantUint64(), v1.Uint64())

v2, err := FromFloat64(1.23456)
if err != nil {
	panic(err)
}
fmt.Printf("value from string: %s, value from float: %s, values are equal: %v\n", v1.String(), v2.String(), v1.Eq(v2))

v3, err := FromMantAndExp(12345, -4)
if err != nil {
	panic(err)
}
fmt.Printf("uint64 values for -6 exp %d, %d\n", v1.ToExp(-6).MantUint64(), v3.ToExp(-6).MantUint64())

data, err := json.Marshal(v1)
if err != nil {
	panic(err)
}
fmt.Printf("json for value: %s\n", string(data))

JSONMode = JSONModeME
data, err = json.Marshal(v1)
if err != nil {
	panic(err)
}
fmt.Printf("json for value and JSONModeME: %s\n", string(data))

Output:

v1 as a float = 1.23456, mantissa = 123456, uint64 = 1
value from string: 1.23456, value from float: 1.23456, values are equal: true
uint64 values for -6 exp 1234560, 1234500
json for value: "1.23456"
json for value and JSONModeME: {"m":123456,"e":-5}

func FromFloat64

func FromFloat64(v float64) (Value, error)

FromFloat64 returns a value for given float64. Returns an error for nagative values, infinities, and not-a-numbers.

func FromMantAndExp

func FromMantAndExp(mant uint64, exp int8) (Value, error)

FromMantAndExp returns a value for given mantissa and exponent. Returns an error, if (mant, exp) pair represents a number out of range.

func FromString

func FromString(s string) (Value, error)

FromString parses a string into a value.

func FromUint64

func FromUint64(v uint64) (Value, error)

FromUint64 returns a value for given uint64 number. Returns an error if v if exceeds the maximum mantissa.

func (Value) Cmp

func (v Value) Cmp(other Value) int

Cmp compares two values. Returns -1 if a < b, 0 if a == b, 1 if a > b

func (Value) Eq

func (v Value) Eq(other Value) bool

Eq returns true, if both values represent the same number.

func (Value) Float64

func (v Value) Float64() float64

Float64 returns a float64 value.

func (Value) GoString

func (v Value) GoString() string

GoString returns debug string representation.

func (Value) MantUint64

func (v Value) MantUint64() uint64

MantUint64 returns v's mantissa as is.

func (Value) MarshalJSON

func (v Value) MarshalJSON() ([]byte, error)

MarshalJSON marshals value according to current JSONMode. See JSONMode and JSONMode* constants.

func (Value) Normalized

func (v Value) Normalized() Value

Normalized eliminates trailing zeros in the fractional part. The process basically inceases the exponent, and stops, if it reaches its maximum value, so that it is possible, that that mantissa has trailing zeros.

func (Value) String

func (v Value) String() string

String returns a string representation of the value.

func (Value) ToExp

func (v Value) ToExp(exp int) Value

ToExp changes the mantissa of v so, that v = m * 10e'exp'. As a result, mantissa can lose some digits in precision, become zero, or Max.

func (Value) Uint64

func (v Value) Uint64() uint64

Uint64 returns the value as a uint64 number.

func (*Value) UnmarshalJSON

func (v *Value) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals a string, float, or an object into a value.