uom 1.2.1

data/lib/uom.rb

@@ -0,0 +1,7 @@
+require 'uom/measurement'
+
+# UOM implements Units of Measurement based on the International System of Units.
+# See [http://github.com/caruby/uom] for details.
+module UOM
+  VERSION = "1.2.1"
+end

data/lib/uom/composite_unit.rb

@@ -0,0 +1,105 @@
+require 'singleton'
+require 'generator'
+require 'extensional'
+require 'active_support/inflector'
+require 'uom/unit'
+require 'uom/composite_unit_key_canonicalizer'
+
+module UOM
+   # A CompositeUnit represents a measurement unit across more than one dimension, e.g. +:gram_per_liter+.
+  class CompositeUnit < Unit
+    SUPPORTED_OPERATORS = [:/, :*]
+
+    @canonicalizer = CompositeUnitKeyCanonicalizer.new
+
+    make_extensional(Hash.new { |hash, spec| match(hash, *spec) }) do |hash, unit|
+      key = @canonicalizer.canonicalize(unit.axes.first, unit.axes.last, unit.operator)
+      hash[key] = unit
+    end
+
+    attr_reader :operator, :axes
+
+    # Creates a CompositeUnit from the given units u1 and u2 and operator symbol +:/+ or +:*+.
+    # Each unit can be either a Unit or another CompositeUnit.
+    # The remaining parameters are described in Unit.
+    #
+    # The CompositeUnit label is inferred from the operator constituent units, e.g.:
+    #   CompositeUnit.new(Unit.for(:gram), Unit.for(:liter), :/) #=> grams_per_liter
+    def initialize(u1, u2, operator, *params)
+      @axes = [u1, u2]
+      @operator = operator
+      raise MeasurementError.new("Unit composition operator unsupported - expected #{SUPPORTED_OPERATORS.join(' or ')}, found #{operator}") unless SUPPORTED_OPERATORS.include?(operator)
+      # make the composite dimension parameter
+      dims = @axes.map { |axis| axis.dimension }
+      # Add the first axis and the dimension to the parameters. The first axis is designated
+      # the axis in Unit; the second axis is a qualifier.
+      params << CompositeDimension.for([dims, @operator])
+      # call the Unit initializer with the parameters except for the axes
+      super(*params)
+      # add to the extent
+      CompositeUnit << self
+    end
+
+    # Returns the the given quantity converted from this Unit into the given unit.
+    def as(quantity, unit)
+      # if unit wraps a composite unit axis, then convert unit => axis => self and invert
+      return 1.0 / unit.as(1.0 / quantity, self) unless CompositeUnit === unit
+      raise MeasurementError.new("No conversion from #{self} to #{unit}") unless unit.axes.size == axes.size and unit.operator == operator
+      # convert the the first axis quantity to the first unit axis
+      first = axes[0].as(quantity, unit.axes[0])
+      # convert the remaining units
+      vector = SyncEnumerator.new(axes[1..-1], unit.axes[1..-1]).map { |from, to| from.as(1, to).to_f }
+      # apply the operator
+      vector.inject(first) { |q, item| q.send(@operator, item) }
+    end
+
+    def to_s(quantity=nil)
+      @operator == :* ? super : [axes.first.to_s(quantity)].concat(axes[1..-1]).join('_per_')
+    end
+
+    def inspect
+      "#{self.class.name}@#{self.object_id}[#{([label] + abbreviations).join(', ')}: #{composition_to_s}]"
+    end
+
+    # Returns a string representation of this CompositeUnit's composition, e.g.
+    #   ((UOM::METER * UOM::SECOND) / UOM::GRAM).composition_to_s #=> (meter * second) / gram
+    def composition_to_s
+      axes.map { |axis| CompositeUnit === axis ? "(#{axis.composition_to_s})" : axis.label.to_s }.join(" #{operator} ")
+    end
+
+    protected
+
+    def create_label
+      case @operator
+      when :/ then create_division_label
+      when :* then create_product_label
+      end
+    end
+
+    private
+
+    # Returns the CompositeUnit which matches the key [u1, u2, operator] in hash. If there is no such key
+    # in hash, then match on the canonicalized form of [u1, u2, operator]. Creates a new CompositeUnit from
+    # the canonical form if there is no match.
+    def self.match(hash, u1, u2, operator)
+      # canonicalize the arguments into the form [cu1, cu2, op], where cu2 is a non-composite unit and
+      # cu1 is either a composite or a non-composite unit and op is an unit product or quotient operator.
+      # the locator block recursively matches a sub-specification generated by the canonicalizer.
+      spec = @canonicalizer.canonicalize(u1, u2, operator) { |spec| hash[spec] }
+      # if there is a match on the canonicalized spec [cu1, cu2, op], then return the match.
+      # otherwise, make a new CompositeUnit from cu1, cu2 and op.
+      hash.has_key?(spec) ? hash[spec] : new(*spec)
+    end
+
+    def create_division_label
+      [axes.first.label.to_s.pluralize].concat(axes[1..-1].map { |unit| unit.label.to_s }).join('_per_').to_sym
+    end
+
+    def create_product_label
+      # unit * unit has label square_unit
+      label = axes.first == axes.last ? "square_#{axes.first.label}" : "#{axes.first.label}_#{axes.last.label}"
+      # convert square_unit_unit to cubic_unit
+      label.gsub(/square_([[:alnum:]]+)_\1/, 'cubic_\1').to_sym
+    end
+  end
+end

