phys-units 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 90c1f56164cc98572b5eae8592785f563a2c3696
-  data.tar.gz: 927f9243197713824969180af7f7666392758cc1
+  metadata.gz: 8fd589f3ac5dded9010b0d83ba9f31abccc40a4f
+  data.tar.gz: 17427a7a2bcb4631adea755b4fed53e9f0adccdd
 SHA512:
-  metadata.gz: 8ad832d3a55009034335bd5ad82e0f91402550a9e501f2628fb6e3ecaf39cdc2fb23a4d084f06aec9791af0b8d00173b4af1f36f5ecf27605d96bf5e235e90d0
-  data.tar.gz: 409b575adb56f94fbee27c99f73e01e141f84be2a4244d3beff2cd4d4f1e604f07df96363bb80a2a6ad125363b112494efbc99517a32f1e09b2da33da4f0ea81
+  metadata.gz: a5018dbf704ba64a03afcfa92718389636f9ac058ee633eebe81ef5e27353178bb7eb9e9c88b127508258d12584071ab32a37df3827e66f26e46fe5909266cff
+  data.tar.gz: 02d92bee85d27cfc47555a3b14bad2b0c2df683786700e73747d0b1a2c65737b9241f081bb03d2ff569d76af54ad1561ad711342ac3c80db7eb5b840e0dd86ac

data/README.md

