Class: UnitMeasurements::Measurement Abstract

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Arithmetic, Comparison, Conversion, Formatter, Math
Defined in:
lib/unit_measurements/measurement.rb

Overview

This class is abstract.

The UnitMeasurements::Measurement is the abstract class and serves as superclass for all the unit groups. It includes several modules that provide mathematical operations, comparison, conversion, formatting, and other functionalities.

This class provides a comprehensive set of methods and functionality for working with measurements in different units. It includes robust error handling and supports conversion between units. Additionally, it ensures that measurements are consistently represented.

You should not directly initialize a Measurement instance. Instead, create specialized measurement types by subclassing Measurement and providing specific units and conversions through the build method defined in the UnitMeasurements module.

See Also:

Author:

Since:

  • 1.0.0

Constant Summary collapse

CONVERSION_STRING_REGEXP =

Regular expression to match conversion strings.

Author:

Since:

  • 1.0.0

/(.+?)\s?(?:\s+(?:in|to|as)\s+(.+)|\z)/i.freeze

Constants included from Formatter

Formatter::DEFAULT_FORMAT

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Math

#abs, #ceil, #floor, #round

Methods included from Formatter

#format

Methods included from Conversion

#to_c, #to_d, #to_f, #to_i, #to_r

Methods included from Comparison

#<=>

Methods included from Arithmetic

#*, #**, #+, #-, #-@, #/, #nonzero?

Constructor Details

#initialize(quantity, unit) ⇒ Measurement

Initializes a new instance of Measurement with a specified quantity and unit.

This method is intended to be overridden by subclasses and serves as a placeholder for common initialization logic. It raises an error if called directly on the abstract Measurement class.

Examples:

Initializing the measurement with scientific number and unit:

UnitMeasurements::Length.new(BigDecimal(2), "km")
=> 2.0 km

UnitMeasurements::Length.new("2e+2", "km")
=> 200.0 km

UnitMeasurements::Length.new("2e²", "km")
=> 200.0 km

UnitMeasurements::Length.new("2e⁻²", "km")
=> 0.02 km

Initializing the measurement with complex number and unit:

UnitMeasurements::Length.new(Complex(2, 3), "km")
=> 2+3i km

UnitMeasurements::Length.new("2+3i", "km")
=> 2.0+3.0i km

Initializing the measurement with rational or mixed rational number and unit:

UnitMeasurements::Length.new(Rational(2, 3), "km")
=> 0.6666666666666666 km

UnitMeasurements::Length.new(2/3r, "km")
=> 2/3 km

UnitMeasurements::Length.new("2/3", "km")
=> 0.6666666666666666 km

UnitMeasurements::Length.new("½", "km")
=> 0.5 km

UnitMeasurements::Length.new("2 ½", "km")
=> 2.5 km

Initializing the measurement with ratio and unit:

UnitMeasurements::Length.new("1:2", "km")
=> 0.5 km

Parameters:

  • quantity (Numeric|String) —

    The quantity of the measurement.

  • unit (String|Unit) —

    The unit of the measurement.

Raises:

  • (BaseError) —

    If quantity or unit is blank.

See Also:

Author:

Since:

  • 1.0.0



112
113
114
115
116
117
118
 
# File 'lib/unit_measurements/measurement.rb', line 112

def initialize(quantity, unit)
  raise BaseError, "Quantity cannot be blank." if quantity.blank?
  raise BaseError, "Unit cannot be blank." if unit.blank?

  @quantity = convert_quantity(quantity)
  @unit = unit_from_unit_or_name!(unit)
end

Instance Attribute Details

#quantity ⇒ Numeric (readonly)

Returns the quantity of the measurement.

Returns:

  • (Numeric) —

    Quantity of the measurement.

Author:

Since:

  • 1.5.0



47
48
49
 
# File 'lib/unit_measurements/measurement.rb', line 47

def quantity
  @quantity
end

#unit ⇒ Unit (readonly)

The unit associated with the measurement.

Returns:

  • (Unit) —

    The unit instance associated with the measurement.

Author:

Since:

  • 1.0.0



55
56
57
 
# File 'lib/unit_measurements/measurement.rb', line 55

def unit
  @unit
end

Class Method Details

.parse(input) ⇒ Measurement

Parses an input string and returns a Measurement instance depending on the input string. This method first normalizes the input internally, using the Normalizer before parsing it using the Parser.

If only the source unit is provided, it returns a new Measurement instance with the quantity in the source unit.If both source and target units are provided in the input string, it returns a new Measurement instance with the quantity converted to the target unit.

Examples:

Parsing string representing a complex number and source unit:

UnitMeasurements::Length.parse("2+3i km")
=> 2.0+3.0i km