data/lib/uom/composite_unit_key_canonicalizer.rb

@@ -0,0 +1,53 @@
+require 'uom/composite_unit'
+
+module UOM
+   # A CompositeUnitKeyCanonicalizer creates a standard key for the CompositeUnit extent.
+  class CompositeUnitKeyCanonicalizer
+    def match(hash, u1, u2, operator)
+      spec = canonicalize(u1, u2, operator)
+      hash[spec] ||= new(*spec)
+    end
+
+    # Returns the canonical form of the given units u1 and u2 and operator +:*+ or +:/+ as an array consisting
+    # of a CompositeUnit, non-composite Unit and operator, e.g.:
+    #   canonicalize(METER, SECOND * SECOND, :*) #=> [METER * SECOND, SECOND, :*]
+    #   canonicalize(METER, SECOND / SECOND, :*) #=> [METER * SECOND, SECOND, :/]
+    #   canonicalize(METER, SECOND * SECOND, :/) #=> [METER / SECOND, SECOND, :/]
+    #   canonicalize(METER, SECOND / SECOND, :/) #=> [METER / SECOND, SECOND, :*]
+    #
+    # The locator block given to this method matches a CompositeUnit with arguments u11, u12 and op1.
+    # 
+    # See also canonicalize_operators.
+    def canonicalize(u1, u2, operator, &locator) # :yields: u11, u12, op1
+      # nothing to do if u2 is already a non-composite unit
+      return u1, u2, operator unless CompositeUnit === u2
+      # canonicalize u2
+      cu21, cu22, cop2 = canonicalize(u2.axes.first, u2.axes.last, u2.operator, &locator)
+      # redistribute u1 with the canonicalized u2 axes cu21 and cu22 using the redistributed operators rop1 and rop2
+      rop1, rop2 = redistribute_operators(operator, cop2)
+      # yield canonicalize(u1, cu21, rop1, &locator)
+      # the maximally reduced canonical form
+      return u1.send(rop1, cu21), cu22, rop2
+    end
+
+    # Returns the operators to apply to a canonical form according to the rules:
+    #   x * (y * z) = (x * y) * z
+    #   x * (y / z) = (x * y) / z
+    #   x / (y * z) = (x / y) / z
+    #   x / (y / z) = (x / y) * z
+    # i.e.:
+    #   redistribute_operators(:*, :*) #=> [:*, :*]
+    #   redistribute_operators(:*, :/) #=> [:*, :/]
+    #   redistribute_operators(:/, :*) #=> [:/, :/]
+    #   redistribute_operators(:/, :/) #=> [:/, :*]
+    def redistribute_operators(operator, other)
+      # not as obscure as it looks: if operator is * then there is no change to the operators since * is associative, i.e.:
+      #   x * (y * z) = (x * y) * z
+      #   x * (y / z) = (x * y) / z
+      # otherwise, operator is /. in that case, apply the rules:
+      #   x / (y * z) = (x / y) / z
+      #   x / (y / z) = (x / y) * z
+      operator == :* ? [operator, other] : (other == :* ? [:/, :/] : [:/, :*])
+    end
+  end
+end

data/lib/uom/dimension.rb

