Merge branch 'wnameless-master'

Add Ruby implementation with travis-ci integration.

Author: drinckes

.travis.yml

@@ -5,16 +5,18 @@ language: node_js
 node_js:
   - "0.10"
 
+
 # Install package dependencies. See
 # http://docs.travis-ci.com/user/installing-dependencies/
 # gulp: required for JS testing
-before_script:
+before_install:
   - npm install -g gulp
 
 # Define the list of directories to execute tests in.
 env:
   - TEST_DIR=js
   - TEST_DIR=go
+  - TEST_DIR=ruby
 
 # Test script to run. This is called once for each TEST_DIR value above.
 script: ./run_tests.sh

ruby/lib/plus_codes.rb

@@ -0,0 +1,26 @@
+# Plus+Codes is a Ruby implementation of Google Open Location Code(Plus+Codes).
+#
+# @author We-Ming Wu
+module PlusCodes
+
+  # A separator used to separate the code into two parts.
+  SEPARATOR = '+'.freeze
+
+  # The max number of characters can be placed before the separator.
+  SEPARATOR_POSITION = 8
+
+  # The character used to pad a code
+  PADDING = '0'.freeze
+
+  # The character set used to encode coordinates.
+  CODE_ALPHABET = '23456789CFGHJMPQRVWX'.freeze
+
+  # ASCII lookup table.
+  DECODE = (CODE_ALPHABET.chars + [PADDING, SEPARATOR]).reduce([]) do |ary, c|
+    ary[c.ord] = CODE_ALPHABET.index(c)
+    ary[c.downcase.ord] = CODE_ALPHABET.index(c)
+    ary[c.ord] ||= -1
+    ary
+  end.freeze
+
+end

ruby/lib/plus_codes/code_area.rb

@@ -0,0 +1,38 @@
+module PlusCodes
+
+  # [CodeArea] contains coordinates of a decoded Open Location Code(Plus+Codes).
+  # The coordinates include the latitude and longitude of the lower left and
+  # upper right corners and the center of the bounding box for the area the
+  # code represents.
+  #
+  # @author We-Ming Wu
+  class CodeArea
+    attr_accessor :south_latitude, :west_longitude, :latitude_height,
+    :longitude_width, :latitude_center, :longitude_center
+
+    # Creates a [CodeArea].
+    #
+    # @param south_latitude [Numeric] the latitude of the SW corner in degrees
+    # @param west_longitude [Numeric] the longitude of the SW corner in degrees
+    # @param latitude_height [Numeric] the height from the SW corner in degrees
+    # @param longitude_width [Numeric] the width from the SW corner in degrees
+    # @return [CodeArea] a code area which contains the coordinates
+    def initialize(south_latitude, west_longitude, latitude_height, longitude_width)
+      @south_latitude = south_latitude
+      @west_longitude = west_longitude
+      @latitude_height = latitude_height
+      @longitude_width = longitude_width
+      @latitude_center = south_latitude + latitude_height / 2.0
+      @longitude_center = west_longitude + longitude_width / 2.0
+    end
+
+    def north_latitude
+      @south_latitude + @latitude_height
+    end
+
+    def east_longitude
+      @west_longitude + @longitude_width
+    end
+  end
+
+end

ruby/lib/plus_codes/open_location_code.rb

