ruby-units 1.3.2 → 1.4.0

data/lib/ruby_units/fixnum.rb

@@ -1,10 +1,11 @@
-# this patch is necessary for ruby 1.8 because cases where
-# Integers are divided by Units don't work quite right
-
 if RUBY_VERSION < "1.9"
+  # :nocov_19:
   class Fixnum
     alias quo_without_units quo
-  
+
+    # @note this patch is necessary for ruby 1.8 because cases where Integers are divided by Units don't work quite right
+    # @param [Numeric]
+    # @return [Unit, Integer]
     def quo_with_units(other)
       case other
       when Unit
@@ -17,4 +18,5 @@ if RUBY_VERSION < "1.9"
     alias quo quo_with_units
     alias / quo_with_units
   end
+  # :nocov_19:
 end

data/lib/ruby_units/math.rb

@@ -1,10 +1,11 @@
-# Math will convert unit objects to radians and then attempt to use the value for 
-# trigonometric functions.  
 require 'mathn'
 
+# Math will convert unit objects to radians and then attempt to use the value for 
+# trigonometric functions.  
 module Math
 
   alias :unit_sqrt :sqrt
+  # @return [Numeric]
   def sqrt(n)
     if Unit === n
       (n**(Rational(1,2))).to_unit 
@@ -12,12 +13,15 @@ module Math
       unit_sqrt(n)
     end
   end
+  # @return [Numeric]
   module_function :unit_sqrt
+  # @return [Numeric]
   module_function :sqrt
 
   #:nocov:
   if self.respond_to?(:cbrt)
     alias :unit_cbrt :cbrt
+    # @return [Numeric]
     def cbrt(n)
       if Unit === n
         (n**(Rational(1,3))).to_unit 
@@ -25,55 +29,76 @@ module Math
         unit_cbrt(n)
       end
     end
+    # @return [Numeric]
     module_function :unit_cbrt
+    # @return [Numeric]
     module_function :cbrt
   end
   #:nocov:
     
   alias :unit_sin :sin
+  # @return [Numeric]
   def sin(n)
    Unit === n ? unit_sin(n.convert_to('radian').scalar) : unit_sin(n)
   end
+  # @return [Numeric]
   module_function :unit_sin
+  # @return [Numeric]
   module_function :sin
 
   alias :unit_cos :cos
+  # @return [Numeric]
   def cos(n)
     Unit === n ? unit_cos(n.convert_to('radian').scalar) : unit_cos(n)
   end
+  # @return [Numeric]
   module_function :unit_cos
+  # @return [Numeric]
   module_function :cos
     
   alias :unit_sinh :sinh
+  # @return [Numeric]
   def sinh(n)
     Unit === n ? unit_sinh(n.convert_to('radian').scalar) : unit_sinh(n)
   end
+  # @return [Numeric]
   module_function :unit_sinh
+  # @return [Numeric]
   module_function :sinh
 
   alias :unit_cosh :cosh
+  # @return [Numeric]
   def cosh(n)
     Unit === n ? unit_cosh(n.convert_to('radian').scalar) : unit_cosh(n)
   end
+  # @return [Numeric]
   module_function :unit_cosh
+  # @return [Numeric]
   module_function :cosh
 
   alias :unit_tan :tan
+  # @return [Numeric]
   def tan(n)
    Unit === n ? unit_tan(n.convert_to('radian').scalar) : unit_tan(n)
   end
+  # @return [Numeric]
   module_function :tan
+  # @return [Numeric]
   module_function :unit_tan
 
   alias :unit_tanh :tanh
+  # @return [Numeric]
   def tanh(n)
     Unit === n ? unit_tanh(n.convert_to('radian').scalar) : unit_tanh(n)
   end
+  # @return [Numeric]
   module_function :unit_tanh
+  # @return [Numeric]
   module_function :tanh
 
   alias :unit_hypot :hypot
   # Convert parameters to consistent units and perform the function
+  # @return [Numeric]
   def hypot(x,y)
     if Unit === x && Unit === y
       (x**2 + y**2)**(1/2)
@@ -81,10 +106,13 @@ module Math
       unit_hypot(x,y)
     end
   end
+  # @return [Numeric]
   module_function :unit_hypot
+  # @return [Numeric]
   module_function :hypot
   
   alias :unit_atan2 :atan2
+  # @return [Numeric]
   def atan2(x,y)
     case
     when (x.is_a?(Unit) && y.is_a?(Unit)) && (x !~ y)
@@ -95,7 +123,9 @@ module Math
       Math::unit_atan2(x,y)
     end
   end
+  # @return [Numeric]
   module_function :unit_atan2
+  # @return [Numeric]
   module_function :atan2
    
 end