@@ -0,0 +1,39 @@
+require 'extensional'
+
+module UOM
+  # Dimension enumerates the standard Unit dimensions. These consist of the seven physical International System of Units
+  # SI base unit dimensions and an INFORMATION dimension for representing computer storage.
+  class Dimension
+    attr_accessor :label
+
+    def initialize(label)
+      @label = label
+    end
+
+    def to_s
+      @label
+    end
+  end
+
+  # A CompositeDimension combines dimensions with an operator.
+  class CompositeDimension < Dimension
+    make_extensional(Hash.new { |hash, spec| new(*spec) }) { |hash, dim| hash[dim.dimensions + [dim.operator]] = dim }
+
+    attr_reader :dimensions, :operator
+
+    # Creates a CompositeDimension from the given dimensions and operator symbol
+    def initialize(dimensions, operator)
+      @dimensions = dimensions
+      @operator = operator
+      super(create_label)
+      # add to the extent
+      CompositeDimension << self
+    end
+
+    private
+
+    def create_label
+      @dimensions.join("_#{@operator}_")
+    end
+  end
+end

data/lib/uom/dimensions.rb

@@ -0,0 +1,12 @@
+require 'uom/dimension'
+
+module UOM
+  LENGTH = Dimension.new(:length)
+  MASS = Dimension.new(:mass)
+  TEMPERATURE = Dimension.new(:temperature)
+  TIME = Dimension.new(:time)
+  ENERGY = Dimension.new(:energy)
+  INTENSITY = Dimension.new(:intensity)
+  CURRENT = Dimension.new(:current)
+  INFORMATION = Dimension.new(:information)
+end

data/lib/uom/error.rb

@@ -0,0 +1,3 @@
+module UOM
+  class MeasurementError < StandardError; end
+end

data/lib/uom/factor.rb

@@ -0,0 +1,55 @@
+require 'extensional'
+require 'uom/error'
+
+module UOM
+  # A Factor designates a Unit mangnitude along a dimensional axis.
+  class Factor
+    make_extensional do |hash, factor|
+      hash[factor.label] = factor if factor.label
+      hash[factor.abbreviation] = factor if factor.abbreviation
+    end
+
+    attr_reader :label, :abbreviation, :converter
+
+    # Creates a Factor with the given label, abbreviations and conversion multiplier or block.
+    # The multiplier is the amount of this factor in the base factor.
+    # For example, KILO and MILLI are defined as:
+    #   KILO = Factor.new(:kilo, :k, UNIT, 1000)
+    #   MILLI = Factor.new(:milli, :m, UNIT, .001)
+    # The +KILO+ definition is the same as:
+    #   Factor.new(:kilo, :k, UNIT) { |unit| unit * 1000 }
+    # This definition denotes that one kilo of a unit equals 1000 of the units.
+    def initialize(label, abbreviation, base, multiplier=nil, &converter) # :yields: factor
+      @label = label
+      @abbreviation = abbreviation
+      @base = base
+      @converter = converter
+      @converter ||= lambda { |n| n * multiplier } if multiplier
+      # add this Factor to the extent
+      Factor << self
+    end
+
+    # Returns the multiplier which converts this Factor into the given factor.
+    def as(factor)
+      if factor == self or (@converter.nil? and factor.converter.nil?) then
+        1.0
+      elsif @converter.nil? then
+        1.0 / factor.as(self)
+      elsif factor == @base then
+        @converter.call(1)
+      else
+        self.as(@base) * @base.as(factor)
+      end
+    end
+
+    def to_s
+      label.to_s
+    end
+
+    def inspect
+      content = "#{label}"
+      content += ", #{abbreviation}" if abbreviation
+      "#{self.class.name}@#{self.object_id}[#{content}]"
+    end
+  end
+end

data/lib/uom/factors.rb

