numru-units 1.7.0

data/ChangeLog

@@ -0,0 +1,111 @@
+Thu Aug  4  2011  T Horinouchi
+	* version 1.7 released ((cvs) tag: numru-units-1_7)
+	* LICENSE.txt: added (BSD 2-clause)
+	* doc/units.rd, doc/units.html: updated (added entry to dcunits.txt)
+Wed Aug  3  2011  T Horinouchi
+	* mulnode.rb: to_s changed to explicitly handle a Float
+	  whose value is an integer.
+	* Makefile: adopet to the change in the "tail" command
+	  (tail +2 --> tail -n +2).
+Mon Mar 15  2010  T Horinouchi
+	* version 1.6 released ((cvs) tag: numru-units-1_6)
+Fri May 23  2008  T Horinouchi
+	* dcunits.txt: added the following units: percent [S], % [S],
+	   permil [S], centigrade [P], millibar [P]
+	* rules.rb: changed not to accept empty unit_spec
+	* lex.rb: 
+	  * method do_parse2: to treat empty string units '' as '1'
+	    (to return NumberNode.new(1) instead of ErrorNode.new(''))
+Fri Feb  8  2008  T Koshiro
+	* lex.rb: next_token: at least one space or tab character is required
+	  before/after 'per', 'after', 'from', 'since', 'ref'
+Wed Aug 24  2005  T Horinouchi
+	* version 1.5 released ((cvs) tag: numru-units-1_5)
+Wed Jun  8  2005  T Horinouchi
+	* lex.rb:
+	  * debug in RE_SECOND
+	  * debug in time zone parser (many bugs)
+	  * improvement in time parser RE_TIME to support hhmm type
+	    in addition to [h]h:[m]m
+	* timenode.rb: 
+	  * TimeNode#utcsod : debug in time zone treatment 
+	    (IT WAS A FATAL BUG!!)
+	  * TimeNode#to_s : debug in the expression of seconds (not to 
+	    take the floor of seconds).
+Wed May 25  2005  T Horinouchi
+	* version 1.4 released ((cvs) tag: numru-units-1_4)
+	* lex.rb: debug in RE_HOUR. It did not handle hours after 20 properly.
+Mon Nov 29  2004  T Horinouchi
+	* timenode.rb: class XDate: added to_date (for intenal usage), and
+	  modified +(ohter) and -(ohter) methods to use it as long as possible.
+	  This is to widen the coverage of time -- up to now, only very
+	  recent years (such as AD19xx-20xx) are accpeted, since the
+	  Time intrincic class is always used.
+Tue Nov  9  2004  T Horinouchi
+	* lex.rb: Units#convert2: changed warning messaging to show backtrace
+Sun Aug 10  2004  T Horinouchi
+	* lex.rb: lex.rb Units#convert, Units#==: debug not to change
+	  (reduce5) self and input units.
+Sun Aug  8  2004  T Horinouchi
+	* version 1.3 released
+	* mulnode.rb: improved Multi#sort: to eliminate Number[1] if
+	  length >= 2. Then, Units.new('1m').reduce5.to_s gives 'm';
+	  it used to give '1 m'.
+	* numbernode.rb: defined == (to compare by values -- implicitly
+	  used in the new Multi#sort)
+	* dcunits.txt: added some units from udunits: Pascal, deg[KF],
+	  deg_[CFK], degree[CFK], [Cc]elcius, angular_(degree|minute|secont),
+	  [Ff]ahrenheit, farad, gravity, conventional_mercury, mercury,
+	  Hg, hg, Julian_year, common_year, tesla
+	* lex.rb: debug === (aliased to ==. The change on May 4 was enbug).
+                  debug =~: to handle other classes (return false)
+Tue May  4  2004  T Horinouchi
+	* pownode.rb: PowNode#to_s: if the expopnent is 1, omit it.
+	* lex.rb: debug === (to allow a difference of a factor and/or offset)
+Sun May  2  2004  T Horinouchi
+	* dcunits.txt: added degree_east/degrees_east etc.
+Sun Mar 21  2004  T Horinouchi
+	* version 1.2 released ((cvs) tag: numru-units-1_2)
+Fri Mar 19  2004  T Horinouchi
+	* mulnode.rb: MutiNode#value: to return 1 if @children.size == 0
+	* dcunits.txt: added degC
+	* lex.rb: convert2: warn if $VERBOSE --> warn regardress $VERBOSE
+Mon Mar  1  2004  T Horinouchi
+	* version 1.1 released ((cvs) tag: numru-units-1_1)
+Mon Mar  1  2004  E Toyoda
+	* test.rb: revised due to the change of reduce4; updated
+	* timenode.rb debugged (Unexpected generation of Float by Date#-
+	  is avoided using Date-like wrapper to Time.)
+	* node.rb: unalias (such as "kilometer" -> "10^3 m") will not
+	  occur at reduce4. (plurals still recognized in reduce4)
+	* namenode.rb,numbernode.rb: unused methods "nameable?" removed
+	* makeutab.rb: Bugfix: units like "second" or "metre" were not
+	  unaliased to its primary name (such as "s" or "m") due to
+	  improper parsing of dcunits.txt.
+Sun Feb 29  2004  E Toyoda (Commited by T Horinouchi)
+	* makeutab.rb: debug plural treatment (/y$/ -> /[^aeou]y$/)
+Fri Feb 27  2004  T Horinouchi
+	* src/lex.rb: added Units#convert2 (similar to Units#convert but
+	  more suitable for UNumeric constraction).
+	  debug in =~
+	* test.rb: added a test of =~
+Thu Feb 26  2004  T Horinouchi
+	* src/lex.rb: added Units#factor_and_offset
+	* doc/units.rd: updated
+Wed Feb 25  2004  T Horinouchi
+	* src/Makefile: add -l option to racc -- not to convert line #s
+	  for better readability of exception messages
+	* Makefile: (very minor) cp --> cp -p
+Tue Feb 24  2004  T Horinouchi
+	* version 1.0 released
+	* packaging for distribution
+	* put Units into the NumRu module ( --> class NumRu::Units )
+	* cvs version control started (CVSROOT=
+	  dennou-k.gfd-dennou.org:/GFD_Dennou_Club/ftp/arch/ruby/cvsroot
+	  project name: numru-units)
+Fri Feb  6  2004  TOYODA Eizi (log written by T Horinouchi 2004/03/24)
+	* revised
+Fri Nov  7  2003  TOYODA Eizi (log written by T Horinouchi 2004/03/24)
+	* revized
+Fri Oct 24  2003(or before) TOYODA Eizi(log written by T Horinouchi 2004/03/24)
+	* created

