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, cache_file) ⇒ 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.

  • cache_file (String) —

    The name of the cache file.

Author:

Since:

  • 1.0.0



59
60
61
62
63
 
# File 'lib/unit_measurements/unit_group.rb', line 59

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

Instance Attribute Details

#cache_file ⇒ String (readonly)

The name of the cache file.

Examples:

UnitMeasurements::Length.cache_file
=> "length.json"

Returns:

  • (String) —

    The name of the cache file.

Author:

Since:

  • 5.2.0



49
50
51
 
# File 'lib/unit_measurements/unit_group.rb', line 49

def cache_file
  @cache_file
end

#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



159
160
161
162
163
 
# File 'lib/unit_measurements/unit_group.rb', line 159

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

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

#systems ⇒ Array<String>

Returns an array of unit system names defined within the unit group.

It scans through the units and compiles a list of unique system names.

Examples:

UnitMeasurements::Length.systems
=> ["metric", "imperial", "us_customary", "astronomical"]

Returns:

  • (Array<String>) —

    An array of unit system names.

Author:

Since:

  • 5.11.0



260
261
262
 
# File 'lib/unit_measurements/unit_group.rb', line 260

def systems
  units.map { _1.system }.uniq
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



81
82
83
 
# File 'lib/unit_measurements/unit_group.rb', line 81

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



105
106
107
108
109
110
 
# File 'lib/unit_measurements/unit_group.rb', line 105

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

  unit
end

#unit_name_to_unit(name) ⇒ Unit|NilClass (private)

Returns the Unit instance for a given unit name.

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



293
294
295
 
# File 'lib/unit_measurements/unit_group.rb', line 293

def unit_name_to_unit(name)
  unit_with_name_and_aliases[name.to_s]
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



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

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



139
140
141
 
# File 'lib/unit_measurements/unit_group.rb', line 139

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



182
183
184
 
# File 'lib/unit_measurements/unit_group.rb', line 182

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

#unit_with_name_and_aliases ⇒ Hash (private)

Returns a hash where keys are unit names (including aliases) and values are corresponding Unit instances.

Examples:

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

Returns:

  • (Hash) —

    A hash containing unit names as keys and Unit objects as values.

Author:

Since:

  • 1.0.0



278
279
280
281
282
 
# File 'lib/unit_measurements/unit_group.rb', line 278

def unit_with_name_and_aliases
  units.each_with_object({}) do |unit, hash|
    unit.names.each { |name| hash[name.to_s] = unit }
  end
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



211
212
213
 
# File 'lib/unit_measurements/unit_group.rb', line 211

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 the unit system system_name is not defined within the unit group.

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:

  • (RuntimeError) —

    If unit system is not defined within the unit group.

See Also:

Author:

Since:

  • 5.0.0



240
241
242
243
244
245
246
 
# File 'lib/unit_measurements/unit_group.rb', line 240

def units_for!(system_name)
  unless systems.include?(system_name.to_s)
    raise "Invalid unit system '#{system_name}' within the unit group."
  end

  units_for(system_name)
end