Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
U

unitwise

> 编程语言
Open source

Physical quantity and units of measure conversion and math for Ruby

286 stars0 likes1 views
WebsiteGitHub

About

Physical quantity and units of measure conversion and math for Ruby

Unitwise

Unitwise is a Ruby library for unit measurement conversion and math.

For an over the top example, consider a car (2800 lb) completing the quarter mile in 10 seconds (with uniform acceleration).

ruby
require 'unitwise'

distance = Unitwise(0.25, 'mile')   # => #
time     = Unitwise(10,   'second') # => #
mass     = Unitwise(2800, 'pound')  # => #

acceleration = 2.0 * distance / time ** 2
# => #

force = (mass * acceleration).to_lbf
# => #

power = (force * distance / time).to_horsepower
# => #

speed = ((2.0 * acceleration * distance) ** 0.5).convert_to("mile/hour")
# => #

RubyTapas subscribers can also view a screencast: 225-Unitwise

Rationale

Unitwise is based on the Unified Code for Units of Measure(UCUM), which aims to maintain a cross-platform list of units and their conversions. This gives Unitwise a few key advantages:

  • An enormous list of units. At the time of writing, there are 96 metric units, 211 non-metric units, and 24 unit prefixes. Whatever unit/units you need, they are here.

  • An accurate and up to date set of units. The units, prefixes, and conversions are maintained by UCUM, and are imported into this library with a rake task.

One of the objectives of Unitwise was that it should comprehend any combination of units. For instance it needed to understand that a unit of 'kilogram.(meter/second)2' was equivalent to 'kilogram.meter.(meter/second2)'. This resulted in two unique features:

  • An expression grammar built with a PEG parser. This makes expression parsing more efficient and allows nested parentheses. For example, this is possible: '(kilogram.(meter/second)2)2'

  • Smart compatibility detection. Each unit is reduced down to its most elementary atoms to determine compatibility with another unit. For example, it knows that 'meter/second2' should be considered compatible with 'kilogram.foot.minute-2/pound'.

Usage

Initialization:

Measurements can be instantiated with Unitwise().

ruby
require 'unitwise'

Unitwise(2.3, 'kilogram') # => #
Unitwise(100, 'pound')    # => #

Conversion

Unitwise is able to convert any unit within the UCUM spec to any other compatible unit.

ruby
Unitwise(5.0, 'kilometer').convert_to('mile')
# => #

The prettier version of convert_to(unit) is appending the unit code, name, etc. to a to_ message name.

ruby
Unitwise(26.2, 'mile').to_kilometer
# => #

Comparison

It also has the ability to compare measurements with the same or different units.

ruby
Unitwise(12, 'inch') == Unitwise(1, 'foot') # => true
Unitwise(1, 'meter') > Unitwise(1, 'yard')  # => true

Again, you have to compare compatible units. For example, comparing two temperatures will work, comparing a mass to a length would fail.

SI abbreviations

You can use shorthand for SI units.

ruby
Unitwise(1000, 'm') == Unitwise(1, 'km')  # => true
Unitwise(1, 'ml') == Unitwise(0.001, 'l') # => true

Complex Units

Units can be combined to make more complex ones. There is nothing special about them -- they can still be converted, compared, or operated on.

ruby
speed = Unitwise(60, 'mile/hour')
# => #

speed.convert_to('m/s')
# => #

Exponents and parenthesis are supported as well.

ruby
Unitwise(1000, 'kg.s-1.(m/s)2').to_kilowatt
# => #

Math

You can add or subtract compatible measurements.

ruby
Unitwise(2.0, 'meter') + Unitwise(3.0, 'inch') - Unitwise(1.0, 'yard')
# => #

You can multiply or divide measurements and numbers.

ruby
Unitwise(110, 'volt') * 2
# => #

You can multiply or divide measurements with measurements.

ruby
Unitwise(20, 'milligram') / Unitwise(1, 'liter')
# => #

Exponentiation is also supported.

ruby
(Unitwise(10, 'cm') ** 3).to_liter
# => #

Unit Names and Atom Codes

This library is based around the units in the UCUM specification, which is extensive and well thought out. However, not all of our unit systems throughout the world and history are consistent or logical. UCUM has devised a system where each unit has a unique atom code to try and solve this. The previous code examples don't show this, because for the most part you won't need it. Unitwise can figure out most of the units by their name or symbol. If you find you need to (or just want to be explicit) you use the UCUM atom codes without any modification.

Just for example, you can see here that there are actually a few versions of inch and foot:

ruby
Unitwise(1, '[ft_i]') == Unitwise(1, '[ft_us]') # => false

Unitwise(3, '[in_br]') == Unitwise(3, '[in_i]') # => false

Available Units

If you are looking for a particular unit, you can search with a string or Regexp.

ruby
Unitwise.search('fathom')
# => [ ... ]

You can also get the official list from the UCUM website in XML format at unitsofmeasure.org/ucum-essence.xml or a YAML version within this repo github.com/joshwlewis/unitwise/tree/master/data.

UCUM designations

UCUM defines several designations for it's units: names, primary_code, secondary_code, and symbol. You can see them all when inspecting an atom:

ruby
Unitwise::Atom.all.sample
# => #, classification="heat", property="energy", metric=false, special=false, arbitrary=false, dim="L2.M.T-2">

When initializing a measurement, you can use any of the designations:

ruby
Unitwise(1, '[Btu]') == Unitwise(1, 'British thermal unit')
# => true
Unitwise(1, 'btu') == Unitwise(1, "[BTU]")
# => true

When inspecting or printing (to_s) that measurement, it will remember the desigation you used. However, if you want to print it with another designation, that's also possible:

ruby
temperature = Unitwise(10, "Cel")
temperature.to_s # => "10 Cel"
temperature.to_s(:names) # => "10 degree Celsius"
temperature.to_s(:symbol) # => "10 °C"

There is on caveat here. You must use the same designation for each atom in a complex unit. Meaning you can't mix designations within a unit.

ruby
Unitwise(1, "m/s")          # Works, both atoms use their primary_code
Unitwise(1, "meter/second") # Works, both atoms use a name
Unitwise(1, "meter/s")      # Does not work, mixed designations (name and primary_code)
Unitwise(1, "meter") / Unitwise(1, "s") # Also works

Adding custom units

While UCUM's list of units is rather exhaustive, there may still be occasions where you need custom or uncommon measurements. You can add them yourself with Unitwise.register, which will allow you to convert to or from the new unit.

For example, if your app needed to pour "3 fingers" of bourbon, you could register an atom for that:

ruby
Unitwise.register(
  names: ["finger", "fingers"],
  symbol: "",
  primary_code: "fng",
  secondary_code: "fng",
  scale: {
    value: 1.0,
    unit_code: '[foz_us]'
  },
  property: 'fluid volume'
)

Unitwise(1, "gallon").to_fingers
# => #

Unitwise(1, "").to_cup
# => #

Supported Ruby Versions

This library aims to support and is tested against the following Ruby implementations:

  • Ruby 2.6 - 3.1
  • JRuby
  • TruffleRuby

If something doesn't work on one of these versions, it's a bug.

This library may inadvertently work (or seem to work) on other Ruby versions or implementations, however support will only be provided for the implementations listed above.

Installation

Add this line to your application's Gemfile:

gem 'unitwise'

And then execute:

$ bundle

Or install it yourself as:

$ gem install unitwise

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Issues· 24 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Ruby

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 18, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言