{"id":13412836,"url":"https://github.com/naughtygopher/currency","last_synced_at":"2025-12-15T03:05:47.534Z","repository":{"id":45469774,"uuid":"90708483","full_name":"naughtygopher/currency","owner":"naughtygopher","description":"A currency computations package.","archived":false,"fork":false,"pushed_at":"2024-10-12T10:20:13.000Z","size":66,"stargazers_count":61,"open_issues_count":0,"forks_count":9,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-09T17:01:33.262Z","etag":null,"topics":["awesome-go","awesome-golang","awesome-list","currency","currency-api","currency-computations","currency-format","finance","go-library","go-package","golang-module","golang-package"],"latest_commit_sha":null,"homepage":"","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/naughtygopher.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2017-05-09T06:06:38.000Z","updated_at":"2024-11-06T11:54:25.000Z","dependencies_parsed_at":"2024-10-14T15:01:04.898Z","dependency_job_id":"6865d0b1-7b1e-4d99-92a0-0a9a0eb63f7a","html_url":"https://github.com/naughtygopher/currency","commit_stats":null,"previous_names":["naughtygopher/currency"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naughtygopher%2Fcurrency","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naughtygopher%2Fcurrency/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naughtygopher%2Fcurrency/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naughtygopher%2Fcurrency/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/naughtygopher","download_url":"https://codeload.github.com/naughtygopher/currency/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248125813,"owners_count":21051807,"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":["awesome-go","awesome-golang","awesome-list","currency","currency-api","currency-computations","currency-format","finance","go-library","go-package","golang-module","golang-package"],"created_at":"2024-07-30T20:01:29.851Z","updated_at":"2025-12-15T03:05:47.117Z","avatar_url":"https://github.com/naughtygopher.png","language":"Go","funding_links":[],"categories":["Financial","金融"],"sub_categories":["Search and Analytic Databases","Advanced Console UIs","检索及分析资料库"],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"https://user-images.githubusercontent.com/1092882/84137258-11328400-aa6a-11ea-94d9-9d58e56a0ea3.png\" alt=\"webgo gopher\" width=\"256px\"/\u003e\u003c/p\u003e\n\n[![](https://github.com/naughtygopher/currency/actions/workflows/go.yml/badge.svg?branch=master)](https://github.com/naughtygopher/currency/actions)\n[![Go Reference](https://pkg.go.dev/badge/github.com/naughtygopher/currency.svg)](https://pkg.go.dev/github.com/naughtygopher/currency)\n[![Go Report Card](https://goreportcard.com/badge/github.com/naughtygopher/currency)](https://goreportcard.com/report/github.com/naughtygopher/currency)\n[![Coverage Status](https://coveralls.io/repos/github/naughtygopher/currency/badge.svg?branch=master)](https://coveralls.io/github/naughtygopher/currency?branch=master)\n[![Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go/tree/main?tab=readme-ov-file#financial)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/creativecreature/sturdyc/blob/master/LICENSE)\n\n## Currency v2.0.1\n\nCurrency package helps you do currency computations accurately. `Currency` struct holds all the data required to define a currency.\n\n```golang\ntype Currency struct {\n\t// Code represents the international currency code\n\tCode string\n\t// Symbol is the respective currency symbol\n\tSymbol string\n\t// Main represents the main value of the currency\n\tMain int\n\t// Fractional represents the fractional/sub unit of the currency\n\tFractional uint\n\t// FUName is the name of the fractional/sub unit of the currency. e.g. paise\n\tFUName string\n\t// FUShare represents the no.of fractional/sub units that make up 1 main unit. e.g. ₹1 = 100 paise\n\t// Number of fractional units that make up 1 unit of the main value\n\tFUShare uint\n\t// PrefixSymbol if true will prefix the symbol when stringified\n\tPrefixSymbol bool\n\t// SuffixSymbol if true will suffix the symbol when stringified\n\tSuffixSymbol bool\n}\n```\n\n### New(main int, fractional int, code, symbol string, funame string, fushare uint)\n\nNew returns a pointer of currency instance created based on the configuration.\n\n```\nmain - Main/Super unit of the currency\nfractional - Subunit/fractional unit of the currency\ncode - is the currency code according to [ISO 4217 specification](https://en.wikipedia.org/wiki/ISO_4217)\nsymbol - Unicode symbol of the currency\nfuname - Name of the fractional/sub unit\nfushare - Number of fractional/sub units that make up 1 unit of the main/super unit\n```\n\n_IMPORTANT! Fractional unit can be negative only when the main value is 0. If the main value is not 0, fractional unit's negative sign is ignored._\n\n### Parsers \u0026 convenience methods\n\n1. `NewFractional(fractional int, symbol string,  fulabel string, fushare uint)` returns a currency struct instance, given a currency's total value represented by the fractional unit\n2. `ParseString(value string, code, symbol string,  fulabel string, fushare uint)` returns a currency struct instance, given a currency value represented as string\n3. `ParseFloat64(value float64, code, symbol string, funame string, fushare uint)` returns a currency struct instance, given a currency value represented in float64\n\n### Computational methods\n\nIMPORTANT: Computation is supported only between same type of currencies (i.e. currency codes _*must*_ match)\n\n1. `c1.Add(c2 currency)` add c2 to c1, and update c1\n2. `c1.AddInt(main int, fractional int)` add the currency equivalent of the main \u0026 fractional int to c1\n3. `c1.Subtract(c2 currency)` subtract c2 from c1, and update c1\n4. `c1.SubtractIn(main int, fractional int)` subtract the currency equivalent of the main \u0026 fractional int from c1\n5. `c1.Multiply(n int)` multiply c1 by n, where n is an integer\n6. `c1.MultiplyFloat64(n float64)` multiply c1 by n, where n is a float64 value\n7. `c1.UpdateWithFractional(ftotal int)` would update the the value of c1, where _ftotal_ is the total value of the currency in fractional unit. e.g. INR, `UpdateWithFractional(100)` would set the main value as `1` and fractional unit as `0`\n8. `c1.FractionalTotal() int` returns the total value of the currency in its fractional unit. e.g. INR, if the Main value is `1` and fractional unit is `0`, it would return `100`, i.e. 100 paise\n9. `c1.Percent(n float64) currency` returns a new currency instance which is n percentage of c1\n10. `c1.Allocate(n int, retain bool)[]currency, ok ` returns a slice of currency of size n. `ok` if **true** means the currency value is fully divisible by n. If `retain` is true,\n    then `c1` will have the remainder value after allocation, otherwise the remainder is distributed among the returned currencies.\n\n#### Why does `Allocate(n int, retain bool)` return a slice of currencies?\n\n`Allocate` unlike other operations, cannot be rounded off. If it is rounded, it would result in currency _peddling_.\n\ne.g. ₹1/- (INR 1) is to be divided by 3. There are 2 options of dividing this by 3.\n\n    1. Set 33 paise per split, and retain the remaining 1 paise at source. (`Divide(n, true)`)\n\n    2. Set 1 of the split with an extra value, i.e. 34 + 33 + 33. (`Divide(n, false)`)\n\n### Multiple currency representations\n\n1. `c1.String()`, returns a string representation of the currency value\n2. `c1.Float64()`, returns a float64 representation of the currency value\n\n## Benchmarks\n\nHow to run?\n\n`$ go test -bench=.`\n\nResults when run on a MacBook Pro (13-inch, M3, 2024), CPU: Apple M3, RAM: 24 GB\n\n```\ngo version go1.23.1 darwin/arm64\ngithub.com/naughtygopher/currency [allocate]$ go test -bench .\ngoos: darwin\ngoarch: arm64\npkg: github.com/naughtygopher/currency/v2\ncpu: Apple M3\nBenchmarkNew-8                    \t55541650\t        21.68 ns/op\nBenchmarkNewFractional-8          \t58322852\t        21.69 ns/op\nBenchmarkParseFloat64-8           \t47724391\t        25.72 ns/op\nBenchmarkParseString-8            \t 6650085\t       182.2 ns/op\nBenchmarkString-8                 \t20838006\t        58.65 ns/op\nBenchmarkStringNoPrefix-8         \t30418314\t        39.87 ns/op\nBenchmarkFloat64-8                \t1000000000\t         0.2722 ns/op\nBenchmarkFractionalTotal-8        \t1000000000\t         0.2697 ns/op\nBenchmarkUpdateWithFractional-8   \t1000000000\t         1.068 ns/op\nBenchmarkAdd-8                    \t190538139\t         6.245 ns/op\nBenchmarkAddInt-8                 \t230544486\t         5.690 ns/op\nBenchmarkSubtract-8               \t185860339\t         6.537 ns/op\nBenchmarkSubtractInt-8            \t217542852\t         5.571 ns/op\nBenchmarkMultiply-8               \t282455095\t         4.335 ns/op\nBenchmarkMultiplyFloat64-8        \t84543258\t        13.13 ns/op\nBenchmarkPercent-8                \t52612252\t        21.28 ns/op\nBenchmarkAllocate-8               \t35645416\t        34.41 ns/op\nPASS\nok  \tgithub.com/naughtygopher/currency/v2\t23.125s\n```\n\n## References\n\n1. [Ref - Sub unit or fractional unit](\u003chttps://en.wikipedia.org/wiki/Denomination_(currency)\u003e)\n2. [Ref - Currencies](https://en.wikipedia.org/wiki/Currency) - about currencies\n3. [Non-decimal sub unit in currencies are only used by 2 countries today](https://en.wikipedia.org/wiki/Non-decimal_currency). These are getting phased out.\n\n_IMPORTANT! This package does not support sub units which are not a power of 10. Nor does it support currencies with more than 1 sub unit_\n\n## The gopher\n\nThe gopher used here was created using [Gopherize.me](https://gopherize.me/). Deal with currency professionally just like this gopher!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaughtygopher%2Fcurrency","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnaughtygopher%2Fcurrency","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaughtygopher%2Fcurrency/lists"}