@@ -0,0 +1,32 @@
+require 'uom/factor'
+
+module UOM
+  # the metric scaling factors
+  UNIT = Factor.new(nil, nil, nil) # the anonymous unit factor
+  DECI = Factor.new(:deci, :d, UNIT, 0.1)
+  CENTI = Factor.new(:centi, :c, UNIT, 0.01)
+  MILLI = Factor.new(:milli, :m, UNIT, 0.001)
+  MICRO = Factor.new(:micro, :u, MILLI, 0.001)
+  NANO = Factor.new(:nano, :n, MICRO, 0.001)
+  PICO = Factor.new(:pico, :p, NANO, 0.001)
+  FEMTO = Factor.new(:femto, :f, PICO, 0.001)
+  ATTO = Factor.new(:atto, :a, FEMTO, 0.001)
+  ZEPTO = Factor.new(:zepto, :z, ATTO, 0.001)
+  YOCTO = Factor.new(:yocto, :y, ZEPTO, 0.001)
+  DECA = Factor.new(:deca, :da, UNIT, 10)
+  HECTO = Factor.new(:hecto, :h, UNIT, 100)
+  KILO = Factor.new(:kilo, :k, UNIT, 1000)
+  MEGA = Factor.new(:mega, :M, KILO, 1000)
+  GIGA = Factor.new(:giga, :G, MEGA, 1000)
+  TERA = Factor.new(:tera, :T, GIGA, 1000)
+  PETA = Factor.new(:peta, :P, TERA, 1000)
+  EXA = Factor.new(:exa, :E, PETA, 1000)
+  ZETTA = Factor.new(:zetta, :Z, EXA, 1000)
+  YOTTA = Factor.new(:yotta, :Y, ZETTA, 1000)
+
+  # All metric factors.
+  METRIC_FACTORS = [YOTTA, ZETTA, EXA, TERA, GIGA, MEGA, KILO, HECTO, DECA, DECI, CENTI, MILLI, MICRO, NANO, PICO, FEMTO, ATTO, ZEPTO, YOCTO]
+
+  # Factors commonly used in electronics
+  ELECTRONIC_FACTORS = [MILLI, MICRO, NANO, PICO, TERA, GIGA, MEGA, KILO]
+end

data/lib/uom/measurement.rb

