calcpace 1.5.5 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '04889c91e456d34e17974f8aeafa14bb99c0f44957bb42fdc6cac4a3c1a87bf1'
-  data.tar.gz: 60b0d8e24f2f10905c8ee8697c892b63efef0fca92fecb42dc86e9cf797b37a9
+  metadata.gz: ba8948e4e291f5381e58be3bc289ad8f54aa480a1cef744fc121dbc43449b523
+  data.tar.gz: a9e4b3da8526c245adfaed895f460b820d737ca4a3eb805a4e2c9b1510f1a6ca
 SHA512:
-  metadata.gz: af863c188a3e74b28211bac8956c5fd1ad7440e9cdb8316f5c329a06daf5387ad81ecdeacced1b0011bfad304b0f8b9607c9deeca63dfba628e04162c718cb1f
-  data.tar.gz: ba0a4e7fd03714ca47c9a1cb9b1d8081327e2821b9da44730866437e3ba54c74aec43d93ae9f2f75ac69f7fe1672ee4fb62f4c17f015a35a83045583ebe872e4
+  metadata.gz: 61cea9354aa1343b9db15e92a1a11c06f053158ed72a48c5d1062e4b7d733888a7a8eaf3b88c7696cb879b7a92d196891c01e85369947dd4dead497b322b69b9
+  data.tar.gz: fcf1db5f88479865c65ce64d7c788a3762ea01f39c28f10fa3604e268bce1737589cec4eb8b66f94a10f70a1acb12b7ab73b082990e0bc9a1a0c11d0461159d6

data/.github/workflows/tests.yml

@@ -1,4 +1,6 @@
 name: Tests
+permissions:
+  contents: read
 on:
   push:
     branches: [ "main" ]

data/.rubocop.yml

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# RuboCop configuration for Calcpace gem
+# Following Ruby best practices and style guidelines
+
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+    - 'node_modules/**/*'
+
+# Prefer double quotes for consistency
+Style/StringLiterals:
+  Enabled: false
+
+# Allow longer lines in tests
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'test/**/*'
+
+# Prefer modern hash syntax
+Style/HashSyntax:
+  EnforcedStyle: ruby19
+
+# Documentation is important for public APIs
+Style/Documentation:
+  Enabled: true
+  Exclude:
+    - 'test/**/*'
+
+# Prefer explicit return in some cases for clarity
+Style/RedundantReturn:
+  Enabled: false
+
+# Allow compact module/class definitions
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+# Metrics
+Metrics/MethodLength:
+  Max: 20
+  Exclude:
+    - 'test/**/*'
+
+Metrics/AbcSize:
+  Max: 20
+  Exclude:
+    - 'test/**/*'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'test/**/*'
+    - '*.gemspec'
+
+# Allow both single and double quotes for strings
+Style/StringLiteralsInInterpolation:
+  Enabled: false
+
+# Naming
+Naming/MethodParameterName:
+  MinNameLength: 1
+  AllowedNames:
+    - _
+    - e

data/.ruby-version

@@ -1 +1 @@
-3.4.2
+3.4.4

data/.tool-versions

@@ -0,0 +1,2 @@
+nodejs 24.1.0
+ruby 3.4.4

data/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.7.0] - Unreleased
+
+### Added
+- RuboCop configuration for code style consistency
+- CHANGELOG.md for tracking project changes
+- Comprehensive YARD documentation for all public methods
+- Race pace calculator for standard distances (5K, 10K, half-marathon, marathon)
+  - `race_time` and `race_time_clock` methods for calculating finish times
+  - `race_pace` and `race_pace_clock` methods for calculating required paces
+  - `list_races` method to see available race distances
+- `UnsupportedUnitError` for better error handling
+- Comprehensive test suite with edge cases and error scenarios
+- Test helper utilities for better test organization
+
+### Changed
+- Improved error messages with more context throughout the gem
+- Enhanced validation for edge cases
+- Better method organization and code structure
+- Optimized `convert_to_seconds` method using case statement
+- Improved error handling in `constant` method with nested rescue
+
+### Fixed
+- Minor code style inconsistencies
+- Typo in README: `converto_to_clocktime` → `convert_to_clocktime`
+
+## [1.6.0] - Previous Release
+
+### Added
+- Custom error classes for better error handling
+- `NonPositiveInputError` for invalid numeric inputs
+- `InvalidTimeFormatError` for invalid time format inputs
+
+### Changed
+- Improved error handling throughout the gem
+
+## [1.5.0] and earlier
+
+See git history for changes in earlier versions.
+
+[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/0jonjo/calcpace/releases/tag/v1.6.0

data/README.md

@@ -1,4 +1,4 @@
-# Calcpace [![Gem Version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=rb&r=r&ts=1683906897&type=6e&v=1.5.5&x2=0)](https://badge.fury.io/rb/calcpace)
+# Calcpace [![Gem Version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=rb&r=r&ts=1683906897&type=6e&v=1.7.0&x2=0)](https://badge.fury.io/rb/calcpace)
 
 Calcpace is a Ruby gem designed for calculations and conversions related to distance and time. It can calculate velocity, pace, total time, and distance, accepting time in various formats, including HH:MM:SS. The gem supports conversion to 42 different units, including kilometers, miles, meters, and feet. It also provides methods to validate input.
 
@@ -7,7 +7,7 @@ Calcpace is a Ruby gem designed for calculations and conversions related to dist
 ### Add to your Gemfile
 
 ```ruby
-gem 'calcpace', '~> 1.5.5'
+gem 'calcpace', '~> 1.7.0'
 ```
 
 Then run:
@@ -87,15 +87,15 @@ To learn more about BigDecimal, check the [documentation](https://ruby-doc.org/s
 
 ### Convert Distances and Velocities
 
-Use the `convert` method to convert a distance or velocity. The first parameter is the value to be converted, and the second parameter is the unit to which the value will be converted. The unit must be a string with the abbreviation of the unit. The gem supports 26 different units, including kilometers, miles, meters, knots, and feet.
+Use the `convert` method to convert a distance or velocity. The first parameter is the value to be converted, and the second parameter is the unit to which the value will be converted. The unit can be a string (e.g. 'km to meters') or a symbol (e.g. :km_to_meters). The gem supports 42 different units, including kilometers, miles, meters, knots, and feet.
 
 Here are some examples:
 
 ```ruby
 converter.convert(10, :km_to_meters) # => 1000
-converter.convert(10, :mi_to_km) # => 16.0934
+converter.convert(10, 'mi to km') # => 16.0934
 converter.convert(1, :nautical_mi_to_km) # => 1.852
-converter.convert(1, :km_h_to_m_s) # => 0.277778
+converter.convert(1, 'km h to m s') # => 0.277778
 converter.convert(1, :m_s_to_mi_h) # => 2.23694
 ```
 
@@ -118,14 +118,65 @@ converter.convert(1, :m_s_to_mi_h) # => 2.23694
 | :km_h_to_mi_h        | Kilometers per Hour to Miles per Hour    |
 | :mi_h_to_km_h        | Miles per Hour to Kilometers per Hour    |
 
-You can list all the available units [here](/lib/calcpace/converter.rb), or using `list` methods:
+You can list all the available units [here](/lib/calcpace/converter.rb), or using `list` methods. The return will be a hash with the unit and a description of the unit.
 
 ```ruby
 converter.list_all
+# => {:km_to_mi=>"KM to MI", :mi_to_km=>"MI to KM", ...}
+
 converter.list_distance
+# => {:km_to_mi=>"KM to MI", :mi_to_km=>"MI to KM", ...}
+
 converter.list_speed
+# => {:m_s_to_km_h=>"M S to KM H", :km_h_to_m_s=>"KM H to M S", ...}
+```
+
+### Chain Conversions
+
+Perform multiple conversions in sequence with the converter chain feature:
+
+```ruby
+calc = Calcpace.new
+
+# Convert kilometers to miles to feet in one call
+calc.convert_chain(1, [:km_to_mi, :mi_to_feet])
+# => 3280.84 (1 km = 0.621 mi = 3280.84 feet)
+
+# Convert with description for debugging
+calc.convert_chain_with_description(100, [:meters_to_km, :km_to_mi])
+# => { result: 0.0621371, description: "100 → meters_to_km → km_to_mi → 0.0621" }
+
+# Speed conversions
+calc.convert_chain(10, [:m_s_to_km_h, :km_h_to_mi_h])
+# => 22.3694 (10 m/s = 36 km/h = 22.37 mi/h)
 ```
 
+### Race Pace Calculator
+
+Calcpace includes a race pace calculator for standard race distances (5K, 10K, half-marathon, and marathon):
+
+```ruby
+calc = Calcpace.new
+
+# Calculate finish time for a race given a pace
+calc.race_time(300, '5k')              # => 1500.0 (5:00/km pace for 5K = 25:00)
+calc.race_time_clock('05:00', 'marathon') # => '03:30:58' (5:00/km pace for marathon)
+
+# Calculate required pace for a target finish time
+calc.race_pace('00:30:00', '5k')       # => 360.0 (need 6:00/km to finish 5K in 30:00)
+calc.race_pace_clock('04:00:00', 'marathon') # => '00:05:41' (need 5:41/km for 4-hour marathon)
+
+# List available race distances
+calc.list_races
+# => { '5k' => 5.0, '10k' => 10.0, 'half_marathon' => 21.0975, 'marathon' => 42.195 }
+```
+
+Supported race distances:
+- `5k` - 5 kilometers
+- `10k` - 10 kilometers
+- `half_marathon` - 21.0975 kilometers
+- `marathon` - 42.195 kilometers
+
 ### Other Useful Methods
 
 Calcpace also provides other useful methods:
@@ -134,7 +185,7 @@ Calcpace also provides other useful methods:
 converter = Calcpace.new
 converter.convert_to_seconds('01:00:00') # => 3600
 converter.convert_to_clocktime(3600) # => '01:00:00'
-converter.converto_to_clocktime(100000) # => '1 03:46:40'
+converter.convert_to_clocktime(100000) # => '1 03:46:40'
 converter.check_time('01:00:00') # => nil
 ```
 
@@ -151,7 +202,7 @@ For example:
 begin
   calculate.pace(945, -1)
 rescue Calcpace::NonPositiveInputError => e
-  puts e.message # => "Input must be a positive number"
+  puts e.message # => "Distance must be a positive number"
 end
 
 begin

data/calcpace.gemspec

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'lib/calcpace/version'
 
 Gem::Specification.new do |spec|
@@ -13,7 +15,8 @@ Gem::Specification.new do |spec|
   spec.license = 'MIT'
   spec.required_ruby_version = '>= 2.7.0'
 
-  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md" # TODO: Create a CHANGELOG.md
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }

data/lib/calcpace/calculator.rb

@@ -1,9 +1,23 @@
 # frozen_string_literal: true
 
 # Module to calculate time, distance, pace and velocity
+#
+# This module provides methods to perform calculations related to running and pace.
+# All methods that accept numeric inputs validate that values are positive.
+# Methods prefixed with 'checked_' accept time strings in HH:MM:SS or MM:SS format.
+# Methods prefixed with 'clock_' return results in time format (HH:MM:SS).
 module Calculator
+  # Calculates velocity (distance per unit time)
+  #
+  # @param time [Numeric] time in any unit (e.g., seconds, hours)
+  # @param distance [Numeric] distance in any unit (e.g., meters, kilometers)
+  # @return [Float] velocity (distance/time)
+  # @raise [Calcpace::NonPositiveInputError] if time or distance is not positive
+  #
+  # @example
+  #   velocity(3600, 12000) #=> 3.333... (12000 meters / 3600 seconds = 3.33 m/s)
   def velocity(time, distance)
-    validate_positive(time, distance)
+    validate_positive({ time: time, distance: distance })
     distance.to_f / time
   end
 
@@ -16,8 +30,17 @@ module Calculator
     convert_to_clocktime(checked_velocity(time, distance))
   end
 
+  # Calculates pace (time per unit distance)
+  #
+  # @param time [Numeric] time in any unit (e.g., seconds, minutes)
+  # @param distance [Numeric] distance in any unit (e.g., kilometers, miles)
+  # @return [Float] pace (time/distance)
+  # @raise [Calcpace::NonPositiveInputError] if time or distance is not positive
+  #
+  # @example
+  #   pace(3600, 12) #=> 300.0 (3600 seconds / 12 km = 300 seconds/km = 5:00/km)
   def pace(time, distance)
-    validate_positive(time, distance)
+    validate_positive({ time: time, distance: distance })
     time.to_f / distance
   end
 
@@ -31,7 +54,7 @@ module Calculator
   end
 
   def time(velocity, distance)
-    validate_positive(velocity, distance)
+    validate_positive({ velocity: velocity, distance: distance })
     velocity * distance
   end
 
@@ -45,7 +68,7 @@ module Calculator
   end
 
   def distance(time, velocity)
-    validate_positive(time, velocity)
+    validate_positive({ time: time, velocity: velocity })
     time.to_f / velocity
   end
 
@@ -57,8 +80,8 @@ module Calculator
 
   private
 
-  def validate_positive(*values)
-    values.each { |value| check_positive(value) }
+  def validate_positive(values)
+    values.each { |name, value| check_positive(value, name.capitalize) }
   end
 
   def validate_time(time)

data/lib/calcpace/checker.rb

@@ -2,19 +2,51 @@
 
 require_relative 'errors'
 
-# Module to check if the input is valid or of the correct type
+# Module to validate input values and formats
+#
+# This module provides validation methods for numeric inputs and time format strings
+# used throughout the Calcpace gem.
 module Checker
-  def check_positive(number)
+  # Validates that a number is positive (greater than zero)
+  #
+  # @param number [Numeric] the number to validate
+  # @param name [String] the name of the parameter for error messages
+  # @raise [Calcpace::NonPositiveInputError] if number is not positive
+  # @return [void]
+  #
+  # @example
+  #   check_positive(10, 'Distance') #=> nil (valid)
+  #   check_positive(-5, 'Time')     #=> raises NonPositiveInputError
+  #   check_positive(0, 'Speed')     #=> raises NonPositiveInputError
+  def check_positive(number, name = 'Input')
     return if number.is_a?(Numeric) && number.positive?
 
     raise Calcpace::NonPositiveInputError,
-          'It must be a positive number'
+          "#{name} must be a positive number"
   end
 
+  # Validates that a time string is in the correct format
+  #
+  # Accepted formats:
+  # - HH:MM:SS (hours:minutes:seconds) - e.g., "01:30:45"
+  # - MM:SS (minutes:seconds) - e.g., "05:30"
+  # - H:MM:SS or M:SS (single digit hours/minutes) - e.g., "1:30:45"
+  #
+  # @param time_string [String] the time string to validate
+  # @raise [Calcpace::InvalidTimeFormatError] if format is invalid
+  # @return [void]
+  #
+  # @example
+  #   check_time('01:30:45') #=> nil (valid)
+  #   check_time('5:30')     #=> nil (valid)
+  #   check_time('invalid')  #=> raises InvalidTimeFormatError
   def check_time(time_string)
-    return if time_string =~ /\A\d{1,2}:\d{2}:\d{2}\z/ ||
-              time_string =~ /\A\d{1,2}:\d{2}\z/
+    # Check if string is valid and matches expected patterns
+    return if time_string.is_a?(String) &&
+              (time_string =~ /\A\d{1,2}:\d{2}:\d{2}\z/ ||
+               time_string =~ /\A\d{1,2}:\d{2}\z/)
 
-    raise Calcpace::InvalidTimeFormatError, 'It must be a valid time in the XX:XX:XX or XX:XX format'
+    raise Calcpace::InvalidTimeFormatError,
+          'It must be a valid time in the XX:XX:XX or XX:XX format'
   end
 end

data/lib/calcpace/converter.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
-# Module to convert units
+# Module to convert between different units of distance and speed
+#
+# This module provides conversion methods for 42 different unit pairs,
+# including distance units (kilometers, miles, meters, feet, etc.) and
+# speed units (m/s, km/h, mi/h, knots, etc.).
 module Converter
   module Distance
     KM_TO_MI = 0.621371
@@ -50,44 +54,98 @@ module Converter
     NAUTICAL_MI_H_TO_MI_H = 1.15078
   end
 
+  # Converts a value from one unit to another
+  #
+  # @param value [Numeric] the value to convert
+  # @param unit [Symbol, String] the conversion unit (e.g., :km_to_mi or 'km to mi')
+  # @return [Float] the converted value
+  # @raise [Calcpace::NonPositiveInputError] if value is not positive
+  # @raise [Calcpace::UnsupportedUnitError] if the unit is not supported
+  #
+  # @example
+  #   convert(10, :km_to_mi)    #=> 6.21371 (10 km = 6.21 miles)
+  #   convert(5, 'mi to km')    #=> 8.0467 (5 miles = 8.05 km)
   def convert(value, unit)
-    check_positive(value)
+    check_positive(value, 'Value')
     unit_constant = constant(unit)
     value * unit_constant
   end
 
+  # Converts a time string to total seconds
+  #
+  # @param time [String] time string in HH:MM:SS or MM:SS format
+  # @return [Integer] total seconds
+  #
+  # @example
+  #   convert_to_seconds('01:30:00') #=> 5400 (1 hour 30 minutes)
+  #   convert_to_seconds('05:30')    #=> 330 (5 minutes 30 seconds)
   def convert_to_seconds(time)
     parts = time.split(':').map(&:to_i)
-    if parts.length == 2
+    case parts.length
+    when 2
       minute, seconds = parts
       (minute * 60) + seconds
-    else
+    when 3
       hour, minute, seconds = parts
       (hour * 3600) + (minute * 60) + seconds
+    else
+      0
     end
   end
 
+  # Converts seconds to a clocktime string
+  #
+  # @param seconds [Numeric] total seconds
+  # @return [String] time in HH:MM:SS format, or "D HH:MM:SS" for durations over 24 hours
+  #
+  # @example
+  #   convert_to_clocktime(3600)    #=> '01:00:00' (1 hour)
+  #   convert_to_clocktime(100000)  #=> '1 03:46:40' (1 day, 3 hours, 46 minutes, 40 seconds)
   def convert_to_clocktime(seconds)
     days = seconds / 86_400
     format = days.to_i.positive? ? "#{days} %H:%M:%S" : '%H:%M:%S'
     Time.at(seconds).utc.strftime(format)
   end
 
-  def constant(symbol)
-    Distance.const_get(symbol.to_s.upcase)
+  # Retrieves the conversion constant for a given unit
+  #
+  # @param unit [Symbol, String] the unit conversion (e.g., :km_to_mi or 'km to mi')
+  # @return [Float] the conversion factor
+  # @raise [Calcpace::UnsupportedUnitError] if the unit is not supported
+  #
+  # @example
+  #   constant(:km_to_mi)    #=> 0.621371
+  #   constant('km to mi')   #=> 0.621371
+  def constant(unit)
+    unit = format_unit(unit) if unit.is_a?(String)
+    Distance.const_get(unit.to_s.upcase)
   rescue NameError
-    Speed.const_get(symbol.to_s.upcase)
+    begin
+      Speed.const_get(unit.to_s.upcase)
+    rescue NameError
+      raise Calcpace::UnsupportedUnitError, unit
+    end
   end
 
   def list_all
-    (Distance.constants + Speed.constants).map { |c| c.downcase.to_sym }
+    format_list(Distance.constants + Speed.constants)
   end
 
   def list_speed
-    Speed.constants.map { |c| c.downcase.to_sym }
+    format_list(Speed.constants)
   end
 
   def list_distance
-    Distance.constants.map { |c| c.downcase.to_sym }
+    format_list(Distance.constants)
+  end
+
+  private
+
+  def format_unit(unit)
+    unit.downcase.gsub(' ', '_').to_sym
+  end
+
+  def format_list(constants)
+    constants.to_h { |c| [c.downcase.to_sym, c.to_s.gsub('_', ' ').gsub(' TO ', ' to ')] }
   end
 end

data/lib/calcpace/converter_chain.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Module for chaining multiple unit conversions
+#
+# This module allows performing multiple conversions in sequence,
+# which is useful for complex unit transformations.
+module ConverterChain
+  # Performs a chain of conversions on a value
+  #
+  # @param value [Numeric] the initial value to convert
+  # @param conversions [Array<Symbol, String>] array of conversion units
+  # @return [Float] the final converted value
+  # @raise [Calcpace::NonPositiveInputError] if value is not positive
+  # @raise [Calcpace::UnsupportedUnitError] if any conversion unit is not supported
+  #
+  # @example Convert kilometers to miles to feet
+  #   convert_chain(1, [:km_to_mi, :mi_to_feet])
+  #   #=> 3280.84 (1 km = 0.621 mi = 3280.84 feet)
+  #
+  # @example Using string format
+  #   convert_chain(100, ['meters to km', 'km to mi'])
+  #   #=> 0.0621371 (100 m = 0.1 km = 0.0621 mi)
+  def convert_chain(value, conversions)
+    check_positive(value, 'Value')
+    conversions.reduce(value) do |result, conversion|
+      result * constant(conversion)
+    end
+  end
+
+  # Performs a chain of conversions and returns a description
+  #
+  # @param value [Numeric] the initial value to convert
+  # @param conversions [Array<Symbol, String>] array of conversion units
+  # @return [Hash] hash with :result and :description keys
+  #
+  # @example
+  #   convert_chain_with_description(1, [:km_to_mi, :mi_to_feet])
+  #   #=> { result: 3280.84, description: "1.0 → km_to_mi → mi_to_feet → 3280.84" }
+  def convert_chain_with_description(value, conversions)
+    initial_value = value
+    result = convert_chain(value, conversions)
+    conversion_names = conversions.map(&:to_s).join(' → ')
+    description = "#{initial_value} → #{conversion_names} → #{result.round(4)}"
+
+    { result: result, description: description }
+  end
+end

data/lib/calcpace/errors.rb

@@ -1,9 +1,30 @@
 # frozen_string_literal: true
 
+# Calcpace custom error classes for better error handling
 class Calcpace
+  # Base error class for all Calcpace errors
   class Error < StandardError; end
 
-  class InvalidTimeFormatError < Error; end
+  # Raised when time string format is invalid
+  # Expected formats: HH:MM:SS or MM:SS
+  class InvalidTimeFormatError < Error
+    def initialize(msg = 'Invalid time format. Expected HH:MM:SS or MM:SS format.')
+      super
+    end
+  end
 
-  class NonPositiveInputError < Error; end
+  # Raised when a numeric input is not positive (zero or negative)
+  class NonPositiveInputError < Error
+    def initialize(msg = 'Input must be a positive number.')
+      super
+    end
+  end
+
+  # Raised when an unsupported unit conversion is requested
+  class UnsupportedUnitError < Error
+    def initialize(unit = nil)
+      msg = unit ? "Unsupported unit conversion: #{unit}" : 'Unsupported unit conversion'
+      super(msg)
+    end
+  end
 end

data/lib/calcpace/pace_calculator.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# Module for calculating race times and paces for standard distances
+#
+# This module provides convenience methods for calculating finish times
+# and paces for common race distances like 5K, 10K, half-marathon, and marathon.
+module PaceCalculator
+  # Standard race distances in kilometers
+  RACE_DISTANCES = {
+    '5k' => 5.0,
+    '10k' => 10.0,
+    'half_marathon' => 21.0975,
+    'marathon' => 42.195
+  }.freeze
+
+  # Calculates the finish time for a race given a pace per kilometer
+  #
+  # @param pace_per_km [Numeric, String] pace in seconds per km or time string (MM:SS)
+  # @param race [String, Symbol] race distance ('5k', '10k', 'half_marathon', 'marathon')
+  # @return [Float] total time in seconds
+  # @raise [ArgumentError] if race distance is not recognized
+  #
+  # @example
+  #   race_time(300, :5k)           #=> 1500.0 (5:00/km pace for 5K = 25:00)
+  #   race_time('05:00', :marathon) #=> 12658.5 (5:00/km pace for marathon = 3:30:58)
+  def race_time(pace_per_km, race)
+    distance = race_distance(race)
+    pace_seconds = pace_per_km.is_a?(String) ? convert_to_seconds(pace_per_km) : pace_per_km
+    check_positive(pace_seconds, 'Pace')
+    distance * pace_seconds
+  end
+
+  # Calculates the finish time for a race and returns it as a clock time string
+  #
+  # @param pace_per_km [Numeric, String] pace in seconds per km or time string (MM:SS)
+  # @param race [String, Symbol] race distance ('5k', '10k', 'half_marathon', 'marathon')
+  # @return [String] finish time in HH:MM:SS format
+  #
+  # @example
+  #   race_time_clock('05:00', :marathon) #=> '03:30:58'
+  #   race_time_clock(300, :half_marathon) #=> '01:45:17'
+  def race_time_clock(pace_per_km, race)
+    convert_to_clocktime(race_time(pace_per_km, race))
+  end
+
+  # Calculates the required pace per kilometer to finish a race in a target time
+  #
+  # @param target_time [Numeric, String] target finish time in seconds or time string (HH:MM:SS)
+  # @param race [String, Symbol] race distance ('5k', '10k', 'half_marathon', 'marathon')
+  # @return [Float] required pace in seconds per kilometer
+  #
+  # @example
+  #   race_pace('03:30:00', :marathon)    #=> 297.48... (4:57/km to finish in 3:30)
+  #   race_pace(1800, :5k)                #=> 360.0 (6:00/km to finish in 30:00)
+  def race_pace(target_time, race)
+    distance = race_distance(race)
+    time_seconds = target_time.is_a?(String) ? convert_to_seconds(target_time) : target_time
+    check_positive(time_seconds, 'Time')
+    time_seconds / distance
+  end
+
+  # Calculates the required pace and returns it as a clock time string
+  #
+  # @param target_time [Numeric, String] target finish time in seconds or time string (HH:MM:SS)
+  # @param race [String, Symbol] race distance ('5k', '10k', 'half_marathon', 'marathon')
+  # @return [String] required pace in MM:SS format
+  #
+  # @example
+  #   race_pace_clock('03:30:00', :marathon) #=> '00:04:57'
+  def race_pace_clock(target_time, race)
+    convert_to_clocktime(race_pace(target_time, race))
+  end
+
+  # Lists all available standard race distances
+  #
+  # @return [Hash] hash of race names and distances in kilometers
+  #
+  # @example
+  #   list_races #=> { '5k' => 5.0, '10k' => 10.0, ... }
+  def list_races
+    RACE_DISTANCES.dup
+  end
+
+  private
+
+  # Gets the distance for a standard race
+  #
+  # @param race [String, Symbol] race name
+  # @return [Float] distance in kilometers
+  # @raise [ArgumentError] if race is not recognized
+  def race_distance(race)
+    key = race.to_s.downcase
+    RACE_DISTANCES.fetch(key) do
+      raise ArgumentError,
+            "Unknown race: #{race}. Available races: #{RACE_DISTANCES.keys.join(', ')}"
+    end
+  end
+end

data/lib/calcpace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Calcpace
-  VERSION = "1.5.5"
+  VERSION = '1.7.0'
 end

data/lib/calcpace.rb

@@ -3,13 +3,39 @@
 require_relative 'calcpace/calculator'
 require_relative 'calcpace/checker'
 require_relative 'calcpace/converter'
+require_relative 'calcpace/converter_chain'
 require_relative 'calcpace/errors'
+require_relative 'calcpace/pace_calculator'
 
-# Main class to calculate velocity, pace, time, distance and velocity
+# Calcpace - A Ruby gem for pace, distance, and time calculations
+#
+# Calcpace provides methods to calculate and convert values related to pace,
+# distance, time, and speed. It supports various time formats and 42 different
+# unit conversions.
+#
+# @example Basic velocity calculation
+#   calc = Calcpace.new
+#   calc.velocity(3600, 12000) #=> 3.333... (12000m in 3600s = 3.33 m/s)
+#
+# @example Time string calculations
+#   calc = Calcpace.new
+#   calc.checked_pace('01:00:00', 10) #=> 360.0 (1 hour / 10 km = 6:00/km pace)
+#   calc.clock_pace('01:00:00', 10)   #=> '00:06:00'
+#
+# @example Unit conversions
+#   calc = Calcpace.new
+#   calc.convert(10, :km_to_mi)      #=> 6.21371 (10 km = 6.21 miles)
+#   calc.convert(1, 'm_s_to_km_h')   #=> 3.6 (1 m/s = 3.6 km/h)
+#
+# @see https://github.com/0jonjo/calcpace
 class Calcpace
   include Calculator
   include Checker
   include Converter
+  include ConverterChain
+  include PaceCalculator
 
-  def initialize; end
+  # Creates a new Calcpace instance
+  #
+  # @return [Calcpace] a new instance ready to perform calculations
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.5.5
+  version: 1.7.0
 platform: ruby
 authors:
 - João Gilberto Saraiva
 bindir: exe
 cert_chain: []
-date: 2025-06-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Calcpace provides methods to calculate and convert values related to
   pace, distance, time, and speed. It supports various time formats and unit conversions.
@@ -19,7 +19,10 @@ extra_rdoc_files: []
 files:
 - ".github/workflows/tests.yml"
 - ".gitignore"
+- ".rubocop.yml"
 - ".ruby-version"
+- ".tool-versions"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - README.md
@@ -29,7 +32,9 @@ files:
 - lib/calcpace/calculator.rb
 - lib/calcpace/checker.rb
 - lib/calcpace/converter.rb
+- lib/calcpace/converter_chain.rb
 - lib/calcpace/errors.rb
+- lib/calcpace/pace_calculator.rb
 - lib/calcpace/version.rb
 homepage: https://github.com/0jonjo/calcpace
 licenses:
@@ -37,6 +42,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/0jonjo/calcpace
   changelog_uri: https://github.com/0jonjo/calcpace/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -51,7 +57,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.7
 specification_version: 4
 summary: A Ruby gem for pace, distance, and time calculations.
 test_files: []