calcpace 1.14.0 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3fb2c004f6564fef1686e1c92db831e7c54a47360dd9c540a90bb334582ee95
-  data.tar.gz: 31c20dd413fe2df72d57f7516bb613c7661724bba196ff81da3af3b2c17c0ee0
+  metadata.gz: 5eefef398417bfe2d045b2afd7ee78991b443c7c9bc1eabd536e81d03789908c
+  data.tar.gz: 7b676576e7e3af9b9d4ce75430af80835a35535b2c8b971ed5ef764ddd608853
 SHA512:
-  metadata.gz: 784831b687993538654becf398906fc798ff089e8344ed1cd8768f3b42735111b490f99f185b0535f09d84ad15b0d207703e49d494c6e61ca1c3311630016b9a
-  data.tar.gz: 3f4170b7d5a3c4f71ed40ab732fb02be5ea2f1daf494c179aedab9b63e1837b90631ebf8db8f1484e83fbd9b55b569b7c9db31f66d915ca3228dae745eb7d619
+  metadata.gz: 2b7481ff8c0c4b91f724af723eacfd9357905fa2207adc0871dd745d7fc4a4beac52349f0051703a91288c724dd2b6c00298beb585d08949b156833e9fc70af7
+  data.tar.gz: 7d58f1c452924bbc9c7a895a5ed5102e1ae298b002984d9708aea23b4f54f7339fa2b4dd6708b678cf5f1dd45d5cfd8cc8dd5c3e869df6b07856f08eaf6c720c

data/.rubocop.yml

@@ -80,3 +80,11 @@ Naming/MethodParameterName:
   AllowedNames:
     - _
     - e
+
+# The documented-examples test evaluates snippets scraped from our own README
+# and docstrings — that is the entire point of the file, and the cop's required
+# comment format cannot be satisfied without it then reporting the disable as
+# redundant.
+Style/DocumentDynamicEvalDefinition:
+  Exclude:
+    - 'test/calcpace/test_documented_examples.rb'

data/CHANGELOG.md

