calcpace 1.13.0 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76b9c7242a528134ed36832a7be8fc3e83ccb65fc7e139232d2987a78116498b
-  data.tar.gz: f87752c75360bfa9dca40ae93bfdeaafc1522f7592d9ba3ca236cd9fb1d63a56
+  metadata.gz: c3fb2c004f6564fef1686e1c92db831e7c54a47360dd9c540a90bb334582ee95
+  data.tar.gz: 31c20dd413fe2df72d57f7516bb613c7661724bba196ff81da3af3b2c17c0ee0
 SHA512:
-  metadata.gz: 63421f8934eb0c94aa0713056fb6014ee7fa1ef7e1f611d16477ab3c84fb9235909b4f2e82e0e6e38a59d66ce801d109a76215ffbe08dddafd19523330327172
-  data.tar.gz: 9754c81c00f31f76e0250ebd0388dd7779cac95312513945364fc8f3efe914efd2f871c47afda9afbe442fdcc68d0c1eee3454348119bbd998f168c258af449c
+  metadata.gz: 784831b687993538654becf398906fc798ff089e8344ed1cd8768f3b42735111b490f99f185b0535f09d84ad15b0d207703e49d494c6e61ca1c3311630016b9a
+  data.tar.gz: 3f4170b7d5a3c4f71ed40ab732fb02be5ea2f1daf494c179aedab9b63e1837b90631ebf8db8f1484e83fbd9b55b569b7c9db31f66d915ca3228dae745eb7d619

data/CHANGELOG.md

@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +381,8 @@ 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.14.0...HEAD
+[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

@@ -93,6 +93,16 @@ 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"
 ```
 
 ---
@@ -152,12 +162,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.
 
 ---
@@ -382,6 +413,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/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/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.14.0'
 end

metadata

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