calcpace 1.7.0 → 1.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba8948e4e291f5381e58be3bc289ad8f54aa480a1cef744fc121dbc43449b523
-  data.tar.gz: a9e4b3da8526c245adfaed895f460b820d737ca4a3eb805a4e2c9b1510f1a6ca
+  metadata.gz: f8e3c9a491b95568c00e5fabb1a9ba33be46c07035f72a24e51155b60bd6ecaa
+  data.tar.gz: 7c644cc582c27f1204a98bf86238c45b5a236520350c97786d04d119698a2840
 SHA512:
-  metadata.gz: 61cea9354aa1343b9db15e92a1a11c06f053158ed72a48c5d1062e4b7d733888a7a8eaf3b88c7696cb879b7a92d196891c01e85369947dd4dead497b322b69b9
-  data.tar.gz: fcf1db5f88479865c65ce64d7c788a3762ea01f39c28f10fa3604e268bce1737589cec4eb8b66f94a10f70a1acb12b7ab73b082990e0bc9a1a0c11d0461159d6
+  metadata.gz: a503fad2dcb76fc61459315f9f6d866dc47cad64fff8459c5ea94ba3b82f22664e2b04a2e7a105de4130e169661de7c01b7b6dc54950bdf2b5179279d30e75d4
+  data.tar.gz: 28e0d2c909e0a7c811d0f992a397b63de2be086ed76a64e29839884a5597d6f1ce161dca9b3092a308947fb49c0bf7d7aca4fdfb351c51fe56253a5096e92efa

data/.github/workflows/tests.yml

@@ -8,12 +8,24 @@ on:
     branches: [ "main" ]
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: .ruby-version
+        bundler-cache: true
+    - name: Run RuboCop
+      run: bundle exec rubocop
   test:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        ruby: ['2.7', '3.0', '3.1', '3.2', '3.3', '3.4']
+        ruby: ['3.2', '3.3', '3.4', '4.0']
     steps:
     - name: Checkout code
       uses: actions/checkout@v4

data/.gitignore

@@ -1,2 +1,5 @@
+coverage/
+
 calcpace-*.gem
 !calcpace.gemspec
+improvements_plan.md

data/.rubocop.yml

@@ -4,7 +4,7 @@
 # Following Ruby best practices and style guidelines
 
 AllCops:
-  TargetRubyVersion: 2.7
+  TargetRubyVersion: 3.2
   NewCops: enable
   Exclude:
     - 'vendor/**/*'
@@ -55,6 +55,14 @@ Metrics/BlockLength:
     - 'test/**/*'
     - '*.gemspec'
 
+Metrics/ClassLength:
+  Exclude:
+    - 'test/**/*'
+
+Metrics/ModuleLength:
+  Exclude:
+    - 'lib/calcpace/race_splits.rb'
+
 # Allow both single and double quotes for strings
 Style/StringLiteralsInInterpolation:
   Enabled: false

data/CHANGELOG.md

@@ -5,7 +5,57 @@ 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
+## [1.8.1] - 2026-03-06
+
+### Added
+- SimpleCov integration for code coverage measurement
+- RuboCop lint job to CI pipeline
+- YARD documentation for all previously undocumented public methods in `Calculator` (`checked_velocity`, `clock_velocity`, `checked_pace`, `clock_pace`, `time`, `checked_time`, `clock_time`, `distance`, `checked_distance`)
+
+### Changed
+- Minimum required Ruby version bumped from 2.7 to 3.2
+- CI matrix updated: removed EOL Ruby versions (2.7, 3.0, 3.1), added Ruby 4.0
+- CI lint job uses `.ruby-version` file instead of a hardcoded version
+- Bundler updated to 4.0.6
+- `Rakefile.rb` renamed to `Rakefile` (standard convention)
+- `PaceConverter` constants `MI_TO_KM` and `KM_TO_MI` consolidated into `Converter::Distance`
+- Negative and positive split calculations refactored to share common logic
+- Test files refactored to inherit from shared `CalcpaceTest` base class
+
+## [1.8.0] - 2026-02-14
+
+### Added
+- Pace conversion module for converting running pace between kilometers and miles
+  - `convert_pace` method with support for both symbol and string format conversions
+  - `pace_km_to_mi` convenience method for kilometers to miles conversion
+  - `pace_mi_to_km` convenience method for miles to kilometers conversion
+  - Support for both numeric (seconds) and string (MM:SS) input formats
+- Race splits calculator for pacing strategies
+  - `race_splits` method to calculate cumulative split times for races
+  - Support for even pace, negative splits (progressive), and positive splits (conservative) strategies
+  - Flexible split distances: standard race distances ('5k', '1mile') or custom distances (numeric km)
+  - Works with all standard race distances including marathon, half marathon, 10K, 5K, and mile races
+- Race time predictor using Riegel formula
+  - `predict_time` and `predict_time_clock` methods to predict race times at different distances
+  - `predict_pace` and `predict_pace_clock` methods to calculate predicted pace for target races
+  - `equivalent_performance` method to compare performances across different race distances
+  - Based on proven Riegel formula: T2 = T1 × (D2/D1)^1.06
+  - Detailed explanation of the formula and its applications in README
+- Additional race distances for international races
+  - `1mile` - 1.60934 kilometers
+  - `5mile` - 8.04672 kilometers
+  - `10mile` - 16.0934 kilometers
+- Comprehensive test suites
+  - 30+ test cases for pace conversions
+  - 30+ test cases for race splits covering all strategies and edge cases
+  - 35+ test cases for race predictions covering various scenarios
+
+### Changed
+- Expanded `RACE_DISTANCES` to include popular US/UK race distances
+- Updated README with pace conversion, race splits, and race prediction examples
+- Improved documentation with practical examples, use cases, and formula explanations
+
+## [1.7.0] - Released
 
 ### Added
 - RuboCop configuration for code style consistency

