{"id":13412856,"url":"https://github.com/govalues/money","last_synced_at":"2026-01-12T02:46:00.482Z","repository":{"id":142257635,"uuid":"604710194","full_name":"govalues/money","owner":"govalues","description":"Immutable monetary amounts and exchange rates for Go","archived":false,"fork":false,"pushed_at":"2024-07-26T18:04:01.000Z","size":223,"stargazers_count":18,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-07-31T20:51:31.959Z","etag":null,"topics":["currencies","currencies-conversions","currency","decimal","exchange-rate","financial","floating-point","go","golang","iso-4217","money"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/govalues/money#section-documentation","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/govalues.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-21T16:21:17.000Z","updated_at":"2024-07-26T17:57:16.000Z","dependencies_parsed_at":"2024-01-08T15:02:39.721Z","dependency_job_id":"f7dab56d-7671-42a3-bb92-2794d3e69bb6","html_url":"https://github.com/govalues/money","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/govalues%2Fmoney","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/govalues%2Fmoney/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/govalues%2Fmoney/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/govalues%2Fmoney/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/govalues","download_url":"https://codeload.github.com/govalues/money/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243625183,"owners_count":20321250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["currencies","currencies-conversions","currency","decimal","exchange-rate","financial","floating-point","go","golang","iso-4217","money"],"created_at":"2024-07-30T20:01:30.125Z","updated_at":"2026-01-12T02:46:00.470Z","avatar_url":"https://github.com/govalues.png","language":"Go","funding_links":[],"categories":["Financial","金融"],"sub_categories":["Search and Analytic Databases","检索及分析资料库"],"readme":"# money\n\n[![githubb]][github]\n[![codecovb]][codecov]\n[![goreportb]][goreport]\n[![godocb]][godoc]\n[![licenseb]][license]\n[![versionb]][version]\n[![awesomeb]][awesome]\n\nPackage money implements immutable monetary amounts and exchange rates for Go.\n\n## Key Features\n\n- **Immutability** - Once set, an amount or exchange rate remains constant,\n  ensuring safe concurrent access across goroutines.\n- **Banker's Rounding** - Uses half-to-even rounding, also known as \"banker's rounding\",\n  to minimize cumulative rounding errors commonly seen in financial calculations.\n- **No Panics** - All methods are panic-free, returning errors instead of crashing\n  your application in cases such as overflow, division by zero, or currency mismatch.\n- **Zero Heap Allocation** - Optimized to avoid heap allocations,\n  reducing garbage collector impact during arithmetic operations.\n- **High Precision** - Supports up to 19 digits of precision, representing amounts\n  from -99,999,999,999,999,999.99 to 99,999,999,999,999,999.99 inclusive.\n- **Correctness** - Arithmetic operations are cross-validated against the\n  [cockroachdb/apd] and [shopspring/decimal] packages through extensive [fuzz testing].\n\n## Getting Started\n\n### Installation\n\nTo add the money package to your Go workspace:\n\n```bash\ngo get github.com/govalues/money\n```\n\n### Basic Usage\n\nCreate an amount using one of the constructors.\nAfter creating an amount, you can perform various operations as shown below:\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"github.com/govalues/decimal\"\n    \"github.com/govalues/money\"\n)\n\nfunc main() {\n    // Constructors\n    a, _ := money.NewAmount(\"USD\", 8, 0)               // a = $8.00\n    b, _ := money.ParseAmount(\"USD\", \"12.5\")           // b = $12.50\n    c, _ := money.NewAmountFromFloat64(\"USD\", 2.567)   // c = $2.567\n    d, _ := money.NewAmountFromInt64(\"USD\", 7, 896, 3) // d = $7.896\n    r, _ := money.NewExchRate(\"USD\", \"EUR\", 9, 1)      // r = $/€ 0.9\n    x, _ := decimal.New(2, 0)                          // x = 2\n\n    // Operations\n    fmt.Println(a.Add(b))          // $8.00 + $12.50\n    fmt.Println(a.Sub(b))          // $8.00 - $12.50\n    fmt.Println(a.SubAbs(b))       // abs($8.00 - $12.50)\n\n    fmt.Println(a.Mul(x))          // $8.00 * 2\n    fmt.Println(a.AddMul(b, x))    // $8.00 + $12.50 * 2\n    fmt.Println(a.SubMul(b, x))    // $8.00 - $12.50 * 2\n    fmt.Println(r.Conv(a))         // $8.00 * $/€ 0.9\n\n    fmt.Println(a.Quo(x))          // $8.00 / 2\n    fmt.Println(a.AddQuo(b, x))    // $8.00 + $12.50 / 2\n    fmt.Println(a.SubQuo(b, x))    // $8.00 - $12.50 / 2\n    fmt.Println(a.QuoRem(x))       // $8.00 div 2, $8.00 mod 2\n    fmt.Println(a.Rat(b))          // $8.00 / $12.50\n    fmt.Println(a.Split(3))        // $8.00 into 3 parts\n\n    // Rounding to 2 decimal places\n    fmt.Println(c.RoundToCurr())   // 2.57\n    fmt.Println(c.CeilToCurr())    // 2.57\n    fmt.Println(c.FloorToCurr())   // 2.56\n    fmt.Println(c.TruncToCurr())   // 2.56\n\n    // Conversions\n    fmt.Println(d.Int64(9))        // 7 896000000\n    fmt.Println(d.Float64())       // 7.896\n    fmt.Println(d.String())        // USD 7.896\n\n    // Formatting\n    fmt.Printf(\"%v\", d)            // USD 7.896\n    fmt.Printf(\"%[1]f %[1]c\", d)   // 7.896 USD\n    fmt.Printf(\"%f\", d)            // 7.896\n    fmt.Printf(\"%c\", d)            // USD\n    fmt.Printf(\"%d\", d)            // 790\n}\n```\n\n## Documentation\n\nFor detailed documentation and additional examples, visit the package\n[documentation](https://pkg.go.dev/github.com/govalues/money#section-documentation).\n\n## Comparison\n\nComparison with other popular packages:\n\n| Feature                         | govalues       | [rhymond] v1.0.10 | [bojanz] v1.2.1 |\n| ------------------------------- | -------------- | ----------------- | --------------- |\n| Speed                           | High           | Medium            | Medium          |\n| Numeric Representation          | Floating Point | Fixed Point       | Floating Point  |\n| Precision                       | 19 digits      | 18 digits         | 39 digits       |\n| Default Rounding                | Half to even   | Not supported     | Half up         |\n| Overflow Control                | Yes            | No[^wrap]         | Yes             |\n| Support for Division            | Yes            | No                | Yes             |\n| Support for Currency Conversion | Yes            | No                | Yes             |\n\n[^wrap]: [rhymond] does not detect overflow and returns an invalid result.\nFor example, 92,233,720,368,547,758.07 + 0.01 results in -92,233,720,368,547,758.08.\n\n### Benchmarks\n\n```text\ngoos: linux\ngoarch: amd64\npkg: github.com/govalues/money-tests\ncpu: AMD Ryzen 7 3700C  with Radeon Vega Mobile Gfx \n```\n\n| Test Case     | Expression            | govalues | [rhymond] v1.0.10 | [bojanz] v1.2.1 | govalues vs rhymond | govalues vs bojanz |\n| ------------- | --------------------- | -------: | ----------------: | --------------: | ------------------: | -----------------: |\n| Add           | $2.00 + $3.00         |   22.95n |           218.30n |         144.10n |            +851.41% |           +528.02% |\n| Mul           | $2.00 * 3             |   21.80n |           133.40n |         239.60n |            +511.79% |           +998.83% |\n| Quo (exact)   | $2.00 / 4             |   80.12n |               n/a |         468.05n |                 n/a |           +484.19% |\n| Quo (inexact) | $2.00 / 3             |   602.1n |               n/a |          512.4n |                 n/a |            -14.91% |\n| Split         | $2.00 into 10 parts   |   374.9n |            897.0n |             n/a |            +139.28% |                n/a |\n| Conv          | $2.00 to €            |   30.88n |               n/a |         348.50n |                 n/a |          +1028.38% |\n| Parse         | $1                    |   44.99n |           139.50n |          99.09n |            +210.07% |           +120.26% |\n| Parse         | $123.456              |   61.45n |           148.60n |         240.90n |            +141.82% |           +292.03% |\n| Parse         | $123456789.1234567890 |   131.2n |            204.4n |          253.0n |             +55.85% |            +92.87% |\n| String        | $1                    |   38.48n |           200.70n |          89.92n |            +421.50% |           +133.65% |\n| String        | $123.456              |   56.34n |           229.90n |         127.05n |            +308.02% |           +125.49% |\n| String        | $123456789.1234567890 |   84.73n |           383.30n |         277.55n |            +352.38% |           +227.57% |\n| Telco         | see [specification]   |   224.2n |               n/a |         1944.0n |                 n/a |           +766.89% |\n\nThe benchmark results shown in the table are provided for informational purposes\nonly and may vary depending on your specific use case.\n\n[codecov]: https://codecov.io/gh/govalues/money\n[codecovb]: https://img.shields.io/codecov/c/github/govalues/money/main?color=brightcolor\n[goreport]: https://goreportcard.com/report/github.com/govalues/money\n[goreportb]: https://goreportcard.com/badge/github.com/govalues/money\n[github]: https://github.com/govalues/money/actions/workflows/go.yml\n[githubb]: https://img.shields.io/github/actions/workflow/status/govalues/money/go.yml\n[godoc]: https://pkg.go.dev/github.com/govalues/money#section-documentation\n[godocb]: https://img.shields.io/badge/go.dev-reference-blue\n[version]: https://go.dev/dl\n[versionb]: https://img.shields.io/github/go-mod/go-version/govalues/money?label=go\n[license]: https://en.wikipedia.org/wiki/MIT_License\n[licenseb]: https://img.shields.io/github/license/govalues/money?color=blue\n[awesome]: https://github.com/avelino/awesome-go#financial\n[awesomeb]: https://awesome.re/mentioned-badge.svg\n[rhymond]: https://pkg.go.dev/github.com/Rhymond/go-money\n[bojanz]: https://pkg.go.dev/github.com/bojanz/currency\n[cockroachdb/apd]: https://pkg.go.dev/github.com/cockroachdb/apd\n[shopspring/decimal]: https://pkg.go.dev/github.com/shopspring/decimal\n[specification]: https://speleotrove.com/decimal/telcoSpec.html\n[fuzz testing]: https://github.com/govalues/decimal-tests\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgovalues%2Fmoney","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgovalues%2Fmoney","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgovalues%2Fmoney/lists"}