quantity 0.0.0 → 0.1.1

data/lib/quantity/all.rb

@@ -0,0 +1,8 @@
+require 'quantity'
+require 'quantity/systems/si'
+# this could just as well be 'imperial', had to pick something.
+require 'quantity/systems/us'
+require 'quantity/systems/information'
+require 'quantity/systems/enumerable'
+# other isn't done yet
+#require 'quantity/systems/other'

data/lib/quantity/dimension.rb

@@ -0,0 +1,269 @@
+class Quantity
+  # A Dimension is a measurable something.  It is often
+  # called a 'base quantity'.
+  #
+  # There are 8 base physical dimensions: Length, Mass,
+  # Current, Mass, Time, Temperature, Substance, and Luminosity.
+  # There are additionally a number of other useful dimensions,
+  # such as Enumerable items (think of 'dozen' as a unit of 
+  # measurement).
+  #
+  # From these base dimensions all other measurement dimensions
+  # can be constructed.  For example, speed is Length / Time.
+  # Such dimensions are called compound dimensions.
+  #
+  class Dimension
+    ### Class-level methods/vars
+    # all known dimensions
+    @@dimensions = {}
+
+    # The dimension for a given symbol, dimension, or string description
+    # of a compound dimension
+    # @param [String Symbol Dimension]
+    # @return [Dimension]
+    def self.for(to)
+      case to
+        when Dimension
+          if @@dimensions[to.name]
+            @@dimensions[to.name]
+          else
+            add_alias to, to.name
+            to
+          end
+        when Symbol
+          if @@dimensions.has_key?(to)
+            @@dimensions[to]
+          else
+            # it's possible we have a non-normalized form, such as mass*length 
+            # instead of length * mass
+            @@dimensions[string_form(parse_string_form(to)).to_sym]
+          end
+        when Array
+          @@dimensions[string_form(to).to_sym]
+        else
+          nil
+      end
+    end
+
+    # DSL component to add a new dimension.  Dimension name, reference unit,
+    # and aliases.  This should be the only way that dimensions are added.
+    # @param [Symbol] name
+    # @param [[Symbol String]] *aliases
+    def self.add_dimension(name, *aliases)
+      dim = nil
+      if name.is_a?(Dimension) 
+        dim = name
+        name.name = aliases.first if aliases.first
+      else
+        dim = self.for(name) || self.new({ :name => aliases.first , :description => name})
+        self.add_alias(dim,name)
+      end
+      unless (dim.class == Dimension) 
+        dim.name = dim.class.name.downcase.split(/::/).last.to_sym
+        self.add_alias(dim,dim.name)
+      end
+      self.add_alias(dim,*aliases)
+      dim
+    end
+
+    # Register a dimension to the known list, with the given aliases
+    # @param [Dimension]
+    # @param [[*names]]
+    def self.add_alias(dimension, *names)
+      names.each do |name|
+        raise ArgumentError, "Invalid dimension alias: #{name}" unless (name.to_s =~ /^(\^|\/)/).nil?
+        @@dimensions[name] = dimension
+      end
+    end
+
+    # All known dimensions
+    # @return [[Dimension]]
+    def self.all_dimensions
+      @@dimensions.values.uniq
+    end
+
+    # Reset the known dimensions.  Generally only used for testing.
+    def self.__reset!
+      @@dimensions = {}
+    end
+
+    DimensionComponent = Struct.new(:dimension, :power)
+    DimensionComponent.class_eval do
+      def inspect
+        "#{dimension.inspect}^#{power}"
+      end
+    end
+
+    attr_reader :numerators, :denominators
+    attr_accessor :name
+    ### Instance-level methods/vars
+
+    # A new dimension
+    # @param [Hash] options
+    # @return Dimension
+    def initialize(opts)
+      if (opts[:description])
+        (@numerators,@denominators) = Dimension.parse_string_form(opts[:description])
+      elsif (opts[:numerators])
+        @numerators = opts[:numerators]
+        @denominators = opts[:denominators]
+      else
+        raise ArgumentError, "Invalid options for dimension constructors"
+      end
+      raise ArgumentError, "Dimensions require a numerator" unless @numerators.first.dimension
+      @name = opts[:name] || string_form.to_sym
+      Dimension.add_alias(self,@name)
+      Dimension.add_alias(self,string_form.to_sym)
+    end
+
+    def to_s
+      @name.to_s
+    end
+
+    # Dimensional multiplication
+    # @param [Dimension] other
+    # @return [Dimension] 
+    def *(other)
+      raise ArgumentError, "Cannot multiply #{self} and #{other.class}" unless other.is_a?(Dimension)
+      (new_n, new_d) = Dimension.reduce(@numerators + other.numerators, @denominators + other.denominators)
+      existing = Dimension.for([new_n,new_d])
+      existing.nil? ? Dimension.new({:numerators => new_n, :denominators => new_d}) : existing
+    end
+
+    # Dimensional division
+    # @param [Dimension] other
+    # @return [Dimension] 
+    def /(other)
+      raise ArgumentError, "Cannot divide #{self} by #{other.class}" unless other.is_a?(Dimension)
+      (new_n, new_d) = Dimension.reduce(@numerators + other.denominators, @denominators + other.numerators)
+      existing = Dimension.for([new_n,new_d])
+      existing.nil? ? Dimension.new({:numerators => new_n, :denominators => new_d}) : existing
+    end
+
+    # Dimensional exponentiation
+    # @param [Numeric] other
+    # @return [Dimension]
+    def **(other)
+      raise ArgumentError, "Dimensions can only be raised to whole powers" unless other.is_a?(Fixnum) && other > 0
+      other == 1 ? self : self * self**(other-1)
+    end
+ 
+    # Whether or not this is a compound representation of a base dimension
+    # @return [Boolean]
+    def is_base?
+      @denominators.size == 0 && @numerators.size == 1 && @numerators.first.power == 1
+    end
+
+    # Spaceship operator for comparable.
+    # @param [Any] other
+    # @return [-1 0 1]
+    def <=>(other)
+      if other.is_a?(Dimension)
+        if self.is_base? && other.is_base?
+          name.to_s <=> other.name.to_s
+        elsif other.is_base?
+          1
+        else
+          string_form <=> other.string_form
+        end
+      else
+        nil
+      end
+    end
+
+    # Returns a developer-friendly representation of this value.
+    #
+    # The string will be of the format `#<Quantity::Dimension::0x12345678(...)>`,
+    # where `...` is the string returned by #to_s.
+    #
+    # @return [String]
+    def inspect
+      sprintf("#<%s:%#0x %s (%s)>", self.class.name, object_id, string_form, @name)
+    end
+
+
+    # Returns a vaguely human-readable and parsable description of this dimension
+    # @return [String]
+    def string_form
+      Dimension.string_form(@numerators,@denominators)
+    end
+      
+    # A vaguely human-readable, vaguely machine-readable string description of 
+    # a set of numerators and denominators.
+    # @private
+    # @ param [[DimensionComponent],[DimensionComponent]]
+    # @return [String]
+    def self.string_form(numerators, denominators = nil)
+      # We sometimes get [numerators,denominators],nil
+      (numerators,denominators) = numerators if (numerators.first.is_a?(Array))
+      string = ""
+      string_thunk = lambda do | array |
+        array.each_with_index do | component, n |
+          string << component.dimension.to_s
+          (string << '^' << component.power.to_s) if component.power.to_i > 1
+          string << '*' if n < array.size - 1
+        end
+      end
+      string_thunk.call(numerators)
+      string << "/" if denominators && denominators.size > 0
+      string_thunk.call(denominators) if denominators
+      string
+    end
+
+    # Parse the output of string_form into numerators and denominators
+    # @param [String] string
+    # @return [[DimensionComponent],[DimensionComponent]]
+    # @private
+    def self.parse_string_form(serialized)
+      parse_thunk = lambda do | string |
+        components = []
+        if !string.nil?
+          string.split(/\*/).each do | component |
+            (dimension, power) = component.split(/\^/)
+            components << DimensionComponent.new(dimension.to_sym,power.nil? ? 1 : power.to_i)
+          end
+        end
+        components
+      end
+      (top, bottom) = serialized.to_s.split(/\//) 
+      Dimension.reduce(parse_thunk.call(top), parse_thunk.call(bottom))
+    end
+
+    # Returns numerators and denominators that represent the reduced form of the given
+    # numerators and denominators
+    # @return [[Array],[Array]]
+    # @private
+    def self.reduce(numerators,denominators)
+      new_numerators = reduce_multiplied_units(numerators)
+      new_denominators = reduce_multiplied_units(denominators)
+ 
+      new_numerators.each_with_index do | comp, i |
+        new_denominators.each_with_index do | dcomp, j |
+          if dcomp.dimension == comp.dimension
+            diff = [dcomp.power,comp.power].max - (dcomp.power - comp.power).abs
+            dcomp.power -= diff
+            comp.power -= diff
+            new_numerators.delete_at(i) if comp.power <= 0
+            new_denominators.delete_at(j) if dcomp.power <= 0
+          end
+        end
+      end
+      [new_numerators, new_denominators]
+    end
+
+    # Reduce an array of units to its most compact, sorted form
+    # @param [[DimensionComponent]]
+    # @return [[DimensionComponent]]
+    # @private
+    def self.reduce_multiplied_units(array)
+      new = {}
+      array.each do | item |
+        new[item.dimension] = DimensionComponent.new(item.dimension,0) unless new[item.dimension]
+        new[item.dimension].power += item.power
+      end
+      new.values.sort { |a,b| a.dimension.to_s <=> b.dimension.to_s }
+    end
+
+
+  end
+end

data/lib/quantity/dimension/base.rb

@@ -0,0 +1,54 @@
+#
+#
+class Quantity
+  #
+  # This module attempts to enumerate all of simple, base dimensions.
+  # This includes all of the base SI dimensions and some others
+  #
+  class Dimension
+
+    class Length < Quantity::Dimension ; end
+    length = Length.add_dimension :length, :width, :distance
+
+    class Time < Quantity::Dimension ; end
+    time = Time.add_dimension :time
+
+    class Mass < Quantity::Dimension ; end
+    mass = Mass.add_dimension :mass
+
+    class Current < Quantity::Dimension ; end
+    current = Current.add_dimension :current
+
+    class Luminosity < Quantity::Dimension ; end
+    luminosity = Luminosity.add_dimension :luminosity
+
+    class Substance < Quantity::Dimension ; end
+    substance = Substance.add_dimension :substance
+
+    class Temperature < Quantity::Dimension ; end
+    temp = Temperature.add_dimension :temperature
+
+    area = add_dimension length**2, :area
+
+    speed = add_dimension length / time, :speed, :velocity
+
+    accel = add_dimension speed / time, :acceleration
+
+    force = add_dimension mass * accel, :force
+
+    volume = add_dimension length**3, :volume
+
+    class Information < Quantity::Dimension ; end
+    information = Information.add_dimension :information, :data
+
+    # Quantity is the base dimension for the quantity of enumerable objects.
+    # Units are things like '2 dozen'.
+    class Quantity < Quantity::Dimension ; end
+    information = Quantity.add_dimension :quantity, :items, :enumerables
+
+    # Hardly a scientific base measurement, but it comes up a lot
+    class Currency < Dimension ; end
+    currency = Currency.add_dimension :money
+
+  end
+end

data/lib/quantity/systems/enumerable.rb

@@ -0,0 +1,12 @@
+# a few countable quantities
+
+class Quantity
+  class Unit
+
+      add_unit :dozen, :quantity, 12, :dozens
+      add_unit :couple, :quantity, 2
+      add_unit :score, :quantity, 20, :scores
+
+  end
+end
+

data/lib/quantity/systems/imperial.rb

@@ -0,0 +1,10 @@
+# Imperial versions of british/american customary units
+class Quantity::Unit
+    add_unit :foot, :length, 304.8, :ft, :feet
+    add_unit :inch, :length, 25.4, :in, :inches
+    add_unit :yard, :length, 914.4, :yd, :yards
+    add_unit :mile, :length, 1_609_344, :miles
+
+    add_unit :pound, :mass, 453592.37, :pounds, :lb, :lbs
+    add_unit :ounce, :mass, 28349.5231, :ounces, :oz
+end

data/lib/quantity/systems/information.rb

@@ -0,0 +1,30 @@
+class Quantity
+  class Unit
+    ##
+    # @see http://en.wikipedia.org/wiki/Mebibyte
+    # @see http://en.wikipedia.org/wiki/Units_of_information
+      
+      add_unit :bit, :data, 1, :bits
+      add_unit :nibble, :data, 4, :nibbles, :nybble, :nybbles
+      add_unit :byte, :data, 8, :bytes
+
+      add_unit :kilobyte, :data, 8 * 1000, :kb, :kilobytes
+      add_unit :megabyte, :data, 8 * (1000**2), :mb, :megabytes
+      add_unit :gigabyte, :data, 8 * (1000**3), :gb, :gigabytes
+      add_unit :terabyte, :data, 8 * (1000**4), :tb, :terabytes
+      add_unit :petabyte, :data, 8 * (1000**5), :pb, :petabytes
+      add_unit :exabyte, :data, 8 * (1000**6), :exabytes
+      add_unit :zettabyte, :data, 8 * (1000**7), :zettabytes
+      add_unit :yottabyte, :data, 8 * (1000**8), :yottabytes
+
+      add_unit :kibibyte, :data, 8 * 1024, :kibibytes, :KiB, :kib
+      add_unit :mebibyte, :data, 8 * (1024**2), :mebibytes, :MiB, :mib
+      add_unit :gibibyte, :data, 8 * (1024**3), :gibibytes, :GiB, :gib
+      add_unit :tebibyte, :data, 8 * (1024**4), :tebibytes, :TiB, :tib
+      add_unit :pebibyte, :data, 8 * (1024**5), :pebibytes, :PiB, :pib
+      add_unit :exbibyte, :data, 8 * (1024**6), :exbibytes, :EiB, :eib
+      add_unit :zebibyte, :data, 8 * (1024**7), :zebibytes, :ZiB, :zib
+      add_unit :yobibyte, :data, 8 * (1024**8), :yobibytes, :YiB, :yib
+
+  end
+end

data/lib/quantity/systems/si.rb

@@ -0,0 +1,105 @@
+require 'quantity/dimension/base'
+
+# SI units for Length, Mass, Luminosity, Current, Substance,
+# Temperature, and Time.  Units from yocto- to yotta- are supplied.
+# 
+# Also supplied:
+#  * Ångstroms are supplied for Length. (use angstrom or angstroms)
+#  * Tonnes (Metric) are supplied for mass.
+#  * cc's for volume
+#
+# Volume (liters) is also part of this, since it follows the same pattern, 
+# even though the SI considers it a derived unit.
+#
+# The 'reference' unit is milli-.  Units larger than milli-
+# constructed via Fixnums/Bignums, such as 2.meters, will be stored with 
+# Fixnum / Bignum accuracy.  Smaller items, such as 35.femtometers, will 
+# be stored with rationals or floats.  Generally speaking, you shouldn't
+# have to worry about this--use the numbers, and it will Do The Right Thing.
+# Do remember that you may need to do a .to_f before dividing if that's
+# what you want.
+#
+# @see http://physics.nist.gov/cuu/Units/units.html
+# @see http://physics.nist.gov/cuu/Units/current.html
+# @see http://physics.nist.gov/cuu/Units/prefixes.html
+class Quantity
+  class Unit
+
+  prefixes = {}
+  units = {}
+  aliases = {}
+
+  prefixes['yotta'] = 10 ** 27
+  prefixes['zetta'] = 10 ** 24
+  prefixes['exa'] = 10 ** 21
+  prefixes['peta'] = 10 ** 18
+  prefixes['tera'] = 10 ** 15
+  prefixes['giga'] = 10 ** 12
+  prefixes['mega'] = 10 ** 9
+  prefixes['kilo'] = 10 ** 6
+  prefixes['hecto'] = 10 ** 5
+  prefixes['deca'] = 10 ** 4
+  prefixes[''] = 10 ** 3
+  prefixes['deci'] = 10 ** 2
+  prefixes['centi'] = 10
+  # milli is the reference point for SI-measured units
+  prefixes['milli'] = 1
+  prefixes['micro'] = 10 ** -3
+  prefixes['nano'] = 10 ** -6
+  prefixes['pico'] = 10 ** -9
+  prefixes['femto'] = 10 ** -12
+  prefixes['atto'] = 10 ** -15
+  prefixes['zepto'] = 10 ** -18
+  prefixes['yocto'] = 10 ** -21
+
+  units['meter']    = :length
+  units['gram']     = :mass
+  units['second']   = :time
+  units['kelvin']   = :temperature
+  units['candela']  = :luminosity
+  units['ampere']   = :current
+  units['mole']     = :substance
+  # liter is a special cased, handled separately below
+
+  aliases['ampere'] = ['amp', 'amps', 'A']
+  aliases['liter'] = ['litre', 'litres']
+  aliases['candela'] = ['cd']
+  aliases['mole'] = ['mol']
+  aliases['kelvin'] = ['K']
+
+  units.each do | unit, dimension |
+    prefixes.each do | prefix, value |
+      add_unit "#{prefix + unit}".to_sym, dimension, value, "#{prefix + unit}s".to_sym
+      if aliases[unit]
+        aliases[unit].each do | unit_alias |
+          add_alias "#{prefix + unit}".to_sym, "#{prefix + unit_alias}".to_sym
+        end
+      end
+    end
+  end
+
+  add_alias :kilometer, :km
+  add_alias :centimeter, :cm
+  add_alias :meter, :m
+  add_alias :nanometer, :nm
+  add_alias :millimeter, :mm
+  add_alias :millisecond, :ms
+  add_unit :angstrom, :length, 10 ** -7, :angstroms
+
+  add_alias :kilogram, :kg
+  add_alias :gram, :g
+  add_alias :milligram, :mg
+  add_alias :megagram, :tonne, :tonnes
+
+
+  prefixes.each do | prefix, value |
+    add_unit "#{prefix}liter".to_sym, :volume, value * 1000, "#{prefix}liters".to_sym
+    (aliases['liter']).each do | unit_alias |
+      add_alias "#{prefix}liter".to_sym, "#{prefix + unit_alias}".to_sym
+    end
+  end
+  add_alias :liter, :l
+  add_alias :milliliter, :ml
+
+  end
+end