Class: UnitMeasurements::UnitGroup

Inherits:
Object
  • Object
show all
Defined in:
lib/unit_measurements/unit_group.rb

Overview

The UnitMeasurements::UnitGroup class provides a collection of units with methods to retrieve units by name, check if a unit is defined, and much more.

It serves as a container for organizing and working with units within the unit group.

Author:

Since:

  • 1.0.0

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(primitive, units) ⇒ UnitGroup

Initializes a new UnitGroup instance.

Parameters:

  • primitive (String|Symbol, optional) —

    The name of the primitive unit.

  • units (Array<Unit>) —

    An array of Unit instances.

Author:

Since:

  • 1.0.0



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

def initialize(primitive, units)
  @units = units.map { |unit| unit.with(unit_group: self) }
  @primitive = unit_for!(primitive) if primitive
end

Instance Attribute Details

#primitive ⇒ Unit (readonly)

The primitive unit of the unit group.

Examples:

UnitMeasurements::Length.primitive
=> #<UnitMeasurements::Unit: m (meter, meters, metre, metres)>

Returns:

  • (Unit) —

    The primitive unit of the unit group.

Author:

Since:

  • 1.0.0



25
26
27
 
# File 'lib/unit_measurements/unit_group.rb', line 25

def primitive
  @primitive
end

#units ⇒ Array<Unit> (readonly)

An array of units within the unit group.

Examples:

