pak_cities 0.1.0

data/lib/pak_cities/distance_calculator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module PakCities
+  module DistanceCalculator
+    EARTH_RADIUS_KM = 6371.0
+    KM_TO_MILES = 0.621371
+
+    module_function
+
+    def haversine_distance(lat1, lon1, lat2, lon2, unit: :km)
+      Validators.validate_coordinates!(lat1, lon1)
+      Validators.validate_coordinates!(lat2, lon2)
+
+      rad_per_deg = Math::PI / 180.0
+
+      dlat = (lat2 - lat1) * rad_per_deg
+      dlon = (lon2 - lon1) * rad_per_deg
+
+      a = Math.sin(dlat / 2)**2 +
+          Math.cos(lat1 * rad_per_deg) * Math.cos(lat2 * rad_per_deg) *
+          Math.sin(dlon / 2)**2
+      c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
+
+      distance_km = EARTH_RADIUS_KM * c
+      convert_distance(distance_km, unit)
+    end
+
+    def convert_distance(distance_km, unit)
+      case unit
+      when :km
+        distance_km
+      when :miles
+        distance_km * KM_TO_MILES
+      else
+        raise ArgumentError, "Invalid unit: #{unit}"
+      end
+    end
+  end
+end

data/lib/pak_cities/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module PakCities
+  class Error < StandardError; end
+  class CityNotFoundError < Error; end
+  class InvalidCoordinatesError < Error; end
+  class InvalidConfigurationError < Error; end
+end

data/lib/pak_cities/query.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module PakCities
+  module Query
+    def all
+      cities
+    end
+
+    def count
+      cities.size
+    end
+
+    def find(name)
+      cities.find { |city| match_name?(city.name, name) }
+    end
+
+    def find!(name)
+      find(name) || raise(CityNotFoundError, "City not found: #{name}")
+    end
+
+    def search(query)
+      query = normalize_string(query)
+      cities.select { |city| normalize_string(city.name).include?(query) }
+    end
+
+    def where(conditions = {})
+      result = cities
+
+      if conditions[:province]
+        province = conditions[:province]
+        result = result.select { |city| match_name?(city.province, province) }
+      end
+
+      result = result.select { |city| city.population >= conditions[:min_population] } if conditions[:min_population]
+
+      result = result.select { |city| city.population <= conditions[:max_population] } if conditions[:max_population]
+
+      result
+    end
+
+    def by_province(province)
+      cities.select { |city| match_name?(city.province, province) }
+    end
+
+    def top_by_population(limit = 10)
+      Validators.validate_positive_integer!(limit, "limit")
+      cities.sort_by(&:population).reverse.take(limit)
+    end
+
+    def by_name(order: :asc)
+      sorted = cities.sort_by(&:name)
+      order == :desc ? sorted.reverse : sorted
+    end
+
+    def by_population(order: :desc)
+      sorted = cities.sort_by(&:population)
+      order == :desc ? sorted.reverse : sorted
+    end
+
+    def random(limit = 1)
+      Validators.validate_positive_integer!(limit, "limit")
+      cities.sample(limit)
+    end
+
+    def provinces
+      cities.map(&:province).uniq.sort
+    end
+
+    def grouped_by_province
+      cities.group_by(&:province)
+    end
+
+    def nearest_to(lat, lng, limit = 5)
+      Validators.validate_coordinates!(lat, lng)
+      Validators.validate_positive_integer!(limit, "limit")
+
+      unit = configuration.distance_unit
+
+      cities_with_distance = cities.map do |city|
+        distance = DistanceCalculator.haversine_distance(
+          lat, lng, city.latitude, city.longitude, unit: unit
+        )
+        [city, distance]
+      end
+
+      cities_with_distance.sort_by { |_, distance| distance }.take(limit).map(&:first)
+    end
+
+    def within_bounds(min_lat:, max_lat:, min_lng:, max_lng:)
+      Validators.validate_coordinates!(min_lat, min_lng)
+      Validators.validate_coordinates!(max_lat, max_lng)
+
+      cities.select do |city|
+        city.latitude.between?(min_lat, max_lat) &&
+          city.longitude.between?(min_lng, max_lng)
+      end
+    end
+
+    def distance_between(city1_name, city2_name)
+      city1 = find!(city1_name)
+      city2 = find!(city2_name)
+
+      DistanceCalculator.haversine_distance(
+        city1.latitude, city1.longitude,
+        city2.latitude, city2.longitude,
+        unit: configuration.distance_unit
+      )
+    end
+
+    def same_province?(city1_name, city2_name)
+      city1 = find!(city1_name)
+      city2 = find!(city2_name)
+      city1.province == city2.province
+    end
+
+    def reload!
+      @cities = nil
+      cities
+    end
+
+    private
+
+    def match_name?(str1, str2)
+      if configuration.case_sensitive
+        str1 == str2
+      else
+        str1.downcase == str2.downcase
+      end
+    end
+
+    def normalize_string(str)
+      configuration.case_sensitive ? str : str.downcase
+    end
+  end
+end

