calcpace 1.6.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d05362249daa1675ba18bb4f6dfc65b79d3380787d451e64b55bc436e3952381
-  data.tar.gz: 3374e54393bb54e443c9feb610e05caf36842d5d1c1d5ceb3e517bc79022f6ef
+  metadata.gz: fb37c0c8cf8bb5944459915e43549229d6db504b77538729cea721fa041f7266
+  data.tar.gz: d6900ff2d3cd7e2a821d4637d96beafa69cd8e656a31f2251b68d9e7a818cefb
 SHA512:
-  metadata.gz: bb5a709698a85d9169ec683a47992eb2dfaf4dfdad430ef4a949b525896378814061a7f31a8f906f7475ff39c141e51e939a5847178baea87e1be9a69cc3015a
-  data.tar.gz: af509b94cb168456939af0329bcc93ee7c7cd0bdb95a8951c34267cfb175681f72ae02c8191671203feb988f30f89d673ef32bb87c197712c960a5febdc4a25b
+  metadata.gz: 683f9af0342d287411cc79fd6b2acbf3ebae0d2bf408a282f2309b36a6f62e7478d51983d9ab86bb9c5b524ffe55ab0b445ac9c6b212bd628466adba84e0e249
+  data.tar.gz: 95286680a44cceede252bb0b9429ba321be66a895246986339dd261af30c0547f8f95726d36bfc85fc2da1e8333fad9141d3836f2659b0237ef39a56ea8f1f6a

data/.gitignore

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

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/CHANGELOG.md

@@ -0,0 +1,81 @@
+# 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.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
+- 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.6.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.6.0'
+gem 'calcpace', '~> 1.8.0'
 ```
 
 Then run:
@@ -131,6 +131,183 @@ 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
+- `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
 
 Calcpace also provides other useful methods:
@@ -139,7 +316,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
 ```
 

data/calcpace.gemspec

@@ -15,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,7 +1,21 @@
 # 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: time, distance: distance })
     distance.to_f / time
@@ -16,6 +30,15 @@ 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: time, distance: distance })
     time.to_f / distance

data/lib/calcpace/checker.rb

@@ -2,8 +2,22 @@
 
 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
+  # 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?
 
@@ -11,10 +25,28 @@ module Checker
           "#{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,34 +54,77 @@ 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, '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
 
+  # 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(unit.to_s.upcase)
+    begin
+      Speed.const_get(unit.to_s.upcase)
+    rescue NameError
+      raise Calcpace::UnsupportedUnitError, unit
+    end
   end
 
   def list_all

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,101 @@
+# 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,
+    '1mile' => 1.60934,
+    '5mile' => 8.04672,
+    '10mile' => 16.0934
+  }.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/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.6.0'
+  VERSION = '1.8.0'
 end

data/lib/calcpace.rb

@@ -3,13 +3,45 @@
 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'
+require_relative 'calcpace/pace_converter'
+require_relative 'calcpace/race_predictor'
+require_relative 'calcpace/race_splits'
 
-# 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
+  include PaceConverter
+  include RacePredictor
+  include RaceSplits
 
-  def initialize; end
+  # Creates a new Calcpace instance
+  #
+  # @return [Calcpace] a new instance ready to perform calculations
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.8.0
 platform: ruby
 authors:
 - João Gilberto Saraiva
@@ -19,8 +19,10 @@ extra_rdoc_files: []
 files:
 - ".github/workflows/tests.yml"
 - ".gitignore"
+- ".rubocop.yml"
 - ".ruby-version"
 - ".tool-versions"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - README.md
@@ -30,7 +32,12 @@ 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/pace_converter.rb
+- lib/calcpace/race_predictor.rb
+- lib/calcpace/race_splits.rb
 - lib/calcpace/version.rb
 homepage: https://github.com/0jonjo/calcpace
 licenses:
@@ -38,6 +45,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