vincenty 1.0.4 → 1.0.9

data/lib/core_extensions.rb

@@ -1,90 +1,98 @@
 require 'scanf'
 
-#Extends Numeric, hence Fixed & Float to_r & to_d
-#Also adds in sign.
+# Extends Numeric, hence Fixed & Float to_r & to_d
+# Also adds in sign.
 class Numeric
-  #Convert Radians to Degrees
-  #if optional argument mod == true, then applies % 360
-  #Returns: degrees
-  def to_degrees(mod=false) 
-    if mod 
-      (self * 180  / Math::PI) % 360
-    else 
-      self * 180  / Math::PI 
+  # Convert Radians to Degrees
+  # @return [Numeric] degrees
+  # @param [true,false]  mod Optional argument mod == true, then applies % 360
+  def to_degrees(mod = false)
+    if mod
+      (self * 180 / Math::PI) % 360
+    else
+      self * 180 / Math::PI
     end
   end
-  
-  #Converts degrees to Radians
-  #if optional argument mod == true, then applies % Math::PI
-  #Returns: radians
-  def to_radians(mod=false)
-    if mod 
+
+  # Converts degrees to Radians
+  # @return [Numeric] radians
+  # @param [true,false] mod Optional argument mod == true, then applies % Math::PI
+  def to_radians(mod = false)
+    if mod
       (self * Math::PI / 180) % Math::PI
-    else 
+    else
       self * Math::PI / 180
     end
   end
-  
+
   alias to_r to_radians
-  alias to_d to_degrees
-  
-  #Returns: 1 if number is positive, -1 if negative.
+  alias to_rad to_radians
+  alias to_deg to_degrees
+
+  # @return [Fixnum] 1 if number is positive, -1 if negative.
   def sign
     self < 0 ? -1 : 1
   end
-    
 end
 
-#Alters round method to have an optional number of decimal places.
+# Alters round method to have an optional number of decimal places.
 class Float
+  # Replace default round, so we can reference it later.
+  # @return [Float]
   alias round0 round
-  #Compatible Replacement for Float.round
-  #Optional argument n is the number of decimal places to round to.
-  #Returns: float rounded to n decimal places.
+
+  # Compatible Replacement for Float.round
+  # @return [Float] float rounded to n decimal places.
+  # @param [Numeric] n Optional argument n is the number of decimal places to round to.
   def round(n = 0)
-    m = 10.0**n
-   (self *  m).round0 / m
+    if n == 0
+      self.round0 # This is to preserve the default behaviour, which is to return a Fixnum, not a float.
+    else
+      m = 10.0**n
+      (self * m).round0 / m
+    end
   end
 end
 
-#Extends String to to_dec_degrees, add to_r and to_d
+# Extends String to to_dec_degrees, add to_r and to_d
 class String
