frac: A Go repository from mitranim

Overview

Missing feature of the Go standard library: parsing and formatting int64 as a fractional numeric string, without any rounding or bignums, by using a fixed fraction size. Supports arbitrary radixes from 2 to 36.

For example:

"123"     <- frac 2, radix 10 -> 123_00
"123"     <- frac 3, radix 10 -> 123_000

"123.45"  <- frac 2, radix 10 -> 123_45
"123.45"  <- frac 3, radix 10 -> 123_450

"123.456" <- frac 2, radix 10 -> <error>
"123.456" <- frac 3, radix 10 -> 123_456

Performance on 64-bit machines is somewhat comparable to strconv and shouldn't be your bottleneck.

See API docs at https://pkg.go.dev/github.com/mitranim/frac.

Why

You use integers for money.
You deal with external APIs that use decimal strings for money.
You want to avoid rounding errors.
You don't want to deal with "big decimal" libraries.

Then frac is for you!

Usage

Basic usage:

import "github.com/mitranim/frac"

func main() {
  num, err := frac.ParseDec(`-123`, 2)
  assert(err == nil && num == -123_00)

  num, err = frac.ParseDec(`-123.00`, 2)
  assert(err == nil && num == -123_00)

  num, err = frac.ParseDec(`-123.45`, 2)
  assert(err == nil && num == -123_45)

  // Exponent exceeds allotted precision. Conversion is impossible.
  num, err = frac.ParseDec(`-123.456`, 2)
  assert(err != nil && num == 0)
}

func assert(ok bool) {if !ok {panic("unreachable")}}

Implementing a monetary type:

import "github.com/mitranim/frac"

type Cents int64

func (self *Cents) UnmarshalText(input []byte) error {
  num, err := frac.UnmarshalDec(input, 2)
  if err != nil {
    return err
  }
  *self = Cents(num)
  return nil
}

func (self Cents) MarshalText() ([]byte, error) {
  return frac.AppendDec(nil, int64(self), 2)
}

The resulting type Cents is an integer, but when decoding and encoding text, it's represented as a fractional with 2 decimal points.

Known Limitations

The code is too assembly-like. Kinda like the standard library.
No special support for unsigned integers.
When formatting, fractional precision is limited to 64. (Imagine allocating gigabytes of memory for 0.0...01.)

License

https://unlicense.org

Misc

I'm receptive to suggestions. If this library almost satisfies you but needs changes, open an issue or chat me up. Contacts: https://mitranim.com/#contacts