Module: PaceCalculator

Included in:
Calcpace
Defined in:
lib/calcpace/pace_calculator.rb

Overview

Module for calculating race times and paces for standard distances

This module provides convenience methods for calculating finish times and paces for common race distances like 5K, 10K, half-marathon, marathon, and 100K.

Constant Summary collapse

RACE_DISTANCES =

Standard race distances in kilometers

{
  '5k' => 5.0,
  '10k' => 10.0,
  'half_marathon' => 21.0975,
  'marathon' => 42.195,
  '100k' => 100.0,
  '1mile' => Converter::Distance::MI_TO_KM,
  '5mile' => 5 * Converter::Distance::MI_TO_KM,
  '10mile' => 10 * Converter::Distance::MI_TO_KM
}.freeze
SAME_DISTANCE_TOLERANCE_RATIO =

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

1e-9

Instance Method Summary collapse

Instance Method Details

#list_races ⇒ Hash

Lists all available standard race distances

Examples:

list_races #=> { '5k' => 5.0, '10k' => 10.0, ... }

Returns:

  • (Hash) —

    hash of race names and distances in kilometers



94
95
96
 
# File 'lib/calcpace/pace_calculator.rb', line 94

def list_races
  RACE_DISTANCES.dup
end

#race_pace(target_time, race) ⇒ Float

Calculates the required pace per kilometer to finish a race in a target time

Examples:

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)

Parameters:

  • target_time (Numeric, String) —

    target finish time in seconds or time string (HH:MM:SS)

  • race (Numeric, String, Symbol) —

    distance in kilometers (7.79, '7.79') or a standard race name ('5k', '10k', 'half_marathon', 'marathon', '100k', ...)

Returns:

  • (Float) —

    required pace in seconds per kilometer



68
69
70
71
72
73
 
# File 'lib/calcpace/pace_calculator.rb', line 68

def race_pace(target_time, race)
  distance = race_distance(race)
  time_seconds = target_time.is_a?(String) ? convert_to_seconds(target_time) : target_time
  check_positive(time_seconds, 'Time')
  time_seconds / distance
end

#race_pace_clock(target_time, race) ⇒ String

Calculates the required pace and returns it as a clock time string

Examples:

race_pace_clock('03:30:00', :marathon) #=> '00:04:58'

Parameters:

  • target_time (Numeric, String) —

    target finish time in seconds or time string (HH:MM:SS)

  • race (Numeric, String, Symbol) —

    distance in kilometers (7.79, '7.79') or a standard race name ('5k', '10k', 'half_marathon', 'marathon', '100k', ...)

Returns:

  • (String) —

    required pace in MM:SS format



84
85
86
 
# File 'lib/calcpace/pace_calculator.rb', line 84

def race_pace_clock(target_time, race)
  convert_to_clocktime(race_pace(target_time, race))
end

#race_time(pace_per_km, race) ⇒ Float

Calculates the finish time for a race given a pace per kilometer

Examples:

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)

Parameters:

  • pace_per_km (Numeric, String) —

    pace in seconds per km or time string (MM:SS)

  • race (Numeric, String, Symbol) —

    distance in kilometers (7.79, '7.79') or a standard race name ('5k', '10k', 'half_marathon', 'marathon', '100k', ...)

Returns:

  • (Float) —

    total time in seconds

Raises:



37
38
39
40
41
42
 
# File 'lib/calcpace/pace_calculator.rb', line 37

def race_time(pace_per_km, race)
  distance = race_distance(race)
  pace_seconds = pace_per_km.is_a?(String) ? convert_to_seconds(pace_per_km) : pace_per_km
  check_positive(pace_seconds, 'Pace')
  distance * pace_seconds
end

#race_time_clock(pace_per_km, race) ⇒ String

Calculates the finish time for a race and returns it as a clock time string

Examples:

race_time_clock('05:00', :marathon) #=> '03:30:58'
race_time_clock(300, :half_marathon) #=> '01:45:29'

Parameters:

  • pace_per_km (Numeric, String) —

    pace in seconds per km or time string (MM:SS)

  • race (Numeric, String, Symbol) —

    distance in kilometers (7.79, '7.79') or a standard race name ('5k', '10k', 'half_marathon', 'marathon', '100k', ...)

Returns:

  • (String) —

    finish time in HH:MM:SS format



54
55
56
 
# File 'lib/calcpace/pace_calculator.rb', line 54

def race_time_clock(pace_per_km, race)
  convert_to_clocktime(race_time(pace_per_km, race))
end