data/lib/pak_cities/statistics.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module PakCities
+  module Statistics
+    def total_population
+      cities.sum(&:population)
+    end
+
+    def average_population
+      return 0 if cities.empty?
+
+      total_population / cities.size.to_f
+    end
+
+    def median_population
+      return 0 if cities.empty?
+
+      sorted = cities.map(&:population).sort
+      mid = sorted.size / 2
+      sorted.size.odd? ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2.0
+    end
+
+    def population_by_province
+      grouped_by_province.transform_values do |cities_in_province|
+        cities_in_province.sum(&:population)
+      end
+    end
+
+    def cities_count_by_province
+      grouped_by_province.transform_values(&:size)
+    end
+
+    def largest_city
+      cities.max_by(&:population)
+    end
+
+    def smallest_city
+      cities.min_by(&:population)
+    end
+  end
+end

data/lib/pak_cities/validators.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module PakCities
+  module Validators
+    LATITUDE_RANGE = (-90..90).freeze
+    LONGITUDE_RANGE = (-180..180).freeze
+
+    module_function
+
+    def validate_coordinates!(latitude, longitude)
+      unless LATITUDE_RANGE.cover?(latitude)
+        raise InvalidCoordinatesError, "Latitude must be between -90 and 90, got #{latitude}"
+      end
+
+      return if LONGITUDE_RANGE.cover?(longitude)
+
+      raise InvalidCoordinatesError, "Longitude must be between -180 and 180, got #{longitude}"
+    end
+
+    def validate_positive_integer!(value, name)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise ArgumentError, "#{name} must be a positive integer, got #{value.inspect}"
+    end
+  end
+end

data/lib/pak_cities/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PakCities
+  VERSION = "0.1.0"
+end

data/lib/pak_cities.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "pak_cities/version"
+require_relative "pak_cities/errors"
+require_relative "pak_cities/configuration"
+require_relative "pak_cities/validators"
+require_relative "pak_cities/city"
+require_relative "pak_cities/distance_calculator"
+require_relative "pak_cities/query"
+require_relative "pak_cities/statistics"
+require "json"
+
+module PakCities
+  DATA_FILE = File.join(__dir__, "pak_cities", "data.json")
+
+  class << self
+    include Query
+    include Statistics
+
+    private
+
+    def cities
+      @cities ||= load_cities
+    end
+
+    def load_cities
+      data = JSON.parse(File.read(DATA_FILE))
+      data.map do |city_data|
+        City.new(
+          name: city_data["city"],
+          province: city_data["province"],
+          latitude: city_data["latitude"],
+          longitude: city_data["longitude"],
+          population: city_data["pop2025"]
+        )
+      end
+    end
+  end
+end

data/sig/pak_cities.rbs

@@ -0,0 +1,4 @@
+module PakCities
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: pak_cities
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Talha Razzaq
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Provides easy access to Pakistan cities data with powerful query methods.
+email:
+- talha36201@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- build_output.txt
+- lib/pak_cities.rb
+- lib/pak_cities/city.rb
+- lib/pak_cities/configuration.rb
+- lib/pak_cities/data.json
+- lib/pak_cities/distance_calculator.rb
+- lib/pak_cities/errors.rb
+- lib/pak_cities/query.rb
+- lib/pak_cities/statistics.rb
+- lib/pak_cities/validators.rb
+- lib/pak_cities/version.rb
+- sig/pak_cities.rbs
+homepage: https://github.com/Talha380/pak_cities
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/Talha380/pak_cities
+  source_code_uri: https://github.com/Talha380/pak_cities
+  changelog_uri: https://github.com/Talha380/pak_cities/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: A Ruby gem for querying Pakistan cities data
+test_files: []