Parsing string representing a complex number, source, and target units:

UnitMeasurements::Length.parse("2+3i km to m")
=> 2000.0+3000.0i m

Parsing string representing a rational or mixed rational number and source unit:

UnitMeasurements::Length.parse("½ km")
=> 0.5 km

UnitMeasurements::Length.parse("2/3 km")
=> 0.666666666666667 km

UnitMeasurements::Length.parse("2 ½ km")
=> 2.5 km

UnitMeasurements::Length.parse("2 1/2 km")
=> 2.5 km

Parsing string representing a rational or mixed rational number, source, and target units:

UnitMeasurements::Length.parse("½ km to m")
=> 500.0 km

UnitMeasurements::Length.parse("2/3 km to m")
=> 666.666666666667 m

UnitMeasurements::Length.parse("2 ½ km to m")
=> 2500.0 m

UnitMeasurements::Length.parse("2 1/2 km to m")
=> 2500.0 m

Parsing string representing a scientific number and source unit:

UnitMeasurements::Length.parse("2e² km")
=> 200.0 km

UnitMeasurements::Length.parse("2e+2 km")
=> 200.0 km

UnitMeasurements::Length.parse("2e⁻² km")
=> 0.02 km

Parsing string representing a scientific number, source, and target units:


UnitMeasurements::Length.parse("2e+2 km to m")
=> 200000.0 m

UnitMeasurements::Length.parse("2e⁻² km to m")
=> 20.0 m

Parsing string representing a ratio and source unit:

UnitMeasurements::Length.parse("1:2 km")
=> 0.5 km

Parsing string representing a ratio, source, and target units:

UnitMeasurements::Length.parse("1:2 km to m")
=> 500.0 m

Parameters:

  • input (String) —

    The input string to be parsed.

Returns:

See Also:

Author:

Since:

  • 1.0.0



306
307
308
309
310
311
 
# File 'lib/unit_measurements/measurement.rb', line 306

def parse(input)
  input = Normalizer.normalize(input)
  source, target = input.match(CONVERSION_STRING_REGEXP)&.captures

  target ? _parse(source).convert_to(target) : _parse(source)
end

Instance Method Details

#convert_to(target_unit) ⇒ Measurement Also known as: to, in, as

Converts the measurement to a target_unit and returns new instance of the measurement.

Examples:

UnitMeasurements::Length.new(1, "m").convert_to("cm")
=> 100.0 cm

UnitMeasurements::Length.new(1, "cm").convert_to("primitive")
=> 0.01 m

Parameters:

  • target_unit (String|Symbol) —

    The target unit for conversion. Specifing primitive will convert the measurement to a primitive unit of the unit group.

Returns:

  • (Measurement) —

    A new Measurement instance with the converted quantity and target unit.

Author:

Since:

  • 1.0.0



140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/unit_measurements/measurement.rb', line 140

def convert_to(target_unit)
  target_unit = if target_unit.to_s.eql?("primitive")
    self.class.unit_group.primitive
  else
    unit_from_unit_or_name!(target_unit)
  end

  return self if target_unit == unit

  conversion_factor = (unit.conversion_factor / target_unit.conversion_factor)

  self.class.new((quantity * conversion_factor), target_unit)
end

#convert_to!(target_unit) ⇒ Measurement Also known as: to!, in!, as!

Converts the measurement to a target_unit and updates the current instance.

Examples:

UnitMeasurements::Length.new(1, "m").convert_to!("cm")
=> 100.0 cm

Parameters:

  • target_unit (String|Symbol) —

    The target unit for conversion.

Returns:

  • (Measurement) —

    The current Measurement instance with updated quantity and unit.

See Also:

Author:

Since:

  • 1.0.0



171
172
173
174
175
176
 
# File 'lib/unit_measurements/measurement.rb', line 171

def convert_to!(target_unit)
  measurement = convert_to(target_unit)
  @quantity, @unit = measurement.quantity, measurement.unit

  self
end

#inspect(dump: false) ⇒ Object

Returns an object representation of the Measurement.

Parameters:

  • dump (TrueClass|FalseClass) (defaults to: false) —

    If true, returns the dump representation.

Returns:

  • (Object) —

    An object representation of the Measurement.

Author:

Since:

  • 1.0.0



189
190
191
 
# File 'lib/unit_measurements/measurement.rb', line 189

def inspect(dump: false)
  dump ? super() : to_s
end

#to_s ⇒ String

Returns a string representation of the Measurement.

Returns:

  • (String) —

    A string representation of the Measurement.

Author:

Since:

  • 1.0.0



199
200
201
 
# File 'lib/unit_measurements/measurement.rb', line 199

def to_s
  "#{quantity} #{unit}"
end