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' => 1.60934,
  '5mile' => 8.04672,
  '10mile' => 16.0934
}.freeze

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



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

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)    #=> 297.48... (4:57/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 (String, Symbol) —

    race distance (‘5k’, ‘10k’, ‘half_marathon’, ‘marathon’, ‘100k’)

Returns:

  • (Float) —

    required pace in seconds per kilometer



59
60
61
62
63
64
 
# File 'lib/calcpace/pace_calculator.rb', line 59

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:57'

Parameters:

  • target_time (Numeric, String) —

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

  • race (String, Symbol) —

    race distance (‘5k’, ‘10k’, ‘half_marathon’, ‘marathon’, ‘100k’)

Returns:

  • (String) —

    required pace in MM:SS format



74
75
76
 
# File 'lib/calcpace/pace_calculator.rb', line 74

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 (String, Symbol) —

    race distance (‘5k’, ‘10k’, ‘half_marathon’, ‘marathon’, ‘100k’)

Returns:

  • (Float) —

    total time in seconds

Raises:

  • (ArgumentError) —

    if race distance is not recognized



30
31
32
33
34
35
 
# File 'lib/calcpace/pace_calculator.rb', line 30

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:17'

Parameters:

  • pace_per_km (Numeric, String) —

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

  • race (String, Symbol) —

    race distance (‘5k’, ‘10k’, ‘half_marathon’, ‘marathon’, ‘100k’)

Returns:

  • (String) —

    finish time in HH:MM:SS format



46
47
48
 
# File 'lib/calcpace/pace_calculator.rb', line 46

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