@@ -7,6 +7,130 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.15.0] - 2026-08-30
+
+### Added
+- Every method that takes a race now accepts a **plain distance in kilometers**,
+  not only one of the eight standard race names. Most races are not a 5K or a
+  marathon, and a formula does not care what a distance is called:
+
+  ```ruby
+  calc.race_time_clock('05:00', 7.79)                        # => "00:38:57"
+  calc.race_pace_clock('00:26:59', 7.79)                     # => "00:03:27"
+  calc.predict_time_clock(7.79, '00:26:59', 'half_marathon') # => "01:17:34"
+  calc.predict_time_clock('10k', '00:42:00', 15)             # => "01:04:33"
+  calc.predict_time_clock(7.79, '00:26:59', 15)              # => "00:54:02"
+  calc.predict_time_cameron_clock(7.79, '00:26:59', 'half_marathon') # => "01:13:44"
+  calc.race_splits(7.79, target_time: '00:26:59', split_distance: '1k')
+  # => ["00:03:28", "00:06:56", "00:10:23", "00:13:51", "00:17:19", "00:20:47", "00:24:15", "00:26:59"]
+  ```
+
+  Both ends of a prediction follow the same rule, so all four combinations work:
+  name to name, name to number, number to name, number to number. The methods
+  that reach a distance through `race_distance` inherit it: `race_time`,
+  `race_pace`, their `_clock` variants, `predict_time`, `predict_pace`,
+  `equivalent_performance`, the Cameron equivalents, the `_adjusted` variants,
+  `race_splits`, and `race_times_from_vo2max`.
+
+  A numeric **string** counts as a distance: `'7.79'` and `7.79` mean the same
+  thing. This is not a new convention — `training_paces_from_race` and
+  `predict_time_from_vo2max` have read numeric strings as distances since they
+  were written, and `race_distance` was the one place that disagreed. A string
+  that is not a number is still a race name, so `'7.79k'` remains
+  `ArgumentError: Unknown race`. Only `Numeric` and `String` are read as
+  distances; a Symbol is always a name, as in the two methods above.
+
+  A numeric distance must be positive, and reports itself the way every other
+  distance in the gem does:
+
+  ```ruby
+  calc.race_time(300, 0) # => Calcpace::NonPositiveInputError: Distance must be a positive number
+  ```
+
+  Before this release those calls raised `ArgumentError: Unknown race: 0`. The
+  input was an error either way; only the class and the message changed.
+
+### Breaking
+- **A non-positive distance now raises `Calcpace::NonPositiveInputError`
+  instead of `ArgumentError`.** Calls like `race_time(300, 0)` or
+  `race_splits('0', ...)` used to fail with `ArgumentError: Unknown race: 0`,
+  because `0` was not a race name; now `0` is read as a distance and rejected
+  as one. `Calcpace::NonPositiveInputError` inherits from `Calcpace::Error`,
+  **not** from `ArgumentError`, so a caller that wraps this library in
+  `rescue ArgumentError` — a form field arriving as `"0"`, for example — will
+  see the exception escape instead of being caught.
+  The alternative was to make this one path raise `ArgumentError` for
+  consistency with the old behaviour, which would have made the library
+  inconsistent with itself: every other non-positive input in the gem already
+  raises `NonPositiveInputError`. Wrapping in `rescue Calcpace::Error,
+  ArgumentError` handles both this and any future version.
+
+### Changed
+- The "from and to must be different distances" guard in `predict_time` and
+  `predict_time_cameron` no longer compares distances with `==`. Two distances
+  now count as the same race when they differ by less than
+  `PaceCalculator::SAME_DISTANCE_TOLERANCE_RATIO` (1e-9, relative), so a
+  distance that only differs by floating-point noise still raises instead of
+  returning a prediction of the same time back:
+
+  ```ruby
+  calc.predict_time(10.0, 2520, '10k')
+  # => ArgumentError: From and to races must be different distances (both are 10.0km)
+  ```
+
+  The window is deliberately narrow: it absorbs representation noise and
+  nothing else. `predict_time(10.0, 2520, 10.2)` is a legitimate 200 m
+  extrapolation and still answers.
+
+- Age grading matches a numeric distance to a standard within **2%**, up from
+  0.5% (`AgeGrading::STANDARD_DISTANCE_TOLERANCE_RATIO`, previously an
+  unnamed literal). GPS rarely reads a 5K as exactly 5.000 km, and 2% is the
+  window calcpace.app already uses to decide a run "is a 5K" — the two used to
+  disagree about the same run:
+
+  ```ruby
+  calc.age_grade_percent(5.0,    '00:25:00', age: 40, sex: :male) # => 51.9
+  calc.age_grade_percent(5.0374, '00:25:00', age: 40, sex: :male) # => 51.9
+  ```
+
+  Nothing else about age grading changed, on purpose. A distance outside the
+  window still raises, and that is the intended answer rather than a missing
+  feature: the WMA 2023 tables publish a factor per *specific* distance, so
+  there is no standard for 7.79 km to compare against, and interpolating one
+  would produce a number with the look of an official standard and none of the
+  authority.
+
+  ```ruby
+  calc.age_grade(7.79, '00:26:59', age: 36, sex: :male)
+  # => ArgumentError: Unsupported distance 7.79km. Supported: 5.0, 10.0, 21.0975, 42.195 km
+  ```
+
+  Riegel and Cameron both degrade as the jump between distances grows — a
+  marathon predicted from a 1 km time is arithmetic, not a forecast. This
+  release adds no guard against that: the gem never warned about it for the
+  standard race names either, and inventing a threshold now would be a new
+  opinion, not a fix. The note is here and in the README so the caller can
+  weigh it.
+
+### Fixed
+- Documentation only, no behavior change: several `@example` values in
+  `PaceCalculator`, `RacePredictor` and `CameronPredictor`, and their
+  counterparts in the README, had drifted from what the code returns — the
+  worst of them by more than six minutes (`predict_time_cameron_clock` was
+  documented as `'00:02:32'` where it returns `'00:04:15'`). Two `@example`
+  lines also used `:5k`, which is not valid Ruby syntax, and now use `'5k'`.
+- An adversarial review of this release found three more that the first pass
+  had missed, including the README block for `equivalent_performance` — which
+  contradicted the docstring corrected in this very release — and the main
+  age-grading example, wrong in four of its eight fields. Every example was
+  then executed and compared line by line, README and `@example` alike. The
+  lesson was acted on rather than recorded: `test_documented_examples.rb` now
+  executes every single-line example in the README and in the docstrings and
+  compares it with what the code returns, so a drifted example fails the suite
+  instead of reaching a reader. It pins two numbers — how many examples it
+  finds and how many it actually compares — because a scanner that silently
+  matches nothing would pass forever.
+
 ## [1.14.0] - 2026-08-29
 
 ### Added