data/lib/ruby_units/numeric.rb

@@ -1,5 +1,6 @@
-# make a unitless unit with a given scalar
 class Numeric
+  # make a unitless unit with a given scalar
+  # @return (see Unit#initialize)
   def to_unit(other = nil)
     other ? Unit.new(self, other) : Unit.new(self)
   end

data/lib/ruby_units/object.rb

@@ -1,8 +1,15 @@
 class Object
+  
+  # Shortcut for creating Unit object
+  # @example 
+  #   Unit("1 mm")
+  #   U("1 mm")
+  # @return [Unit]
   def Unit(*other)
     other.to_unit
   end
-  
   alias :U :Unit
+
+  # @deprecated
   alias :u :Unit
 end

data/lib/ruby_units/string.rb

@@ -1,14 +1,18 @@
 require 'time'
-# make a string into a unit
 class String
+  # make a string into a unit
+  # @return (see Unit#initialize)
   def to_unit(other = nil)
     other ? Unit.new(self).convert_to(other) : Unit.new(self)
   end
   alias :unit :to_unit
   alias :u :to_unit
-  alias :unit_format :%
-  
-  # format unit output using formating codes '%0.2f' % '1 mm'.unit => '1.00 mm'
+
+
+  alias :unit_format :%  
+  # format unit output using formating codes 
+  # @example '%0.2f' % '1 mm'.unit => '1.00 mm'
+  # @return [String]
   def %(*args)
 		return "" if self.empty?
     case 
@@ -23,112 +27,9 @@ class String
     end
   end
   
-  #needed for compatibility with Rails, which defines a String.from method  
-  # if self.public_instance_methods.include? 'from'
-  #   alias :old_from :from
-  # end 
-  
-  # # "5 min".from("now")
-  # def from(time_point = ::Time.now)
-  #   return old_from(time_point) if self.respond_to?(:old_from) && time_point.instance_of?(Integer)
-  #   self.unit.from(time_point)
-  # end
-  # 
-  # alias :after :from
-
-  # def from_now
-  #   self.from('now')
-  # end
-  # 
-  # # "5 min".ago
-  # def ago
-  #   self.unit.ago
-  # end
-  # 
-  # def before(time_point = ::Time.now)
-  #   self.unit.before(time_point)
-  # end
-  # 
-  # def before_now
-  #   self.before('now')
-  # end
-  # 
-  # def since(time_point = ::Time.now)
-  #   self.unit.since(time_point)
-  # end
-  # 
-  # def until(time_point = ::Time.now)
-  #   self.unit.until(time_point)
-  # end
-  # 
+  # @param (see Unit#convert_to)
+  # @return (see Unit#convert_to)
   def convert_to(other)
     self.unit.convert_to(other)
   end
-  # 
-  # unless String.instance_methods.include?(:to)
-  #   def to(other)
-  #     warn "string.to is deprecated, use string.convert_to if you must, but the best would be Unit('unit').convert_to('target unit')"
-  #     convert_to(other)
-  #   end
-  # end
-  # 
-  # def time(options = {})
-  #   self.to_time(options) rescue self.to_datetime(options)
-  # end
-  # 
-  # def to_time(options = {})
-  #   begin
-  #     #raises exception when Chronic not defined or when it returns a nil (i.e., can't parse the input)
-  #     r = Chronic.parse(self,options)
-  #     raise(ArgumentError, 'Invalid Time String') unless r
-  #     return r
-  #   rescue Exception  => e
-  #     puts e.inspect
-  #     case
-  #     when self == "now"
-  #       Time.now
-  #     when Time.respond_to?(:parse)
-  #       Time.parse(self)
-  #     else
-  #       Time.local(*ParseDate.parsedate(self))
-  #     end
-  #   end
-  # end
-  # 
-  # def to_datetime(options = {})
-  #   begin
-  #     # raises an exception if Chronic.parse = nil or if Chronic not defined
-  #     r = Chronic.parse(self,options).send(:to_datetime)
-  #   rescue NameError  => e
-  #     r = case
-  #     when self.to_s == "now"
-  #       DateTime.now
-  #     else
-  #       DateTime.parse(self)
-  #     end
-  #   end
-  #   raise RuntimeError, "Invalid Time String (#{self.to_s})" if r == DateTime.new      
-  #   return r
-  # end
-  # 
-  # def to_date(options={})
-  #   begin
-  #     r = Chronic.parse(self,options).to_date
-  #   rescue
-  #     r = case
-  #     when self == "today" 
-  #       Date.today
-  #     when RUBY_VERSION < "1.9"
-  #       Date.civil(*ParseDate.parsedate(self)[0..5].compact)
-  #     else
-  #       Date.parse(self)
-  #     end
-  #   end
-  #   raise RuntimeError, 'Invalid Date String' if r == Date.new
-  #   return r
-  # end
-  # 
-  # def datetime(options = {})
-  #   self.to_datetime(options) rescue self.to_time(options)
-  # end
 end

