calcpace 1.13.0 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76b9c7242a528134ed36832a7be8fc3e83ccb65fc7e139232d2987a78116498b
-  data.tar.gz: f87752c75360bfa9dca40ae93bfdeaafc1522f7592d9ba3ca236cd9fb1d63a56
+  metadata.gz: 5eefef398417bfe2d045b2afd7ee78991b443c7c9bc1eabd536e81d03789908c
+  data.tar.gz: 7b676576e7e3af9b9d4ce75430af80835a35535b2c8b971ed5ef764ddd608853
 SHA512:
-  metadata.gz: 63421f8934eb0c94aa0713056fb6014ee7fa1ef7e1f611d16477ab3c84fb9235909b4f2e82e0e6e38a59d66ce801d109a76215ffbe08dddafd19523330327172
-  data.tar.gz: 9754c81c00f31f76e0250ebd0388dd7779cac95312513945364fc8f3efe914efd2f871c47afda9afbe442fdcc68d0c1eee3454348119bbd998f168c258af449c
+  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,186 @@ 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
+- `compact:` keyword on every pace-producing method, so a caller can ask for the
+  display format `convert_to_clocktime(compact: true)` introduced in 1.13.0
+  without reformatting the string itself
+  - `convert_pace(pace, conversion, compact: false)`
+  - `pace_km_to_mi(pace_per_km, compact: false)`
+  - `pace_mi_to_km(pace_per_mi, compact: false)`
+  - `track_splits(points, split_km = 1.0, compact: false)` — only the `:pace`
+    value changes; `:km` and `:elapsed` are numbers and stay as they are
+
+  ```ruby
+  calc.pace_km_to_mi('05:00')                # => "00:08:02"
+  calc.pace_km_to_mi('05:00', compact: true) # => "8:02"
+  calc.track_splits(points, 1.0, compact: true)
+  # => [{ km: 1.0, elapsed: 312, pace: "5:12" }, ...]
+  ```
+
+  The default stays `compact: false` everywhere, byte-for-byte the previous
+  output — the one exception is the negative-split fix below, which corrects a
+  value that was arithmetically wrong. Input validation is untouched:
+  a zero or negative pace still raises `Calcpace::NonPositiveInputError` and an
+  unknown conversion still raises `ArgumentError` in both modes.
+
+  Three places the two formats disagree about more than padding, all of them
+  now reachable through the pace APIs:
+
+  - A split pace slower than an hour per unit: the padded format keeps counting
+    minutes (`"66:33"`), as `track_splits` always has, while the compact one
+    rolls them into an hour field (`"1:06:33"`), consistent with every other
+    compact duration in the gem. Past 24 hours per unit the gap widens —
+    `"2248:18"` padded against `"37:28:18"` compact.
+  - Durations past 24 hours, the day-prefix rule 1.13.0 documented for
+    `convert_to_clocktime` alone, now visible through `convert_pace` too:
+    `convert_pace(100_000, :km_to_mi)` #=> `"1 20:42:14"`, against
+    `"44:42:14"` compact.
+  - A negative split (see Fixed below), signed in both formats but padded to a
+    different width: `"-00:40"` against `"-0:40"`.
+
+### Fixed
+- `track_splits` no longer misreports a negative split pace. A GPS track can
+  step backwards in time — a watch resyncing its clock, a device paused and
+  restarted, two segments merged out of order — which makes a split's elapsed
+  time negative. The padded format rendered that through Ruby's floor division,
+  so a −40 s split printed as `"-1:20"`; it now prints `"-00:40"`, and the
+  compact format prints `"-0:40"`. Neither mode raises: bad GPS data has always
+  been reported rather than blown up, and `compact: true` does not change that.
+- `convert_pace`, `pace_km_to_mi` and `pace_mi_to_km` documented their return
+  value as `'08:02'` when they have always returned the padded `'00:08:02'`.
+  The docs now match the code; the code is unchanged.
+- README and YARD examples for `track_distance`, `haversine_distance` and
+  `track_splits` printed numbers their own input never produced (`0.87` km for
+  a 1.51 km track, a `"05:12"` split for a `"06:55"` one). Every example is now
+  the real output of the code above it.
+
 ## [1.13.0] - 2026-08-28
 
 ### Added
