calcpace 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba8948e4e291f5381e58be3bc289ad8f54aa480a1cef744fc121dbc43449b523
-  data.tar.gz: a9e4b3da8526c245adfaed895f460b820d737ca4a3eb805a4e2c9b1510f1a6ca
+  metadata.gz: fb37c0c8cf8bb5944459915e43549229d6db504b77538729cea721fa041f7266
+  data.tar.gz: d6900ff2d3cd7e2a821d4637d96beafa69cd8e656a31f2251b68d9e7a818cefb
 SHA512:
-  metadata.gz: 61cea9354aa1343b9db15e92a1a11c06f053158ed72a48c5d1062e4b7d733888a7a8eaf3b88c7696cb879b7a92d196891c01e85369947dd4dead497b322b69b9
-  data.tar.gz: fcf1db5f88479865c65ce64d7c788a3762ea01f39c28f10fa3604e268bce1737589cec4eb8b66f94a10f70a1acb12b7ab73b082990e0bc9a1a0c11d0461159d6
+  metadata.gz: 683f9af0342d287411cc79fd6b2acbf3ebae0d2bf408a282f2309b36a6f62e7478d51983d9ab86bb9c5b524ffe55ab0b445ac9c6b212bd628466adba84e0e249
+  data.tar.gz: 95286680a44cceede252bb0b9429ba321be66a895246986339dd261af30c0547f8f95726d36bfc85fc2da1e8333fad9141d3836f2659b0237ef39a56ea8f1f6a

data/.gitignore

@@ -1,2 +1,3 @@
 calcpace-*.gem
 !calcpace.gemspec
+improvements_plan.md

data/CHANGELOG.md

@@ -5,7 +5,40 @@ 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.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/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.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.7.0'
+gem 'calcpace', '~> 1.8.0'
 ```
 
 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/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,96 @@
+# 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
+  # Conversion factor: 1 mile = 1.60934 kilometers
+  MI_TO_KM = 1.60934
+  KM_TO_MI = 0.621371
+
+  # 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 * MI_TO_KM
+    when :mi_to_km
+      # If running at X seconds per mile, pace per km = X / (miles to km ratio)
+      pace_seconds * 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,208 @@
+# 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)
+    half_distance = total_distance / 2.0
+    avg_pace = target_seconds / total_distance
+
+    # First half: 4% slower, second half: 4% faster
+    first_half_pace = avg_pace * 1.04
+    second_half_pace = avg_pace * 0.96
+
+    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
+        # First half
+        cumulative_time = distance_covered * first_half_pace
+      else
+        # Second half
+        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
+
+  # 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)
+    half_distance = total_distance / 2.0
+    avg_pace = target_seconds / total_distance
+
+    # First half: 4% faster, second half: 4% slower
+    first_half_pace = avg_pace * 0.96
+    second_half_pace = avg_pace * 1.04
+
+    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
+        # First half
+        cumulative_time = distance_covered * first_half_pace
+      else
+        # Second half
+        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.0'
 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.0
 platform: ruby
 authors:
 - João Gilberto Saraiva
@@ -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: