Ruby Units

Ruby-units distinguishes between a temperature (a property/point on a scale, e.g., tempC) and degrees of temperature (a differential/interval, e.g., degC).

• Temperature (tempX): Can be converted between scales (e.g., tempC to tempF) taking zero-point differences into account. Math is limited: you can subtract two temperatures to get a differential, but you cannot add two temperatures together.
• Differential (degX): Behaves like standard units.

Warning: Attempting to create a temperature below absolute zero will raise an exception.

Unit.new('37 tempC').convert_to('tempF')   #=> 98.6 tempF
Unit.new('100 tempC') - Unit.new('10 tempC') #=> '90 tempC'.to_unit

Ruby-units extends Time, Date, and DateTime to allow natural duration arithmetic.

Adding/Subtracting Durations:

• Time.now + Unit.new("10 min")
• Date.today - Unit.new("30 days")

Note on Large Units: When using years, decades, or centuries, the duration is converted to days and rounded to maintain calendar accuracy (e.g., 1 year $\approx$ 365 days). For precision, use hours or minutes.

Converting Time to Units:

• Time.now.to_unit: Returns duration in seconds since epoch.
• Date.today.to_unit('week'): Returns duration in weeks since Julian calendar start.

Creating Time from Units:

• Time.at(Unit.new("1 hour"))
• Time.in('5 min'): Shorthand for future times.

Time.now + Unit.new("10 min")   #=> 10 minutes from now
Time.now.to_unit('hours')       #=> Duration in hours since epoch
Time.in('2 hours')               #=> 2 hours from now

To manage the dependency via Bundler, add the following line to your Gemfile:

gem 'ruby-units'

You can install the ruby-units gem using the system gem command or by adding it to your Gemfile. This package requires Ruby 3.2 or later.

gem install ruby-units

If the global Unit class conflicts with other gems, you can use the RubyUnits namespace instead. To do this, require ruby_units/namespaced instead of the standard library.

Note: When using the namespaced version, the Unit.new('unit string') helper is not defined; you must use RubyUnits::Unit.new.

# In your code
require 'ruby_units/namespaced'

# In your Gemfile
gem 'ruby-units', require: 'ruby_units/namespaced'

Global configuration can be managed via RubyUnits.configure. This affects how units are formatted and displayed.

Options:

• format: Output format. :rational (default, e.g., 3 m/s^2) or :exponential (e.g., 3 m*s^-2).
• separator: Space between number and unit. :space (default) or :none (e.g., 3m/s).
• default_precision: Precision for rationalizing fractional values (default 0.0001).

Use RubyUnits.reset to return to defaults.

RubyUnits.configure do |config|
  config.format = :exponential
  config.separator = :none
  config.default_precision = 0.001
end

When working with temperature units, the library ensures that values do not fall below absolute zero. If a unit is identified as a temperature unit and the base scalar is negative, an ArgumentError is raised.

Error message: "Temperatures must not be less than absolute zero"

When performing arithmetic with Time and RubyUnits::Unit, the library distinguishes between 'exact' durations and 'calendar' durations to prevent precision errors caused by varying year lengths.

1. Exact Durations: Units like second, minute, and hour are converted directly to seconds.
2. Calendar Durations: Units like year, decade, and century are converted to days first, rounded to the nearest whole day, and then converted to seconds. This ensures that adding '1 year' behaves more like a calendar year than a fixed number of seconds (e.g., 31,536,000s).

You can customize the global behavior of the RubyUnits library, such as how units are formatted and spaced, using the RubyUnits.configure block or by accessing the RubyUnits.configuration object directly. This allows you to control output representation without modifying individual unit instances.

RubyUnits.configure do |config|
  config.separator = :none
  config.format = :exponential
  config.default_precision = 0.0001
end

Units can be converted to different scales or compared against each other.

Conversion:

• unit.convert_to('ft'): Returns a new converted unit.
• unit >> "ft": Converts to 'feet'.
• unit >>= "ft": Converts and overwrites the original object.

Comparison:

• unit1 <=> unit2: Compares quantities in base units (throws exception if incompatible).
• unit1 === unit2: Returns true only if units and quantity are identical.

unit.convert_to('ft')             # convert
unit1 = unit >> "ft"              # convert to 'feet'
unit1 <=> unit2                   # comparison on quantities in base units