Package float

import "gitlab.com/zoralab/cerigo/encoding/float"

package float is an encoder/decoder for floating-points numerical values.

The encoder/decoder (ENDEC) is meant to process the presentation of a given floating-points number, either in a form of float32, float64 or math/big.Float object.

The ENDEC also supports base numbering conversion, allowing one to convert floating-points number from the conventional Base 10 representation to anywhere between 2 to 36.

MATHEMATICAL BASE CONVERSION

The mathematical model for base conversion relies on the following derrivatives: B^y = 10^x y = x*logB(10) — [1]

From [1],
y = ‖x*(log2(10) / log2(B))‖
y = ‖x*c, c = log2(10) / log2(B)‖    --- [2]

∴,
base2,
y = x*c, c = log2(10) / log2(2)
y = x*c, c = log2(10)
y = ‖x*log2(10)‖

base5,
y = x*log5(10)
y = ‖x*c, c = log2(10) / log2(5)‖

base8,
y = x*log8(10)
y = x*c, c = log2(10) / log2(8)
y = ‖x*c, c = log2(10) / 3‖

base16,
y = x*log16(10)
y = x*c, c = log2(10) / log2(16)
y = ‖x*c, c = log2(10) / 4‖

With base conversion made available for exponent values, the rest would be converting the mantissa, where round numbers and partial numbers are converted separately.

For round number, it is a direct conversion using standard library strconv package. It has both ParseFloat(…) and FormatFloat(…) functions that can easily translate any round numbers.

For partial numbers, it is converted using base number multiplication upto a given precision limit.

APPLIED OPTIMIZATIONS

  1. c Constant Lookup Table

Currently, the exponent’s base number mathematical model relies on division. To speed up the process, the constant c is pre-calculated and tabulated into a look-up table for known bases like Base-2, Base-8, and Base-16. Otherwise, it will falls back to manual division calculations.

LIMITATIONS

  1. Accuracy

The ENDEC is under Go’s float numbers' limitations and c Constant’s accuracy. Otherwise, the ENDEC is usable for any base conversion. User must keep in mind that the more operations done onto a floating point numbers, the more accuracy it loses. Hence, it is best to use ENDEC once all calculations are done in conventional Go.

Example

f := float32(12.321231e-123)

b := New()

b.ParseFloat32(f)

s := b.ToString(Normal, 10)
fmt.Println(s)

t, err := b.ToBase(9, NormalizeNormal, 10, 5)
if err != nil {

return
}

fmt.Println(t)

Constants

Format Type Enumerations

const (
	// Normal is the normal REAL number format.
	//

	// This is essentially the same as math.big.Float.Text('g',
	// precision). The format is: 1. -d.dddde±dd --> for large
	// exponents 2. -ddddd.dddd --> for otherwise
	Normal = 0

	// Scientific is the scientific REAL number format.
	//

	// This is the presentation for scientific community's
	// representation. The format is: 1. -ddddd.dddd*10^(±dd)
	Scientific = 1

	// ISO6093NR1 is the REAL number containing only round
	// numbers format.
	//

	// This is essentially the same as math.big.Float.Text('f',
	// 0). The format is: 1. -ddddd
	ISO6093NR1 = 2

	// ISO6093NR2 is the REAL number containing decimal number
	// only format.
	//

	// This is the essentially the same as
	// math.big.Float.Text('f', precision). The format is: 1.
	// -ddddd.dddd
	ISO6093NR2 = 3

	// ISO6093NR3 is the decimal number and exponent format.
	//

	// This is essentially the same as math.big.Float.Text('e',
	// precision). The format is: 1. -d.dddde±dd
	ISO6093NR3 = 4
)

Normalization Enumerations

const (
	// NormalizeNormal is to normalize toward single digit round
	// number.
	//

	// Example: 1. XXXX.YYYYeZZZ --> X.XXXYYYYe(ZZZ+3)
	NormalizeNormal = 0

	// NormalizeFullRound is to normalize toward full round
	// numbers.
	//

	// Example: 1. XXXX.YYYYeZZZ --> XXXXYYYY.0e(ZZZ-4)
	NormalizeFullRound = 1

	// NormalizeNone is to not apply any normalization.
	//

	// Example: 1. XXXX.YYYYeZZZ --> XXXX.YYYYeZZZ
	NormalizeNone = 2
)

ENDEC

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

ENDEC is the REAL number format encoder and decoder (ENDEC).

It holds one float value at a time for format translation. To change into different float number, simply parse the float values again.

This structure contains unexported configuration fields so use float.New() function to create one instead of the conventional &structure{} way.

Func New() *ENDEC

New creates the float.ENDEC for encoding/decoding float data into other format.

Func (e *ENDEC) ParseBigFloat(x *big.Float)

ParseBigFloat accepts math/big/Float object pointer as the float data.

The input is:

  1. x - math/big.Float object pointer (e.g. &var)

Func (e *ENDEC) ParseFloat32(x float32)

ParseFloat32 accepts float32 object as the float data.

The input is:

  1. x - float32 number

Func (e *ENDEC) ParseFloat64(x float64)

ParseFloat64 accepts float64 object as the float data.

The input is:

  1. x - float64 number

Func (e *ENDEC) ToBase(base int, normalization int, accuracy int, precision int) (t *floatconv.Text, err error)

ToBase changes the float REAL value into other base number system.

It produces float.Text data structure output holding various segments of REAL number. Due to the support between base2 to base36 (2…z), the output is strictly limited to string data type and [Scientific] format. To view output as a whole, simply call the Text.String().

The inputs are:

  1. base - base number system from 2 to 36.
  2. normalization - Normalization choice. The default is [NormalizeNormal]. See “Normalization Enumerations” for more info.
  3. accuracy - the REAL value’s accuracy before base change. The output preserves the REAL value as close as possible.
  4. precision - the fraction precision limit after conversion. The default is 100.

The outputs are:

  1. float.*Text - the float.Text data structure pointer holding the string parts values.
  2. error - any error occurred during conversion. If error exists, the float.*Text output will be nil.

Func (e *ENDEC) ToString(format int, accuracy int) string

ToString changes the float REAL value into the selected format.

If the format is unavailable or incompatible, the return value is empty ("").

The input are:

  1. format - the format enumerated value. There is no default. See “Format Type Enumerations” for more info.
  2. accuracy - the precision degree for the output.

The output are:

  1. format - the formatted presentation in string.