{"id":13509324,"url":"https://github.com/carturoch/ex_uc","last_synced_at":"2025-10-21T14:59:05.375Z","repository":{"id":62429477,"uuid":"66878169","full_name":"carturoch/ex_uc","owner":"carturoch","description":"Elixir Unit Converter","archived":false,"fork":false,"pushed_at":"2022-10-10T15:34:40.000Z","size":88,"stargazers_count":21,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-01T19:21:26.392Z","etag":null,"topics":["conversion","hex","units-of-measure"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/ex_uc","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/carturoch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-29T20:29:44.000Z","updated_at":"2024-07-15T10:00:42.000Z","dependencies_parsed_at":"2022-11-01T20:01:57.285Z","dependency_job_id":null,"html_url":"https://github.com/carturoch/ex_uc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carturoch%2Fex_uc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carturoch%2Fex_uc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carturoch%2Fex_uc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carturoch%2Fex_uc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carturoch","download_url":"https://codeload.github.com/carturoch/ex_uc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222552802,"owners_count":17002160,"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":["conversion","hex","units-of-measure"],"created_at":"2024-08-01T02:01:06.196Z","updated_at":"2025-10-21T14:59:05.296Z","avatar_url":"https://github.com/carturoch.png","language":"Elixir","funding_links":[],"categories":["Text and Numbers"],"sub_categories":[],"readme":"# ExUc - Elixir Unit Converter\n\n[![Build Status](https://travis-ci.org/carturoch/ex_uc.svg?branch=master)](https://travis-ci.org/carturoch/ex_uc)\n\nConverts values between units.\n\n## Installation\n\nFrom [Hex](https://hexdocs.pm/ex_uc), the package can be installed as:\n\n  1. Add `ex_uc` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [{:ex_uc, \"~\u003e 1.2\"}]\nend\n```\n\n### Requirements\n\nThis package requires _Elixir **1.5+**_\n\n## Usage\n\nThe quickest way is the function `convert`:\n```elixir\niex\u003eExUc.convert(\"5 pounds\", \"oz\")\n\"80.00 oz\"\n```\nThis is just a shortcut for the 3-steps pipeline:\n```elixir\nimport ExUc\n\nnew_val = from(\"5 pounds\")  # %ExUc.Value{unit: :lb, value: 5, kind: :mass}\n|\u003e to(:oz)                  # %ExUc.Value{unit: :oz, value: 80, kind: :mass}\n|\u003e as_string                # \"80.00 oz\"\n```\n\nThe same unit can be identified by several aliases:\n```elixir\nconvert(\"5 km\", \"miles\") # \"3.11 miles\"\nconvert(\"5 kms\", \"mi\") # \"3.11 mi\"\nconvert(\"5 kilometers\", \"mile\") # \"3.11 mile\"\nconvert(\"5km\", \"mile\") # \"3.11 mile\"\n```\n\n### Errors\n\nOnly two errors are returned when found, both as self descriptive **strings**:\n\n  - `\"undefined origin\"`: Unit for the original value can't be parsed or found in any defined kind.\n  - `\"undetermined conversion\"`: Conversion between the given units can't be determined.\n\n\n## Configuration\n\nConfigurable variables are:\n\n  - `precision` How many decimals will have the result when is converted into **string**\n  - `allow_exact_results` When `true`, truncates decimal zeros in exact results.\n  - `units_modules` Names of kinds of units used. Defaults to the included modules.\n\nCould be set as:\n```elixir\nconfig :ex_uc, precision: 2\nconfig :ex_uc, allow_exact_results: false\nconfig :ex_uc, units_modules: ~w(length mass)\n```\n\n## Included Units\n\nIncluded are some of the most frequent units grouped by kinds:\n\n  - Length: (`m`, `km`, `cm`, `mm`, `ft`, `in`, `yd`, `mi`, `ft_in`).\n  - Mass: (`g`, `kg`, `mg`, `lb`, `oz`, `lb_oz`).\n  - Time: (`μs`, `ms`, `s`, `min`, `h`, `d`).\n  - Temperature: (`C`, `F`, `K`).\n  - Speed: (`km/h`, `mph`, `m/s`, `kn`).\n  - Pressure: (`Pa`,  `hPa`,  `kPa`,  `bar`,  `at`,  `atm`,  `mmHg`,  `psi`).\n  - Memory: (`B`, `KB`, `MB`, `GB`, `TB`, `PB`, `EB`, `ZB`, `YB`, `b`, `Kb`, `Mb`, `Gb`, `Tb`, `Pb`, `Eb`, `Zb`, `Yb`, `KiB`, `MiB`, `GiB`, `TiB`, `PiB`, `EiB`, `ZiB`, `YiB`).\n\n## Extending ExUc\n\n### Overriding Conversions\n\nDefault conversions may be overridden just by providing a new value to in a configuration file:\n\n```elixir\nconfig :ex_uc, :mass_conversions, # The kind suffixed with _conversions\n  kg_to_lb: 2.20462 # More precise factor required\n  # More units within this kind could go here\n```\n\nThere are three types of conversion:\n\n- **Factor**: A numeric value, like in the previous example, that is gonna be used to multiply the origin value. _Most conversions can use this type_.\n\n- **Formula**: A function where one or more operation will performed to the origin value.\n_Example_:\n```elixir\nconfig :ex_uc, :_temperature_conversions,\n  C_to_F: \u0026(\u00261 * 1.8 + 32),\n```\n\n- **Special**: An atom referencing a function in a module. This function takes the origin value and returns a string. _Right now this is only used for composed units and can not be overridden_.\n\n### Updating Alias for Existent Units\n\nAn alias is just another term that can be used to reference an existent unit and therefore all its conversions.\n\n```elixir\nconfig :ex_uc, :length_units, # The kind suffixed with _units\n  m: [\"meter\", \"meters\", \"mètre\", \"mètres\"]\n```\n\nThe main unit (`m`, in the sample) should be used as the key for the list of aliases, and such list must include every desired alias.\n\nEvery _main unit_ and default aliases for included units, are in the [docs](https://hexdocs.pm/ex_uc) in the *Included Units and Aliases* sections.\n\n### Adding New Units to Existent **Kinds**\n\nNew units can be added in configuration files by providing aliases for the new unit and a conversion to or from an existent unit of the same **kind**:\n\n```elixir\nconfig :ex_uc, :length_units,\n  dm: ~w(decimeter decimeters), # Main unit and aliases\n\nconfig :ex_uc, :length_conversions,\n  m_to_dm: 10, # A conversion from an existent unit\n```\n\n### Adding New **Kinds**\n\nNew unit types (_kinds_) should be defined using configuration options for `:ex_uc` application. Each unit must have definitions for _units_ and _conversions_ (See some included examples at `config/units` in this repository).\n\nA new kind should have this structure:\n\n```elixir\nuse Mix.Config\n\nconfig :ex_uc, :\u003cKIND\u003e_units,\n  \u003cUNIT\u003e: [\"alias 1\", \"alias 2\", \"alias N\"], # List with every alias intended to relate to unit identified by UNIT\n\nconfig :ex_uc, :\u003cKIND\u003e_conversions,\n  \u003cUNIT_A\u003e_to_\u003cUNIT_B\u003e: 0.001,      # Multiplication factor\n  \u003cUNIT_C\u003e_to_\u003cUNIT_D\u003e: \u0026(\u00261 + 5)   # Conversion formula.\n  \u003cUNIT_X\u003e_to_\u003cUNIT_Y\u003e: :special    # Atom referencing a special method.  \n```\n\nThis new kind will be included automatically without the need to specify it in `:units_modules`.\n\n### Better Unit Conversions\n\n**PRs** or **Issues** with bugs, new units or more accurate default conversions are welcome.\n\n## Documentation\n\nDetailed documentation can be found at [hex docs](https://hexdocs.pm/ex_uc).\n\n## Note\n\nThis project was inspired by the awesome [Ruby gem](https://github.com/olbrich/ruby-units) by _Kevin C. Olbrich, Ph.D._\n\n## License\n\n[MIT](https://github.com/carturoch/ex_uc/blob/master/License.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarturoch%2Fex_uc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarturoch%2Fex_uc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarturoch%2Fex_uc/lists"}