data/lib/ruby_units/string/extra.rb

@@ -1,3 +1,5 @@
+require 'time'
+
 #
 # String Extras
 # 
@@ -6,16 +8,13 @@
 #
 # in most cases it is better to do something like
 #
-# Unit("1 m").convert_to("ft")
-# 
-# instead of
-#
-# "1 m".convert_to("ft")
+# @example 
+#   Unit("1 m").convert_to("ft")
+#   instead of
+#   "1 m".convert_to("ft")
 #
 # to use these methods:
 # require 'ruby-units/string/extra'
-
-require 'time'
 class String
   
   #needed for compatibility with Rails, which defines a String.from method  
@@ -23,7 +22,11 @@ class String
     alias :old_from :from
   end 
   
-  # "5 min".from("now")
+  # @example 
+  #   "5 min".from("now")
+  # @param [Time] time_point
+  # @return (see Unit#from)
+  # @deprecated
   def from(time_point = ::Time.now)
     return old_from(time_point) if self.respond_to?(:old_from) && time_point.instance_of?(Integer)
     warn Kernel.caller.first + " called ruby-units/string#from, which is deprecated.  Use Unit(string).from(string) instead"
@@ -32,49 +35,74 @@ class String
   
   alias :after :from
 
+  # @example 
+  #   "5 min".from_now
+  # @return (see Unit#from)
+  # @deprecated
   def from_now
     warn Kernel.caller.first + " called ruby-units/string#from_now, which is deprecated.  Use Unit(string).from(Time.now) instead"
     self.from(Time.now)
   end
   
-  # "5 min".ago
+  # @example 
+  #  "5 min".ago
+  # @return (see Unit#ago)
+  # @deprecated
   def ago
     warn Kernel.caller.first + " called ruby-units/string#ago, which is deprecated.  Use Unit(string).ago instead"
     self.unit.ago
   end
   
+  # @example 
+  #  "5 min".before("now")
+  # @param [Time] time_point
+  # @return (see Unit#before)
+  # @deprecated
   def before(time_point = ::Time.now)
     warn Kernel.caller.first + " called ruby-units/string#before, which is deprecated.  Use Unit(string).before(Time.now) instead"
     self.unit.before(time_point)
   end
-  
+
+  # @example 
+  #  "5 min".before_now
+  # @return (see Unit#before)
+  # @deprecated
   def before_now
     warn Kernel.caller.first + " called ruby-units/string#before_now, which is deprecated.  Use Unit(string).before(Time.now) instead"
     self.before(Time.now)
   end
   
+  # @return (see Unit#since)
+  # @deprecated
   def since(time_point = ::Time.now)
     warn Kernel.caller.first + " called ruby-units/string#since, which is deprecated.  Use Unit(string).since(Time.now) instead"
     self.unit.since(time_point)
   end
   
+  # @return (see Unit#until)
+  # @deprecated
   def until(time_point = ::Time.now)
     warn Kernel.caller.first + " called ruby-units/string#until, which is deprecated.  Use Unit(string).until(Time.now) instead"
     self.unit.until(time_point)
   end
   
-  
   unless String.instance_methods.include?(:to)
+    # @deprecated
+    # @return (see #convert_to)
     def to(other)
       warn "string.to is deprecated, use string.convert_to if you must, but the best would be Unit('unit').convert_to('target unit')"
       convert_to(other)
     end
   end
   
+  # @deprecated
+  # @return (see #to_time)
   def time(options = {})
     self.to_time(options) rescue self.to_datetime(options)
   end
   
+  # @deprecated
+  # @return [Time]
   def to_time(options = {})
     begin
       #raises exception when Chronic not defined or when it returns a nil (i.e., can't parse the input)
@@ -93,6 +121,8 @@ class String
     end
   end
   
+  # @deprecated
+  # @return [DateTime]
   def to_datetime(options = {})
     begin
       # raises an exception if Chronic.parse = nil or if Chronic not defined
@@ -109,6 +139,8 @@ class String
     return r
   end
   
+  # @deprecated
+  # @return [Date]
   def to_date(options={})
     begin
       r = Chronic.parse(self,options).to_date
@@ -126,6 +158,8 @@ class String
     return r
   end
   
+  # @deprecated
+  # @return (see #to_datetime)
   def datetime(options = {})
     self.to_datetime(options) rescue self.to_time(options)
   end