{"id":16389449,"url":"https://github.com/qqwy/elixir-number","last_synced_at":"2025-12-12T00:28:47.916Z","repository":{"id":41809642,"uuid":"76358973","full_name":"Qqwy/elixir-number","owner":"Qqwy","description":"Numbers -- A generic wrapper to use *any* custom Numeric type in Elixir!","archived":false,"fork":false,"pushed_at":"2023-04-26T18:00:37.000Z","size":80,"stargazers_count":40,"open_issues_count":4,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-29T14:18:01.847Z","etag":null,"topics":["arithmetic","coercion","conversion","custom-numeric","decimals","elixir","elixir-lang","interface","tensor"],"latest_commit_sha":null,"homepage":"https://hex.pm/packages/numbers","language":"Elixir","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/Qqwy.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":"2016-12-13T12:59:08.000Z","updated_at":"2025-01-23T03:07:23.000Z","dependencies_parsed_at":"2024-06-21T04:18:10.092Z","dependency_job_id":"24cdf149-9c3d-4e2a-97a1-43a8305dc162","html_url":"https://github.com/Qqwy/elixir-number","commit_stats":null,"previous_names":["qqwy/elixir_number"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Qqwy/elixir-number","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qqwy%2Felixir-number","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qqwy%2Felixir-number/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qqwy%2Felixir-number/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qqwy%2Felixir-number/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Qqwy","download_url":"https://codeload.github.com/Qqwy/elixir-number/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qqwy%2Felixir-number/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266076350,"owners_count":23872741,"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":["arithmetic","coercion","conversion","custom-numeric","decimals","elixir","elixir-lang","interface","tensor"],"created_at":"2024-10-11T04:33:02.753Z","updated_at":"2025-12-12T00:28:47.881Z","avatar_url":"https://github.com/Qqwy.png","language":"Elixir","readme":"# Numbers\n[![hex.pm version](https://img.shields.io/hexpm/v/numbers.svg)](https://hex.pm/packages/numbers)\n[![Build Status](https://travis-ci.org/Qqwy/elixir-number.svg?branch=master)](https://travis-ci.org/Qqwy/elixir-number)\n[![Inline docs](http://inch-ci.org/github/qqwy/elixir_number.svg)](http://inch-ci.org/github/qqwy/elixir_number)\n\n\n**Numbers** is a tiny Elixir package that facilitates the creation of libraries\nthat want to be able to use _any_ kind of Numberlike type.\n\nSome known custom numeric types that implement Numbers' protocols:\n\n- [Ratio](https://hex.pm/packages/ratio) -- rational numbers.\n- [Decimal](https://hex.pm/packages/decimal) -- arbitrary precision decimal numbers.\n- [Tensor](https://hex.pm/packages/tensor) -- Vectors, Matrices and higher-order tensors.\n- [ComplexNum](https://github.com/Qqwy/elixir_complex_num) -- Complex numbers.\n\nJust add one (or multiple) of these libraries to your project, together with Numbers, and you're good to go!\n\n## How does it work?\n\nStarting at version 5, Numbers contains a set of protocols that can be independently implemented for your data structures.\n\nEach protocol maps to a single arithmetical operation that your data structure might support.\n\nBecause protocols are used, Numbers can dispatch quite fast!\nAlso, Numbers does not restrict your modules to any special naming schemes (as was the case with older versions of Numbers that used a Behaviour).\n\nThe following operations are supported:\n\n- `add` for addition, by implementing `Numbers.Protocols.Addition`.\n- `sub` for subtraction, by implementing `Numbers.Protocols.Subtraction`.\n- `mult` for multiplication, by implementing `Numbers.Protocols.Multiplication`.\n- `div` for division, by implementing `Numbers.Protocols.Division`.\n- `minus` for unary minus (negation), by implementing `Numbers.Protocols.Minus`.\n- `abs` to calculate the absolute value of a number, by implementing `Numbers.Protocols.Absolute`.\n- `pow` for calculating integer powers, by implementing `Numbers.Protocols.Exponentiation`. A special helper in `Numbers.Helpers.pow_by_sq` can be used inside this implementation to automatically make use of the _'Exponentiation by Squaring'_ algorithm.\n- `to_float` for (possibly lossy) conversion to the built-in Float datatype, by implementing `Numbers.Protocols.ToFloat`.\n\n## Coercion\n\nNumbers does not automatically transform numbers from one type to another if one of the functions is called with two different types.\n\nFrequently you do want to use other data types together with your custom data type. For this, a custom coercion can be specified,\nusing `Coerce.defcoercion` as exposed by the [`Coerce`](https://hex.pm/packages/coerce) library that `Numbers` depends on.\n\nThe only coercion that ships with Numbers itself, is a coercion of Integers to Floats, meaning that they work the same way as when using\nthe standard library math functions with these types.\n\n## Overloaded Operators\n\nYou can opt-in to overloaded `+, -, *, /` operators by calling `use Numbers, overload_operators: true`.\nThis allows you to use these inline operators for all other Numberlike types.\n\nThe library uses a conditional compilation technique to make sure that \n**you will _still_ be able to use the operators inside guards** for built-in integers and floats.\n\nAs example consider:\n\n```elixir\ndefmodule An.Example do\n  use Numbers, overload_operators: true\n\n  def foo(a, b) when a + b \u003c 10 do  # Uses the normal guard-safe '+' operator (e.g. Kernel.+/2)\n    42\n  end\n  def foo(c, d) do \n    c + d # Uses the overloaded '+' operator.\n  end\nend\n```\n\n## Examples:\n\nUsing built-in numbers:\n\n```elixir\niex\u003e alias Numbers, as: N\n\niex\u003e N.add(1, 2)\n3\n\niex\u003e N.mult(3,5)\n15\n\niex\u003e N.mult(1.5, 100)\n150.0\n```\n\nUsing Decimals: (requires the [Decimal](https://hex.pm/packages/decimal) library.)\n\n```elixir\niex\u003e alias Numbers, as: N\n\niex\u003e d = Decimal.new(2)\niex\u003e N.div(d, 10)\n#Decimal\u003c0.2\u003e\niex\u003e small_number = N.div(d, 1234)\n#Decimal\u003c0.001620745542949756888168557536\u003e\niex\u003e N.pow(small_number, 100)\n\n```\n\n\n## Installation\n\nThe package can be installed as:\n\n1. Add `numbers` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [{:numbers, \"~\u003e 5.2\"}]\nend\n```\n\n## Changelog\n\n- 5.2.4 Updates `:decimal` dependency to now allow both version `1.x` as well as version `2.x`.\n- 5.2.3 Updates `:decimal` dependency to `1.9` or newer, and replaces deprecated `Decimal.minus/1` call with `Decimal.negate/1`\n- 5.2.2 Updated `mix.exs` to use `extra_applications` rather than manually overridding `applications`. This drops support for now very old versions of Elixir (\u003c v1.4) but ensures proper support with Elixir v1.11 and beyond.\n- 5.2.1 Better error message when wrongly using an operator at the left side of a match (e.g. `a - 1 = 10`).\n- 5.2.0 Ensures that overloaded operators do not prevent built-in operators to be used in guards.\n- 5.1.1 Makes `Decimal` dependency version less specific to play nicer with other libraries :-).\n- 5.1.0 Possibility to import overloaded operator variants. Also, greatly improved documentation.\n- 5.0.0 MAJOR OVERHAUL: New implementation based on a set of Protocols. Should be a lot faster and easier on implementers. Also uses a new method to perform coercions based on the `Coerce` library. [Announcement post](https://elixirforum.com/t/numbers-a-generic-wrapper-to-use-any-custom-numeric-type/2846/7)\n- 4.0.0 Breaking change: Move `Numeric` to `Numbers.Numeric`, to follow proper code organization conventions.\n- 3.0.1 Improved README\n- 3.0.0 Remove public `Numbers.coerce/2` function, as it had confused naming and very limited use. Added optional `Numeric.coerce/2` callback (which works very different from the old `Numbers.coerce/2` function) which is now used underwater when coercion should happen.\n- 2.0.3 Improving documentation.\n- 2.0.2 Adding many tests.\n- 2.0.1 Fixing error message that is shown when conversion to float is not possible to use the Inspect protocol. \n- 2.0.0 Breaking change, `mul` -\u003e `mult`. \n- 1.0.0 First Stable Version.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqqwy%2Felixir-number","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqqwy%2Felixir-number","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqqwy%2Felixir-number/lists"}