@@ -3,32 +3,28 @@
 GNU Units-compatible library for Ruby. 
 Former name is [Quanty](http://narray.rubyforge.org/quanty/quanty-en.html),
 the first Ruby units library released in 2001.
-This library provides the following Classes:
 
-* Phys::Quantity
-* Phys::Unit
+## Phys::Quantity
+is a primary class of Phys-Units library, to be manipulated by users.
+See Documentation at [Rubygems Site](https://rubygems.org/gems/phys-units)
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Install from gem as:
 
-    gem 'phys-units'
-
-And then execute:
-
-    $ bundle
+    $ gem install phys-units
 
-Or install it yourself as:
+Or install from source tree:
 
-    $ gem install phys-units
+    $ ruby setup.rb
 
 ## Usage
 
     require 'phys/units'
     Q = Phys::Quantity
-    Q[1.23,'km'] + Q[4.56,'m']    #=> Phys::Quanty[1.23456,'km']
-    Q[123,'mile'] / Q[2,'hr']     #=> Phys::Quanty[61,'mile/hr']
-    Q[61,'miles/hr'].want('m/s')  #=> Phys::Quanty[27.26944,'m/s']
+    Q[1.23,'km'] + Q[4.56,'m']    #=> Phys::Quantity[1.23456,'km']
+    Q[123,'mile'] / Q[2,'hr']     #=> Phys::Quantity[61,'mile/hr']
+    Q[61,'miles/hr'].want('m/s')  #=> Phys::Quantity[27.26944,'m/s']
     Q[1.0,'are'] == Q[10,'m']**2  #=> true
     Q[70,'tempF'] + Q[10,'tempC'] #=> Phys::Quantity[88,'tempF']
     Q[20,'tempC'].want('tempF')   #=> Phys::Quantity[68,'tempF']
@@ -36,16 +32,23 @@ Or install it yourself as:
 
 ## Features
 
-Phys-Units library is discriminated from the other many units libraies for Ruby,
+Phys-Units library is discriminated from many other units libraies for Ruby,
 by the following features:
-* Compatible with GNU Units except the nonlinear units.
+
+* Compatible with GNU Units except nonlinear units.
 * Provides 2415 units, 85 prefixes, including UTF-8 unit names.
-* All the units are defined in a unit data file from GNU Units
+* All units are defined in a unit data file from GNU Units
   and not defined as a Ruby codes, except temperature definitions.
 * No addition or modification to Ruby standard classes by default,
   avoiding conflict with other libraries.
-* Calculation of values is only through the Ruby Numeric arithmetic methods.
+* Calculation of values is through Ruby Numeric arithmetic methods.
   None of the Phys-Units lib's buisiness.
 * Conversion factors are held in Rational even defined
   in the decimal form such as `1.0e10'.
 * PI number has a dimension.
+
+## Copying License
+GPL3
+
+## Author
+Masahiro TANAKA

data/lib/phys/units.rb

@@ -1,4 +1,5 @@
 require "phys/units/version"
+require "phys/units/errors.rb"
 require "phys/units/unit_class.rb"
 require "phys/units/unit.rb"
 require "phys/units/utils.rb"

data/lib/phys/units/errors.rb

@@ -0,0 +1,10 @@
+module Phys
+  class UnitError < StandardError
+  end
+  class UnitParseError < UnitError
+  end
+  class UnitConversionError < UnitError
+  end
+  class UnitOperationError < UnitError
+  end
+end

data/lib/phys/units/quantity.rb

@@ -13,12 +13,16 @@ module Phys
     Quantity.new(*a)
   end
 
+  # Phys::Quantity is a class to represent physical quantities
+  # with unit of measure.
+  # It contains a value in Numeric or similar class,
+  # and unit in Phys::Unit class.
   #== Usage
   #   require 'phys/units'
   #   Q=Phys::Quantity
-  #   Q[1.23,'km'] + Q[4.56,'m']    #=> Phys::Quanty[1.23456,'km']
-  #   Q[123,'mile'] / Q[2,'hr']     #=> Phys::Quanty[61,'mile/hr']
-  #   Q[61,'miles/hr'].want('m/s')  #=> Phys::Quanty[27.26944,'m/s']
+  #   Q[1.23,'km'] + Q[4.56,'m']    #=> Phys::Quantity[1.23456,'km']
+  #   Q[123,'mile'] / Q[2,'hr']     #=> Phys::Quantity[61,'mile/hr']
+  #   Q[61,'miles/hr'].want('m/s')  #=> Phys::Quantity[27.26944,'m/s']
   #   Q[1.0,'are'] == Q[10,'m']**2  #=> true
   #   Q[70,'tempF'] + Q[10,'tempC'] #=> Phys::Quantity[88,'tempF']
   #   Q[20,'tempC'].want('tempF')   #=> Phys::Quantity[68,'tempF']
@@ -26,16 +30,28 @@ module Phys
   class Quantity
 
     class << self
-      # Same as Quantity.new.
-      def [](*a)
-        self.new(*a)
+      # Alias to Phys::Quantity.new.
+      # @param  [Object] value
+      #         Value of quantity.
+      # @param  [String] expr  unit expression.
+      #         If +expr+ is not supplied, it becomes dimeinsionless.
+      # @return [Phys::Quantity]
+      # @raise  [Phys::UnitConversionError] if unit conversion is failed.
+      def [](value,expr=nil)
+        self.new(value,expr)
       end
     end
 
     # Initialize a new quantity.
-    # _value_: Numeric value of quantity.
-    # _expr_: Unit string. Result of Unit.parse(_expr_) is used as a unit.
-    # _unit_: (optional) Unit of quantity instead of parsing _expr_.
+    # @param  [Object] value
+    #         Value of quantity.
+    #         +value+ must be a class instance having arithmetic methods
+    #         in a duck typing way.
+    # @param  [String] expr  unit expression.
+    #         If +expr+ is not supplied, it becomes dimeinsionless.
+    # @param  [Phys::Unit] unit  (optional)
+    # @raise  [Phys::UnitConversionError] if unit conversion is failed.
+    #
     def initialize(value,expr=nil,unit=nil)
       @val = value
       expr = expr.to_s if Symbol===expr
@@ -48,14 +64,21 @@ module Phys
       end
     end
 
+    # @return [Object] value of the quantity
     attr_reader :val
+    alias value val
+
+    # @return [String] unit expression
     attr_reader :expr
-    attr_reader :unit
 
-    # Returns the value of the quantity.
-    alias value val
+    # @return [Phys::Unit] unit
+    attr_reader :unit
 
-    # Conversion to a quantity in another _expr_ unit.
+    # Conversion to a quantity in another unit.
+    # @param  [String] expr unit expression.
+    # @return [Phys::Quantity] quantity in the unit of +expr+.
+    # @raise  [Phys::UnitConversionError] if unit conversion is failed.
+    #
     def want(expr)
       unit = Unit.parse(expr)
       val  = unit.convert(self)
@@ -64,63 +87,124 @@ module Phys
     alias convert want
 
     # Addition of two quantities.
-    # Operation is made after the unit of _other_ is
-    # converted to the unit of _self_.
-    # Exception is raised if unit conversion is failed.
-    # Returns an instance of Quantity class in the unit of former quantity.
+    # Before the operation, it converts +other+ to the unit of +self+.
+    # * If the +other+ param is Phys::Quantity,
+    #   +other+ is converted to the unit of +self+.
+    # * If the +other+ param is *not* Phys::Quantity,
+    #   both params must be dimensionless.
+    # @param  [Object] other
+    # @return [Phys::Quantity] a quantity in the unit of +self+.
+    # @raise  [Phys::UnitConversionError] if unit conversion is failed.
+    #
     def +(other)
       val = @val + @unit.convert_scale(other)
       self.class.new( val, @expr, @unit )
     end
 
     # Subtraction of two quantities.
-    # Operation is made after the unit of _other_ is
-    # converted to the unit of _self_.
-    # Exception is raised if unit conversion is failed.
-    # Returns an instance of Quantity class in the unit of former quantity.
+    # Before the operation, it converts +other+ to the unit of +self+.
+    # * If the +other+ param is Phys::Quantity,
+    #   +other+ is converted to the unit of +self+.
+    # * If the +other+ param is *not* Phys::Quantity,
+    #   both params must be dimensionless.
+    # @param  [Object] other
+    # @return [Phys::Quantity] a quantity in the unit of +self+.
+    # @raise  [Phys::UnitConversionError] if unit conversion is failed.
+    #
     def -(other)
       val = @val - @unit.convert_scale(other)
       self.class.new( val, @expr, @unit )
     end
 
-    %w[abs ceil round floor truncate].each do |s|
-      define_method(s) do
-        self.class.new( @val.send(s), @expr, @unit )
-      end
+    # @return [Phys::Quantity] abs quantity in the unit of +self+.
+    def abs
+      self.class.new( @val.abs, @expr, @unit )
     end
 
-    # Unary Plus. Returns self.
-    def +@ ; self.class.new(  @val, @expr, @unit ) end
+    # @return [Phys::Quantity] abs2 quantity in the squared unit of +self+.
+    def abs2
+      self**2
+    end
 
-    # Unary Minus. Returns the negated quantity.
-    def -@ ; self.class.new( -@val, @expr, @unit ) end
+    # @return [Phys::Quantity] ceil quantity in the unit of +self+.
+    def ceil
+      self.class.new( @val.ceil, @expr, @unit )
+    end
 
-    # Comparison of quantities. Comparison is made after
-    # converting _other_ to a quantity in the unit of _self_.
-    def <=> (other); @val <=> @unit.convert(other) end
+    # @return [Phys::Quantity] round quantity in the unit of +self+.
+    def round
+      self.class.new( @val.round, @expr, @unit )
+    end
 
-    # Comparison of quantities. Comparison is made after
-    # converting _other_ to a quantity in the unit of _self_.
-    def  == (other); @val  == @unit.convert(other) end
+    # @return [Phys::Quantity] floor quantity in the unit of +self+.
+    def floor
+      self.class.new( @val.floor, @expr, @unit )
+    end
 
-    # Comparison of quantities. Comparison is made after
-    # converting _other_ to a quantity in the unit of _self_.
-    def  >= (other); @val  >= @unit.convert(other) end
+    # @return [Phys::Quantity] truncate quantity in the unit of +self+.
+    def truncate
+      self.class.new( @val.truncate, @expr, @unit )
+    end
 
-    # Comparison of quantities. Comparison is made after
-    # converting _other_ to a quantity in the unit of _self_.
-    def  <= (other); @val  <= @unit.convert(other) end
+    # Unary Plus.
+    # @return [Phys::Quantity] +self+.
+    def +@
+      self.class.new(  @val, @expr, @unit )
+    end
 
-    # Comparison of quantities. Comparison is made after
-    # converting _other_ to a quantity in the unit of _self_.
-    def  <  (other); @val  <  @unit.convert(other) end
+    # Unary Minus.
+    # @return [Phys::Quantity] a quantity in the unit of +self+.
+    def -@
+      self.class.new( -@val, @expr, @unit )
+    end
+
+    # Comparison of quantities.
+    # Before the comparison, it converts +other+ to the unit of +self+.
+    # @return [Integer]
+    def <=> (other)
+      @val <=> @unit.convert(other)
+    end
+
+    # Comparison of quantities.
+    # Before the comparison, it converts +other+ to the unit of +self+.
+    # @return [Boolean]
+    def  == (other)
+      @val  == @unit.convert(other)
+    end
+
+    # Comparison of quantities.
+    # Before the comparison, it converts +other+ to the unit of +self+.
+    # @return [Boolean]
+    def  >= (other)
+      @val  >= @unit.convert(other)
+    end
 
-    # Comparison of quantities. Comparison is made after
-    # converting _other_ to a quantity in the unit of _self_.
-    def  >  (other); @val  >  @unit.convert(other) end
+    # Comparison of quantities.
+    # Before the comparison, it converts +other+ to the unit of +self+.
+    # @return [Boolean]
+    def  <= (other)
+      @val  <= @unit.convert(other)
+    end
+
+    # Comparison of quantities.
+    # Before the comparison, it converts +other+ to the unit of +self+.
+    # @return [Boolean]
+    def  <  (other)
+      @val  <  @unit.convert(other)
+    end
+
+    # Comparison of quantities.
+    # Before the comparison, it converts +other+ to the unit of +self+.
+    # @return [Boolean]
+    def  >  (other)
+      @val  >  @unit.convert(other)
+    end
 
     # Power of a quantity.
-    # Returns an instance of Quantity class in a powerd unit.
+    # @param  [Numeric] n
+    # @return [Phys::Quantity] a quantity in the +n+ -powered unit of +self+.
+    # @raise  [Phys::UnitConversionError] if unit conversion is failed.
+    #
     def **(n)
       if @expr.nil?
         expr = nil
@@ -132,7 +216,10 @@ module Phys
       self.class.new( @val**n, expr, @unit**n )
     end
 
-    def enclose_expr     #:nodoc:
+    # (internally used method)
+    # @private
+    # @return [String]
+    def enclose_expr     #:nodoc: used internally
       return nil if @expr.nil?
       if /\/|\||per/o =~ @expr
         '('+@expr+')'
@@ -140,8 +227,11 @@ module Phys
         @expr
       end
     end
-
-    def enclose_expr_div    #:nodoc:
+    
+    # (internally used method)
+    # @private
+    # @return [String]
+    def enclose_expr_div    #:nodoc: used internally
       return nil if @expr.nil?
       if /\w[^\w]+\w/o =~ @expr
         '/('+@expr+')'
@@ -151,7 +241,13 @@ module Phys
     end
 
     # Multiplication of two quantities.
-    # Returns an instance of Quantity class in a multiplied unit.
+    # If the +other+ param is *not* Phys::Quantity,
+    # +other+ is regarded as a dimensionless value.
+    # @param  [Object] other
+    # @return [Phys::Quantity] a quantity
+    # both the values and units are multiplied respectively.
+    # @raise  [Phys::UnitOperationError] if unit is not operable.
+    #
     def *(other)
       if Quantity===other
         a = [self.enclose_expr, other.enclose_expr]
@@ -163,42 +259,131 @@ module Phys
     end
 
     # Division of two quantities.
-    # Returns an instance of Quantity class in a divided unit.
-    %w[/ div quo].each do |s|
-      define_method(s) do |other|
-        if Quantity===other
-          a = [self.enclose_expr, other.enclose_expr_div]
-          a.delete(nil)
-          self.class.new( @val.send(s,other.val), a.join, @unit/other.unit )
-        else
-          self.class.new( @val.send(s,other), @expr, @unit )
-        end
+    # If the +other+ param is *not* Phys::Quantity,
+    # +other+ is regarded as a dimensionless value.
+    # @param  [Object] other
+    # @return [Phys::Quantity] a quantity
+    # both the values and units are divided respectively.
+    # @raise  [Phys::UnitOperationError] if unit is not operable.
+    #
+    def /(other)
+      if Quantity===other
+        a = [self.enclose_expr, other.enclose_expr_div]
+        a.delete(nil)
+        self.class.new( @val/other.val, a.join, @unit/other.unit )
+      else
+        self.class.new( @val/other, @expr, @unit )
+      end
+    end
+
+    # Division of two quantities.
+    # If the +other+ param is *not* Phys::Quantity,
+    # +other+ is regarded as a dimensionless value.
+    # @param  [Object] other
+    # @return [Phys::Quantity] a quantity
+    # both the values and units are divided respectively.
+    # @raise  [Phys::UnitOperationError] if unit is not operable.
+    #
+    def quo(other)
+      if Quantity===other
+        a = [self.enclose_expr, other.enclose_expr_div]
+        a.delete(nil)
+        self.class.new( @val.quo(other.val), a.join, @unit/other.unit )
+      else
+        self.class.new( @val.quo(other), @expr, @unit )
       end
     end
     alias fdiv quo
 
-    %w[% remainder].each do |s|
-      define_method(s) do |other|
-        other = (Quantity===other) ? other.val : other
-        self.class.new( @val.send(s,other), @expr, @unit )
+    # Division of two quantities without Remainder.
+    # * If the +other+ param is Phys::Quantity,
+    #   +other+ is converted to the unit of +self+,
+    #   and returns +div+ of values.
+    # * If the +other+ param is *not* Phys::Quantity,
+    #   +other+ is regarded as dimensionless,
+    #   and returns +div+ of Phys::Quantity.
+    # @param  [Object] other
+    # @return [Object] div
+    # @raise  [Phys::UnitConversionError] if unit conversion is failed.
+    #
+    def div(other)
+      if Quantity===other
+        @val.div( @unit.convert(other) )
+      else
+        self.class.new( @val.div(other), @expr, @unit )
       end
     end
-    alias modulo %
 
-    def coerce(other)
-      [ self.class.new(other), self ]
+    # Remainder of two quantities.
+    # * If the +other+ param is Phys::Quantity,
+    #   +other+ is converted to the unit of +self+,
+    #   and returns +remainder+ of values.
+    # * If the +other+ param is *not* Phys::Quantity,
+    #   +other+ is regarded as dimensionless,
+    #   and returns +remainder+ of Phys::Quantity.
+    # @param  [Object] other
+    # @return [Object] remainder
+    # @raise  [Phys::UnitConversionError] if unit conversion is failed.
+    #
+    def remainder(other)  #:nodoc: used internally
+      if Quantity===other
+        @val.remainder( @unit.convert(other) )
+      else
+        self.class.new( @val.remainder(other), @expr, @unit )
+      end
     end
 
-    def abs
-      self.class.new( @val.abs, @expr, @unit )
+    # Modulo of two quantities.
+    # * If the +other+ param is Phys::Quantity,
+    #   +other+ is converted to the unit of +self+,
+    #   and returns +modulo+ of values.
+    # * If the +other+ param is *not* Phys::Quantity,
+    #   +other+ is regarded as dimensionless,
+    #   and returns +modulo+ of Phys::Quantity.
+    # @param  [Object] other
+    # @return [Object] modulo
+    # @raise  [Phys::UnitConversionError] if unit conversion is failed.
+    #
+    def %(other)
+      if Quantity===other
+        @val % @unit.convert(other)
+      else
+        self.class.new( @val % other, @expr, @unit )
+      end
     end
+    alias modulo %
 
-    def abs2
-      self**2
+    # Division and Modulo of two quantities.
+    # * If the +other+ param is Phys::Quantity,
+    #   +other+ is converted to the unit of +self+,
+    #   and returns +divmod+ of values.
+    # * If the +other+ param is *not* Phys::Quantity,
+    #   +other+ is regarded as dimensionless,
+    #   and returns +divmod+ of Phys::Quantity.
+    # @param  [Object] other
+    # @return [Array] result of +divmod+, an array of [quotient, modulo].
+    # @raise  [Phys::UnitConversionError] if unit conversion is failed.
+    #
+    def divmod(other)
+      if Quantity===other
+        @val.divmod( @unit.convert(other) )
+      else
+        d,m = @val.divmod(other)
+        [ self.class.new( d, @expr, @unit ),
+          self.class.new( m, @expr, @unit ) ]
+      end
+    end
+
+    # @return [Array]
+    def coerce(other)
+      [ self.class.new(other), self ]
     end
 
     # Conversion to base unit.
     # Returns the quantity converted to a base unit.
+    # @return [Phys::Quantity] a quantity in the base unit.
+    # @raise  [Phys::UnitConversionError] if unit conversion is failed.
+    #
     def to_base_unit
       unit = @unit.base_unit
       val  = unit.convert(self)
@@ -209,28 +394,45 @@ module Phys
     alias to_SI to_base_unit
 
     # Conversion to Numeric.
-    # Returns Numeric if the unit is dimensionless.
-    # Raises an Error if the unit is non-dminensionless.
+    # @return [Numeric]
+    # @raise  [Phys::UnitConversionError] if the unit is non-dminensionless.
+    #
     def to_numeric
       @unit.convert_to_numeric(@val)
     end
+    alias to_num to_numeric
 
+    # Conversion to Float.
+    # @return [Float]
+    # @raise  [Phys::UnitConversionError] if the unit is non-dminensionless.
+    #
     def to_f
       to_numeric.to_f
     end
     alias to_float to_f
 
+    # Conversion to Integer.
+    # @return [Integer]
+    # @raise  [Phys::UnitConversionError] if the unit is non-dminensionless.
+    #
     def to_i
       to_numeric.to_i
     end
     alias to_int to_i
     alias to_integer to_i
 
+    # Conversion to Rational.
+    # @return [Rational]
+    # @raise  [Phys::UnitConversionError] if the unit is non-dminensionless.
+    #
     def to_r
       to_numeric.to_r
     end
     alias to_rational to_r
 
+    # Conversion to String.
+    # @return [String]
+    #
     def to_s
       if @expr
         expr = ",'" +@expr+"'"
@@ -240,6 +442,9 @@ module Phys
       self.class.to_s+"["+Unit::Utils.num_inspect(@val)+expr+"]"
     end
 
+    # Inspect String.
+    # @return [String]
+    #
     def inspect
       if @expr
         expr = "," +@expr.inspect