class Unitwise::Atom

Atoms are the most basic elements in Unitwise. They are named coded and scaled units without prefixes, multipliers, exponents, etc. Examples are 'meter', 'hour', 'pound force'.

Public Class Methods

data() click to toggle source

Array of hashes representing default atom properties. @api private

# File lib/unitwise/atom.rb, line 12
def data
  @data ||= data_files.map { |file| YAML.load(File.open file) }.flatten
end
data_files() click to toggle source

Data files containing default atom data @api private

# File lib/unitwise/atom.rb, line 18
def data_files
  %w(base_unit derived_unit).map { |type| Unitwise.data_file type }
end

Public Instance Methods

arbitrary() click to toggle source

Determine if a unit is arbitrary. Arbitrary atoms are not of any specific dimension and have no general meaning, therefore cannot be compared with any other unit. @return [true, false] @api public

# File lib/unitwise/atom.rb, line 62
def arbitrary
  !!@arbitrary
end
Also aliased as: arbitrary?
arbitrary?()
Alias for: arbitrary
base?() click to toggle source

Determine if an atom is base level. All atoms that are not base are defined directly or indirectly in reference to a base atom. @return [true, false] @api public

# File lib/unitwise/atom.rb, line 27
def base?
  !!(@dim && !scale)
end
depth() click to toggle source

Determine how far away a unit is from a base unit. @return [Integer] @api public

# File lib/unitwise/atom.rb, line 70
def depth
  base? ? 0 : scale.depth + 1
end
derived?() click to toggle source

Determine if an atom is derived. Derived atoms are defined with respect to other atoms. @return [true, false] @api public

# File lib/unitwise/atom.rb, line 35
def derived?
  !base?
end
dim() click to toggle source

A representation of an atoms composition. Used to determine if two different atoms are compatible. @return [String] @api public

# File lib/unitwise/atom.rb, line 86
def dim
  terminal? ? @dim || property : composition_string
end
magnitude(scalar = scalar()) click to toggle source
# File lib/unitwise/atom.rb, line 109
def magnitude(scalar = scalar())
  special? ? scale.magnitude(scalar) : 1
end
metric() click to toggle source

Determine if an atom is metric. Metric atoms can be combined with metric prefixes. @return [true, false] @api public

# File lib/unitwise/atom.rb, line 43
def metric
  base? ? true : !!@metric
end
Also aliased as: metric?
metric?()
Alias for: metric
root_terms() click to toggle source

An atom may have a complex scale with several base atoms at various depths. This method returns all of this atoms base level terms. @return [Array] An array containing base Unitwise::Term

# File lib/unitwise/atom.rb, line 116
def root_terms
  base? ? [Term.new(:atom_code => primary_code)] : scale.root_terms
end
scalar(magnitude = 1) click to toggle source

Get a numeric value that can be used to with other atoms to compare with or operate on. Base units have a scalar of 1. @return [Numeric] @api public

# File lib/unitwise/atom.rb, line 105
def scalar(magnitude = 1)
  base? ? magnitude : scale.scalar(magnitude)
end
scale=(attrs) click to toggle source

Set the atom's scale. It can be set as a Scale or a Functional @return [Unitwise::Functional, Unitwise::Scale] @api public

# File lib/unitwise/atom.rb, line 93
def scale=(attrs)
  @scale = if attrs[:function_code]
    Functional.new(attrs[:value], attrs[:unit_code], attrs[:function_code])
  else
    Scale.new(attrs[:value], attrs[:unit_code])
  end
end
special() click to toggle source

Determine if a unit is special. Special atoms are not defined on a traditional ratio scale. @return [true, false] @api public

# File lib/unitwise/atom.rb, line 52
def special
  !!@special
end
Also aliased as: special?
special?()
Alias for: special
terminal?() click to toggle source

Determine if this is the last atom in the scale chain @return [true, false] @api public

# File lib/unitwise/atom.rb, line 78
def terminal?
  depth <= 3
end
validate!() click to toggle source

A basic validator for atoms. It checks for the bare minimum properties and that it's scalar and magnitude can be resolved. Note that this method requires the units it depends on to already exist, so it is not used when loading the initial data from UCUM. @return [true] returns true if the atom is valid @raise [Unitwise::DefinitionError]

# File lib/unitwise/atom.rb, line 128
def validate!
  missing_properties = %i{primary_code names scale}.select do |prop|
    val = liner_get(prop)
    val.nil? || (val.respond_to?(:empty) && val.empty?)
  end

  if !missing_properties.empty?
    missing_list = missing_properties.join(',')
    raise Unitwise::DefinitionError,
      "Atom has missing properties: #{missing_list}."
  end

  msg = "Atom definition could not be resolved. Ensure that it is a base " \
        "unit or is defined relative to existing units."

  begin
    !scalar.nil? && !magnitude.nil? || raise(Unitwise::DefinitionError, msg)
  rescue Unitwise::ExpressionError
    raise Unitwise::DefinitionError,  msg
  end
end