libgeo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 795971339fd7c0de9304b188ec33f51057cd4adb
+  data.tar.gz: 27003885f254776998b25dd67b6aa41d84c24270
+SHA512:
+  metadata.gz: ab071931a81588e30804c7f008d77eb8bb49c9abeaae7b2e155a99a3e76aa6e12a97eedfa10bfc35a83582f45e8426ff7041267594bd400442c276b96aea0027
+  data.tar.gz: 9367c5f271715e96b56de6033d41b18ed918e0f874baeaa23cce61cbca2fb113d803e675d61c4135b385bf2b73f8299450fc8a72a76371632b6781501eb91126

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,13 @@
+bundler_args: --without dev
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - rbx-2.2
+  - jruby-19mode
+
+branches:
+  only:
+    - master
+
+script: bundle exec rspec

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in libgeo.gemspec
+gemspec
+
+gem 'rspec', '~> 3.0.0.beta'
+
+group :dev do
+  gem 'simplecov'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Andrey Savchenko
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,60 @@
+# Libgeo
+
+Collection of geographical primitives
+
+- [![Build Status](https://travis-ci.org/Ptico/libgeo.png?branch=master)](https://travis-ci.org/Ptico/libgeo)
+- [![Code Climate](https://codeclimate.com/github/Ptico/libgeo.png)](https://codeclimate.com/github/Ptico/libgeo)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'libgeo'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install libgeo
+
+## Usage
+
+### Latitude/Longitude
+
+```ruby
+lng = Longitude.decimal(39.342679)
+
+lng.hemisphere # => :E
+lng.degrees    # => 39
+lng.minutes    # => 20
+lng.seconds    # => 33.6444
+
+lng.western?   # => false
+lng.eastern?   # => true
+
+lng.to_s    # => '39°20′33.6444″E'
+lng.to_nmea # => '03920.56074,E'
+
+lng.western!
+lng.hemisphere # => :W
+
+ltt = Latitude.nmea('03920.56074,N')
+
+ltt.to_s  # => '39°20′33.6444″N'
+
+ltt_dms = Latitude.dms('39°20′33.6444″N')
+
+ltt_dms.to_s     # => '39°20′33.6444″N'
+ltt_dms.to_nmea  # => '3920.56074,N'
+
+```
+
+## Contributing
+
+1. Fork it ( http://github.com/Ptico/libgeo/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/libgeo.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+require 'set'
+
+require 'libgeo/version'
+require 'libgeo/formatter'
+
+module Libgeo
+
+  NORTH = :N
+  SOUTH = :S
+  WEST  = :W
+  EAST  = :E
+
+  module Format
+    DMS      = Formatter.new('%2d°%2m′%S″%H')
+    NMEA_LAT = Formatter.new('%2d%2M,%H')
+    NMEA_LON = Formatter.new('%3d%2M,%H')
+  end
+end
+
+require 'libgeo/coordinate'
+require 'libgeo/latitude'
+require 'libgeo/longitude'

data/lib/libgeo/coordinate.rb

@@ -0,0 +1,187 @@
+# encoding: utf-8
+
+require 'bigdecimal'
+require 'bigdecimal/util'
+require 'set'
+
+require 'libgeo/coordinate/class_methods'
+require 'libgeo/coordinate/presenters'
+require 'libgeo/coordinate/hemi_helpers'
+
+module Libgeo
+  ##
+  # Class: basic coordinate
+  #
+  # Provides basic functionality for Latitude and Longitude.
+  # In some cases can be used as standalone class.
+  #
+  class Coordinate
+    extend ClassMethods
+    include Presenters
+    include HemiHelpers
+
+    HEMISPHERES = Set.new([:N, :E, :S, :W]).freeze
+    NEGATIVE_HEMISPHERES = Set.new([:S, :W]).freeze
+
+    attr_accessor :degrees, :minutes, :seconds, :hemisphere
+
+    ##
+    # Shortcuts
+    alias :hemi :hemisphere
+    alias :deg  :degrees
+    alias :mins :minutes
+    alias :secs :seconds
+
+    ##
+    # Coordinate type
+    #
+    def type
+      nil
+    end
+
+    ##
+    # Check coordinates equality
+    #
+    # Returns: {Boolean} true if coordinates are same
+    #
+    def eql?(other)
+      degrees.eql?(other.degrees) &&
+      minutes.eql?(other.minutes) &&
+      seconds.eql?(other.seconds) &&
+      hemisphere.eql?(other.hemisphere)
+    end
+    alias_method :==, :eql?
+
+    ##
+    # Decimal minutes with seconds included
+    #
+    # Returns: {Float} minutes
+    #
+    def minutes_only
+      (minutes + seconds.to_d / 60).to_f
+    end
+
+    ##
+    # Hemisphere validator
+    #
+    # Validates if given value can be assigned to Coordinate
+    # or if current hemi is valid
+    #
+    # Params:
+    # - value hemisphere value to check (optional)
+    #
+    # Returns: {Boolean}
+    #
+    def valid_hemisphere?(value=nil)
+      self.class::HEMISPHERES.include?(value || hemisphere)
+    end
+
+    ##
+    # Check if current hemisphere negative
+    #
+    # Returns: {Boolean}
+    #
+    def negative_hemisphere?
+      if valid_hemisphere?
+        NEGATIVE_HEMISPHERES.include?(hemi)
+      elsif direction
+        :< == direction
+      else
+        false
+      end
+    end
+
+    ##
+    # Freeze all the things!
+    #
+    def freeze
+      normalize_data
+
+      [@degrees, @minutes, @seconds, @hemisphere, @direction].each { |ivar| ivar.freeze }
+
+      super
+    end
+
+  private
+
+    attr_reader :direction
+
+    ##
+    # Constructor:
+    #
+    # Params:
+    # - hemi_or_dir {Symbol|String} hemisphere value or direction
+    # - degrees     {Fixnum}        degrees part
+    # - minutes     {Fixnum}        minutes part
+    # - seconds     {Float}         seconds part
+    #
+    def initialize(hemi_or_dir, degrees, minutes, seconds)
+      @degrees = degrees
+      @minutes = minutes
+      @seconds = seconds
+
+      if [:<, :>].include?(hemi_or_dir)
+        @direction = hemi_or_dir
+      else
+        @hemisphere = hemi_or_dir
+      end
+
+      normalize_data
+    end
+
+    ##
+    # Private: make sure that all attrs has right types
+    #
+    def normalize_data
+      normalize_hemi
+      normalize_values
+    end
+
+    ##
+    # Private: detect and assign hemisphere value
+    #
+    # Check if hemisphere can be properly detected
+    # and assign it
+    #
+    def normalize_hemi
+      if hemisphere
+        normalize_hemi_wording
+      elsif direction
+        get_hemi_from_direction
+      end
+    end
+
+    ##
+    # Private: normalize hemisphere value
+    #
+    # If hemisphere have incorrect value - lookup for
+    # available correction from dictionary
+    #
+    def normalize_hemi_wording
+      unless valid_hemisphere?
+        self.class::CORRECTIONS.each_pair do |v, c|
+          @hemisphere = v if c.include?(hemisphere)
+        end
+      end
+    end
+
+    ##
+    # Private: get hemisphere value from direction
+    #
+    # Mostly for plain Coordinate instance (not Latitude or Longitude)
+    #
+    def get_hemi_from_direction
+      @hemisphere = self.class::DIRECTIONS[direction]
+    end
+
+    ##
+    # Private: normalize attribute types
+    #
+    def normalize_values
+      @degrees = degrees.to_i
+      @minutes = minutes.to_i
+      @seconds = seconds.to_f
+    end
+
+  end
+end

data/lib/libgeo/coordinate/class_methods.rb

@@ -0,0 +1,243 @@
+# encoding: utf-8
+
+module Libgeo
+  class Coordinate
+    module ClassMethods
+
+      DMS_SEPARATORS  = /['°′"`\ \,]+/.freeze
+      NMEA_SEPARATORS = /(,\ |,|\ )/.freeze
+
+      ##
+      # Factory: make a coordinate from decimal value
+      #
+      # Examples:
+      #
+      #     Longitude.decimal(39.342679) # => #<Longitude hemisphere=E degrees=39 minutes=20 ...
+      #
+      # Params:
+      # - value {Float} decimal coordinate
+      #
+      # Returns: {Latitude|Longitude|Coordinate} instance
+      #
+      def decimal(value)
+        minutes = value.abs.to_d.modulo(1) * 60 # extract minutes from decimal degrees
+        create(dir_from(value), value.abs.to_i, *min_with_sec(minutes))
+      end
+
+      ##
+      # Factory: make a coordinate from nmea input
+      #
+      # Examples:
+      #
+      #     Longitude.nmea('03920.56074,E') # => #<Longitude hemisphere=E degrees=39 minutes=20 ...
+      #
+      # Params:
+      # - input {String} nmea coordinate
+      #
+      # Returns: {Latitude|Longitude|Coordinate} instance
+      #
+      def nmea(input)
+        value, hemi = prepare_nmea(input)
+
+        value = value.to_f
+
+        direction = dir_from_values(value, hemi)
+
+        degrees = value.to_i.abs / 100
+
+        create(direction, degrees, *min_with_sec_nmea(value.abs), hemi)
+      end
+
+      ##
+      # Factory: make a coordinate from dms value
+      #
+      # Examples:
+      #
+      #     Longitude.dms("58°39′13.5 S") # => #<Longitude hemisphere=S degrees=58 minutes=39 ...
+      #
+      # Params:
+      # - inputs {String} dms coordinate
+      #
+      # Returns: {Latitude|Longitude|Coordinate} instance
+      #
+      def dms(input)
+        string_values = input.split(DMS_SEPARATORS)
+
+        degrees = string_values[0].to_i # get degrees and minutes
+        minutes = (string_values[1] || 0).to_i
+        seconds = (string_values[2] || 0).to_f
+        hemi    = string_values[3]
+
+        direction = dir_from_values(degrees, hemi)
+
+        create(direction, degrees.abs, minutes, seconds, hemi)
+      end
+
+      ##
+      # Factory: make a coordinate from degrees and full minutes
+      #
+      # Params:
+      # - degrees {Fixnum} degrees part
+      # - minutes {Float}  full minutes, with seconds
+      #
+      # Examples:
+      #
+      #     Latitude.degrees_minutes(-39, 20.56074) # => #<Latitude hemisphere=S degrees=39 minutes=20 ...
+      #
+      # Returns: {Latitude|Longitude|Coordinate} instance
+      #
+      def degrees_minutes(degrees, minutes)
+        create(dir_from(degrees), degrees.abs.to_i, *min_with_sec(minutes))
+      end
+
+    private
+
+      ##
+      # Private: extract splited values from nmea notation
+      #
+      # Params:
+      # - input {String} input string in nmea notation
+      #
+      # Examples:
+      #
+      #     input # => "03922.54, E"
+      #     prepare_nmea(input) # => ["03922.54", "E"]
+      #
+      #     input2 # => "+03922.54"
+      #     prepare_nmea(input) # => ["+03922.54"]
+      #
+      # Returns: [{String}, {String}] numbers and hemisphere
+      #
+      def prepare_nmea(input)
+        splited_values = input.split(NMEA_SEPARATORS)
+
+        splited_values.delete_if { |str| str =~ NMEA_SEPARATORS }
+      end
+
+      ##
+      # Private: extract integer minutes and  float seconds from float minutes
+      #
+      # Params:
+      # - minutes {Float|Decimal} minutes
+      #
+      # Returns: [{Ineteger}, {Float}] rounded minutes and exracted seconds
+      #
+      def min_with_sec(minutes_f)
+        seconds = minutes_f.to_d.modulo(1) * 60
+
+        [minutes_f.to_i, seconds.to_f]
+      end
+
+      ##
+      # Private: extract minutes and seconds from nmea coord
+      #
+      # Params:
+      # - value {Float} nmea coordinate
+      #
+      # Returns: [{Ineteger}, {Float}] extracted minutes and seconds
+      #
+      def min_with_sec_nmea(value)
+        minutes = value.to_i % 100
+        seconds = (value.modulo(1) * 60).round(4)
+
+        [minutes, seconds]
+      end
+
+      ##
+      # Private: detect direction based on neg/pos
+      #
+      # Params:
+      # - degrees {Integer} degrees
+      #
+      # Examples:
+      #
+      #     dir_from(-5) # => :<
+      #     dir_from(10) # => :>
+      #
+      # Returns: {Symbol} symbol of direction
+      #
+      def dir_from(degrees)
+        degrees < 0 ? :< : :>
+      end
+
+      ##
+      # Private: detect direction from degrees of hemisphere
+      #
+      # Params:
+      # - numbers {Ineteger|Float|Decimal} numerical value of coordinate (degrees)
+      # - hemi {String|Symbol|nil} hemisphere if available
+      #
+      # Examples:
+      #
+      #     dir_from_values(43, 'S') # => :<
+      #     dir_from_values(43, nil) # => :>
+      #
+      # Returns: {Symbol} symbol of direction
+      #
+      def dir_from_values(numbers, hemi)
+        if hemi
+          (NEGATIVE_HEMISPHERES.include? hemi.to_sym) ? :< : :>
+        else
+          dir_from(numbers.to_i)
+        end
+      end
+
+      ##
+      # Private: fabric. Make a coordinate from given values
+      #
+      # Params:
+      # - direction {Symbol} symbol of hemisphere direction
+      # - degrees {Integer}
+      # - minutes {Integer}
+      # - second {Integer|Float}
+      # - hemi {Symbol|String} (optional) hemisphere
+      #
+      # Raises:
+      # - {ArgumentError} on wrong params values
+      #
+      # Returns: {Longitude|Latotude} created coordinate
+
+      def create(direction, degrees, minutes, seconds, hemi=nil)
+        validate_values(degrees, minutes, seconds, hemi)
+
+        self.new(direction, degrees, minutes, seconds)
+      end
+
+      ##
+      # Private: validates given values
+      #
+      # Params:
+      # - degrees {Ineteger}
+      # - minutes {Integer}
+      # - seconds {Ineteger|Float}
+      # - hemi {Symbol|String|nil} hemisphere
+      #
+      # Raises:
+      # - {ArgumentError} on wrong values
+      #
+      def validate_values(degrees, minutes, seconds, hemi)
+        if degrees > self::MAX_DEGREES || minutes > 60 || seconds > 60
+          raise ArgumentError.new('values out of range')
+        end
+
+        validate_hemisphere(hemi.to_sym) if hemi
+      end
+
+
+      ##
+      # Hemisphere validator
+      #
+      # Validates given hemisphere
+      #
+      # Params:
+      # - value {Symbol} - hemisphere
+      #
+      # Raises:
+      # - {ArgumentError} on wrong hemisphere
+      #
+      def validate_hemisphere(value)
+        raise ArgumentError.new('wrong hemisphere') unless HEMISPHERES.include?(value)
+      end
+    end
+  end
+end