README
¶
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 for0.0...01.)
License
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
Documentation
¶
Overview ¶
Missing feature of the Go standard library: parsing and formatting integers as fractional numeric strings, without any rounding or bignums, by using a fixed fraction size. Supports arbitrary radixes from 2 to 36.
See `readme.md` for examples.
Index ¶
- func Append(buf []byte, num int64, frac uint, radix uint) ([]byte, error)
- func AppendBin(buf []byte, num int64, frac uint) ([]byte, error)
- func AppendDec(buf []byte, num int64, frac uint) ([]byte, error)
- func AppendHex(buf []byte, num int64, frac uint) ([]byte, error)
- func AppendOct(buf []byte, num int64, frac uint) ([]byte, error)
- func Format(num int64, frac uint, radix uint) (string, error)
- func FormatBin(num int64, frac uint) (string, error)
- func FormatDec(num int64, frac uint) (string, error)
- func FormatHex(num int64, frac uint) (string, error)
- func FormatOct(num int64, frac uint) (string, error)
- func Parse(src string, frac uint, radix uint) (num int64, err error)
- func ParseBin(src string, frac uint) (int64, error)
- func ParseDec(src string, frac uint) (int64, error)
- func ParseHex(src string, frac uint) (int64, error)
- func ParseOct(src string, frac uint) (int64, error)
- func Unmarshal(src []byte, frac uint, radix uint) (int64, error)
- func UnmarshalBin(src []byte, frac uint) (int64, error)
- func UnmarshalDec(src []byte, frac uint) (int64, error)
- func UnmarshalHex(src []byte, frac uint) (int64, error)
- func UnmarshalOct(src []byte, frac uint) (int64, error)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Append ¶
Same as `Format` but appends the resulting text to the provided buffer, returning the resulting union. When there's an error, the buffer is returned as-is with no hidden modifications.
func Format ¶
Formats an integer as a fractional number, virtually "divided" by the given fractional precision.
For example, for `frac = 2, radix = 10`, the number 12345 is encoded as "123.45", while the number 12300 is encoded as simply "123".
func Parse ¶
Parses a string that represents a fractional number, with an optional leading "+" or "-", into an integer whose value is virtually "multiplied" by the provided fractional precision.
For example, for `frac = 2, radix = 10`, "123.45" is parsed into the number 12345, while "123.456" is rejected with an error because it exceeds the allotted precision.
See `readme.md` for examples.
func ParseDec ¶
Shortcut for `Parse(src, frac, 10)`.
Example ¶
package main
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")
}
}
func UnmarshalBin ¶
Shortcut for `UnmarshalBin(src, frac, 2)`.
func UnmarshalDec ¶
Shortcut for `UnmarshalDec(src, frac, 10)`.
func UnmarshalHex ¶
Shortcut for `UnmarshalHex(src, frac, 16)`.
Types ¶
This section is empty.
Source Files