@@ -0,0 +1,127 @@
+require 'forwardable'
+require 'uom/error'
+require 'uom/units'
+
+module UOM
+  # Measurement qualifies a quantity with a unit.
+  class Measurement
+    extend Forwardable
+
+    attr_reader :quantity, :unit
+
+    # Creates a new Measurement with the given quantity and unit label, e.g.:
+    #   Measurement.new(:mg, 4) #=> 4 mg
+    def initialize(unit, quantity)
+      unit = UOM::Unit.for(unit) if Symbol === unit
+      @quantity = quantity
+      @unit = unit
+      @unit_alias = unit unless unit == @unit.label
+    end
+
+    # numeric operators without an argument delegate to the quantity
+    unary_operators = Numeric.instance_methods(false).map { |method| method.to_sym }.select { |method| Numeric.instance_method(method).arity.zero? } + [:to_i, :to_f]
+    def_delegators(:@quantity, *unary_operators)
+
+    # numeric operators with an argument apply to the quantity and account for a Measurement argument
+    binary_operators = Numeric.instance_methods(false).map { |method| method.to_sym }.select { |method| Numeric.instance_method(method).arity == 1 } + [:+, :-, :*, :/, :==, :<=>, :eql?]
+    binary_operators.each { |method| define_method(method) { |other| apply_to_quantity(method, other) } }
+    [:+, :-, :==, :<=>, :div, :divmod, :quo, :eql?].each { |method| define_method(method) { |other| apply_to_quantity(method, other) } }
+
+    def ==(other)
+      return quantity == other unless Measurement === other
+      unit == other.unit ? quantity == other.quantity : other.as(unit) == self
+    end
+
+    # Returns the product of this measurement and the other measurement or Numeric.
+    # If other is a Measurement, then the returned Measurement Unit is the product of this
+    # Measurement's unit and the other Measurement's unit.
+    def *(other)
+      compose(:*, other)
+    end
+
+    # Returns the quotient of this measurement and the other measurement or Numeric.
+    # If other is a Measurement, then the returned Measurement Unit is the quotient of this
+    # Measurement's unit and the other Measurement's unit.
+    def /(other)
+      compose(:/, other)
+    end
+
+    # Returns a new Measurement which expresses this measurement as the given unit.
+    def as(unit)
+      unit = UOM::Unit.for(unit.to_sym) if String === unit or Symbol === unit
+      return self if @unit == unit
+      Measurement.new(unit, @unit.as(quantity, unit))
+    end
+
+    def to_s
+      unit = @unit_alias || unit.to_s(quantity)
+      unit_s = unit.to_s
+      suffix = quantity == 1 ? unit_s : unit_s.pluralize
+      "#{quantity} #{suffix}"
+    end
+
+    private
+
+    # Returns a new Measurement whose unit is this Measurement's unit and quantity is the
+    # result of applying the given method to this Measurement's quantity and the other quantity.
+    #
+    # If other is a Measurement, then the operation argument is the other Measurement quantity, e.g.:
+    #   Measurement.new(:g, 3).apply(Measurement.new(:mg, 2000), :div) #=> 1 gram
+    def apply_to_quantity(method, other)
+      other = other.as(unit).quantity if Measurement === other
+      new_quantity = block_given? ? yield(to_f, other) : to_f.send(method, other)
+      Measurement.new(unit, new_quantity)
+    end
+
+    # Returns the application of method to this measurement and the other measurement or Numeric.
+    # If other is a Measurement, then the returned Measurement Unit is the composition of this
+    # Measurement's unit and the other Measurement's unit.
+    def compose(method, other)
+     return apply_to_quantity(method, other) unless Measurement === other
+     other = other.as(unit) if other.unit.axis == unit.axis
+     new_quantity = quantity.zero? ? 0.0 : quantity.to_f.send(method, other.quantity)
+     Measurement.new(unit.send(method, other.unit), new_quantity)
+    end
+  end
+end
+
+class String
+  # Returns the Measurement parsed from this string, e.g.:
+  #   "1 gm".to_measurement.unit #=> grams
+  # If no unit is discernable from this string, then the default unit is used.
+  #
+  # Raises MeasurementError if there is no unit in either this string or the argument.
+  def to_measurement(default_unit=nil)
+    stripped = strip.delete(',')
+    quantity_s = stripped[/[.\d]*/]
+    quantity = quantity_s =~ /\./ ? quantity_s.to_f : quantity_s.to_i
+    unit_s = stripped[quantity_s.length..-1] if quantity_s.length < length
+    unit_s ||= default_unit.to_s if default_unit
+    raise UOM::MeasurementError.new("Unit could not be determined from #{self}") if unit_s.nil?
+    unit_s = unit_s.sub('/', '_per_')
+    unit = UOM::Unit.for(unit_s.strip.to_sym)
+    UOM::Measurement.new(unit, quantity)
+  end
+
+  # Returns this String as a unitized quantity.
+  # If this is a numerical String, then it is returned as a Numeric.
+  # Commas and a non-numeric prefix are removed if present.
+  # Returns nil if this is not a measurement string.
+  # If unit is given, then this method converts the measurement to the given unit.
+  def to_measurement_quantity(unit=nil)
+    # remove commas
+    return to_measurement_quantity(delete(',')) if self[',']
+    # extract the quantity portion
+    quantity_s = self[/\d*\.?\d*/]
+    return if quantity_s.nil? or quantity_s == '.'
+    quantity = quantity_s['.'] ? quantity_s.to_f : quantity_s.to_i
+    # extract the unit portion
+    unit_s = self[/([[:alpha:]]+)(\s)?$/, 1]
+    return quantity if unit_s.nil?
+    # make the measurement
+    msmt = "#{quantity} #{unit_s.downcase}".to_measurement
+    # return the measurement quantity
+    msmt = msmt.as(unit) if unit
+    msmt.quantity
+  end
+end

data/lib/uom/unit.rb