data/LICENSE.txt

@@ -0,0 +1,34 @@
+NumRu::Units is copyrighted free software by Takeshi Horinouchi and
+GFD Dennou Club (http://www.gfd-dennou.org/).
+
+Copyright 2011 (C) Takeshi Horinouchi and GFD Dennou Club
+(http://www.gfd-dennou.org/) All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   1. Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in
+      the documentation and/or other materials provided with the
+      distribution.
+
+THIS SOFTWARE IS PROVIDED BY GFD DENNOU CLUB AND CONTRIBUTORS ``AS IS'' 
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL GFD DENNOU CLUB OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation
+are those of the authors and should not be interpreted as representing
+official policies, either expressed or implied, of Takeshi Horinouchi
+and GFD Dennou Club.

data/Makefile

@@ -0,0 +1,14 @@
+all:
+	@(cd src && make && cp -p units.rb ../lib/numru/)
+	@(cd doc && make)
+
+install:
+	ruby install.rb
+
+test:
+	@(cd src && make test)
+
+distclean: clean
+
+clean:
+	@rm -f `find . -name "*~" -print`

data/Rakefile

@@ -0,0 +1,39 @@
+require 'rake/gempackagetask'
+
+NAME = 'numru-units'
+VER = '1.7.0'
+
+PKG_FILES = FileList[
+  '**',
+  'lib/**/*',
+  'doc/**/*',
+  'src/**/*'
+]
+
+spec = Gem::Specification.new do |s|
+  s.name             = NAME
+  s.version          = VER
+  s.authors           = ["Eizi Toyoda","Takeshi Horinouchi"]
+  s.email            = ['eriko@gfd-dennou.org']
+  s.homepage         = 'http://www.gfd-dennou.org/arch/ruby/products/numru-units/'
+  s.licenses         = ["Takeshi Horinouchi", "GFD Dennou Club"]
+  s.platform         = Gem::Platform::RUBY
+  s.summary          = %q{Class to handle units of physical quantities}
+  s.description      = %q{This is a class to handle units of physical quantities. It covers most functionality of UNIDATA's UDUNITS Library, however, with a more sophisticated handling of string expressions. See the documentation for more infomation.}
+
+  s.files            = PKG_FILES.to_a
+  s.require_paths    = ['lib']
+  #s.test_files = Dir.glob("test/*")
+  #s.has_rdoc         = true
+  s.required_ruby_version = Gem::Requirement.new(">= 1.6")
+  #s.add_runtime_dependency(%q<narray>, [">= 0"])
+  #s.add_runtime_dependency(%q<narray_miss>, [">= 0"])
+  #s.extra_rdoc_files = ['README']
+
+  #s.extensions << "install.rb"
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+  pkg.need_tar = true
+end

data/doc/Makefile

@@ -0,0 +1,5 @@
+all: units.html
+
+units.html: units.rd
+	rd2 units.rd | sed -e 's/<dt>/<dt><h4>/' -e 's/<\/dt>/<\/h4><\/dt>/' \
+           > units.html

data/doc/units.html

@@ -0,0 +1,241 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html 
+  PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>units.rd</title>
+</head>
+<body>
+<h1><a name="label-0" id="label-0">class NumRu::Units</a></h1><!-- RDLabel: "class NumRu::Units" -->
+<ul>
+<li><a href="#label-1">Overview</a></li>
+<li><a href="#label-2">Installation</a></li>
+<li><a href="#label-3">Usage Examples</a></li>
+<li><a href="#label-4">Class Methods</a></li>
+<li><a href="#label-8">Instance Methods</a></li>
+<li><a href="http://ruby.gfd-dennou.org/products/numru-units/doc/dcunits.txt">Supported units</a>  (Plural form allowed if the second field is "P")</li>
+</ul>
+<h2><a name="label-1" id="label-1">Overview</a></h2><!-- RDLabel: "Overview" -->
+<p>A class of units of physical quantities.</p>
+<p>This class covers most functionality of UNIDATA's 
+<a href="http://www.unidata.ucar.edu/packages/udunits/">UDUNITS Library</a>, 
+however, with a more sophisticated handling of string expressions. </p>
+<p>UDUNITS always decomposes units into the four base units and discards
+the original string expressions. Therefore, 'hPa' always becomes
+'100 kg.m-1.sec-1', and 'day' always becomes '86400 sec'. On the other 
+hand, this library tries to keep the original expressions as much as
+possible by default, while allowing partial to complete decompositions
+if needed.</p>
+<h2><a name="label-2" id="label-2">Installation</a></h2><!-- RDLabel: "Installation" -->
+<p>Move to the top directly of this library (where you find
+the file install.rb). Then, type in the following:</p>
+<pre>% ruby install.rb</pre>
+<h2><a name="label-3" id="label-3">Usage Examples</a></h2><!-- RDLabel: "Usage Examples" -->
+<p>Here is an example using the "irb" interactive shell ("%" is the
+command prompt, and "&gt;&gt;" is the irb prompt -- Type in those after it
+to test.  "=&gt;" shows the result.):</p>
+<pre>% irb --simple-prompt
+&gt;&gt; require "numru/units"
+=&gt; true
+&gt;&gt; un1 = NumRu::Units.new('kg.m2/s')
+=&gt; Units{kg.m2/s}
+&gt;&gt; un2 = NumRu::Units.new('g.m')
+=&gt; Units{g.m}
+&gt;&gt; un3 = un1 / un2
+=&gt; Units[Multi[Pow[Name[g], Number[-1]], Name[kg], Pow[Name[m], Number[1]], Pow[Name[s], Number[-1]]]]
+&gt;&gt; un1.to_s
+=&gt; "kg.m2/s"
+&gt;&gt; un2.to_s
+=&gt; "g.m"
+&gt;&gt; un3.to_s
+=&gt; "g-1 kg.m1 s-1"
+&gt;&gt; un3.reduce5
+=&gt; Units[Multi[Number[1000], Pow[Name[m], Number[1]], Pow[Name[s], Number[-1]]]]
+&gt;&gt; un3.to_s
+=&gt; "1000 m1 s-1"</pre>
+<p>Note the difference between the results of un3.to_s 
+before and after un3.reduce5,
+where the former retains the literal expression
+of each atomic unit, while the latter does the maximum reduction.
+You can change the default behavior by using the class method 
+reduce_level=:</p>
+<pre>&gt;&gt; NumRu::Units.reduce_level = 5
+=&gt; :reduce5
+&gt;&gt; un3.to_s
+=&gt; "1000 m1 s-1"</pre>
+<p>Note that you can eliminate the prefix NumRu:: by "including"
+it:</p>
+<pre>&gt;&gt; require "numru/units"
+=&gt; true
+&gt;&gt; include NumRu
+=&gt; Object
+&gt;&gt; un1 = Units.new('kg.m2/s')
+=&gt; Units{kg.m2/s}
+&gt;&gt; Units.reduce_level = 5
+=&gt; :reduce5</pre>
+<h2><a name="label-4" id="label-4">Class Methods</a></h2><!-- RDLabel: "Class Methods" -->
+<p>In what follows, the prefix NumRu:: is omitted for conciseness.
+See <a href="#label-3">Usage Examples</a> on this issue.</p>
+<dl>
+<dt><h4><a name="label-5" id="label-5"><code>Units.new(<var>string</var>)</code></a></h4></dt><!-- RDLabel: "Units.new" -->
+<dd>
+<p>Constructor.</p>
+<p>ARGUMENTS</p>
+<ul>
+<li>string (String): string expression of the units. 
+      [factor] units; [factor] time units [since ...] (see EXAMPLES below)</li>
+</ul>
+<p>RETURN VALUE</p>
+<ul>
+<li>a Units</li>
+</ul>
+<p>EXAMPLE</p>
+<pre>units = Units.new('kg.m2/s')
+units = Units.new('100 m')
+units = Units.new('g/kg')
+units = Units.new('hour since 2003-10-01 00:00:0 +0:00')
+units = Units.new('hour since 2003-10-01')   # same as above
+units = Units.new('minutes since 2003-10-01 03:15:22.5 -6:00')</pre></dd>
+<dt><h4><a name="label-6" id="label-6"><code>Units[string]</code></a></h4></dt><!-- RDLabel: "Units[string]" -->
+<dd>
+Same as <a href="#label-5">Units.new</a></dd>
+<dt><h4><a name="label-7" id="label-7"><code>Units.reduce_level=(<var>n</var>)</code></a></h4></dt><!-- RDLabel: "Units.reduce_level=" -->
+<dd>
+<p>Set the reduction level before <a href="#label-9">to_s</a> is applied.</p>
+<p>ARGUMENTS</p>
+<ul>
+<li>n (Integer): the reduction level. The default value is 4.
+      Use 5 if you want a full reduction. Levels lower than 4 
+      will not be needed.</li>
+</ul></dd>
+</dl>
+<h2><a name="label-8" id="label-8">Instance Methods</a></h2><!-- RDLabel: "Instance Methods" -->
+<dl>
+<dt><h4><a name="label-9" id="label-9"><code>to_s</code></a></h4></dt><!-- RDLabel: "to_s" -->
+<dd>
+Returns a string expression of the units.</dd>
+<dt><h4><a name="label-10" id="label-10"><code>*(<var>other</var>)</code></a></h4></dt><!-- RDLabel: "*" -->
+<dd>
+<p>Multiplies self with another units. 
+Applies <a href="#label-16">reduce4</a> to format the string expression of the result.</p>
+<p>ARGUMENTS</p>
+<ul>
+<li>other [Units]: the other units</li>
+</ul>
+<p>RETURN VALUE</p>
+<ul>
+<li>a Units</li>
+</ul></dd>
+<dt><h4><a name="label-11" id="label-11"><code>/(<var>other</var>)</code></a></h4></dt><!-- RDLabel: "/" -->
+<dd>
+<p>Divides self with another units.
+Applies <a href="#label-16">reduce4</a> to format the string expression of the result.</p>
+<p>ARGUMENTS</p>
+<ul>
+<li>other [Units]: the other units</li>
+</ul>
+<p>RETURN VALUE</p>
+<ul>
+<li>a Units</li>
+</ul></dd>
+<dt><h4><a name="label-12" id="label-12"><code>**(<var>pow</var>)</code></a></h4></dt><!-- RDLabel: "**" -->
+<dd>
+<p>Power.
+Applies <a href="#label-16">reduce4</a> to format the string expression of the result.</p>
+<p>ARGUMENTS</p>
+<ul>
+<li>pow [Numeric -- Integer, Rational, or Float]</li>
+</ul>
+<p>RETURN VALUE</p>
+<ul>
+<li>a Units</li>
+</ul></dd>
+<dt><h4><a name="label-13" id="label-13"><code>==(<var>other</var>)</code></a></h4></dt><!-- RDLabel: "==" -->
+<dd>
+Whether the two units are the same. 
+('m/s' and 'm.s-1' are the same, for instance.)</dd>
+<dt><h4><a name="label-14" id="label-14"><code>===(<var>other</var>)</code></a></h4></dt><!-- RDLabel: "===" -->
+<dd>
+Same as <a href="#label-13">==</a>.</dd>
+<dt><h4><a name="label-15" id="label-15"><code>=~(<var>other</var>)</code></a></h4></dt><!-- RDLabel: "=~" -->
+<dd>
+Whether the two units are compatible (i.e., with the same dimensionality).
+('m/s' and '10 m.s-1' are compatible, for instance.)</dd>
+<dt><h4><a name="label-16" id="label-16"><code>reduce4</code></a></h4></dt><!-- RDLabel: "reduce4" -->
+<dd>
+<p>Moderately reduces the string expression of the units (destructive method).
+This method preserves string expression of atomic units. 
+See also <a href="#label-17">reduce5</a>.</p>
+<p>RETURN VALUE</p>
+<ul>
+<li>self</li>
+</ul>
+<p>EXAMPLE</p>
+<pre>Untis.new('hour/hour').reduce4.to_s
+  # =&gt; "1"
+Units.new('mm/m').reduce4.to_s
+  # =&gt; "mm.m-1"</pre></dd>
+<dt><h4><a name="label-17" id="label-17"><code>reduce5</code></a></h4></dt><!-- RDLabel: "reduce5" -->
+<dd>
+<p>Aggressively reduces the string expression of the units (destructive method).
+See also <a href="#label-16">reduce4</a>.</p>
+<p>RETURN VALUE</p>
+<ul>
+<li>self</li>
+</ul>
+<p>EXAMPLE</p>
+<pre>Units.new('hour/hour').reduce4.to_s
+  # =&gt; "1"
+Units.new('mm/m').reduce5.to_s
+  # =&gt; "0.001"</pre></dd>
+<dt><h4><a name="label-18" id="label-18"><code>convert(<var>numeric</var>, <var>to_units</var>)</code></a></h4></dt><!-- RDLabel: "convert" -->
+<dd>
+<p>Converts a numeric of the current units (=self) to <var>to_units</var>.</p>
+<p>ARGUMENTS</p>
+<ul>
+<li>numeric [Numeric]: the numeric to convert</li>
+<li>to_units [Units]: the units converted into</li>
+</ul>
+<p>RETURN VALUE</p>
+<ul>
+<li>a Numeric</li>
+</ul>
+<p>EXCEPTIONS</p>
+<ul>
+<li><var>self</var> and <var>to_units</var> are incompatible.</li>
+</ul></dd>
+<dt><h4><a name="label-19" id="label-19"><code>convert2(<var>val</var>, <var>to_units</var>)</code></a></h4></dt><!-- RDLabel: "convert2" -->
+<dd>
+<p>Like <a href="#label-18">convert</a>, but (1) accpets any Numeric-like objects, and (2)
+does not raise an exception even if the two units are incompatible -- 
+in this case, simply returns <var>val</var> (warned).</p>
+<p>ARGUMENTS</p>
+<ul>
+<li>val [a Numeric-like class, for which * and + are defined]:
+      the value to convert</li>
+<li>to_units [Units]: the units converted into</li>
+</ul>
+<p>RETURN VALUE</p>
+<ul>
+<li>an object with the same class as <var>val</var>.</li>
+</ul></dd>
+<dt><h4><a name="label-20" id="label-20"><code>factor_and_offset(<var>to_units</var>)</code></a></h4></dt><!-- RDLabel: "factor_and_offset" -->
+<dd>
+<p>Returns the factor and offset to convert from <var>self</var> to <var>to_units</var>.
+The conversion is done as  scale_factor * operand + add_offset.</p>
+<p>ARGUMENTS</p>
+<ul>
+<li>to_units [Units]: the units to be converted into</li>
+</ul>
+<p>RETURN VALUE</p>
+<ul>
+<li>[ scale_factor, add_offset ] (a 2-element Array, where both are Numeric)</li>
+</ul>
+<p>EXAMPLE</p>
+<pre>scale_factor, add_offset = from_units.factor_and_offset(to_units)
+to = scale_factor * from + add_offset</pre></dd>
+</dl>
+
+</body>
+</html>