UnitMeasurements::Length.units
=> [#<UnitMeasurements::Unit: m (meter, meters, metre, metres)>, ...]

Returns:

  • (Array<Unit>) —

    An array of Unit instances.

Author:

Since:

  • 1.0.0



37
38
39
 
# File 'lib/unit_measurements/unit_group.rb', line 37

def units
  @units
end

Instance Method Details

#defined?(name) ⇒ TrueClass|FalseClass

Checks if a unit with a given name is defined within the unit group.

Examples:

UnitMeasurements::Length.defined?("m")
=> true

UnitMeasurements::Length.defined?("metre")
=> false

Parameters:

  • name (String|Symbol) —

    The name of the unit to look for.

Returns:

  • (TrueClass|FalseClass) —

    true if the unit is defined, false otherwise.

Author:

Since:

  • 1.0.0



145
146
147
148
149
 
# File 'lib/unit_measurements/unit_group.rb', line 145

def defined?(name)
  unit = unit_for(name)

  unit ? unit.name == name.to_s : false
end

#unit_for(name) ⇒ Unit|NilClass

Returns the unit instance for a given unit name. It returns nil if unit is not defined within the unit group.

Examples:

UnitMeasurements::Length.unit_for("m")
=> #<UnitMeasurements::Unit: m (meter, meters, metre, metres)>

UnitMeasurements::Length.unit_for("z")
=> nil

Parameters:

  • name (String|Symbol) —

    The name of the unit.

Returns:

  • (Unit|NilClass) —

    A Unit instance or nil if the unit is not found.

Author:

Since:

  • 1.0.0



67
68
69
 
# File 'lib/unit_measurements/unit_group.rb', line 67

def unit_for(name)
  unit_name_to_unit(name)
end

#unit_for!(name) ⇒ Unit Also known as: []

This method works same as unit_for but it raises UnitError if the unit is not defined within the unit group.

Examples:

UnitMeasurements::Length.unit_for!("m")
=> #<UnitMeasurements::Unit: m (meter, meters, metre, metres)>

UnitMeasurements::Length.unit_for!("z")
=> Invalid unit: 'z'. (UnitMeasurements::UnitError)

Parameters:

  • name (String|Symbol) —

    The name of the unit to look for.

Returns:

  • (Unit) —

    A Unit instance.

Raises:

See Also:

Author:

Since:

  • 1.0.0



91
92
93
94
95
96
 
# File 'lib/unit_measurements/unit_group.rb', line 91

def unit_for!(name)
  unit = unit_for(name)
  raise UnitError, name unless unit

  unit
end

#unit_names ⇒ Array<String>

Returns an array of names of all the units defined within the unit group, sorted alphabetically.

Examples:

UnitMeasurements::Length.unit_names
=> ["ft", "in", "m", "mi", "yd"]

Returns:

  • (Array<String>) —

    An array of unit names.

Author:

Since:

  • 1.0.0



110
111
112
 
# File 'lib/unit_measurements/unit_group.rb', line 110

def unit_names
  units.map(&:name).sort
end

#unit_names_with_aliases ⇒ Array<String>

Returns an array of names and aliases of all the units defined within the unit group, sorted alphabetically.

Examples:

UnitMeasurements::Length.unit_names_with_aliases
=> ["\"", "'", "feet", "foot", "ft", "in", "inch", "inches", "m", "meter", "meters", "metre", "metres", "mi", "mile", "miles", "yard", "yards", "yd"]

Returns:

  • (Array<String>) —

    An array of unit names and aliases.

Author:

Since:

  • 1.0.0



125
126
127
 
# File 'lib/unit_measurements/unit_group.rb', line 125

def unit_names_with_aliases
  units.flat_map(&:names).sort
end

#unit_or_alias?(name) ⇒ TrueClass|FalseClass

Checks if a given name corresponds to a defined unit or an alias of any defined unit.

Examples:

UnitMeasurements::Length.unit_or_alias?("m")
=> true

UnitMeasurements::Length.unit_or_alias?("metre")
=> true

Parameters:

  • name (String|Symbol) —

    The name or alias of the unit to look for.

Returns:

  • (TrueClass|FalseClass) —

    true if the name corresponds to a unit or alias, false otherwise.

Author:

Since:

  • 1.0.0



168
169
170
 
# File 'lib/unit_measurements/unit_group.rb', line 168

def unit_or_alias?(name)
  !!unit_for(name)
end

#units_for(system_name) ⇒ Array<Unit>

Returns an array of units associated with a specified unit_system.

This method takes a unit system name as an argument and filters the units in the unit group to return only those units that belong to the specified unit system. It then returns an array containing these filtered units. If there are no units associated with unit system, it returns empty array.

Examples:

UnitMeasurements::Length.units_for("metric")
=> [#<UnitMeasurements::Unit: m (meter, meters, metre, metres)>]

UnitMeasurements::Length.units_for("imperial")
=> [#<UnitMeasurements::Unit: in (", inch, inches)>, ...]

UnitMeasurements::Length.units_for("troy")
=> []

Parameters:

  • system_name (String|Symbol) —

    The name of the unit system to retrieve units for.

Returns:

  • (Array<Unit>) —

    An array of Unit instances associated with the specified unit system.

Author:

Since:

  • 5.0.0



197
198
199
 
# File 'lib/unit_measurements/unit_group.rb', line 197

def units_for(system_name)
  units.select { |unit| unit.system.to_s == system_name.to_s }
end

#units_for!(system_name) ⇒ Array<Unit>

This method works same as units_for method but it raises an error if there are no units associated with the system_name.

Examples:

UnitMeasurements::Length.units_for!("metric")
=> [#<UnitMeasurements::Unit: m (meter, meters, metre, metres)>]

UnitMeasurements::Length.units_for!("imperial")
=> [#<UnitMeasurements::Unit: in (", inch, inches)>, ...]

UnitMeasurements::Length.units_for!("troy")
=> Invalid unit system 'troy' within the unit group. (UnitMeasurements::BaseError)

Parameters:

  • system_name (String|Symbol) —

    The name of the unit system to retrieve units for.

Returns:

  • (Array<Unit>) —

    An array of Unit instances associated with the specified unit system.

Raises:

  • (BaseError) —

    If there are no units associated with the provided system_name.

See Also:

Author:

Since:

  • 5.0.0



226
227
228
229
230
231
232
233
234
 
# File 'lib/unit_measurements/unit_group.rb', line 226

def units_for!(system_name)
  system_units = units_for(system_name)

  unless system_units.any?
    raise BaseError, "Invalid unit system '#{system_name}' within the unit group."
  end

  system_units
end