@@ -0,0 +1,213 @@
+require 'set'
+require 'active_support/inflector'
+require 'extensional'
+require 'uom/factors'
+require 'uom/unit_factory'
+
+module UOM
+  # A Unit demarcates a standard magnitude on a Measurement Dimension.
+  # A _base_ unit is an unscaled dimensional Unit, e.g. METER.
+  # A _derived_ unit is composed of other units. The derived unit includes
+  # a required dimensional _axis_ unit and an optional _scalar_ Factor,
+  # e.g. the +millimeter+ unit is derived from the +meter+ axis and the
+  # +milli+ scaling factor.
+  #
+  # The axis is orthogonal to the scalar. There is a distinct unit for each
+  # axis and scalar. The base unit specifies the permissible scalar factors.
+  class Unit
+    @factory = UnitFactory.new
+
+    # make the extension label=>Unit hash. this hash creates a new Unit on demand
+    make_extensional(Hash.new { |hash, label| @factory.create(label) }) { |hash, unit| add_to_extent(hash, unit) }
+
+    attr_reader :label, :scalar, :axis, :abbreviations, :dimension, :permissible_factors
+
+    # Creates the Unit with the given label and parameters. The params include the following:
+    # * a unit label followed by zero, one or more Symbol unit abbreviations
+    # * one or more Dimension objects for a basic unit
+    # * an optional axis Unit for a derived unit
+    # * an optional scaling Factor for a derived unit
+    # * an optional normalization multiplier which converts this unit to the axis
+    # For example, a second is defined as:
+    #   SECOND = Unit.new(:second, :sec, Dimension::TIME, MILLI, MICRO, NANO, PICO, FEMTO)
+    # and a millisecond is defined as:
+    #   Unit.new(MILLI, UOM::SECOND)
+    # In most cases, a derived unit does not need to define a label or abbreviation
+    # since these are inferred from the axis and factor.
+    def initialize(*params, &converter)
+      # this long initializer ensures that every unit is correct by construction
+      # the first symbol is the label
+      labels = params.select { |param| Symbol === param }
+      @label = labels.first
+      # a Numeric parameter indicates a conversion multiplier instead of a converter block
+      multiplier = params.detect { |param| Numeric === param }
+      if multiplier then
+        # there can't be both a converter and a multiplier
+        if converter then
+          raise MeasurementError.new("Derived unit #{label} specifies both a conversion multiplier constant and a converter block")
+        end
+        # make the converter block from the multiplier
+        converter = lambda { |n| n * multiplier }
+      end
+      # the optional Factor parameters are the permissible scaling factors
+      factors = params.select { |param| Factor === param }.to_set
+      # a convertable unit must have a unique factor
+      if converter and factors.size > 1 then
+        raise MeasurementError.new("Derived unit #{label} can have at most one scalar: #{axes.join(', ')}")
+        @permissible_factors = []
+      else
+        @permissible_factors = factors
+      end
+      # the optional single Unit parameter is the axis for a derived unit
+      axes = params.select { |param| Unit === param }
+      raise MeasurementError.new("Unit #{label} can have at most one axis: #{axes.join(', ')}") if axes.size > 1
+      @axis = axes.first
+      # validate that a convertable unit has an axis; the converter argument is an axis quantity
+      raise MeasurementError.new("Derived unit #{label} has a converter but does not have an axis unit") if @default_converter and @axis.nil?
+      # the axis of an underived base unit is the unit itself
+      @axis ||= self
+      # validate that there is not a converter on self
+      raise MeasurementError.new("Unit #{label} specifies a converter but not a conversion unit") unless converter.nil? if @axis == self
+      # the default converter for a derived unit is identity
+      converter ||= lambda { |n| n } unless @axis == self
+      # the scalar is the first specified factor, or UNIT if there are multiple permissible factors
+      @scalar = @permissible_factors.size == 1 ? @permissible_factors.to_a.first : UNIT
+      # validate the scalar
+      if @axis == self then
+        #a derived unit cannot have a scalar factor
+        raise MeasurementError.new("Base unit #{label} cannot have a scalar value - #{@scalar}") unless @scalar == UNIT
+      elsif @scalar != UNIT and not @axis.permissible_factors.include?(@scalar) then
+        # a derived unit scalar factor must be in the axis permissible factors
+        raise MeasurementError.new("Derived unit #{label} scalar #{scalar} not a #{@axis} permissible factor #{@axis.permissible_factors.to_a.join(', ')}")
+      end
+      # if a scalar is defined, then adjust the converter
+      scaled_converter = @scalar == UNIT ? converter : lambda { |n| @scalar.as(@axis.scalar) * converter.call(n) } 
+      # add the axis converter to the converters hash
+      @converters = {}
+      @converters[@axis] = scaled_converter if converter
+      # define the multiplier converter inverse
+      @axis.add_converter(self) { |n| 1.0 / scaled_converter.call(1.0 / n) } unless @scalar.nil? and multiplier.nil?
+      # make the label from the scalar and axis
+      @label ||= create_label
+      # validate label existence
+      raise MeasurementError.new("Unit does not have a label") if self.label.nil?
+      # validate label uniqueness
+      if Unit.extent.association.has_key?(@label) then
+        raise MeasurementError.new("Unit label #{@label} conflicts with existing unit #{Unit.extent.association[@label].inspect}")
+      end
+      # get the dimension
+      dimensions = params.select { |param| Dimension === param }
+      if dimensions.empty? then
+        # a base unit must have a dimension
+        raise MeasurementError.new("Base unit #{label} is missing a dimension") if @axis == self
+        # a derived unit dimension is the axis dimension
+        @dimension = axis.dimension
+      elsif dimensions.size > 1 then
+        # there can be at most one dimension
+        raise MeasurementError.new("Unit #{label} can have at most one dimension")
+      else
+        # the sole specified dimension
+        @dimension = dimensions.first
+      end
+      # the remaining symbols are abbreviations
+      @abbreviations = labels.size < 2 ? [] : labels[1..-1]
+      # validate abbreviation uniqueness
+      conflict = @abbreviations.detect { |abbrev| Unit.extent.association.has_key?(abbrev) }
+      raise MeasurementError.new("Unit label #{@label} conflicts with an existing unit") if conflict
+      # add this Unit to the extent
+      Unit << self
+    end
+
+    # Returns the Unit which is the basis for a derived unit.
+    # If this unit's axis is the axis itself, then that is the basis.
+    # Otherwise, the basis is this unit's axis basis. 
+    def basis
+      basic? ? self : axis.basis
+    end
+
+    # Returns whether this unit's axis is the unit itself.
+    def basic?
+      self == axis
+    end
+
+    def add_abbreviation(abbrev)
+      @abbreviations << abbrev.to_sym
+      Unit.extent.association[abbrev] = self
+    end
+
+    # Defines a conversion from this unit to the other unit.
+    def add_converter(other, &converter)
+      @converters[other] = converter
+    end
+
+    # Returns a division CompositeUnit consisting of this unit and the other unit, e.g.:
+    #   (Unit.for(:gram) / Unit.for(:liter)).label #=> gram_per_liter
+    def /(other)
+      CompositeUnit.for(self, other, :/)
+    end
+
+    # Returns a product CompositeUnit consisting of this unit and the other unit, e.g.:
+    #   (Unit.for(:pound) * Unit.for(:inch)).label #=> foot_pound
+    def *(other)
+      CompositeUnit.for(self, other, :*)
+    end
+
+    # Returns the given quantity converted from this Unit into the given unit.
+    def as(quantity, unit)
+      begin
+        convert(quantity, unit)
+      rescue MeasurementError => e
+        raise MeasurementError.new("No conversion path from #{self} to #{unit} - #{e}")
+      end
+    end
+
+    def to_s(quantity=nil)
+      (quantity.nil? or quantity == 1) ? label.to_s : label.to_s.pluralize
+    end
+
+    def inspect
+      "#{self.class.name}@#{self.object_id}[#{([label] + abbreviations).join(', ')}]"
+    end
+
+    protected
+
+    def create_label
+      "#{scalar.label}#{axis.label}".to_sym
+    end
+
+    private
+
+    # Returns the given quantity converted from this Unit into the given unit.
+    def convert(quantity, unit)
+      return quantity if unit == self
+      # if there is a converter to the target unit, then call it
+      converter = @converters[unit]
+      return converter.call(quantity) if converter
+      # validate the target unit dimension
+      raise MeasurementError.new("Cannot convert #{unit} dimension #{unit.dimension} to #{self} dimension #{@dimension}") unless @dimension == unit.dimension
+      # convert via an axis pivot intermediary
+      pivot = conversion_pivot(unit)
+      pivot.as(self.as(quantity, pivot), unit)
+    end
+
+    def conversion_pivot(unit)
+      # this unit's axis is the preferred pivot unless there is no separate axis
+      return @axis unless self == @axis
+      # out of luck if there is no axis intermediary
+      raise MeasurementError.new("No converter from #{self} to #{unit}") if unit.axis == unit
+      # convert via the other unit's axis intermediary
+      unit.axis
+    end
+
+    # Utility method called by the Unit class after initialization to add this unit to the extent.
+    def self.add_to_extent(hash, unit)
+      hash[unit.label] = unit
+      hash[unit.label.to_s.pluralize.to_sym] = unit
+      unit.abbreviations.each do |abbrev|
+        hash[abbrev] = unit
+        hash[abbrev.to_s.pluralize.to_sym] = unit
+      end
+      unit
+    end
+  end
+end