{"id":13507326,"url":"https://github.com/Qqwy/elixir-rational","last_synced_at":"2025-03-30T07:32:47.608Z","repository":{"id":6096287,"uuid":"54771538","full_name":"Qqwy/elixir-rational","owner":"Qqwy","description":"Rational number library for Elixir.","archived":false,"fork":false,"pushed_at":"2024-03-15T14:43:39.000Z","size":167,"stargazers_count":41,"open_issues_count":7,"forks_count":10,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-27T22:58:31.631Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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-03-26T09:12:39.000Z","updated_at":"2024-10-16T17:34:13.000Z","dependencies_parsed_at":"2024-03-15T15:52:10.875Z","dependency_job_id":null,"html_url":"https://github.com/Qqwy/elixir-rational","commit_stats":{"total_commits":135,"total_committers":17,"mean_commits":"7.9411764705882355","dds":0.5851851851851853,"last_synced_commit":"62c8d907f0e1960fe484644547257d81f80b1dd3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qqwy%2Felixir-rational","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qqwy%2Felixir-rational/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qqwy%2Felixir-rational/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qqwy%2Felixir-rational/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Qqwy","download_url":"https://codeload.github.com/Qqwy/elixir-rational/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222535178,"owners_count":16999233,"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":[],"created_at":"2024-08-01T02:00:31.209Z","updated_at":"2024-11-01T06:31:46.188Z","avatar_url":"https://github.com/Qqwy.png","language":"Elixir","funding_links":[],"categories":["Algorithms and Data structures"],"sub_categories":[],"readme":"# Ratio\n\n\n[![hex.pm version](https://img.shields.io/hexpm/v/ratio.svg)](https://hex.pm/packages/ratio)\n[![Documentation](https://img.shields.io/badge/hexdocs-latest-blue.svg)](https://hexdocs.pm/ratio/index.html)\n[![ci](https://github.com/Qqwy/elixir-rational/actions/workflows/ci.yml/badge.svg)](https://github.com/Qqwy/elixir-rational/actions/workflows/ci.yml)\n\nThis library allows you to use Rational numbers in Elixir, to enable exact calculations with all numbers big and small.\n\nRatio follows the Numeric behaviour from [Numbers](https://github.com/Qqwy/elixir_number), and can therefore be used in combination with any data type that uses Numbers (such as [Tensor](https://hex.pm/packages/tensor) and [ComplexNum](https://github.com/Qqwy/elixir_complex_num)).\n\n## Using Ratio\n\n`Ratio` defines arithmetic and comparison operations to work with rational numbers.\n\nRational numbers can be created by using `Ratio.new/2`,\nor by calling mathematical operators where one of the two operands is already a rational number.\n\n\n### Shorthand infix construction operator\n\nSince version 4.0, `Ratio` no longer defines an infix operator to create rational numbers.\nInstead, rational numbers are made using `Ratio.new`,\nand as the output from using an existing `Ratio` struct with a mathematical operation.\n\nIf you do want to use an infix operator such as\n`\u003c~\u003e` (supported in all Elixir versions)\nor `\u003c|\u003e` (deprecated in Elixir v1.14, the default of older versions of the `Ratio` library)\n\nyou can add the following one-liner to the module(s) in which you want to use it:\n\n```elixir\ndefdelegate numerator \u003c~\u003e denominator, to: Ratio, as: :new\n```\n\n### Basic functionality\n\nRational numbers can be manipulated using the functions in the [`Ratio`](https://hexdocs.pm/ratio/Ratio.html) module.\n\n```elixir\niex\u003e Ratio.mult(Ratio.new(1, 3), Ratio.new(1, 2))\nRatio.new(1, 6)\niex\u003e Ratio.div(Ratio.new(2, 3), Ratio.new(8, 5))\nRatio.new(5, 12)\niex\u003e Ratio.pow(Ratio.new(2), 4)\nRatio.new(16, 1)\n```\n\nThe Ratio module also contains:\n- a guard-safe `is_rational/1` check.\n- a `compare/2` function for use with e.g. `Enum.sort`.\n- `to_float/1` to (lossly) convert a rational into a float.\n\n### Inline Math Operators and Casting\n\nRatio interopts with the [`Numbers`](https://github.com/Qqwy/elixir-number) library:\nIf you want to overload Elixir's builtin math operators, \nyou can add `use Numbers, overload_operators: true` to your module.\n\nThis also allows you to pass in a rational number as one argument\nand an integer, float or Decimal (if you have installed the `Decimal` library),\nwhich are then cast to rational numbers whenever necessary:\n\n``` elixir\ndefmodule IDoAlotOfMathHere do\n  defdelegate numerator \u003c~\u003e denominator, to: Ratio, as: :new\n  use Numbers, overload_operators: true\n\n  def calculate(input) do\n     num = input \u003c~\u003e 2\n     result = num * 2 + (3 \u003c~\u003e 4) * 5.0\n     result / 2\n  end\nend\n\n```\n\n``` elixir\niex\u003e IDoAlotOfMathHere.calculate(42)\nRatio.new(183, 8)\n```\n\n\n## Installation\n\n  The package can be installed from hex, by adding `:ratio` to your list of dependencies in `mix.exs`:\n\n        def deps do\n          [\n            {:ratio, \"~\u003e 4.0\"}\n          ]\n        end\n\n\n\n## Changelog\n- 4.0.1 - \n  - Fix compiler warnings on Elixir v1.16 (c.f. #128). Thank you, @kidq330\n- 4.0.0 - \n  - Remove infix operator `\u003c|\u003e` as its usage is deprecated in Elixir v1.14. This is a backwards-incompatible change. If you want to use the old syntax with the new version, add `defdelegate num \u003c|\u003e denom, to: Ratio, as: :new` to your module. Alternatively, you might want to use the not-deprecated `\u003c~\u003e` operator for this instead.\n  - Switch the `Inspect` implementation to use the form `Ratio.new(10, 20)` instead of `10 \u003c|\u003e 20`, related to above. This is also a backwards-incompatible change.\n  - Remove implementation of `String.Chars`, as the earlier implementation was not a (non-programmer) human-readable format.\n  - Ensure that the right-hand-side operand of calls to `Ratio.{add, sub, mult, div}/2` is allowed to be an integer for ease of use and backwards compatibility. Thank you for noticing this problem, @kipcole9 ! (c.f. #111)\n- 3.0.2 - \n  - Fixes: A bug with `\u003c|\u003e` when the numerator was a rational and the denuminator an integer. (c.f. #104) Thank you, @varsill!\n- 3.0.1 -\n  - Fixes:\n    - Problem where `Ratio.ceil/1` would be off-by-one (c.f. #89). Thank you, @Hajto!\n    - Problem where `Ratio.pow/2` would return an integer rather than a new Ratio.(c.f. #100). Thank you, @speeddragon!\n- 3.0.0 - \n  - All operators except `\u003c|\u003e` are removed from Ratio. Instead, the operators defined by [`Numbers`](https://github.com/Qqwy/elixir-number) (which `Ratio` depends on) can be used, by adding `use Numbers, overload_operators: true` to your modules. (c.f. #34)\n  - All math-based functions expect and return `Ratio` structs (rather than also working on integers and returning integers sometimes if the output turned out to be a whole number).  (c.f. #43)\n    This makes the code more efficient and more clear for users.\n    - Ratio structs representing whole numbers are no longer implicitly converted 'back' to integers, as this behaviour was confusing. (c.f. #28)\n    - If conversion to/from other number-like types is really desired, \n      use the automatic conversions provided by `Ratio.new`, `\u003c|\u003e` \n      or (a bit slower but more general) the math functions exposed by [`Numbers`](https://github.com/Qqwy/elixir-number).\n      Ratio ships with implementations of `Coerce.defcoercion` for Integer -\u003e Ratio, Float -\u003e Ratio and Decimal -\u003e Ratio.\n  - `is_rational?/1` is replaced with the guard-safe `is_rational/1` (only exported on Erlang versions where `:erlang.map_get/2` is available, i.e. \u003e= OTP 21.0.) (c.f. #37)\n  - `Float.ratio/1` is now used to convert floats into `Ratio` structs, rather than maintaining a hand-written version of this logic. (c.f #46) Thank you, @marcinwasowicz !\n  - A lot of property-based tests have been added to get some level of confidence of the correctness of the library's operations.\n- 2.4.2 Uses `extra_applications` in `mix.exs` to silence warnings in Elixir 1.11 and onwards.\n- 2.4.1 Fixes a bug in the decimal conversion implementation where certain decimals were not converted properly. Thank you, @iterateNZ!\n- 2.4.0 Adds optional support for automatic conversion from [Decimal](https://github.com/ericmj/decimal)s. Thank you, @kipcole !\n- 2.3.1 Removes spurious printing statement in `Rational.FloatConversion` that would output a line of text at compile-time. Fixes support for Numbers v5+ which was broken.\n- 2.3.0 Adds `trunc` and `to_floor_error` functions.\n- 2.1.1 Fixes implementation of `floor` and `ceil` which was counter-intuitive for negative numbers (it now correctly rounds towards negative infinity). \n  - Drops support for Elixir versions older than 1.4, because of use of `Integer.floor_div`.\n  - First version to support new Erlang versions (20 and onward) that have native `floor` and `ceil` functions.\n- 2.1.0 Adds optional overloaded comparison operators.\n- 2.0.0 Breaking change: Brought `Ratio.compare/2` in line with Elixir's comparison function guideline, to return `:lt | :eq | :gt`. (This used to be `-1 | 0 | 1`).\n- 1.2.9 Improved documentation. (Thanks, @morontt!)\n- 1.2.8 Adding `:numbers` to the `applications:` list, to ensure that no warnings are thrown when building releases on Elixir \u003c 1.4.0.\n- 1.2.6, 1.2.7 Improving documentation.\n- 1.2.5 added `ceil/1` and `floor/1`.\n- 1.2.4 Fixes Elixir 1.4 warnings in the `mix.exs` file.\n- 1.2.3 Upgraded version of the `Numbers` dependency to 2.0.\n- 1.2.2 Added default argument to `Ratio.new/2`, to follow the Numeric behaviour fully, and added `Ratio.minus/1` as alias for `Ratio.negate/1` for the same reason.\n- 1.2.0 Changed name of `Ratio.mul/2` to `Ratio.mult/2`, to avoid ambiguety, and to allow incorporation with `Numbers`. Deprecation Warning was added to using `Ratio.mul/2`.\n- 1.1.1 Negative floats are now converted correctly.\n- 1.1.0 Elixir 1.3 compliance (Statefree if/else/catch clauses, etc.)\n- 1.0.0 Proper `__using__` macro, with more readable option names. Stable release.\n- 0.6.0 First public release\n- 0.0.1 First features\n\n\n## Difference with the 'rational' library\n\nObservant readers might notice that there also is a '[rational](https://hex.pm/packages/rational)' library in Hex.pm. The design idea between that library vs. this one is a bit different: `Ratio` hides the internal data representation as much as possible, and numbers are therefore only created using `Ratio.new/2`. This has as mayor advantage that the internal representation is always correct and simplified.\n\nThe Ratio library also (optionally) overrides (by virtue of the `Numbers` library) the built-in math operations `+, -, *, /, div, abs` so they work with combinations of integers, floats and rationals.\n\nFinally, Ratio follows the Numeric behaviour, which means that it can be used with any data types that follow [Numbers](https://github.com/Qqwy/elixir_number).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FQqwy%2Felixir-rational","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FQqwy%2Felixir-rational","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FQqwy%2Felixir-rational/lists"}