一个用于 ruby 的库处理单元
Kevin C. Olbrich, Ph.D.
Project page: http://github.com/olbrich/ruby-units
Many technical applications make use of specialized calculations at some point. Frequently, these calculations require unit conversions to ensure accurate results. Needless to say, this is a pain to properly keep track of, and is prone to numerous errors.
The 'Ruby units' gem is designed to simplify the handling of units for scientific calculations. The units of each quantity are specified when a Unit object is created and the Unit class will handle all subsequent conversions and manipulations to ensure an accurate result.
This package requires Ruby 3.2 or later.
This package may be installed using:
gem install ruby-unitsor add this to your Gemfile
gem 'ruby-units'…Many methods require that the units of two operands are compatible. Compatible units are those that can be easily converted into each other, such as 'meters' and 'feet'.
unit1 =~ unit2 #=> true if units are compatible
unit1.compatible?(unit2) #=> true if units are compatible…Unit will coerce other objects into a Unit if used in a formula. This means...
Unit.new("1 mm") + "2 mm" == Unit.new("3 mm")This will work as expected so long as you start the formula with a Unit
object.
Units can be converted to other units in a couple of ways.
…Any object that defines a to_unit method will be automatically coerced to a
unit during calculations.
Units will display themselves nicely based on the display_name for the units and
prefixes. Since Unit implements a Unit#to_s, all that is needed in most
cases is:
"#{Unit.new('1 mm')}" #=> "1 mm"The to_s also accepts some options.
Unit.new('1.5 mm').to_s("%0.2f") # "1.50 mm". Enter any valid format
# string. Also accepts strftime format
Unit.new('10 mm').to_s("%0.2f in")# "0.39 in". can also format and convert in
# the same time.
Unit.new('1.5 mm').to_s("in") # converts to inches before printing
Unit.new("2 m").to_s(:ft) # returns 6'7"
Unit.new("100 kg").to_s(:lbs) # returns 220 lbs, 7 oz
Unit.new("100 kg").to_s(:stone) # returns 15 stone, 10 lbYou can also use Ruby's standard string formatting operator (%) with units:
'%0.2f' % '1 mm'.to_unit # "1.00 mm"
'%0.2f in' % '1 mm'.to_unit # "0.04 in" - format and convert
'%.2e' % '1000 m'.to_unit # "1.00e+03 m" - scientific notationStrings can be converted to units using the convert_to method:
'10 mm'.convert_to('cm') # converts directly to centimeters
'100 km/h'.convert_to('m/s') # converts compound unitsRuby-units extends the Time, Date, and DateTime classes to support unit-based arithmetic,
allowing you to add or subtract durations from time objects naturally.
Time.now + Unit.new("10 min") #=> 10 minutes from now
Time.now - Unit.new("2 hours") #=> 2 hours ago
Date.today + Unit.new("1 week") #=> 7 days from today
Date.today - Unit.new("30 days") #=> 30 days agoImportant: When adding or subtracting large time units (years, decades, centuries),
the duration is first converted to days and rounded to maintain calendar accuracy.
This means 1 year is treated as approximately 365 days rather than an exact number of seconds.
Time.now + Unit.new("1 year") #=> Approximately 365 days from now
Time.now - Unit.new("1 decade") #=> Approximately 3650 days agoFor more precise durations, use smaller units (hours, minutes, seconds):
Time.now + Unit.new("24 hours") #=> Exactly 24 hours from nowYou can convert Time objects to units representing the duration since the Unix epoch:
Time.now.to_unit #=> Duration in seconds since epoch
Time.now.to_unit('hours') #=> Duration in hours since epoch
Time.now.to_unit('days') #=> Duration in days since epochYou can convert Date objects to units representing days since the Julian calendar start:
Date.today.to_unit #=> Duration in days since Julian calendar start
Date.today.to_unit('week') #=> Duration in weeks since Julian calendar start
Date.today.to_unit('year') #=> Duration in years since Julian calendar startUse Time.at to create a Time object from a duration unit:
Time.at(Unit.new("1000 seconds")) #=> Time 1000 seconds after epoch
Time.at(Unit.new("1 hour"), 500, :ms) #=> Time 1 hour + 500 milliseconds after epochThe Time.in method provides a shorthand for calculating future times:
Time.in('5 min') #=> 5 minutes from now
Time.in('2 hours') #=> 2 hours from nowDurations may be entered as 'HH:MM:SS, usec' and will be returned in 'hours'.
Unit.new('1:00') #=> 1 h
Unit.new('0:30') #=> 0.5 h
Unit.new('0:30:30') #=> 0.5 h + 30 secIf only one ":" is present, it is interpreted as the separator between hours and minutes.
Several helpers are available for working with natural language time parsing. Note: If you include the 'Chronic' gem, you can specify times in natural language.
Unit.new('min').since(DateTime.parse('9/18/06 3:00pm'))If time arithmetic would result in a date outside the valid range for the Time class
(typically 1970-2038 on 32-bit systems), ruby-units automatically falls back to using
DateTime objects to handle the calculation.
[Unit.new('0 h')..Unit.new('10 h')].each {|x| p x}works so long as the starting point has an integer scalar
Ruby-units extends the Math module to support Unit objects seamlessly. All trigonometric
and mathematical functions work with units, handling conversions automatically.
Trigonometric Functions (angles converted to radians automatically):
sin, cos, tan - Standard trigonometric functionssinh, cosh, tanh - Hyperbolic trigonometric functionsInverse Trigonometric Functions (return angles in radians as Unit objects):
asin, acos, atan - Inverse trigonometric functionsatan2 - Two-argument arctangent for full quadrant determinationRoot Functions (preserve dimensional analysis):
sqrt - Square root (e.g., √(4 m²) = 2 m)cbrt - Cube root (e.g., ³√(27 m³) = 3 m)Other Functions:
hypot - Euclidean distance calculation with unitslog, log10 - Logarithmic functions (extract scalar from units)…Note: Trigonometric functions expect angular units or dimensionless numbers. If you pass a Unit with dimensions (like meters), it will be converted to radians, which may produce unexpected results.
Ruby-units makes a distinction between a temperature (which technically is a property) and degrees of temperature (which temperatures are measured in).
Temperature units (i.e., 'tempK') can be converted back and forth, and will take into account the differences in the zero points of the various scales. Differential temperature (e.g., Unit.new('100 degC')) units behave like most other units.
Unit.new('37 tempC').convert_to('tempF') #=> 98.6 tempFRuby-units will raise an exception if you attempt to create a temperature unit that would fall below absolute zero.
Unit math on temperatures is fairly limited.
…This conversion references the 0 point on the scale of the temperature unit
Unit.new('100 degC').convert_to('tempC') #=> '-173 tempC'.to_unitThese conversions are always interpreted as being relative to absolute zero. Conversions are probably better done like this...
Unit.new('0 tempC') + Unit.new('100 degC') #=> Unit.new('100 tempC')It is possible to define new units or redefine existing ones.
The easiest approach is to define a unit in terms of other units using the block form.
Unit.define("foobar") do |foobar|
foobar.definition = Unit.new("1 foo") * Unit.new("1 bar") # anything that results in a Unit object
foobar.aliases = %w{foobar fb} # array of synonyms for the unit
foobar.display_name = "Foobar" # How unit is displayed when output
endYou can also create a unit definition directly and pass it to Unit.define:
unit_definition = Unit::Definition.new("foobar") do |foobar|
foobar.definition = Unit.new("1 baz")
foobar.aliases = %w{foobar fb}
foobar.display_name = "Foobar"
end
Unit.define(unit_definition)For more control, you can set the unit attributes explicitly:
Unit.define("electron-volt") do |ev|
ev.aliases = %w{eV electron-volt electron_volt}
ev.scalar = 1.602e-19
ev.kind = :energy
ev.numerator = %w{ }
ev.denominator = %w{ }
ev.display_name = "electron-volt"
endRedefining a unit allows the user to change a single aspect of a definition without having to re-create the entire definition. This is useful for changing display names, adding aliases, etc.
Unit.redefine!("cup") do |cup|
cup.display_name = "cup"
endscalar will return the numeric portion of the unit without the attached
unitsbase_scalar will return the scalar in base units (SI)units will return the name of the units (without the scalar)base will return the unit converted to base units (SI)best_prefix will return a new unit scaled with an appropriate prefix for
human readability (e.g., '1000 m' becomes '1 km')Units can be stored in a database as either the string representation or in two separate columns defining the scalar and the units. Note that if sorting by units is desired you will want to ensure that you are storing the scalars in a consistent unit (i.e, the base units).
Sometimes the default class 'Unit' may conflict with other gems or applications.
Internally ruby-units defines itself using the RubyUnits namespace. The actual
class of a unit is the RubyUnits::Unit. For simplicity and backwards
compatibility, the ::Unit class is defined as an alias to ::RubyUnits::Unit.
To load ruby-units without this alias...
require 'ruby_units/namespaced'When using bundler...
gem 'ruby-units', require: 'ruby_units/namespaced'Note: when using the namespaced version, the Unit.new('unit string') helper
will not be defined.
Configuration options can be set like:
RubyUnits.configure do |config|
config.format = :rational
config.separator = :none
config.default_precision = 0.001
end| Option | Description | Valid Values | Default |
|---|---|---|---|
format |
Only used for output formatting. :rational is formatted like 3 m/s^2. :exponential is formatted like |
暂无开放 Issues,或尚未同步最近议题。