@@ -381,7 +505,8 @@ predictors are untouched.
 
 See git history for changes in earlier versions.
 
-[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.14.0...HEAD
+[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.15.0...HEAD
+[1.15.0]: https://github.com/0jonjo/calcpace/compare/v1.14.0...v1.15.0
 [1.14.0]: https://github.com/0jonjo/calcpace/compare/v1.13.0...v1.14.0
 [1.13.0]: https://github.com/0jonjo/calcpace/compare/v1.12.1...v1.13.0
 [1.12.0]: https://github.com/0jonjo/calcpace/compare/v1.11.0...v1.12.0

data/README.md

@@ -22,7 +22,7 @@ calc = Calcpace.new
 ```ruby
 calc.velocity(3625, 12275)          # => 3.386  (distance / time)
 calc.pace(3665, 12)                 # => 305.4  (time / distance)
-calc.time(210, 12)                  # => 2520.0 (pace × distance)
+calc.time(210, 12)                  # => 2520   (pace × distance)
 calc.distance(9660, 120)            # => 80.5   (velocity × time)
 
 # Clocktime input/output (HH:MM:SS or MM:SS)
@@ -109,12 +109,24 @@ calc.convert_pace('05:00', :km_to_mi, compact: true)  # => "8:02"
 
 ### Race Pace & Time
 
+Every method that takes a race accepts either a standard race name or a plain
+distance in kilometers — most races are not a 5K or a marathon.
+
 ```ruby
 calc.race_time_clock('05:00', 'marathon')          # => "03:30:58"
 calc.race_pace_clock('04:00:00', 'marathon')       # => "00:05:41"
 calc.list_races  # => { '5k' => 5.0, '10k' => 10.0, 'half_marathon' => 21.0975, 'marathon' => 42.195, '100k' => 100.0, ... }
+
+# Any distance, named or not — 7.79 km and '7.79' mean the same thing
+calc.race_time_clock('05:00', 7.79)                # => "00:38:57"
+calc.race_time_clock('05:00', '7.79')              # => "00:38:57"
+calc.race_pace_clock('00:26:59', 7.79)             # => "00:03:27"
 ```
 
+A distance must be positive (`Calcpace::NonPositiveInputError` otherwise), and
+anything that is neither a number nor a known race name still raises
+`ArgumentError` — `'7.79k'` is a typo, not a distance.
+
 ---
 
 ### Race Splits
@@ -127,6 +139,10 @@ calc.race_splits('half_marathon', target_time: '01:30:00', split_distance: '5k')
 # Strategies: :even (default), :negative (second half faster), :positive (first half faster)
 calc.race_splits('10k', target_time: '00:40:00', split_distance: '5k', strategy: :negative)
 # => ["00:20:48", "00:40:00"]
+
+# The race may be a plain distance too; the last split is always the finish
+calc.race_splits(7.79, target_time: '00:26:59', split_distance: '1k')
+# => ["00:03:28", "00:06:56", "00:10:23", "00:13:51", "00:17:19", "00:20:47", "00:24:15", "00:26:59"]
 ```
 
 ---
@@ -139,16 +155,45 @@ calc.race_splits('10k', target_time: '00:40:00', split_distance: '5k', strategy:
 calc.predict_time_clock('5k', '00:20:00', 'marathon')   # => "03:11:49"
 calc.predict_pace_clock('5k', '00:20:00', 'marathon')   # => "00:04:32"
 calc.equivalent_performance('10k', '00:42:00', '5k')
-# => { time: 1209.0, time_clock: "00:20:09", pace: 241.8, pace_clock: "00:04:02" }
+# => { time: 1208.67, time_clock: "00:20:08", pace: 241.73, pace_clock: "00:04:01" }
 ```
 
 **Cameron formula** (exponential correction — tends to be more conservative from short distances):
 
 ```ruby
-calc.predict_time_cameron_clock('10k', '00:42:00', 'marathon')  # => "02:57:46"
-calc.predict_pace_cameron_clock('10k', '00:42:00', 'marathon')  # => "00:04:13"
+calc.predict_time_cameron_clock('10k', '00:42:00', 'marathon')  # => "02:57:34"
+calc.predict_pace_cameron_clock('10k', '00:42:00', 'marathon')  # => "00:04:12"
 ```
 
+**Any distance, on either end.** Both formulas are arithmetic on two distances,
+so neither end has to be a standard race:
+
+```ruby
+# From a 7.79 km club race in 26:59
+calc.predict_time_clock(7.79, '00:26:59', 'half_marathon')          # => "01:17:34"
+calc.predict_time_cameron_clock(7.79, '00:26:59', 'half_marathon')  # => "01:13:44"
+
+# To an unnamed distance, and between two of them
+calc.predict_time_clock('10k', '00:42:00', 15)    # => "01:04:33"
+calc.predict_time_clock(7.79, '00:26:59', 15)     # => "00:54:02"
+
+calc.equivalent_performance(7.79, '00:26:59', '10k')
+# => { time: 2109.682710043339, time_clock: "00:35:09", pace: 210.96827100433387, pace_clock: "00:03:30" }
+```
+
+Predicting a distance from itself has no answer, so it raises — for a name, a
+number, or one of each:
+
+```ruby
+calc.predict_time(10.0, 2520, '10k')
+# => ArgumentError: From and to races must be different distances (both are 10.0km)
+```
+
+Both formulas were fitted around race distances and degrade as the jump grows:
+a marathon predicted from a 1 km time is arithmetic, not a forecast. The gem
+computes what you ask for and does not second-guess the gap — that judgement is
+the caller's, and it always was, standard race names included.
+
 ---
 
 ### GPS Track Analysis
@@ -202,22 +247,40 @@ age factors and open standards.
 result = calc.age_grade(10.0, '00:45:00', age: 55, sex: :male)
 # numeric distances also accepted in miles: calc.age_grade(6.21371, '00:45:00', age: 55, sex: :male, distance_unit: :mi)
 # => {
-#      age_grade_percent: 64.6,
+#      age_grade_percent: 69.0,
 #      category: "Local Class",
-#      age_graded_time_seconds: 2376.0,
-#      age_graded_time_clock: "00:39:36",
+#      age_graded_time_seconds: 2278.26,
+#      age_graded_time_clock: "00:37:58",
 #      open_standard_seconds: 1571.0,
 #      open_standard_clock: "00:26:11",
-#      factor: 0.88,
+#      factor: 0.8438,
 #      table_version: "WMA_2023_ONE_YEAR_FACTORS_V1"
 #    }
 
-calc.age_grade_percent(5.0, '00:22:30', age: 40, sex: :female) # => 74.1
-calc.age_grade_label(74.1)                                      # => "Regional Class"
+calc.age_grade_percent(5.0, '00:22:30', age: 40, sex: :female) # => 65.2
+calc.age_grade_label(65.2)                                      # => "Local Class"
 ```
 
 Supported distances: 5K, 10K, half marathon, marathon.
 
+A numeric distance within **2%** of one of those is graded as that standard —
+a GPS watch rarely reads a 5K as exactly 5.000 km:
+
+```ruby
+calc.age_grade_percent(5.0,    '00:25:00', age: 40, sex: :male) # => 51.9
+calc.age_grade_percent(5.0374, '00:25:00', age: 40, sex: :male) # => 51.9
+
+calc.age_grade(7.79, '00:26:59', age: 36, sex: :male)
+# => ArgumentError: Unsupported distance 7.79km. Supported: 5.0, 10.0, 21.0975, 42.195 km
+```
+
+That refusal is deliberate, and it is where age grading parts ways with the
+predictors above. A prediction is a formula and works at any distance; an age
+grade is a lookup in the WMA table, which publishes a factor per *specific*
+distance. There is no world standard for 7.79 km, so there is no honest
+percentage to return — interpolating one would produce a number with the look
+of an official standard and none of the authority.
+
 Age factors are based on WMA 2023 one-year age grading tables:
 https://world-masters-athletics.org/documents/competition-rules/
 
@@ -238,7 +301,7 @@ Estimate aerobic fitness from a race result using the **Daniels & Gilbert formul
 
 ```ruby
 calc.estimate_vo2max(10.0, '00:40:00')   # => 51.9 ml/kg/min
-calc.estimate_vo2max(42.195, '03:30:00') # => 44.8
+calc.estimate_vo2max(42.195, '03:30:00') # => 44.6
 calc.estimate_vo2max(5.0, 2400)          # also accepts total seconds
 calc.estimate_vo2max(6.21371, '00:40:00', distance_unit: :mi)  # => 51.9 (miles input)
 

data/lib/calcpace/age_grading.rb

@@ -47,6 +47,15 @@ module AgeGrading
 
   SUPPORTED_DISTANCES_KM = DISTANCE_TO_METERS.keys.freeze
 
+  # How far a distance may sit from a standard and still be graded as it. 2% is
+  # the same window calcpace.app uses to decide a run "is a 5K", so the gem and
+  # the site never disagree about the same run. It stays a matching tolerance,
+  # not an interpolation: a distance outside it has no WMA factor and is refused
+  STANDARD_DISTANCE_TOLERANCE_RATIO = 0.02
+
+  # Floor for the window above, so a future shorter standard still matches
+  MINIMUM_DISTANCE_TOLERANCE_KM = 0.001
+
   # Returns a full age-grading report for a race performance
   #
   # @param distance [Numeric, String, Symbol] race distance in kilometres
@@ -145,10 +154,11 @@ module AgeGrading
     end
   end
 
-  # Runners write rounded distances (3.1 mi, 13.1 mi, 26.2 mi), so the match
-  # window is relative — 0.5% of the standard distance, never below 1 metre
+  # Runners write rounded distances (3.1 mi, 13.1 mi, 26.2 mi) and GPS watches
+  # rarely read a 5K as exactly 5.000 km, so the match window is relative
   def standard_distance?(distance, standard)
-    (distance - standard).abs <= [0.001, standard * 0.005].max
+    (distance - standard).abs <= [MINIMUM_DISTANCE_TOLERANCE_KM,
+                                  standard * STANDARD_DISTANCE_TOLERANCE_RATIO].max
   end
 
   def parse_time_seconds(time)

data/lib/calcpace/cameron_predictor.rb

@@ -24,27 +24,26 @@ module CameronPredictor
 
   # Predicts race time using the Cameron formula
   #
-  # @param from_race [String, Symbol] known race distance ('5k', '10k', 'half_marathon', 'marathon', '100k', etc.)
+  # @param from_race [Numeric, String, Symbol] known distance in kilometers (7.79,
+  #   '7.79') or a standard race name ('5k', '10k', 'half_marathon', 'marathon', '100k', 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
+  # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @return [Float] predicted time in seconds
-  # @raise [ArgumentError] if races are invalid or distances are the same
+  # @raise [ArgumentError] if a race name is invalid or the distances are the same
+  # @raise [Calcpace::NonPositiveInputError] if a numeric distance is not positive
   #
   # @example Predict marathon time from 10K
   #   predict_time_cameron('10k', '00:42:00', 'marathon')
-  #   #=> ~10,666 seconds (approximately 2:57:46)
+  #   #=> ~10,654 seconds (approximately 2:57:34)
   #
   # @example Predict 10K time from 5K
   #   predict_time_cameron('5k', '00:20:00', '10k')
-  #   #=> ~2,544 seconds (approximately 42:24)
+  #   #=> ~2,546 seconds (approximately 42:26)
   def predict_time_cameron(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
+    ensure_different_distances!(from_distance, to_distance)
 
     time_seconds = from_time.is_a?(String) ? convert_to_seconds(from_time) : from_time
     check_positive(time_seconds, 'Time')
@@ -56,23 +55,23 @@ module CameronPredictor
 
   # Predicts race time using the Cameron formula, returned as a clock time string
   #
-  # @param from_race [String, Symbol] known race distance
+  # @param from_race [Numeric, String, Symbol] known distance in kilometers or race name
   # @param from_time [String, Numeric] time achieved at known distance
-  # @param to_race [String, Symbol] target race distance to predict
+  # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @return [String] predicted time in HH:MM:SS format
   #
   # @example
   #   predict_time_cameron_clock('10k', '00:42:00', 'marathon')
-  #   #=> '02:57:46'
+  #   #=> '02:57:34'
   def predict_time_cameron_clock(from_race, from_time, to_race)
     convert_to_clocktime(predict_time_cameron(from_race, from_time, to_race))
   end
 
   # Predicts pace per kilometer using the Cameron formula
   #
-  # @param from_race [String, Symbol] known race distance
+  # @param from_race [Numeric, String, Symbol] known distance in kilometers or race name
   # @param from_time [String, Numeric] time achieved at known distance
-  # @param to_race [String, Symbol] target race distance to predict
+  # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @return [Float] predicted pace in seconds per kilometer
   #
   # @example
@@ -84,23 +83,23 @@ module CameronPredictor
 
   # Predicts pace per kilometer using the Cameron formula, returned as a clock time string
   #
-  # @param from_race [String, Symbol] known race distance
+  # @param from_race [Numeric, String, Symbol] known distance in kilometers or race name
   # @param from_time [String, Numeric] time achieved at known distance
-  # @param to_race [String, Symbol] target race distance to predict
+  # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @return [String] predicted pace in HH:MM:SS format
   #
   # @example
   #   predict_pace_cameron_clock('5k', '00:20:00', 'marathon')
-  #   #=> '00:02:32'
+  #   #=> '00:04:15'
   def predict_pace_cameron_clock(from_race, from_time, to_race)
     convert_to_clocktime(predict_pace_cameron(from_race, from_time, to_race))
   end
 
   # Predicts race time adjusted for environmental conditions using Cameron formula
   #
-  # @param from_race [String, Symbol] known race distance
+  # @param from_race [Numeric, String, Symbol] known distance in kilometers or race name
   # @param from_time [String, Numeric] time achieved at known distance
-  # @param to_race [String, Symbol] target race distance to predict
+  # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @param options [Hash] environmental options (temperature, altitude, etc.)
   # @return [Hash] hash with adjusted prediction and penalty details
   def predict_time_cameron_adjusted(from_race, from_time, to_race, **)

data/lib/calcpace/pace_calculator.rb

@@ -17,15 +17,22 @@ module PaceCalculator
     '10mile' => 10 * Converter::Distance::MI_TO_KM
   }.freeze
 
+  # Relative window under which two distances count as the same race. It exists
+  # only to absorb floating-point noise, never to call two different distances
+  # equal — 10.0 km and 10.2 km are a legitimate prediction, not a mistake
+  SAME_DISTANCE_TOLERANCE_RATIO = 1e-9
+
   # 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', '100k')
+  # @param race [Numeric, String, Symbol] distance in kilometers (7.79, '7.79') or a
+  #   standard race name ('5k', '10k', 'half_marathon', 'marathon', '100k', ...)
   # @return [Float] total time in seconds
-  # @raise [ArgumentError] if race distance is not recognized
+  # @raise [ArgumentError] if a race name is not recognized
+  # @raise [Calcpace::NonPositiveInputError] if a numeric distance is not positive
   #
   # @example
-  #   race_time(300, :5k)           #=> 1500.0 (5:00/km pace for 5K = 25:00)
+  #   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)
@@ -37,12 +44,13 @@ module PaceCalculator
   # 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', '100k')
+  # @param race [Numeric, String, Symbol] distance in kilometers (7.79, '7.79') or a
+  #   standard race name ('5k', '10k', 'half_marathon', 'marathon', '100k', ...)
   # @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'
+  #   race_time_clock(300, :half_marathon) #=> '01:45:29'
   def race_time_clock(pace_per_km, race)
     convert_to_clocktime(race_time(pace_per_km, race))
   end
@@ -50,12 +58,13 @@ module PaceCalculator
   # 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', '100k')
+  # @param race [Numeric, String, Symbol] distance in kilometers (7.79, '7.79') or a
+  #   standard race name ('5k', '10k', 'half_marathon', 'marathon', '100k', ...)
   # @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)
+  #   race_pace('03:30:00', :marathon)    #=> 298.61... (4:58/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
@@ -66,11 +75,12 @@ module PaceCalculator
   # 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', '100k')
+  # @param race [Numeric, String, Symbol] distance in kilometers (7.79, '7.79') or a
+  #   standard race name ('5k', '10k', 'half_marathon', 'marathon', '100k', ...)
   # @return [String] required pace in MM:SS format
   #
   # @example
-  #   race_pace_clock('03:30:00', :marathon) #=> '00:04:57'
+  #   race_pace_clock('03:30:00', :marathon) #=> '00:04:58'
   def race_pace_clock(target_time, race)
     convert_to_clocktime(race_pace(target_time, race))
   end
@@ -87,18 +97,61 @@ module PaceCalculator
 
   private
 
-  # Gets the distance for a standard race
+  # Resolves a race argument to a distance in kilometers
+  #
+  # A standard race name resolves through RACE_DISTANCES; a distance resolves
+  # to itself. Numeric strings ('7.79') count as distances — the convention
+  # TrainingZones#training_paces_from_race and FitnessPredictor already follow,
+  # so 7.79 and '7.79' can never mean two different things.
   #
-  # @param race [String, Symbol] race name
+  # @param race [Numeric, String, Symbol] race name or distance in kilometers
   # @return [Float] distance in kilometers
-  # @raise [ArgumentError] if race is not recognized
+  # @raise [ArgumentError] if a race name is not recognized
+  # @raise [Calcpace::NonPositiveInputError] if a numeric distance is not positive
   def race_distance(race)
+    numeric = numeric_distance(race)
+    return numeric if numeric
+
     RACE_DISTANCES.fetch(normalize_race_key(race)) do
       raise ArgumentError,
             "Unknown race: #{race}. Available races: #{RACE_DISTANCES.keys.join(', ')}"
     end
   end
 
+  # Reads a race argument as a plain distance, or nil when it is a race name
+  #
+  # @param race [Numeric, String, Symbol] race name or distance in kilometers
+  # @return [Float, nil] the distance in kilometers, nil for a non-numeric input
+  # @raise [Calcpace::NonPositiveInputError] if the distance is not positive
+  def numeric_distance(race)
+    value = race.is_a?(Numeric) ? race.to_f : Float(race, exception: false)
+    return nil unless value
+
+    check_positive(value, 'Distance')
+    value
+  end
+
+  # Guards the "predict a distance from itself" call, which has no answer to give
+  #
+  # @param from_distance [Float] known distance in kilometers
+  # @param to_distance [Float] target distance in kilometers
+  # @raise [ArgumentError] if both distances are the same race
+  def ensure_different_distances!(from_distance, to_distance)
+    return unless same_distance?(from_distance, to_distance)
+
+    raise ArgumentError,
+          "From and to races must be different distances (both are #{from_distance}km)"
+  end
+
+  # Two distances are the same race only when they differ by representation
+  # noise — a window narrow enough that any distance a runner actually types is
+  # outside it. Deciding when two genuinely different distances are close
+  # enough to count as the same race is age grading's business, and it has its
+  # own, much wider, explicit tolerance
+  def same_distance?(one, other)
+    (one - other).abs <= [one.abs, other.abs].max * SAME_DISTANCE_TOLERANCE_RATIO
+  end
+
   # Single normalization for every race-name lookup in the gem (here and in
   # AgeGrading), so ' 10K ' and :marathon always resolve like '10k' and 'marathon'
   #

data/lib/calcpace/race_predictor.rb

@@ -19,27 +19,26 @@ module RacePredictor
   # - 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', '100k', etc.)
+  # @param from_race [Numeric, String, Symbol] known distance in kilometers (7.79,
+  #   '7.79') or a standard race name ('5k', '10k', 'half_marathon', 'marathon', '100k', 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
+  # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @return [Float] predicted time in seconds
-  # @raise [ArgumentError] if races are invalid or distances are the same
+  # @raise [ArgumentError] if a race name is invalid or the distances are the same
+  # @raise [Calcpace::NonPositiveInputError] if a numeric distance is not positive
   #
   # @example Predict marathon time from 5K
   #   predict_time('5k', '00:20:00', 'marathon')
-  #   #=> 11123.4 (approximately 3:05:23)
+  #   #=> 11509.32 (approximately 3:11:49)
   #
   # @example Predict 10K time from half marathon
   #   predict_time('half_marathon', '01:30:00', '10k')
-  #   #=> 2565.8 (approximately 42:46)
+  #   #=> 2447.42 (approximately 40:47)
   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
+    ensure_different_distances!(from_distance, to_distance)
 
     time_seconds = from_time.is_a?(String) ? convert_to_seconds(from_time) : from_time
     check_positive(time_seconds, 'Time')
@@ -50,14 +49,14 @@ module RacePredictor
 
   # Predicts race time and returns it as a clock time string
   #
-  # @param from_race [String, Symbol] known race distance
+  # @param from_race [Numeric, String, Symbol] known distance in kilometers or race name
   # @param from_time [String, Numeric] time achieved at known distance
-  # @param to_race [String, Symbol] target race distance to predict
+  # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @return [String] predicted time in HH:MM:SS format
   #
   # @example
   #   predict_time_clock('5k', '00:20:00', 'marathon')
-  #   #=> '03:05:23'
+  #   #=> '03:11:49'
   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)
@@ -65,14 +64,14 @@ module RacePredictor
 
   # Predicts the pace per kilometer for a target race
   #
-  # @param from_race [String, Symbol] known race distance
+  # @param from_race [Numeric, String, Symbol] known distance in kilometers or race name
   # @param from_time [String, Numeric] time achieved at known distance
-  # @param to_race [String, Symbol] target race distance to predict
+  # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @return [Float] predicted pace in seconds per kilometer
   #
   # @example
   #   predict_pace('5k', '00:20:00', 'marathon')
-  #   #=> 263.6 (approximately 4:24/km)
+  #   #=> 272.77 (approximately 4:32/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)
@@ -81,14 +80,14 @@ module RacePredictor
 
   # Predicts the pace per kilometer and returns it as a clock time string
   #
-  # @param from_race [String, Symbol] known race distance
+  # @param from_race [Numeric, String, Symbol] known distance in kilometers or race name
   # @param from_time [String, Numeric] time achieved at known distance
-  # @param to_race [String, Symbol] target race distance to predict
+  # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @return [String] predicted pace in MM:SS format
   #
   # @example
   #   predict_pace_clock('5k', '00:20:00', 'marathon')
-  #   #=> '00:04:24' (4:24/km)
+  #   #=> '00:04:32' (4:32/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)
@@ -99,18 +98,18 @@ module RacePredictor
   # 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_race [Numeric, String, Symbol] known distance in kilometers or race name
   # @param from_time [String, Numeric] time achieved at known distance
-  # @param to_race [String, Symbol] target race distance for comparison
+  # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @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"
+  #         time: 1208.67,
+  #         time_clock: "00:20:08",
+  #         pace: 241.73,
+  #         pace_clock: "00:04:01"
   #       }
   def equivalent_performance(from_race, from_time, to_race)
     predicted_time = predict_time(from_race, from_time, to_race)
@@ -126,9 +125,9 @@ module RacePredictor
 
   # Predicts race time adjusted for environmental conditions
   #
-  # @param from_race [String, Symbol] known race distance
+  # @param from_race [Numeric, String, Symbol] known distance in kilometers or race name
   # @param from_time [String, Numeric] time achieved at known distance
-  # @param to_race [String, Symbol] target race distance to predict
+  # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @param options [Hash] environmental options:
   #   - :temperature [Numeric]
   #   - :temperature_unit [Symbol, String] :c or :f
@@ -137,7 +136,7 @@ module RacePredictor
   #
   # @example Predict marathon time from 5K adjusted for heat (25C)
   #   predict_time_adjusted('5k', '00:20:00', 'marathon', temperature: 25)
-  #   #=> { adjusted_time: 12213.4, penalty_percent: 6.0, ... }
+  #   #=> { adjusted_time: 13140.19, penalty_percent: 14.17, ... }
   def predict_time_adjusted(from_race, from_time, to_race, **)
     predicted_seconds = predict_time(from_race, from_time, to_race)
     adjust_time(predicted_seconds, **)

data/lib/calcpace/race_splits.rb

@@ -7,16 +7,18 @@
 module RaceSplits
   # Calculates split times for a race
   #
-  # @param race [String, Symbol] race distance ('5k', '10k', 'half_marathon', 'marathon', '100k', etc.)
+  # @param race [Numeric, String, Symbol] distance in kilometers (7.79, '7.79') or a
+  #   standard race name ('5k', '10k', 'half_marathon', 'marathon', '100k', 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
+  # @raise [ArgumentError] if a race or split_distance name is invalid
+  # @raise [Calcpace::NonPositiveInputError] if a numeric distance is not positive
   #
   # @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"]
+  #   #=> ["00:21:20", "00:42:40", "01:03:59", "01:25:19", "01:30:00"]
   #
   # @example Negative splits (second half faster)
   #   race_splits('10k', target_time: '00:40:00', split_distance: '5k', strategy: :negative)
@@ -48,8 +50,9 @@ module RaceSplits
       # 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
+      rescue ArgumentError, Calcpace::NonPositiveInputError
+        # Not a usable race distance, try to parse as numeric so that the split
+        # rules below (positive, not longer than the race) report the problem
       end
 
       # Try to parse as number with optional 'k' or 'km'
@@ -68,7 +71,8 @@ module RaceSplits
   #
   # @param split_km [Float] split distance in kilometers
   # @param total_distance [Float] total race distance in kilometers
-  # @raise [ArgumentError] if split distance is invalid
+  # @raise [ArgumentError] if a split distance name is invalid
+  # @raise [Calcpace::NonPositiveInputError] if a numeric split distance is not positive
   def validate_split_distance(split_km, total_distance)
     raise ArgumentError, "Split distance must be positive" if split_km <= 0
 

data/lib/calcpace/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.14.0
+  version: 1.15.0
 platform: ruby
 authors:
 - João Gilberto Saraiva