Basic Temperature

basic_temperature is a Ruby library which provides a simple value object to work with temperatures and allows to perform basic operations like conversion from Celsius to Kelvin, from Kelvin to Fahrenheit etc.

Features

• Provides a Temperature class which encapsulates all information about a certain temperature, such as its amount of degrees and its scale.

• Provides APIs for exchanging temperatures from one scale to another (currently Celsius, Fahrenheit, Kelvin and Rankine).

• Allows comparing temperatures between each other.

• Queries like boil_water?, freeze_water?.

• Tested against Ruby 2.3, 2.4, 2.5, 2.6 & 2.7. See .travis-ci.yml for the exact versions.

Dependecies

• None.

Documentation

• Visit https://marian13.github.io/basic_temperature/ to view the documentation.

Installation

Gemfile:

gem 'basic_temperature', '~> 1.0.0'

And then run:

$ bundle install

And that's it.

You can access all the features of basic_temperature by creating instances of BasicTemperature::Temperature.

But there is a shorter form.

If Temperature constant was not used before in your app, you can add this line to your Gemfile:

gem 'basic_temperature', '~> 1.0.0', require: ['basic_temperature/alias']

This way BasicTemperature::Temperature class will be accesible simply by Temperature.

The following guide assumes you have chosen the shorter form.

If not, just replace all Temperature to BasicTemperature::Temperature.

Usage

Creating Temperatures

A new temperature can be created in multiple ways:

• Using keyword arguments:

Temperature.new(degrees: 0, scale: :celsius)

• Using positional arguments:

Temperature.new(0, :celsius)

• Even more concise way using Temperature.[] (an alias of Temperature.new):

Temperature[0, :celsius]

Creating Temperatures from already existing temperature objects

Sometimes it is useful to create a new temperature from already existing one.

For such cases, there are set_degrees and set_scale.

Since temperatures are value objects, both methods return new instances.

Examples:

temperature = Temperature[0, :celsius]
# => 0 °C

new_temperature = temperature.set_degrees(15)
# => 15 °C

temperature = Temperature[0, :celsius]
# => 0 °C

new_temperature = temperature.set_scale(:kelvin)
# => 0 K

Conversions

Temperatures can be converted to diffirent scales.

Currently, the following scales are supported: Celsius, Fahrenheit, Kelvin and Rankine.

Temperature[20, :celsius].to_celsius
# => 20 °C

Temperature[20, :celsius].to_fahrenheit
# => 68 °F

Temperature[20, :celsius].to_kelvin
# => 293.15 K

Temperature[20, :celsius].to_rankine
# => 527.67 °R

If it is necessary to convert scale dynamically, to_scale method is available.

Temperature[20, :celsius].to_scale(scale)

All conversion formulas are taken from RapidTables.

Conversion precision: 2 accurate digits after the decimal dot.

Comparison

Temperature implements idiomatic <=> spaceship operator and mixes in Comparable module.

As a result, all methods from Comparable are available, e.g:

Temperature[20, :celsius] < Temperature[25, :celsius]
# => true

Temperature[20, :celsius] <= Temperature[25, :celsius]
# => true

Temperature[20, :celsius] == Temperature[25, :celsius]
# => false

Temperature[20, :celsius] > Temperature[25, :celsius]
# => false

Temperature[20, :celsius] >= Temperature[25, :celsius]
# => false

Temperature[20, :celsius].between?(Temperature[15, :celsius], Temperature[25, :celsius])
# => true

# Starting from Ruby 2.4.6
Temperature[20, :celsius].clamp(Temperature[20, :celsius], Temperature[25, :celsius])
# => 20 °C

Please note, if the second temperature has a different scale, the first temperature is automatically converted to that scale before comparison.

Temperature[20, :celsius] == Temperature[293.15, :kelvin]
# => true

IMPORTANT !!!

degrees are rounded to the nearest value with a precision of 2 decimal digits before comparison.

This means the following temperatures are considered as equal:

Temperature[20.020, :celsius] == Temperature[20.024, :celsius]
# => true

Temperature[20.025, :celsius] == Temperature[20.029, :celsius]
# => true

while these ones are treated as NOT equal:

Temperature[20.024, :celsius] == Temperature[20.029, :celsius]
# => false

Queries

Temperature[0, :celsius].boil_water?
# => false

Temperature[0, :celsius].freeze_water?
# => true

Versioning

Basic Temperature follows the Semantic Versioning standard.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/marian13/basic_temperature.

Development

• Check specs: bundle exec rspec.

• Check linter: bundle exec rubocop.

• Update docs: bundle exec sdoc lib -T rails -o docs.

Development with Docker

• Build container: docker build . -f docker/Dockerfile-2.3 -t basic_temperature_2.3.

• Run specs inside container: docker run -it basic_temperature_2.3:latest bundle exec rspec.

• Interactive shell inside container: docker run -it basic_temperature_2.3:latest bash.

• 2.3 can be replaced by 2.4, 2.5, 2.6 and 2.7.

License

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

Copyright (c) 2020 Marian Kostyk.