quantify 1.0.0

data/lib/quantify/unit/unit.rb

@@ -0,0 +1,217 @@
+#! usr/bin/ruby
+
+module Quantify
+  module Unit
+
+    extend ExtendedMethods
+
+    # The Unit module contains functionality for defining and handling
+    # representations of physical units.
+    #
+    # All units are defined using the Unit::SI and Unit::NonSI classes, both of
+    # which inherit from Unit::Base.
+    #
+    # New units can be defined to represent whatever is required. However a
+    # system of known units is stored in the Unit module instance variable
+    # @units, accessible using Unit.units. These known units can be configured
+    # to represent which ever units are required. The Unit module will handle
+    # any combinations of units and prefixes according to the known units and
+    # prefixes specified in config.rb. New units can be defined (with or without
+    # prefixes) at any time and either used in place or loaded into the known
+    # system.
+
+    # Make the @units instance array readable
+    class << self
+      attr_reader :units
+    end
+
+    def self.configure &block
+      self.class_eval &block if block
+    end
+
+    # Instance variable containing system of known units
+    @units = []
+
+    # Load a new unit into they system of known units
+    def self.load(unit)
+      @units << unit if unit.is_a? Unit::Base
+    end
+
+    # Remove a unit from the system of known units
+    def self.unload(*unloaded_units)
+      [unloaded_units].flatten.each do |unloaded_unit|
+        unloaded_unit = Unit.for(unloaded_unit)
+        @units.delete_if { |unit| unit.label == unloaded_unit.label }
+      end
+    end
+
+    # Returns an instance of the class Quantity which represents the ratio of two
+    # units. For example, the ratio of miles to kilometers is 1.609355, or there
+    # are 1.609355 km in 1 mile.
+    #
+    #   ratio = Unit.ratio :km, :mi         #=> <Quantify::Quantity:0xj9ab878a7>
+    #
+    #   ratio.to_s :name                    #=> "1.609344 kilometres per mile"
+    #
+    # In other words the quantity represents the definition of one unit in terms
+    # of the other.
+    #
+    def self.ratio(unit,other_unit)
+      unit = Unit.for unit
+      other_unit = Unit.for other_unit
+      unless unit.is_alternative_for? other_unit
+        raise InvalidUnitError, "Units do not represent the same physical quantity"
+      end
+      new_unit = (unit / other_unit)
+      value = 1/new_unit.factor
+      Quantity.new(value, new_unit)
+    end
+
+    # Retrieve an object representing the specified unit.
+    #
+    # Argument can be the unit name, symbol or JScience label and provided as
+    # a string or a symbol, e.g.
+    #
+    #   Unit.for :metre
+    #
+    #   Unit.for 'kilogram'
+    #
+    # This can be shortened to, for example, Unit.metre by virtue of the
+    # #method_missing method (see below)
+    #
+    # This method will recognise valid combinations of known units and prefixes,
+    # irrespective of whether the prefixed unit has been initialized into the
+    # system of known units in it's own right. For example,
+    #
+    #   Unit.centimetre ... or, alternatively ... Unit.cm
+    #
+    # will return a Unit::SI object with attributes representing a centimetre
+    # based on the initialized Unit for :metre and Prefix :centi.
+    #
+    def self.for(name_symbol_label_or_object)
+      return name_symbol_label_or_object.clone if name_symbol_label_or_object.is_a? Unit::Base
+      return nil if name_symbol_label_or_object.nil? or
+        ( name_symbol_label_or_object.is_a?(String) and name_symbol_label_or_object.empty? )
+      name_symbol_or_label = name_symbol_label_or_object
+      unless name_symbol_or_label.is_a? String or name_symbol_or_label.is_a? Symbol
+        raise InvalidArgumentError, "Argument must be a Symbol or String"
+      end
+      if unit = Unit.match(name_symbol_or_label)
+        return unit
+      end
+      if unit = Unit.parse(name_symbol_or_label)
+        return unit
+      end
+    rescue InvalidUnitError
+      return nil
+    end
+
+    # Parse complex strings into unit.
+    #
+    def self.parse(string)
+      string = string.standardize
+      if string.scan(/(\/|per)/).size > 1
+        raise InvalidArgumentError, "Malformed unit: multiple uses of '/' or 'per'"
+      end
+
+      units = []
+      numerator, per, denominator = string.split(/(\/|per)/)
+      units += Unit.parse_numerator_units(numerator)
+      units += Unit.parse_denominator_units(denominator) unless denominator.nil?
+      if units.size == 1 and units.first.index == 1
+        return units.first.unit
+      else
+        return Unit::Compound.new(*units)
+      end
+    end
+
+    def self.match(name_symbol_or_label)
+      return name_symbol_or_label.clone if name_symbol_or_label.is_a? Unit::Base
+      Unit.match_known_unit_or_prefixed_variant(:label, name_symbol_or_label) or
+      Unit.match_known_unit_or_prefixed_variant(:name, name_symbol_or_label) or
+      Unit.match_known_unit_or_prefixed_variant(:symbol, name_symbol_or_label)
+    end
+
+    protected
+
+    def self.match_known_unit_or_prefixed_variant(attribute, string_or_symbol)
+      Unit.match_known_unit(attribute, string_or_symbol) or
+      Unit.match_prefixed_variant(attribute, string_or_symbol)
+    end
+
+    def self.match_known_unit(attribute, string_or_symbol)
+      string_or_symbol = Unit.format_unit_attribute(attribute, string_or_symbol)
+      unit = @units.find { |unit| unit.send(attribute) == string_or_symbol }
+      return unit.clone rescue nil
+    end
+
+    def self.match_prefixed_variant(attribute, string_or_symbol)
+      string_or_symbol = Unit.format_unit_attribute(attribute, string_or_symbol)
+      if string_or_symbol =~ /\A(#{Unit::Prefix.si_prefixes.map(&attribute).join("|")})(#{Unit.si_non_prefixed_units.map(&attribute).join("|")})\z/ or
+         string_or_symbol =~ /\A(#{Unit::Prefix.non_si_prefixes.map(&attribute).join("|")})(#{Unit.non_si_non_prefixed_units.map(&attribute).join("|")})\z/
+        return Unit.for($2).with_prefix($1).clone
+      end
+      return nil
+    end
+
+    # Standardizes query strings or symbols into canonical form for unit names,
+    # symbols and labels
+    #
+    def self.format_unit_attribute(attribute, string_or_symbol)
+      string_or_symbol = case attribute
+        when :symbol then string_or_symbol.standardize
+        when :name then string_or_symbol.standardize.singularize.downcase
+        else string_or_symbol.to_s
+      end
+    end
+    
+    def self.parse_unit_and_index(string)
+      string.scan(/([^0-9\^]+)\^?([\d\.-]*)?/i)
+      index = ($2.nil? or $2.empty? ? 1 : $2.to_i)
+      CompoundBaseUnit.new($1.to_s, index)
+    end
+
+    def self.parse_numerator_units(string)
+      # If no middot then names parsed by whitespace
+      # Need to consider multi word unit names
+      num_units = ( string =~ /·/ ? string.split("·") : string.split(" ") )
+      num_units.map! do |substring|
+        Unit.parse_unit_and_index(substring)
+      end
+    end
+
+    def self.parse_denominator_units(string)
+      Unit.parse_numerator_units(string).map do |unit|
+        unit.index *= -1
+        unit
+      end
+    end
+
+    # This can be replicated by method missing approach, but explicit method provided
+    # given importance in #match (and #for) methods regexen
+    #
+    def self.si_non_prefixed_units
+      @units.select {|unit| unit.is_si_unit? and not unit.is_prefixed_unit? }
+    end
+
+    # This can be replicated by method missing approach, but explicit method provided
+    # given importance in #match (and #for) methods regexen
+    #
+    def self.non_si_non_prefixed_units
+      @units.select {|unit| unit.is_non_si_unit? and not unit.is_prefixed_unit? }
+    end
+
+    def self.multi_word_unit_names
+      @units.map(&:name).compact.select {|name| name.word_count > 1 }
+    end
+
+    def self.multi_word_unit_pluralized_names
+      multi_word_unit_names.map(&:pluralize)
+    end
+
+    def self.multi_word_unit_symbols
+      @units.map(&:symbol).compact.select {|symbol| symbol.word_count > 1 }
+    end
+
+  end
+end

data/lib/quantify.rb

@@ -0,0 +1,26 @@
+
+# The Quantify library provides a system for handling physical quantities. Physical
+# quantities are represented by a value and a unit. Quantities can be added,
+# subtracted, multiplied, etc. or converted into alternative units
+#
+
+require 'pp'
+require 'rubygems'
+require 'active_support/inflector'
+require 'quantify/quantify'
+require 'quantify/core_extensions'
+require 'quantify/inflections'
+require 'quantify/exception'
+require 'quantify/dimensions'
+require 'quantify/unit/prefix/prefix'
+require 'quantify/unit/prefix/base_prefix'
+require 'quantify/unit/prefix/si_prefix'
+require 'quantify/unit/prefix/non_si_prefix'
+require 'quantify/unit/unit'
+require 'quantify/unit/base_unit'
+require 'quantify/unit/si_unit'
+require 'quantify/unit/non_si_unit'
+require 'quantify/unit/compound_base_unit'
+require 'quantify/unit/compound_unit'
+require 'quantify/quantity'
+require 'quantify/config'

data/spec/dimension_spec.rb

@@ -0,0 +1,294 @@
+require 'quantify'
+include Quantify
+
+describe Dimensions do
+
+  it "should hold array of recignised base quantities" do
+    Dimensions::BASE_QUANTITIES. should == [
+      :mass, :length, :time, :electric_current, :temperature,
+      :luminous_intensity, :amount_of_substance, :information,
+      :currency, :item ]
+  end
+
+  it "should return an array class variable" do
+    Dimensions.dimensions.class.should == Array
+  end
+
+  it "class variable should contain dimension objects" do
+    Dimensions.dimensions[0].class.should == Dimensions
+    Dimensions.dimensions[1].class.should == Dimensions
+  end
+
+  it "should list all physical quantities as strings" do
+    list = Dimensions.physical_quantities
+    list.should include "acceleration"
+    list.should include "force"
+    list.should_not include "effort"
+  end
+
+  it "should return correct dimension object with symbol :length" do
+    dimensions = Dimensions.for(:length)
+    dimensions.class.should == Dimensions
+    dimensions.length.should == 1
+    dimensions.mass.should == nil
+  end
+
+  it "should return correct dimension object with symbol :energy" do
+    dimensions = Dimensions.for(:energy)
+    dimensions.class.should == Dimensions
+    dimensions.length.should == 2
+    dimensions.mass.should == 1
+    dimensions.time.should == -2
+    dimensions.luminous_intensity.should == nil
+  end
+
+  it "should return correct dimension object with string 'energy'" do
+    dimensions = Dimensions.for('ENERGY')
+    dimensions.class.should == Dimensions
+    dimensions.length.should == 2
+    dimensions.mass.should == 1
+    dimensions.time.should == -2
+    dimensions.luminous_intensity.should == nil
+  end
+
+  it "should return correct dimension object with string 'length'" do
+    dimensions = Dimensions.for('length')
+    dimensions.class.should == Dimensions
+    dimensions.length.should == 1
+    dimensions.mass.should == nil
+  end
+
+  it "should raise error with invalid integer argument" do
+    lambda{dimensions = Dimensions.for(1)}.should raise_error
+  end
+
+  it "should raise error with unknown dimension" do
+    lambda{dimensions = Dimensions.for(:effort)}.should raise_error
+  end
+
+  it "should initialize a new object in @@dimensions class variable" do
+    Dimensions.load :physical_quantity => :some_dimensions, :length => 12
+    dimensions = Dimensions.for :some_dimensions
+    dimensions.class.should == Dimensions
+    dimensions.length.should == 12
+  end
+
+  it "should refuse to load new object in class array if no physical quantity" do
+    lambda{Dimensions.load :mass => 1}.should raise_error
+  end
+
+  it "should refuse to load new object in class array if no physical quantity" do
+    lambda{Dimensions.load :physical_quantity => nil, :mass => 1}.should raise_error
+  end
+
+  it "should create a new object with valid arguments" do
+    dimensions = Dimensions.new :mass => 1, :length => -2
+    dimensions.class.should == Dimensions
+    dimensions.mass.should == 1
+    dimensions.length.should == -2
+    dimensions.time.should == nil
+  end
+
+  it "should raise error with invalid arguments" do
+    lambda{dimension = Dimensions.new :acceleration => 1}.should raise_error
+  end
+
+  it "should identify the physical quantity and set ivar if known" do
+    dimensions = Dimensions.new :mass => 1
+    dimensions.describe.should == 'mass'
+    dimensions.physical_quantity.should == 'mass'
+  end
+
+  it "should identify the physical quantity if known" do
+    dimensions = Dimensions.new :mass => 1, :length => 2, :time => -2
+    dimensions.describe.should == 'energy'
+    dimensions.is_known?.should == true
+  end
+
+  it "should return nil if physical quantity not known" do
+    dimensions = Dimensions.new :mass => 81, :length => 2, :time => -2
+    dimensions.describe.should == nil
+    dimensions.is_known?.should == false
+  end
+
+  it "should return the correct dimensions representation on multiplying" do
+    dimensions_1 = Dimensions.for :length
+    dimensions_2 = Dimensions.for :length
+    dimensions_3 = dimensions_1 * dimensions_2
+    dimensions_3.class.should == Dimensions
+    dimensions_3.length.should == 2
+    dimensions_3.physical_quantity.should == 'area'
+  end
+
+  it "should return the correct dimensions representation on dividing" do
+    dimensions_1 = Dimensions.for :area
+    dimensions_2 = Dimensions.for :length
+    dimensions_3 = dimensions_1 / dimensions_2
+    dimensions_3.class.should == Dimensions
+    dimensions_3.length.should == 1
+    dimensions_3.physical_quantity.should == 'length'
+  end
+
+  it "should return the correct dimensions representation on raising to power" do
+    dimensions_1 = Dimensions.for :length
+    dimensions_2 = dimensions_1 ** 2
+    dimensions_2.class.should == Dimensions
+    dimensions_2.length.should == 2
+    dimensions_2.physical_quantity.should == 'area'
+  end
+
+  it "should return the correct dimensions representation on reciprocalize" do
+    dimensions_1 = Dimensions.for :time
+    dimensions_2 = dimensions_1.reciprocalize
+    dimensions_2.class.should == Dimensions
+    dimensions_2.time.should == -1
+    dimensions_2.physical_quantity.should == 'frequency'
+  end
+
+  it "should retrieve the correct dimension with dynamic method" do
+    Dimensions.acceleration.physical_quantity.should == 'acceleration'
+  end
+
+  it "should recognise length as a base quantity" do
+    dimension = Dimensions.length
+    dimension.is_base?.should == true
+  end
+
+  it "should recognise mass as a base quantity" do
+    dimension = Dimensions.mass
+    dimension.is_base?.should == true
+  end
+
+  it "should not recognise force as a base quantity" do
+    dimension = Dimensions.force
+    dimension.is_base?.should == false
+  end
+
+  it "should recognise plane angle as dimensionless" do
+    dimension = Dimensions.plane_angle
+    dimension.is_dimensionless?.should == true
+  end
+
+  it "should not recognise power as dimensionless" do
+    dimension = Dimensions.power
+    dimension.is_dimensionless?.should == false
+  end
+
+  it "should make an instance dimensionless" do
+    dimension = Dimensions.power
+    dimension.is_dimensionless?.should == false
+    dimension
+  end
+
+  it "should return appropriate associated units" do
+    dimension = Dimensions.power
+    units = dimension.units :name
+    units.class.should == Array
+    units.include?('watt').should == true
+  end
+
+  it "should return appropriate associated units" do
+    dimension = Dimensions.length
+    units = dimension.units :name
+    units.class.should == Array
+    units.include?('yard').should == true
+    units.include?('siemens').should == false
+  end
+
+  it "should return appropriate associated units" do
+    dimension = Dimensions.energy
+    units = dimension.units :symbol
+    units.class.should == Array
+    units.include?('J').should == true
+    units.include?('ft').should == false
+    units.include?('kWh').should == true
+  end
+
+  it "should return appropriate associated units" do
+    dimension = Dimensions.temperature
+    units = dimension.units :symbol
+    units.class.should == Array
+    units.include?('K').should == true
+    units.include?('°C').should == true
+    units.include?('L').should == false
+  end
+
+  it "should return correct SI unit" do
+    dimension = Dimensions.temperature
+    dimension.si_unit.symbol.should == 'K'
+  end
+
+  it "should return correct SI unit" do
+    dimension = Dimensions.power
+    dimension.si_unit.symbol.should == 'W'
+  end
+
+  it "should return correct SI unit" do
+    dimension = Dimensions.kinematic_viscosity
+    dimension.si_unit.name.should == 'square metre per second'
+  end
+
+  it "should return correct SI unit" do
+    dimension = Dimensions.mass
+    dimension.si_unit.symbol.should == 'kg'
+    dimension.si_unit.symbol.should_not == 'd'
+  end
+
+  it "should return correct SI unit" do
+    dimension = Dimensions.plane_angle
+    dimension.si_unit.symbol.should == 'rad'
+    dimension.si_unit.symbol.should_not == 'W'
+  end
+
+  it "should return the correct SI base units" do
+    units = Dimensions.mass.si_base_units :name
+    units.class.should == Array
+    units.include?('kilogram').should == true
+    units.include?('gram').should == false
+  end
+
+  it "should return the correct SI base units" do
+    units = Dimensions.energy.si_base_units :name
+    units.class.should == Array
+    units.include?('kilogram').should == true
+    units.include?('square metre').should == true
+    units.include?('per square second').should == true
+    units.include?('kelvin').should == false
+    units.size.should == 3
+  end
+
+  it "should return the correct SI base units" do
+    units = Dimensions.force.si_base_units :name
+    units.class.should == Array
+    units.include?('kilogram').should == true
+    units.include?('metre').should == true
+    units.include?('second').should == false
+    units.size.should == 3
+  end
+
+  it "should return the correct SI base units" do
+    units = Dimensions.mass.si_base_units :symbol
+    units.class.should == Array
+    units.include?('kg').should == true
+    units.size.should == 1
+  end
+
+  it "should return the correct SI base units" do
+    units = Dimensions.area.si_base_units :symbol
+    units.class.should == Array
+    units.include?('m^2').should == true
+  end
+
+  it "should recognise molar quantity" do
+    dimension = Dimensions.mass/Dimensions.amount_of_substance
+    dimension.is_molar_quantity?.should == true
+    dimension.is_specific_quantity?.should == false
+  end
+
+  it "should recognise specific quantity" do
+    dimension = Dimensions.volume/Dimensions.mass
+    dimension.is_molar_quantity?.should == false
+    dimension.is_specific_quantity?.should == true
+  end
+end
+