-  #string expected to be degrees, returns decimal degrees.
-  #common forms are S37 001'7.5'', 37 001'7.5''S , -37 001'7.5'', -37 0 1.512'. -37.01875 0, 37 001'.512S, S37 001'.512, ...
-  #Returns: angle in decimal degrees
-  def to_dec_degrees 
-    #reorder 37 001'.512S, S37 001'.512 into 37 001.512'S, S37 001.512' respectively
-    s = self.gsub(/([0-9])([''])\.([0-9]+)/, '\1.\3\2')
-    #add in minutes and seconds to get 3 values 'deg 0 0'from  S37 0, 37 0S
-    s.gsub!(/^([^0-9\.\-]*)([0-9\-\.]+)([^0-9\-\.]*)$/, '\1\2\3 0 0\5')
-    #add in seconds get 3 values 'deg min 0' from  S37 01.512',  37 01.512'S
-    s.gsub!(/^([^0-9\.\-]*)([0-9\-\.]+)([^0-9\-\.]+)([0-9\-\.]+)([^0-9\-\.]*)$/, '\1\2\3\4 0\5')
-    
-    #look for anything of the form S37 001'7.5'', S37 01.512', S37.01875 0, ...
-    s.scanf("%[NSEW]%f%[^0-9-]%f%[^0-9-]%f") do |direction, deg, sep1, min, sep2, sec|
+  # string expected to be degrees, returns decimal degrees.
+  # common forms are S37 001'7.5'', 37 001'7.5''S , -37 001'7.5'', -37 0 1.512'. -37.01875 0, 37 001'.512S, S37 001'.512, ...
+  # @return [Float] angle in decimal degrees
+  def to_dec_degrees
+    # reorder 37 001'.512S, S37 001'.512 into 37 001.512'S, S37 001.512' respectively
+    s = self.gsub(/([0-9])(')\.([0-9]+)/, '\1.\3\2')
+    # add in minutes and seconds to get 3 values 'deg 0 0'from  S37 0, 37 0S
+    s.gsub!(/^([^0-9.\-]*)([0-9\-.]+)([^0-9\-.]*)$/, '\1\2\3 0 0\5')
+    # add in seconds get 3 values 'deg min 0' from  S37 01.512',  37 01.512'S
+    s.gsub!(/^([^0-9.\-]*)([0-9\-.]+)([^0-9\-.]+)([0-9\-.]+)([^0-9\-.]*)$/, '\1\2\3\4 0\5')
+
+    # look for anything of the form S37 001'7.5'', S37 01.512', S37.01875 0, ...
+    s.scanf('%[NSEW]%f%[^0-9-]%f%[^0-9-]%f') do |direction, deg, _sep1, min, _sep2, sec|
       return Angle.decimal_deg( deg,  min,  sec,  direction)
     end
-    
-    #look for anything of the form 37 001'7.5''S , -37 001'7.5'', -37 0 1.512'. -37.01875 0, ...
-    s.scanf("%f%[^0-9-]%f%[^0-9-]%f%[^NSEW]%[NSEW]") do |deg, sep1, min, sep2, sec, sep3, direction|
+
+    # look for anything of the form 37 001'7.5''S , -37 001'7.5'', -37 0 1.512'. -37.01875 0, ...
+    s.scanf('%f%[^0-9-]%f%[^0-9-]%f%[^NSEW]%[NSEW]') do |deg, _sep1, min, _sep2, sec, _sep3, direction|
       return Angle.decimal_deg( deg,  min,  sec,  direction)
     end
   end
-  
-  #Convert Radians to Degrees
-  #if optional argument mod == true, then applies % 360
-  #Returns: degrees
-  def to_degrees(mod=false) #string expected to be radians, returns degrees
-    self.to_f.to_degrees(mod)
+
+  # Convert String number in Radians to Degrees
+  # @return [Float]  degrees
+  # @param [true,false] mod Optional argument mod == true, then applies % 360
+  def to_degrees(mod = false)
+    return self.to_f.to_degrees(mod)
   end
-  
-  #Converts string degrees to to_decimal_degrees, then to Radians
-  #if optional argument mod == true, then applies % Math::PI
-  #Returns: radians
-  def to_radians(mod=false) #string expected to be degrees, returns radians
-    self.to_dec_degrees.to_radians(mod)
+
+  # Converts string degrees to to_decimal_degrees, then to Radians
+  # @return [Float] radians
+  # @param [true,false] mod Optional argument mod == true, then applies % Math::PI
+  def to_radians(mod = false)
+    return self.to_dec_degrees.to_radians(mod)
   end
-  
+
+  alias to_rad to_radians
   alias to_r to_radians
-  alias to_d to_degrees
+  alias to_deg to_degrees
 end

data/lib/latitude.rb

@@ -1,41 +1,42 @@
+require_relative 'angle.rb'
 
-require 'angle.rb'
-
-#Subclass of Angle to add in special treatment of to_d, to_r , to_s
-#Latitude degrees are between -PI and PI, South to North (+/- 90 degrees)
-
+# Subclass of Angle to add in special treatment of to_d, to_r , to_s
+# Latitude degrees are between -PI and PI, South to North (+/- 90 degrees)
 class Latitude < Angle
-  
-  #Returns angle as degrees in range -90 and 90
+  # @return [Float] angle as degrees in range -90 and 90
   def to_degrees
     degrees = super
-    case
-    when degrees > 270 ; -(360 - degrees)
-    when degrees > 180 ; 180 - degrees
-    when degrees > 90 ; 180 - degrees
-    when degrees < -90 ; 180 - degrees
-    else degrees
+    if degrees > 270
+      -(360 - degrees)
+    elsif degrees > 180 || degrees > 90 || degrees < -90
+      180 - degrees
+    else
+      degrees
     end
   end
-  
-  #Returns: angle as degrees in range -PI and PI
+
+  # @return [Float] angle as degrees in range -PI and PI
   def to_radians
-    case
-    when @angle > 3*Math::PI/2 ;  @angle - Math::PI * 2
-    when @angle > Math::PI ; Math::PI - @angle
-    when @angle > Math::PI/2 ; Math::PI - @angle
-    when @angle < -Math::PI/2 ; -Math::PI - @angle
-    else @angle
+    if @angle > 3 * Math::PI / 2
+      @angle - Math::PI * 2
+    elsif @angle > Math::PI || @angle > Math::PI / 2
+      Math::PI - @angle
+    elsif @angle < -Math::PI / 2
+      -Math::PI - @angle
+    else
+      @angle
     end
   end
 
-  #Returns: angle as string in degrees minutes seconds direction.
-  #A South angle is negative, North is Positive.
-  def to_s(fmt="%2d %2m'%2.4s\"%N")
-      super(fmt)
+  # @return [String] angle as string in degrees minutes seconds direction.
+  # A South angle is negative, North is Positive.
+  # @param [String] fmt Optional format string passed to Angle#to_s
+  def to_s(fmt = "%2d %2m'%2.4s\"%N")
+    super(fmt)
   end
-  
-  alias to_r to_radians
-  alias to_d to_degrees
 
-end
+  alias to_r to_radians
+  alias to_rad to_radians
+  # alias to_d to_degrees
+  alias to_deg to_degrees
+end

data/lib/longitude.rb

@@ -1,35 +1,34 @@
+require_relative 'angle.rb'
 
-require 'angle.rb'
-
-#Subclass of Angle to add in special treatment of to_d, to_r and to_s
-#Longitude degrees are between -2PI and 2PI, West to East (+/- 180 degrees)
-
+# Subclass of Angle to add in special treatment of to_d, to_r and to_s
+# Longitude degrees are between -2PI and 2PI, West to East (+/- 180 degrees)
 class Longitude < Angle
-  
-  #Returns angle as degrees in range -180 and 180
+  # @return [Float] angle as degrees in range -180 and 180
   def to_degrees
     degrees = super
-    case
-      when degrees > 180 ; degrees - 360
-      else degrees
+    if degrees > 180 then degrees - 360
+    else
+      degrees
     end
   end
-  
-  #Returns: angle as degrees in range -2PI and 2PI
+
+  # @return [Float] angle as degrees in range -2PI and 2PI
   def to_radians
-    case
-      when @angle > Math::PI ; @angle - 2 * Math::PI
-      else @angle
+    if @angle > Math::PI then @angle - 2 * Math::PI
+    else
+      @angle
     end
   end
-  
-  #Returns: angle as string in degrees minutes seconds direction.
-  #A West angle is negative, East is Positive.
-  def to_s(fmt="%3d %2m'%2.4s\"%E")
+
+  # @return [String] angle as string in degrees minutes seconds direction.
+  # A West angle is negative, East is Positive.
+  # @param [String] fmt Optional format string passed to Angle#to_s
+  def to_s(fmt = "%3d %2m'%2.4s\"%E")
     super(fmt)
   end
-  
+
   alias to_r to_radians
-  alias to_d to_degrees
-  
-end
+  alias to_rad to_radians
+  # alias to_d to_degrees
+  alias to_deg to_degrees
+end

data/lib/track_and_distance.rb

@@ -1,36 +1,40 @@
+require_relative 'angle.rb'
 
-require 'angle.rb'
-
-#Holds a bearing and distance
+# Holds a bearing and distance
 class TrackAndDistance
-    attr_accessor :bearing, :distance
-    
-    #Bearing is in degrees unless radians == true (or set to :radians).
-    #Bearing can be a String or Numeric or any object with to_radians and to_f
-    def initialize(bearing, distance, radians=false)
-      @bearing = Angle.new(bearing, radians)
-      @distance = distance
-    end
-    
-    #format string fmt is currently just for the bearing angle.
-    #Need to change this to include the distance is single format string.
-    #Returns: Bearing angle and distance in a string.
-    def to_s(fmt = nil)
-      if(fmt)
-        #needs work to include distance as well as angle fmt.
-        "#{@bearing.strf(fmt)} #{distance.round(4)}m"
-      else
-        "#{@bearing.strf} #{distance.round(4)}m"
-      end
-    end
+  # @return [Angle]
+  attr_accessor :bearing
+  # @return [Float]
+  attr_accessor :distance
 
-    #Returns an array with members bearing and distance.
-    def to_ary
-      [ @bearing, @distance ]
-    end
-    
-    #Returns a hash with keys :bearing and :distance
-    def to_hash
-      { :bearing => @bearing, :distance => @distance }
+  # @param [String, Numeric, #to_radian, #to_f] Bearing can be a String or Numeric or any object with to_radians and to_f
+  # @param [Numeric] distance
+  # @param [true,false, :radians] radians Bearing is in degrees unless radians == true (or set to :radians).
+  def initialize(bearing, distance, radians = false)
+    @bearing = Angle.new(bearing, radians)
+    @distance = distance
+  end
+
+  # format string fmt is currently just for the bearing angle.
+  # Need to change this to include the distance is single format string.
+  # @return [String] Bearing angle and distance in meters.
+  # @param [String] fmt Optional format string passed to Coordinate#strf
+  def to_s(fmt = nil)
+    if fmt
+      # needs work to include distance as well as angle fmt.
+      return "#{@bearing.strf(fmt)} #{distance.round(4)}m"
+    else
+      return "#{@bearing.strf} #{distance.round(4)}m"
     end
-end
+  end
+
+  # @return [Array] with members bearing and distance.
+  def to_ary
+    return [ @bearing, @distance ]
+  end
+
+  # @return [Hash] with keys :bearing and :distance
+  def to_hash
+    return { bearing: @bearing, distance: @distance }
+  end
+end