@@ -325,7 +505,9 @@ predictors are untouched.
 
 See git history for changes in earlier versions.
 
-[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.13.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
 [1.11.0]: https://github.com/0jonjo/calcpace/compare/v1.10.0...v1.11.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)
@@ -93,18 +93,40 @@ See all units: `calc.list_all`, `calc.list_distance`, `calc.list_speed`.
 ```ruby
 calc.pace_km_to_mi('05:00')   # => "00:08:02"
 calc.pace_mi_to_km('08:00')   # => "00:04:58"
+calc.convert_pace(300, :km_to_mi)  # => "00:08:02"
+```
+
+All three take a `compact:` keyword for the display format a runner reads on a
+screen, the same one `convert_to_clocktime` offers:
+
+```ruby
+calc.pace_km_to_mi('05:00', compact: true)         # => "8:02"
+calc.pace_mi_to_km(480, compact: true)             # => "4:58"
+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
@@ -117,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"]
 ```
 
 ---
@@ -129,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
@@ -152,12 +207,33 @@ points = [
   { lat: -23.5520, lon: -46.6480, ele: 758.0, time: Time.parse('2024-01-01 07:10:00') },
 ]
 
-calc.haversine_distance(-23.5505, -46.6333, -23.5510, -46.6340)  # => 0.089 km
-calc.track_distance(points)    # => 0.87 km
-calc.elevation_gain(points)    # => { gain: 5.0, loss: 7.0 }
-calc.track_splits(points, 1.0) # => [{ km: 1, elapsed: 312, pace: "05:12" }, ...]
+calc.haversine_distance(-23.5505, -46.6333, -23.5510, -46.6340)
+# => 0.09045636644035066 (km)
+
+calc.track_distance(points)  # => 1.51 (km)
+calc.elevation_gain(points)  # => { gain: 5.0, loss: 7.0 }
+
+calc.track_splits(points, 1.0)
+# => [{ km: 1.0, elapsed: 415, pace: "06:55" },
+#     { km: 1.51, elapsed: 600, pace: "06:04" }]
+
+# Compact pace for display; :km and :elapsed are unchanged
+calc.track_splits(points, 1.0, compact: true)
+# => [{ km: 1.0, elapsed: 415, pace: "6:55" },
+#     { km: 1.51, elapsed: 600, pace: "6:04" }]
 ```
 
+The last entry is the partial split — the leftover distance after the last full
+one, so its `:km` is the track total rather than a multiple of `split_km`.
+
+Two things to know about `compact:` here. A split slower than an hour per unit
+is where the formats stop differing by padding alone: the padded one keeps
+counting minutes (`"66:33"`), as `track_splits` always has, while the compact
+one rolls them into an hour field (`"1:06:33"`). And a track that steps
+backwards in time — a watch resyncing its clock, a paused device, two segments
+merged out of order — produces a negative split, reported with a leading minus
+in both formats (`"-00:40"` / `"-0:40"`) rather than raising.
+
 **Haversine formula** — great-circle distance on a sphere (R = 6,371 km). Accuracy: ~0.3% of GPS/WGS84. Best for running and cycling distances; not for geodetic surveying.
 
 ---
@@ -171,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/
 
@@ -207,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)
 
@@ -382,6 +476,10 @@ prefixes a day count (`"1 03:46:40"`). Fractional seconds truncate in both.
 A negative number of seconds raises `Calcpace::NonPositiveInputError`; zero is a
 valid duration (`"00:00:00"` / `"0:00"`).
 
+The same `compact:` keyword is accepted by `convert_pace`, `pace_km_to_mi`,
+`pace_mi_to_km`, and `track_splits`. It always defaults to `false`, so every
+call without it returns exactly what it returned before.
+
 ---
 
 ### Errors

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/pace_converter.rb

@@ -7,48 +7,61 @@
 module PaceConverter
   # Converts pace from one unit to another
   #
+  # The pace comes back in the same two formats #convert_to_clocktime offers:
+  # the padded HH:MM:SS by default, and the compact display format a runner
+  # reads on a screen with <tt>compact: true</tt>.
+  #
   # @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
+  # @param compact [Boolean] when true, return the compact display format
+  # @return [String] converted pace in HH:MM:SS format, or 'M:SS' / 'H:MM:SS' with compact: true
   # @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)
+  # @example padded (default)
+  #   convert_pace('05:00', :km_to_mi)    #=> '00:08:02' (5:00/km = 8:02/mi)
+  #   convert_pace('08:00', :mi_to_km)    #=> '00:04:58' (8:00/mi ≈ 4:58/km)
+  #   convert_pace(300, 'km to mi')       #=> '00:08:02' (300s/km = 482s/mi)
+  #
+  # @example compact
+  #   convert_pace('05:00', :km_to_mi, compact: true)  #=> '8:02'
+  #   convert_pace(300, 'km to mi', compact: true)     #=> '8:02'
+  def convert_pace(pace, conversion, compact: false)
     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)
+    convert_to_clocktime(converted_seconds, compact: compact)
   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
+  # @param compact [Boolean] when true, return the compact display format
+  # @return [String] pace per mile in HH:MM:SS format, or 'M:SS' / 'H:MM:SS' with compact: true
   #
   # @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)
+  #   pace_km_to_mi('05:00')                #=> '00:08:02' (5:00/km = 8:02/mi)
+  #   pace_km_to_mi(300)                    #=> '00:08:02' (300s/km = 482s/mi)
+  #   pace_km_to_mi('05:00', compact: true) #=> '8:02'
+  def pace_km_to_mi(pace_per_km, compact: false)
+    convert_pace(pace_per_km, :km_to_mi, compact: compact)
   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
+  # @param compact [Boolean] when true, return the compact display format
+  # @return [String] pace per kilometer in HH:MM:SS format, or 'M:SS' / 'H:MM:SS' with compact: true
   #
   # @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)
+  #   pace_mi_to_km('08:00')                #=> '00:04:58' (8:00/mi ≈ 4:58/km)
+  #   pace_mi_to_km(480)                    #=> '00:04:58' (480s/mi = 298s/km)
+  #   pace_mi_to_km('08:00', compact: true) #=> '4:58'
+  def pace_mi_to_km(pace_per_mi, compact: false)
+    convert_pace(pace_per_mi, :mi_to_km, compact: compact)
   end
 
   private

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/track_calculator.rb

@@ -14,7 +14,7 @@
 #     { lat: -23.5510, lon: -46.6340 },
 #     { lat: -23.5520, lon: -46.6350 }
 #   ]
-#   calc.track_distance(points) #=> 0.17 (km)
+#   calc.track_distance(points) #=> 0.24 (km)
 #
 # @example Calculate elevation gain and loss
 #   points = [
@@ -49,7 +49,7 @@ module TrackCalculator
   #
   # @example Distance between two points in São Paulo
   #   haversine_distance(-23.5505, -46.6333, -23.5510, -46.6340)
-  #   #=> 0.089 (km)
+  #   #=> 0.09045636644035066 (km)
   def haversine_distance(lat1, lon1, lat2, lon2)
     validate_coordinates(lat1, lon1)
     validate_coordinates(lat2, lon2)
@@ -69,7 +69,7 @@ module TrackCalculator
   #     { lat: -23.5510, lon: -46.6340 },
   #     { lat: -23.5520, lon: -46.6350 }
   #   ]
-  #   track_distance(points) #=> 0.17
+  #   track_distance(points) #=> 0.24
   def track_distance(points)
     return 0.0 if points.nil? || points.size < 2
 
@@ -114,13 +114,26 @@ module TrackCalculator
   # split distance is reached, then records elapsed time and pace for that split.
   # Any remaining distance at the end is included as a partial split.
   #
+  # Only :pace changes with compact: — :km and :elapsed are numbers, not
+  # formatted strings, and are the same in both modes.
+  #
+  # The two pace formats differ by more than padding once a split is slower than
+  # an hour per unit: the padded format keeps counting minutes ('66:33'), as it
+  # always has, while the compact one rolls them into an hour field ('1:06:33'),
+  # like every other compact duration in the gem. A track that steps backwards
+  # in time (a watch clock resync, a paused device, merged segments) yields a
+  # negative split, reported with a leading minus in both formats ('-00:40' /
+  # '-0:40') rather than raising.
+  #
   # @param points [Array<Hash>] array of points with :lat, :lon, and :time keys.
   #   :time must respond to #to_f (Unix timestamp) or be a Time object.
   # @param split_km [Numeric] split interval in kilometers (default: 1.0)
+  # @param compact [Boolean] when true, :pace uses the compact display format
   # @return [Array<Hash>] array of split hashes, each with:
   #   - :km [Float] cumulative distance at split end
   #   - :elapsed [Integer] elapsed seconds from start of track to end of split
-  #   - :pace [String] pace for this split in MM:SS format
+  #   - :pace [String] pace for this split in MM:SS format, or 'M:SS' / 'H:MM:SS'
+  #     with compact: true
   # @raise [ArgumentError] if split_km is not positive
   # @raise [ArgumentError] if any point is missing a :time key
   #
@@ -131,12 +144,16 @@ module TrackCalculator
   #         { km: 2.0, elapsed: 624, pace: "05:12" },
   #         ...
   #       ]
-  def track_splits(points, split_km = 1.0)
+  #
+  # @example compact pace
+  #   calc.track_splits(points, 1.0, compact: true)
+  #   #=> [{ km: 1.0, elapsed: 312, pace: "5:12" }, ...]
+  def track_splits(points, split_km = 1.0, compact: false)
     raise ArgumentError, 'split_km must be positive' unless split_km.is_a?(Numeric) && split_km.positive?
     return [] if points.nil? || points.size < 2
 
     validate_points_have_time(points)
-    collect_splits(points, split_km)
+    collect_splits(points, split_km, compact: compact)
   end
 
   private
@@ -209,17 +226,37 @@ module TrackCalculator
     t_a + ((t_b - t_a) * (distance_into_segment / segment_km))
   end
 
-  def seconds_to_pace(seconds, km)
-    return '00:00' if km.zero?
-
+  # Formats a split pace, in either format, without ever raising.
+  #
+  # A GPS track can step backwards in time — a watch resyncing its clock, a
+  # device paused and restarted, two segments merged out of order — which makes
+  # a split elapsed time negative. That is bad data, not a caller error, and
+  # track_splits has always reported it rather than blowing up; #sign_of keeps
+  # it that way now that the compact format goes through #convert_to_clocktime,
+  # which rejects negative durations.
+  def seconds_to_pace(seconds, km, compact: false)
     pace_seconds = (seconds.to_f / km).round
+    "#{sign_of(pace_seconds)}#{format_pace(pace_seconds.abs, compact: compact)}"
+  end
+
+  def sign_of(pace_seconds)
+    pace_seconds.negative? ? '-' : ''
+  end
+
+  # The padded format keeps the historical MM:SS, where the minutes keep
+  # counting past 60 (a 66-minute hiking split reads '66:33'); the compact
+  # format defers to #convert_to_clocktime, which rolls those minutes into an
+  # hour field ('1:06:33') exactly as it does everywhere else.
+  def format_pace(pace_seconds, compact:)
+    return convert_to_clocktime(pace_seconds, compact: true) if compact
+
     format('%<min>02d:%<sec>02d', min: pace_seconds / 60, sec: pace_seconds % 60)
   end
 
-  def collect_splits(points, split_km)
+  def collect_splits(points, split_km, compact:)
     state = { splits: [], start_time: point_time(points.first),
               split_start_time: point_time(points.first),
-              accumulated_km: 0.0, split_number: 1 }
+              accumulated_km: 0.0, split_number: 1, compact: compact }
 
     points.each_cons(2) { |a, b| process_segment(a, b, split_km, state) }
     append_partial_split(points.last, split_km, state)
@@ -249,7 +286,7 @@ module TrackCalculator
     {
       km: (split_km * state[:split_number]).round(2),
       elapsed: (boundary_time - state[:start_time]).round,
-      pace: seconds_to_pace(split_elapsed, split_km)
+      pace: seconds_to_pace(split_elapsed, split_km, compact: state[:compact])
     }
   end
 
@@ -261,7 +298,8 @@ module TrackCalculator
     state[:splits] << {
       km: state[:accumulated_km].round(2),
       elapsed: (last_time - state[:start_time]).round,
-      pace: seconds_to_pace((last_time - state[:split_start_time]).round, remaining_km)
+      pace: seconds_to_pace((last_time - state[:split_start_time]).round, remaining_km,
+                            compact: state[:compact])
     }
   end
 end

data/lib/calcpace/version.rb

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

metadata

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