Calcpace

Calcpace is a Ruby gem designed for calculations and conversions related to distance and time. It can calculate velocity, pace, total time, and distance, accepting time in various formats, including HH:MM:SS. The gem supports conversion to 42 different units, including kilometers, miles, meters, and feet. It also provides methods to validate input.

gem 'calcpace', '~> 1.5.0'

Then run:

bundle install

gem install calcpace

Before performing any calculations or conversions, create a new instance of Calcpace:

require 'calcpace'

calculate = Calcpace.new

Calcpace provides methods to calculate velocity, pace, total time, and distance. The methods are unit-agnostic, and the return value is a float. Here are some examples:

calculate.velocity(3625, 12275) # => 3.386206896551724
calculate.pace(3665, 12) # => 305.4166666666667
calculate.time(210, 12) # => 2520.0
calculate.distance(9660, 120) # => 80.5

Tip: Use the round method to round a float. For example:

calculate.velocity(3625, 12275).round(3) # => 3.386

Remember:

• Velocity is the distance divided by the time (e.g., m/s or km/h).
• Pace is the time divided by the distance (e.g., minutes/km or minutes/miles).
• Total time is the distance divided by the velocity.
• Distance is the velocity multiplied by the time.

Calcpace also provides methods to calculate using clocktime (HH:MM:SS format string). The return value will be in seconds or clocktime, depending on the method called, except for checked_distance. Here are some examples:

# The return will be in the unit you input/seconds or seconds/unit you input
calculate.checked_velocity('01:00:00', 12275) # => 3.4097222222222223
calculate.checked_pace('01:21:32', 10) # => 489.2
calculate.checked_time('00:05:31', 12.6) # => 4170.599999999999

calculate.checked_distance('01:21:32', '00:06:27') # => 12.640826873385013

# The return will be in clocktime
calculate.clock_pace('01:21:32', 10) # => "00:08:09"
calculate.clock_velocity('01:00:00', 10317) # => "00:00:02"
calculate.clock_time('00:05:31', 12.6) # => "01:09:30"

Note: Using the clock methods may be less precise than using other methods due to conversions.

You can also use BigDecimal for more precise calculations. For example:

require 'bigdecimal'
calculate.checked_velocity('10:00:00', 10317).to_d # => #<BigDecimal:7f9f1b8b1d08,'0.2865833333 333333E1',27(36)>

To learn more about BigDecimal, check the documentation.

Use the convert method to convert a distance or velocity. The first parameter is the value to be converted, and the second parameter is the unit to which the value will be converted. The unit must be a string with the abbreviation of the unit. The gem supports 26 different units, including kilometers, miles, meters, knots, and feet.

Here are some examples:

converter.convert(10, :km_to_meters) # => 1000
converter.convert(10, :mi_to_km) # => 16.0934
converter.convert(1, :nautical_mi_to_km) # => 1.852
converter.convert(1, :km_h_to_m_s) # => 0.277778
converter.convert(1, :m_s_to_mi_h) # => 2.23694

You can list all the available units here, or using list methods:

converter.list_all
converter.list_distance
converter.list_speed

Calcpace also provides other useful methods:

converter = Calcpace.new
converter.convert_to_seconds('01:00:00') # => 3600
converter.convert_to_clocktime(3600) # => '01:00:00'
converter.check_time('01:00:00') # => nil

If you input an invalid value, the gem will raise a ArgumentError with a message explaining the error. For example:

calculate.pace(945, -1) # => It must be a X.X positive number (ArgumentError)
calculate.checked_time('string', 10) # => It must be a XX:XX:XX time (ArgumentError)
converter.check_time('01-00-00') # => It must be a XX:XX:XX time (ArgumentError)

We welcome contributions to Calcpace! To contribute, clone this repository and submit a pull request. Please ensure that your code adheres to our style and includes tests where appropriate.

The gem is available as open source under the terms of the MIT License.