@@ -0,0 +1,264 @@
+require_relative '../plus_codes'
+require_relative '../plus_codes/code_area'
+
+module PlusCodes
+
+  # [OpenLocationCode] implements the Google Open Location Code(Plus+Codes) algorithm.
+  #
+  # @author We-Ming Wu
+  class OpenLocationCode
+
+    # Determines if a string is a valid sequence of Open Location Code(Plus+Codes) characters.
+    #
+    # @param code [String] a plus+codes
+    # @return [TrueClass, FalseClass] true if the code is valid, false otherwise
+    def valid?(code)
+      valid_length?(code) &&
+      valid_separator?(code) &&
+      valid_padding?(code) &&
+      valid_character?(code)
+    end
+
+    # Determines if a string is a valid short Open Location Code(Plus+Codes).
+    #
+    # @param code [String] a plus+codes
+    # @return [TrueClass, FalseClass] true if the code is short, false otherwise
+    def short?(code)
+      valid?(code) && code.index(SEPARATOR) < SEPARATOR_POSITION
+    end
+
+    # Determines if a string is a valid full Open Location Code(Plus+Codes).
+    #
+    # @param code [String] a plus+codes
+    # @return [TrueClass, FalseClass] true if the code is full, false otherwise
+    def full?(code)
+      valid?(code) && !short?(code)
+    end
+
+    # Converts a latitude and longitude into a Open Location Code(Plus+Codes).
+    #
+    # @param latitude [Numeric] a latitude in degrees
+    # @param longitude [Numeric] a longitude in degrees
+    # @param code_length [Integer] the number of characters in the code, this excludes the separator
+    # @return [String] a plus+codes
+    def encode(latitude, longitude, code_length = 10)
+      raise ArgumentError,
+      "Invalid Open Location Code(Plus+Codes) length: #{code_length}" if invalid_length?(code_length)
+
+      latitude = clip_latitude(latitude)
+      longitude = normalize_longitude(longitude)
+      latitude -= precision_by_length(code_length) if latitude == 90
+
+      lat = (latitude + 90).to_r
+      lng = (longitude + 180).to_r
+
+      digit = 0
+      code = ''
+      while digit < code_length
+        lat, lng = narrow_region(digit, lat, lng)
+        digit, lat, lng = build_code(digit, code, lat, lng)
+        code << SEPARATOR if (digit == SEPARATOR_POSITION)
+      end
+
+      digit < SEPARATOR_POSITION ? padded(code) : code
+    end
+
+    # Decodes an Open Location Code(Plus+Codes) into a [CodeArea].
+    #
+    # @param code [String] a plus+codes
+    # @return [CodeArea] a code area which contains the coordinates
+    def decode(code)
+      raise ArgumentError,
+      "Open Location Code(Plus+Codes) is not a valid full code: #{code}" unless full?(code)
+
+      code = code.gsub(SEPARATOR, '')
+      code = code.gsub(/#{PADDING}+/, '')
+      code = code.upcase
+
+      south_latitude = -90.0
+      west_longitude = -180.0
+
+      lat_resolution = 400.to_r
+      lng_resolution = 400.to_r
+
+      digit = 0
+      while digit < code.length
+        if digit < 10
+          lat_resolution /= 20
+          lng_resolution /= 20
+          south_latitude += lat_resolution * DECODE[code[digit].ord]
+          west_longitude += lng_resolution * DECODE[code[digit + 1].ord]
+          digit += 2
+        else
+          lat_resolution /= 5
+          lng_resolution /= 4
+          row = DECODE[code[digit].ord] / 4
+          column = DECODE[code[digit].ord] % 4
+          south_latitude += lat_resolution * row
+          west_longitude += lng_resolution * column
+          digit += 1
+        end
+      end
+
+      CodeArea.new(south_latitude, west_longitude, lat_resolution, lng_resolution)
+    end
+
+    # Recovers a full Open Location Code(Plus+Codes) from a short code and a reference location.
+    #
+    # @param short_code [String] a plus+codes
+    # @param reference_latitude [Numeric] a reference latitude in degrees
+    # @param reference_longitude [Numeric] a reference longitude in degrees
+    # @return [String] a plus+codes
+    def recover_nearest(short_code, reference_latitude, reference_longitude)
+      return short_code if full?(short_code)
+      raise ArgumentError,
+      "Open Location Code(Plus+Codes) is not valid: #{short_code}" unless short?(short_code)
+
+      ref_lat = clip_latitude(reference_latitude)
+      ref_lng = normalize_longitude(reference_longitude)
+
+      prefix_len = SEPARATOR_POSITION - short_code.index(SEPARATOR)
+      code = prefix_by_reference(ref_lat, ref_lng, prefix_len) << short_code
+      code_area = decode(code)
+
+      area_range = precision_by_length(prefix_len)
+      area_edge = area_range / 2
+
+      latitude = code_area.latitude_center
+      latitude_diff = latitude - ref_lat
+      if (latitude_diff > area_edge)
+        latitude -= area_range
+      elsif (latitude_diff < -area_edge)
+        latitude += area_range
+      end
+
+      longitude = code_area.longitude_center
+      longitude_diff = longitude - ref_lng
+      if (longitude_diff > area_edge)
+        longitude -= area_range
+      elsif (longitude_diff < -area_edge)
+        longitude += area_range
+      end
+
+      encode(latitude, longitude, code.length - SEPARATOR.length)
+    end
+
+    # Removes four, six or eight digits from the front of an Open Location Code(Plus+Codes) given a reference location.
+    #
+    # @param code [String] a plus+codes
+    # @param latitude [Numeric] a latitude in degrees
+    # @param longitude [Numeric] a longitude in degrees
+    # @return [String] a short plus+codes
+    def shorten(code, latitude, longitude)
+      raise ArgumentError,
+      "Open Location Code(Plus+Codes) is a valid full code: #{code}" unless full?(code)
+      raise ArgumentError,
+      "Cannot shorten padded codes: #{code}" unless code.index(PADDING).nil?
+
+      code_area = decode(code)
+      lat_diff = (latitude - code_area.latitude_center).abs
+      lng_diff = (longitude - code_area.longitude_center).abs
+      max_diff = [lat_diff, lng_diff].max
+      [8, 6, 4].each do |removal_len|
+        area_edge = precision_by_length(removal_len + 2) / 2
+        return code[removal_len..-1] if max_diff < area_edge
+      end
+
+      code.upcase
+    end
+
+    private
+
+    def prefix_by_reference(latitude, longitude, prefix_len)
+      precision = precision_by_length(prefix_len)
+      rounded_latitude = (latitude / precision).floor * precision
+      rounded_longitude = (longitude / precision).floor * precision
+      encode(rounded_latitude, rounded_longitude)[0...prefix_len]
+    end
+
+    def narrow_region(digit, latitude, longitude)
+      if digit == 0
+        latitude /= 20
+        longitude /= 20
+      elsif digit < 10
+        latitude *= 20
+        longitude *= 20
+      else
+        latitude *= 5
+        longitude *= 4
+      end
+      [latitude, longitude]
+    end
+
+    def build_code(digit_count, code, latitude, longitude)
+      lat_digit = latitude.to_i
+      lng_digit = longitude.to_i
+      if digit_count < 10
+        code << CODE_ALPHABET[lat_digit]
+        code << CODE_ALPHABET[lng_digit]
+        [digit_count + 2, latitude - lat_digit, longitude - lng_digit]
+      else
+        code << CODE_ALPHABET[4 * lat_digit + lng_digit]
+        [digit_count + 1, latitude - lat_digit, longitude - lng_digit]
+      end
+    end
+
+    def valid_length?(code)
+      !code.nil? && code.length >= 2 + SEPARATOR.length && code.split(SEPARATOR).last.length != 1
+    end
+
+    def valid_separator?(code)
+      separator_idx = code.index(SEPARATOR)
+      code.count(SEPARATOR) == 1 && separator_idx <= SEPARATOR_POSITION && separator_idx.even?
+    end
+
+    def valid_padding?(code)
+      if code.include?(PADDING)
+        return false if code.start_with?(PADDING)
+        return false if code[-2..-1] != PADDING + SEPARATOR
+
+        paddings = code.scan(/#{PADDING}+/)
+        return false if !paddings.one? || paddings[0].length.odd?
+        return false if paddings[0].length > SEPARATOR_POSITION - 2
+      end
+      true
+    end
+
+    def valid_character?(code)
+      code.chars.each { |ch| return false if DECODE[ch.ord].nil? }
+      true
+    end
+
+    def invalid_length?(code_length)
+      code_length < 2 || (code_length < SEPARATOR_POSITION && code_length.odd?)
+    end
+
+    def padded(code)
+      code << PADDING * (SEPARATOR_POSITION - code.length) << SEPARATOR
+    end
+
+    def precision_by_length(code_length)
+      if code_length <= 10
+        precision = 20 ** ((code_length / -2).to_i + 2)
+      else
+        precision = (20 ** -3) / (5 ** (code_length - 10))
+      end
+      precision.to_r
+    end
+
+    def clip_latitude(latitude)
+      [90.0, [-90.0, latitude].max].min
+    end
+
+    def normalize_longitude(longitude)
+      until longitude < 180
+        longitude -= 360
+      end
+      until longitude >= -180
+        longitude += 360
+      end
+      longitude
+    end
+  end
+
+end