data/Gemfile

@@ -7,3 +7,4 @@ gem 'rake', '~> 13.2'
 gem 'rake-compiler', '~> 1.0'
 gem 'rdoc', '~> 6.2'
 gem 'rubocop', '~> 1.69'
+gem 'simplecov', '~> 0.22', require: false

data/Gemfile.lock

@@ -1,45 +1,68 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
-    date (3.4.1)
-    json (2.10.2)
-    language_server-protocol (3.17.0.4)
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    date (3.5.1)
+    docile (1.4.1)
+    erb (6.0.2)
+    json (2.19.0)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    minitest (5.25.4)
-    parallel (1.26.3)
-    parser (3.3.7.1)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    minitest (5.27.0)
+    parallel (1.27.0)
+    parser (3.3.10.2)
       ast (~> 2.4.1)
       racc
-    psych (5.2.3)
+    prism (1.9.0)
+    psych (5.3.1)
       date
       stringio
+    public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
-    rake-compiler (1.2.9)
+    rake (13.3.1)
+    rake-compiler (1.3.1)
       rake
-    rdoc (6.12.0)
+    rdoc (6.17.0)
+      erb
       psych (>= 4.0.0)
-    regexp_parser (2.10.0)
-    rubocop (1.73.2)
+      tsort
+    regexp_parser (2.11.3)
+    rubocop (1.85.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.38.1)
-      parser (>= 3.3.1.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
     ruby-progressbar (1.13.0)
-    stringio (3.1.5)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    stringio (3.2.0)
+    tsort (0.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
 
 PLATFORMS
   ruby
@@ -50,6 +73,7 @@ DEPENDENCIES
   rake-compiler (~> 1.0)
   rdoc (~> 6.2)
   rubocop (~> 1.69)
+  simplecov (~> 0.22)
 
 BUNDLED WITH
-   2.4.22
+  4.0.6

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.7.0&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.8.1&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.7.0'
+gem 'calcpace', '~> 1.8.1'
 ```
 
 Then run:
@@ -176,6 +176,137 @@ Supported race distances:
 - `10k` - 10 kilometers
 - `half_marathon` - 21.0975 kilometers
 - `marathon` - 42.195 kilometers
+- `1mile` - 1.60934 kilometers
+- `5mile` - 8.04672 kilometers
+- `10mile` - 16.0934 kilometers
+
+### Pace Conversions
+
+Convert running pace between kilometers and miles:
+
+```ruby
+calc = Calcpace.new
+
+# Convert pace from km to miles
+calc.pace_km_to_mi('05:00')           # => '00:08:02' (5:00/km = 8:02/mi)
+calc.convert_pace('05:00', :km_to_mi) # => '00:08:02' (same as above)
+
+# Convert pace from miles to km
+calc.pace_mi_to_km('08:00')           # => '00:04:58' (8:00/mi ≈ 4:58/km)
+calc.convert_pace('08:00', :mi_to_km) # => '00:04:58' (same as above)
+
+# Works with numeric input (seconds) as well
+calc.pace_km_to_mi(300)               # => '00:08:02' (300 seconds/km)
+calc.pace_mi_to_km(480)               # => '00:04:58' (480 seconds/mi)
+
+# String format also supported
+calc.convert_pace('05:00', 'km to mi') # => '00:08:02'
+```
+
+The pace conversions are particularly useful when:
+- Planning races in different countries (metric vs imperial)
+- Comparing training paces with international runners
+- Converting workout plans between pace formats
+
+### Race Splits
+
+Calculate split times for races to help pace your race strategy:
+
+```ruby
+calc = Calcpace.new
+
+# Even pace splits for half marathon (every 5k)
+calc.race_splits('half_marathon', target_time: '01:30:00', split_distance: '5k')
+# => ["00:21:20", "00:42:40", "01:03:59", "01:25:19", "01:30:00"]
+
+# Kilometer splits for 10K
+calc.race_splits('10k', target_time: '00:40:00', split_distance: '1k')
+# => ["00:04:00", "00:08:00", "00:12:00", ..., "00:40:00"]
+
+# Mile splits for marathon
+calc.race_splits('marathon', target_time: '03:30:00', split_distance: '1mile')
+# => ["00:08:02", "00:16:04", ..., "03:30:00"]
+
+# Negative splits strategy (second half faster)
+calc.race_splits('10k', target_time: '00:40:00', split_distance: '5k', strategy: :negative)
+# => ["00:20:48", "00:40:00"] # First 5k slower, second 5k faster
+
+# Positive splits strategy (first half faster)
+calc.race_splits('10k', target_time: '00:40:00', split_distance: '5k', strategy: :positive)
+# => ["00:19:12", "00:40:00"] # First 5k faster, second 5k slower
+```
+
+Supported strategies:
+- `:even` - Constant pace throughout (default)
+- `:negative` - Second half ~4% faster (progressive race)
+- `:positive` - First half ~4% faster (conservative start)
+
+Split distances can be:
+- Standard race distances: `'5k'`, `'10k'`, `'1mile'`, etc.
+- Custom distances: `2.5` (in kilometers), `'3k'`, etc.
+
+### Race Time Predictions
+
+Predict your race times at different distances based on a recent performance using the **Riegel formula**:
+
+```ruby
+calc = Calcpace.new
+
+# Predict marathon time from a 5K result
+calc.predict_time_clock('5k', '00:20:00', 'marathon')
+# => "03:11:49" (predicts 3:11:49 marathon from 20:00 5K)
+
+# Predict 10K time from half marathon
+calc.predict_time_clock('half_marathon', '01:30:00', '10k')
+# => "00:40:47"
+
+# Get predicted pace for target race
+calc.predict_pace_clock('5k', '00:20:00', 'marathon')
+# => "00:04:32" (4:32/km pace for predicted marathon)
+
+# Get complete equivalent performance info
+calc.equivalent_performance('10k', '00:42:00', '5k')
+# => {
+#      time: 1209.0,
+#      time_clock: "00:20:09",
+#      pace: 241.8,
+#      pace_clock: "00:04:02"
+#    }
+```
+
+#### How the Riegel Formula Works
+
+The Riegel formula is a mathematical model that predicts race performance across different distances:
+
+**Formula:** `T2 = T1 × (D2/D1)^1.06`
+
+Where:
+- **T1** = your known time at distance D1
+- **T2** = predicted time at distance D2
+- **D1** = known race distance (in km)
+- **D2** = target race distance (in km)
+- **1.06** = fatigue/endurance factor
+
+**The 1.06 exponent** represents how pace slows as distance increases. If endurance was perfect (1.0), doubling distance would simply double time. But in reality, you slow down slightly - the 1.06 factor accounts for this accumulated fatigue.
+
+**Example:** From a 5K in 20:00, predict marathon time:
+- T1 = 1200 seconds (20:00)
+- D1 = 5 km
+- D2 = 42.195 km (marathon)
+- T2 = 1200 × (42.195/5)^1.06
+- T2 = 1200 × 9.591 = 11,509 seconds
+- T2 = **3:11:49**
+
+The formula works best for:
+- Distances from 5K to marathon
+- Recent race results (within 6-8 weeks)
+- Similar terrain and weather conditions
+- Well-trained runners with consistent pacing
+
+**Important notes:**
+- Predictions assume equal training and effort across distances
+- Results are estimates - actual performance varies by individual fitness, training focus, and race conditions
+- The formula is most accurate when predicting between similar distance ranges (e.g., 10K to half marathon)
 
 ### Other Useful Methods
 

data/calcpace.gemspec

@@ -9,11 +9,11 @@ Gem::Specification.new do |spec|
   spec.email         = ['joaogilberto@tuta.io']
 
   spec.summary       = 'A Ruby gem for pace, distance, and time calculations.'
-  spec.description   = 'Calcpace provides methods to calculate and convert values related to pace, distance, time, and speed. It supports various time formats and unit conversions.'
+  spec.description   = 'Ruby gem for pace, distance, time, and speed calculations. Supports multiple units and formats.'
   spec.homepage      = 'https://github.com/0jonjo/calcpace'
   spec.metadata['source_code_uri'] = spec.homepage
   spec.license = 'MIT'
-  spec.required_ruby_version = '>= 2.7.0'
+  spec.required_ruby_version = '>= 3.2.0'
 
   spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
   spec.metadata['rubygems_mfa_required'] = 'true'

data/lib/calcpace/calculator.rb

@@ -21,11 +21,31 @@ module Calculator
     distance.to_f / time
   end
 
+  # Calculates velocity from a time string
+  #
+  # @param time [String] time in HH:MM:SS or MM:SS format
+  # @param distance [Numeric] distance in any unit (e.g., meters, kilometers)
+  # @return [Float] velocity (distance/time)
+  # @raise [Calcpace::InvalidTimeFormatError] if time string is invalid
+  # @raise [Calcpace::NonPositiveInputError] if distance is not positive
+  #
+  # @example
+  #   checked_velocity('01:00:00', 10_000) #=> 2.778 (10000 meters / 3600 seconds)
   def checked_velocity(time, distance)
     seconds = convert_to_seconds(validate_time(time))
     velocity(seconds, distance)
   end
 
+  # Calculates velocity from a time string and returns result as a clock time string
+  #
+  # @param time [String] time in HH:MM:SS or MM:SS format
+  # @param distance [Numeric] distance in any unit
+  # @return [String] velocity in HH:MM:SS format
+  # @raise [Calcpace::InvalidTimeFormatError] if time string is invalid
+  # @raise [Calcpace::NonPositiveInputError] if distance is not positive
+  #
+  # @example
+  #   clock_velocity('01:00:00', 10_000) #=> '00:00:00'
   def clock_velocity(time, distance)
     convert_to_clocktime(checked_velocity(time, distance))
   end
@@ -44,34 +64,101 @@ module Calculator
     time.to_f / distance
   end
 
+  # Calculates pace from a time string
+  #
+  # @param time [String] time in HH:MM:SS or MM:SS format
+  # @param distance [Numeric] distance in any unit (e.g., kilometers, miles)
+  # @return [Float] pace (time/distance) in seconds
+  # @raise [Calcpace::InvalidTimeFormatError] if time string is invalid
+  # @raise [Calcpace::NonPositiveInputError] if distance is not positive
+  #
+  # @example
+  #   checked_pace('00:50:00', 10) #=> 300.0 (300 seconds/km = 5:00/km)
   def checked_pace(time, distance)
     seconds = convert_to_seconds(validate_time(time))
     pace(seconds, distance)
   end
 
+  # Calculates pace from a time string and returns result as a clock time string
+  #
+  # @param time [String] time in HH:MM:SS or MM:SS format
+  # @param distance [Numeric] distance in any unit
+  # @return [String] pace in HH:MM:SS format
+  # @raise [Calcpace::InvalidTimeFormatError] if time string is invalid
+  # @raise [Calcpace::NonPositiveInputError] if distance is not positive
+  #
+  # @example
+  #   clock_pace('00:50:00', 10) #=> '00:05:00'
   def clock_pace(time, distance)
     convert_to_clocktime(checked_pace(time, distance))
   end
 
+  # Calculates time given velocity and distance
+  #
+  # @param velocity [Numeric] velocity in any unit
+  # @param distance [Numeric] distance in any unit
+  # @return [Float] time (velocity * distance)
+  # @raise [Calcpace::NonPositiveInputError] if velocity or distance is not positive
+  #
+  # @example
+  #   time(300, 10) #=> 3000.0 (300 s/km * 10 km = 3000 seconds)
   def time(velocity, distance)
     validate_positive({ velocity: velocity, distance: distance })
     velocity * distance
   end
 
+  # Calculates time from a velocity string and distance
+  #
+  # @param velocity [String] velocity in HH:MM:SS or MM:SS format
+  # @param distance [Numeric] distance in any unit
+  # @return [Float] time in seconds
+  # @raise [Calcpace::InvalidTimeFormatError] if velocity string is invalid
+  # @raise [Calcpace::NonPositiveInputError] if distance is not positive
+  #
+  # @example
+  #   checked_time('05:00', 10) #=> 3000.0 (5:00/km * 10 km = 3000 seconds)
   def checked_time(velocity, distance)
     velocity_seconds = convert_to_seconds(validate_time(velocity))
     time(velocity_seconds, distance)
   end
 
+  # Calculates time from a velocity string and returns result as a clock time string
+  #
+  # @param velocity [String] velocity in HH:MM:SS or MM:SS format
+  # @param distance [Numeric] distance in any unit
+  # @return [String] time in HH:MM:SS format
+  # @raise [Calcpace::InvalidTimeFormatError] if velocity string is invalid
+  # @raise [Calcpace::NonPositiveInputError] if distance is not positive
+  #
+  # @example
+  #   clock_time('05:00', 10) #=> '00:50:00'
   def clock_time(velocity, distance)
     convert_to_clocktime(checked_time(velocity, distance))
   end
 
+  # Calculates distance given time and velocity
+  #
+  # @param time [Numeric] time in any unit
+  # @param velocity [Numeric] velocity in any unit
+  # @return [Float] distance (time/velocity)
+  # @raise [Calcpace::NonPositiveInputError] if time or velocity is not positive
+  #
+  # @example
+  #   distance(3000, 300) #=> 10.0 (3000 seconds / 300 s/km = 10 km)
   def distance(time, velocity)
     validate_positive({ time: time, velocity: velocity })
     time.to_f / velocity
   end
 
+  # Calculates distance from time and velocity strings
+  #
+  # @param time [String] time in HH:MM:SS or MM:SS format
+  # @param velocity [String] velocity in HH:MM:SS or MM:SS format
+  # @return [Float] distance
+  # @raise [Calcpace::InvalidTimeFormatError] if any string is invalid
+  #
+  # @example
+  #   checked_distance('00:50:00', '05:00') #=> 10.0 (50 min / 5:00/km = 10 km)
   def checked_distance(time, velocity)
     time_seconds = convert_to_seconds(validate_time(time))
     velocity_seconds = convert_to_seconds(validate_time(velocity))

data/lib/calcpace/converter_chain.rb

@@ -39,7 +39,7 @@ module ConverterChain
   def convert_chain_with_description(value, conversions)
     initial_value = value
     result = convert_chain(value, conversions)
-    conversion_names = conversions.map(&:to_s).join(' → ')
+    conversion_names = conversions.join(' → ')
     description = "#{initial_value} → #{conversion_names} → #{result.round(4)}"
 
     { result: result, description: description }

data/lib/calcpace/pace_calculator.rb

@@ -10,7 +10,10 @@ module PaceCalculator
     '5k' => 5.0,
     '10k' => 10.0,
     'half_marathon' => 21.0975,
-    'marathon' => 42.195
+    'marathon' => 42.195,
+    '1mile' => 1.60934,
+    '5mile' => 8.04672,
+    '10mile' => 16.0934
   }.freeze
 
   # Calculates the finish time for a race given a pace per kilometer

data/lib/calcpace/pace_converter.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Module for converting pace between different distance units
+#
+# This module provides methods to convert running pace between kilometers
+# and miles, maintaining the time per distance unit format.
+module PaceConverter
+  # Converts pace from one unit to another
+  #
+  # @param pace [Numeric, String] pace in seconds per unit or time string (MM:SS)
+  # @param conversion [Symbol, String] conversion type (:km_to_mi, :mi_to_km, 'km to mi', 'mi to km')
+  # @return [String] converted pace in MM:SS format
+  # @raise [ArgumentError] if conversion type is not supported
+  # @raise [Calcpace::NonPositiveInputError] if pace is not positive
+  #
+  # @example
+  #   convert_pace('05:00', :km_to_mi)    #=> '08:02' (5:00/km = 8:02/mi)
+  #   convert_pace('08:00', :mi_to_km)    #=> '04:58' (8:00/mi ≈ 4:58/km)
+  #   convert_pace(300, 'km to mi')       #=> '08:02' (300s/km = 482s/mi)
+  def convert_pace(pace, conversion)
+    pace_seconds = pace.is_a?(String) ? convert_to_seconds(pace) : pace
+    check_positive(pace_seconds, 'Pace')
+
+    conversion_type = normalize_conversion(conversion)
+    converted_seconds = apply_pace_conversion(pace_seconds, conversion_type)
+
+    convert_to_clocktime(converted_seconds)
+  end
+
+  # Converts pace from kilometers to miles
+  #
+  # @param pace_per_km [Numeric, String] pace in seconds per km or time string (MM:SS)
+  # @return [String] pace per mile in MM:SS format
+  #
+  # @example
+  #   pace_km_to_mi('05:00')  #=> '08:02' (5:00/km = 8:02/mi)
+  #   pace_km_to_mi(300)      #=> '08:02' (300s/km = 482s/mi)
+  def pace_km_to_mi(pace_per_km)
+    convert_pace(pace_per_km, :km_to_mi)
+  end
+
+  # Converts pace from miles to kilometers
+  #
+  # @param pace_per_mi [Numeric, String] pace in seconds per mile or time string (MM:SS)
+  # @return [String] pace per kilometer in MM:SS format
+  #
+  # @example
+  #   pace_mi_to_km('08:00')  #=> '04:58' (8:00/mi ≈ 4:58/km)
+  #   pace_mi_to_km(480)      #=> '04:58' (480s/mi = 298s/km)
+  def pace_mi_to_km(pace_per_mi)
+    convert_pace(pace_per_mi, :mi_to_km)
+  end
+
+  private
+
+  # Normalizes conversion string/symbol to standard format
+  #
+  # @param conversion [Symbol, String] conversion type
+  # @return [Symbol] normalized conversion symbol
+  # @raise [ArgumentError] if conversion type is not supported
+  def normalize_conversion(conversion)
+    normalized = if conversion.is_a?(String)
+                   conversion.downcase.gsub(/\s+/, '_').to_sym
+                 else
+                   conversion.to_sym
+                 end
+
+    unless %i[km_to_mi mi_to_km].include?(normalized)
+      raise ArgumentError,
+            "Unsupported pace conversion: #{conversion}. " \
+            "Supported conversions: km_to_mi, mi_to_km"
+    end
+
+    normalized
+  end
+
+  # Applies the pace conversion
+  #
+  # @param pace_seconds [Numeric] pace in seconds
+  # @param conversion_type [Symbol] conversion type (:km_to_mi or :mi_to_km)
+  # @return [Float] converted pace in seconds
+  def apply_pace_conversion(pace_seconds, conversion_type)
+    case conversion_type
+    when :km_to_mi
+      # If running at X seconds per km, pace per mile = X * (miles to km ratio)
+      pace_seconds * Converter::Distance::MI_TO_KM
+    when :mi_to_km
+      # If running at X seconds per mile, pace per km = X / (miles to km ratio)
+      pace_seconds * Converter::Distance::KM_TO_MI
+    end
+  end
+end

data/lib/calcpace/race_predictor.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# Module for predicting race times based on performance at other distances
+#
+# This module uses the Riegel formula to predict race times based on a known
+# performance at a different distance. The formula accounts for the endurance
+# fatigue factor that occurs as race distance increases.
+module RacePredictor
+  # Riegel formula exponent (represents endurance/fatigue factor)
+  RIEGEL_EXPONENT = 1.06
+
+  # Predicts race time for a target distance based on a known performance
+  #
+  # Uses the Riegel formula: T2 = T1 × (D2/D1)^1.06
+  # where:
+  # - T1 = time at known distance
+  # - D1 = known distance
+  # - T2 = predicted time at target distance
+  # - D2 = target distance
+  # - 1.06 = endurance/fatigue factor (longer races require proportionally more time)
+  #
+  # @param from_race [String, Symbol] known race distance ('5k', '10k', 'half_marathon', 'marathon', etc.)
+  # @param from_time [String, Numeric] time achieved at known distance (HH:MM:SS or seconds)
+  # @param to_race [String, Symbol] target race distance to predict
+  # @return [Float] predicted time in seconds
+  # @raise [ArgumentError] if races are invalid or distances are the same
+  #
+  # @example Predict marathon time from 5K
+  #   predict_time('5k', '00:20:00', 'marathon')
+  #   #=> 11123.4 (approximately 3:05:23)
+  #
+  # @example Predict 10K time from half marathon
+  #   predict_time('half_marathon', '01:30:00', '10k')
+  #   #=> 2565.8 (approximately 42:46)
+  def predict_time(from_race, from_time, to_race)
+    from_distance = race_distance(from_race)
+    to_distance = race_distance(to_race)
+
+    if from_distance == to_distance
+      raise ArgumentError,
+            "From and to races must be different distances (both are #{from_distance}km)"
+    end
+
+    time_seconds = from_time.is_a?(String) ? convert_to_seconds(from_time) : from_time
+    check_positive(time_seconds, 'Time')
+
+    # Riegel formula: T2 = T1 × (D2/D1)^1.06
+    time_seconds * ((to_distance / from_distance)**RIEGEL_EXPONENT)
+  end
+
+  # Predicts race time and returns it as a clock time string
+  #
+  # @param from_race [String, Symbol] known race distance
+  # @param from_time [String, Numeric] time achieved at known distance
+  # @param to_race [String, Symbol] target race distance to predict
+  # @return [String] predicted time in HH:MM:SS format
+  #
+  # @example
+  #   predict_time_clock('5k', '00:20:00', 'marathon')
+  #   #=> '03:05:23'
+  def predict_time_clock(from_race, from_time, to_race)
+    predicted_seconds = predict_time(from_race, from_time, to_race)
+    convert_to_clocktime(predicted_seconds)
+  end
+
+  # Predicts the pace per kilometer for a target race
+  #
+  # @param from_race [String, Symbol] known race distance
+  # @param from_time [String, Numeric] time achieved at known distance
+  # @param to_race [String, Symbol] target race distance to predict
+  # @return [Float] predicted pace in seconds per kilometer
+  #
+  # @example
+  #   predict_pace('5k', '00:20:00', 'marathon')
+  #   #=> 263.6 (approximately 4:24/km)
+  def predict_pace(from_race, from_time, to_race)
+    predicted_seconds = predict_time(from_race, from_time, to_race)
+    to_distance = race_distance(to_race)
+    predicted_seconds / to_distance
+  end
+
+  # Predicts the pace per kilometer and returns it as a clock time string
+  #
+  # @param from_race [String, Symbol] known race distance
+  # @param from_time [String, Numeric] time achieved at known distance
+  # @param to_race [String, Symbol] target race distance to predict
+  # @return [String] predicted pace in MM:SS format
+  #
+  # @example
+  #   predict_pace_clock('5k', '00:20:00', 'marathon')
+  #   #=> '00:04:24' (4:24/km)
+  def predict_pace_clock(from_race, from_time, to_race)
+    pace_seconds = predict_pace(from_race, from_time, to_race)
+    convert_to_clocktime(pace_seconds)
+  end
+
+  # Calculates the equivalent performance at a different distance
+  #
+  # This is useful for comparing performances across different race distances.
+  # For example, "My 10K time is equivalent to what 5K time?"
+  #
+  # @param from_race [String, Symbol] known race distance
+  # @param from_time [String, Numeric] time achieved at known distance
+  # @param to_race [String, Symbol] target race distance for comparison
+  # @return [Hash] hash with :time (seconds), :time_clock (HH:MM:SS), :pace (/km), :pace_clock
+  #
+  # @example
+  #   equivalent_performance('10k', '00:42:00', '5k')
+  #   #=> {
+  #         time: 1228.5,
+  #         time_clock: "00:20:28",
+  #         pace: 245.7,
+  #         pace_clock: "00:04:06"
+  #       }
+  def equivalent_performance(from_race, from_time, to_race)
+    predicted_time = predict_time(from_race, from_time, to_race)
+    predicted_pace = predict_pace(from_race, from_time, to_race)
+
+    {
+      time: predicted_time,
+      time_clock: convert_to_clocktime(predicted_time),
+      pace: predicted_pace,
+      pace_clock: convert_to_clocktime(predicted_pace)
+    }
+  end
+end

data/lib/calcpace/race_splits.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+# Module for calculating race splits (partial times)
+#
+# This module provides methods to calculate split times for races,
+# supporting different pacing strategies like even pace, negative splits, etc.
+module RaceSplits
+  # Calculates split times for a race
+  #
+  # @param race [String, Symbol] race distance ('5k', '10k', 'half_marathon', 'marathon', etc.)
+  # @param target_time [String] target finish time in HH:MM:SS or MM:SS format
+  # @param split_distance [String, Numeric] distance for each split ('5k', '1k', '1mile', or numeric in km)
+  # @param strategy [Symbol] pacing strategy - :even (default), :negative, or :positive
+  # @return [Array<String>] array of cumulative split times in HH:MM:SS format
+  # @raise [ArgumentError] if race or split_distance is invalid
+  #
+  # @example Even pace splits for half marathon
+  #   race_splits('half_marathon', target_time: '01:30:00', split_distance: '5k')
+  #   #=> ["00:21:18", "00:42:35", "01:03:53", "01:30:00"]
+  #
+  # @example Negative splits (second half faster)
+  #   race_splits('10k', target_time: '00:40:00', split_distance: '5k', strategy: :negative)
+  #   #=> ["00:20:48", "00:40:00"] (first 5k slower, second 5k faster)
+  def race_splits(race, target_time:, split_distance:, strategy: :even)
+    total_distance = race_distance(race)
+    target_seconds = target_time.is_a?(String) ? convert_to_seconds(target_time) : target_time
+    check_positive(target_seconds, 'Target time')
+
+    split_km = normalize_split_distance(split_distance)
+    validate_split_distance(split_km, total_distance)
+
+    calculate_splits(total_distance, target_seconds, split_km, strategy)
+  end
+
+  private
+
+  # Normalizes split distance to kilometers
+  #
+  # @param split_distance [String, Numeric] distance for each split
+  # @return [Float] split distance in kilometers
+  def normalize_split_distance(split_distance)
+    if split_distance.is_a?(Numeric)
+      split_distance.to_f
+    elsif split_distance.is_a?(String)
+      # Try to get from RACE_DISTANCES first (includes standard distances like '5k', '1mile', etc.)
+      distance_key = split_distance.to_s.downcase
+
+      # Check if it's a standard race distance
+      begin
+        return race_distance(distance_key)
+      rescue ArgumentError
+        # Not a race distance, try to parse as numeric
+      end
+
+      # Try to parse as number with optional 'k' or 'km'
+      normalized = distance_key.gsub(/km?$/, '').strip
+      begin
+        Float(normalized)
+      rescue StandardError
+        raise(ArgumentError, "Invalid split distance: #{split_distance}")
+      end
+    else
+      raise ArgumentError, "Split distance must be a number or string"
+    end
+  end
+
+  # Validates that split distance is reasonable for the race
+  #
+  # @param split_km [Float] split distance in kilometers
+  # @param total_distance [Float] total race distance in kilometers
+  # @raise [ArgumentError] if split distance is invalid
+  def validate_split_distance(split_km, total_distance)
+    raise ArgumentError, "Split distance must be positive" if split_km <= 0
+
+    if split_km > total_distance
+      raise ArgumentError,
+            "Split distance (#{split_km}km) cannot be greater than race distance (#{total_distance}km)"
+    end
+
+    # Allow some flexibility for non-exact divisions
+    return unless (total_distance / split_km) > 100
+
+    raise ArgumentError,
+          "Split distance too small - would generate more than 100 splits"
+  end
+
+  # Calculates split times based on strategy
+  #
+  # @param total_distance [Float] total race distance in kilometers
+  # @param target_seconds [Float] target finish time in seconds
+  # @param split_km [Float] split distance in kilometers
+  # @param strategy [Symbol] pacing strategy
+  # @return [Array<String>] array of cumulative split times
+  def calculate_splits(total_distance, target_seconds, split_km, strategy)
+    case strategy
+    when :even
+      calculate_even_splits(total_distance, target_seconds, split_km)
+    when :negative
+      calculate_negative_splits(total_distance, target_seconds, split_km)
+    when :positive
+      calculate_positive_splits(total_distance, target_seconds, split_km)
+    else
+      raise ArgumentError,
+            "Unknown strategy: #{strategy}. Supported strategies: :even, :negative, :positive"
+    end
+  end
+
+  # Calculates even pace splits (constant pace throughout)
+  #
+  # @param total_distance [Float] total race distance in kilometers
+  # @param target_seconds [Float] target finish time in seconds
+  # @param split_km [Float] split distance in kilometers
+  # @return [Array<String>] array of cumulative split times
+  def calculate_even_splits(total_distance, target_seconds, split_km)
+    pace_per_km = target_seconds / total_distance
+    splits = []
+    distance_covered = 0.0
+
+    while distance_covered < total_distance - 0.001 # small tolerance for floating point
+      distance_covered += split_km
+      # Don't exceed total distance
+      distance_covered = total_distance if distance_covered > total_distance
+
+      split_time = (distance_covered * pace_per_km).round
+      splits << convert_to_clocktime(split_time)
+    end
+
+    splits
+  end
+
+  # Calculates negative splits (second half faster than first half)
+  # First half is ~4% slower, second half is ~4% faster
+  #
+  # @param total_distance [Float] total race distance in kilometers
+  # @param target_seconds [Float] target finish time in seconds
+  # @param split_km [Float] split distance in kilometers
+  # @return [Array<String>] array of cumulative split times
+  def calculate_negative_splits(total_distance, target_seconds, split_km)
+    calculate_variable_splits(total_distance, target_seconds, split_km, first_factor: 1.04, second_factor: 0.96)
+  end
+
+  # Calculates positive splits (first half faster than second half)
+  # First half is ~4% faster, second half is ~4% slower
+  #
+  # @param total_distance [Float] total race distance in kilometers
+  # @param target_seconds [Float] target finish time in seconds
+  # @param split_km [Float] split distance in kilometers
+  # @return [Array<String>] array of cumulative split times
+  def calculate_positive_splits(total_distance, target_seconds, split_km)
+    calculate_variable_splits(total_distance, target_seconds, split_km, first_factor: 0.96, second_factor: 1.04)
+  end
+
+  # Shared logic for variable pace split strategies
+  #
+  # @param total_distance [Float] total race distance in kilometers
+  # @param target_seconds [Float] target finish time in seconds
+  # @param split_km [Float] split distance in kilometers
+  # @param first_factor [Float] pace multiplier for the first half
+  # @param second_factor [Float] pace multiplier for the second half
+  # @return [Array<String>] array of cumulative split times
+  def calculate_variable_splits(total_distance, target_seconds, split_km, first_factor:, second_factor:)
+    half_distance = total_distance / 2.0
+    avg_pace = target_seconds / total_distance
+    first_half_pace = avg_pace * first_factor
+    second_half_pace = avg_pace * second_factor
+
+    splits = []
+    distance_covered = 0.0
+    cumulative_time = 0.0
+
+    while distance_covered < total_distance - 0.001
+      distance_covered += split_km
+      distance_covered = total_distance if distance_covered > total_distance
+
+      if distance_covered <= half_distance
+        cumulative_time = distance_covered * first_half_pace
+      else
+        time_at_halfway = half_distance * first_half_pace
+        distance_in_second_half = distance_covered - half_distance
+        cumulative_time = time_at_halfway + (distance_in_second_half * second_half_pace)
+      end
+
+      splits << convert_to_clocktime(cumulative_time.round)
+    end
+
+    splits
+  end
+end

data/lib/calcpace/version.rb

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

data/lib/calcpace.rb

@@ -6,6 +6,9 @@ require_relative 'calcpace/converter'
 require_relative 'calcpace/converter_chain'
 require_relative 'calcpace/errors'
 require_relative 'calcpace/pace_calculator'
+require_relative 'calcpace/pace_converter'
+require_relative 'calcpace/race_predictor'
+require_relative 'calcpace/race_splits'
 
 # Calcpace - A Ruby gem for pace, distance, and time calculations
 #
@@ -34,6 +37,9 @@ class Calcpace
   include Converter
   include ConverterChain
   include PaceCalculator
+  include PaceConverter
+  include RacePredictor
+  include RaceSplits
 
   # Creates a new Calcpace instance
   #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.1
 platform: ruby
 authors:
 - João Gilberto Saraiva
@@ -9,8 +9,8 @@ bindir: exe
 cert_chain: []
 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.
+description: Ruby gem for pace, distance, time, and speed calculations. Supports multiple
+  units and formats.
 email:
 - joaogilberto@tuta.io
 executables: []
@@ -26,7 +26,7 @@ files:
 - Gemfile
 - Gemfile.lock
 - README.md
-- Rakefile.rb
+- Rakefile
 - calcpace.gemspec
 - lib/calcpace.rb
 - lib/calcpace/calculator.rb
@@ -35,6 +35,9 @@ files:
 - lib/calcpace/converter_chain.rb
 - lib/calcpace/errors.rb
 - lib/calcpace/pace_calculator.rb
+- lib/calcpace/pace_converter.rb
+- lib/calcpace/race_predictor.rb
+- lib/calcpace/race_splits.rb
 - lib/calcpace/version.rb
 homepage: https://github.com/0jonjo/calcpace
 licenses:
@@ -50,14 +53,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A Ruby gem for pace, distance, and time calculations.
 test_files: []