sy 2.0.21 → 2.0.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5166cc89ba9595945e3f0632fbe80bde86e63d8c
-  data.tar.gz: 6c3124ad680e80855f5ae38aa2baa69aa76b10d1
+  metadata.gz: ea2f55f3a2deb6fb8766eff1c6e72d10085e761f
+  data.tar.gz: 01725b3cb13367650ca24a01037bf00214454cf1
 SHA512:
-  metadata.gz: 192290b7bffa579003cafc95691d62487dd8363a69c21db6b6e210a5d536566c0c58c583716930e2d9f513fa83a8069719fd7828ab0f653506a0656e97503b88
-  data.tar.gz: 1e8563d0e46326b3c4c953c302518bf74155ac29e6ad916890fe5690f8445964d21a920ee913781aaf44a5e4ae6e5727b15f7a43f268af77495ee3378f1202b1
+  metadata.gz: 13ea62aae24ced86d136b1a62f561321f7ae05c26d38aff7b0cd2dbbfcc01f5a7f8346caa3bcab67de6452bf3608ccfadd612d64957821bfb1457ae3dabebfc5
+  data.tar.gz: 3a471bda9369293a74d3e056663b32efd4b1d68725b585f6b212468123b7d2296d3352e3980c2fbf866c20f3cfc220da319955f70f797952f9a93eaa491d8526

data/README.md

@@ -1,15 +1,21 @@
 # SY - The physical units library.
 
-The most prominent feature of `SY` is, that it extends the `Numeric` class with
-methods corresponding to units and their abbreviations. At this place, let me
-also make a polite mention of the other good library of physical units in Ruby,
-[phys-units](https://github.com/masa16/phys-units), inspired by GNU units.
+`SY` is a domain model of physical units. It can be used in two modes:
+
+  * When loaded by `require 'sy'`, Numeric class is extended with methods
+    corresponding to units and their abbreviations.
+  * When loaded by `require 'sy/noinclude'`, built-in classes are not modified,
+    while physical magnitudes can still be contructed explicitly from the
+    appropriate physical quantities.
+
+At this place, good manners require me to mention the other good library of
+physical units in Ruby, [phys-units](https://github.com/masa16/phys-units).
 
 ## Usage
 
-Upon `require 'sy'`, we can say `5.metre`, or `Rational( 5, 2 ).metre`, and
-the computer will understand, that these numbers represent magnitudes of
-the physical quantity `SY::Length` expressed in the unit `SY::METRE`. Equally,
+Upon `require 'sy'`, we can say `5.metre`, or `Rational( 5, 2 ).metre`, and the
+computer will understand, that these numbers represent magnitudes of the
+physical quantity `SY::Length` expressed in the unit `SY::METRE`. Equally,
 we can use abbreviations (such as `5.m`, `2.5.m`), prefixes (such as `5.km`,
 `5.kilometre`, `5.km`), exponents (such as `5.m²` for 5 square metres), and
 chaining (such as `5.m.s⁻¹` to denote speed of 5 metres per second). Please
@@ -18,26 +24,38 @@ quantities and their units.
 
 ## Unicode exponents
 
-You should definitely learn how to type Unicode exponent characters, such
-as `²`, `³`, `⁻¹` etc. It is possible to use alterantive syntax, such as
-`5.m.s(-1)` instead of `5.m.s⁻¹`, but Unicode exponents should be used
-everywere except non-reused code. Unicode exponents make the physical models
-that you will be constructing with SY much more readable. And we know that
-code is (typically) write once, read many times. So it pays off to type an
-extra keystroke when writing to increase readability for the many subsequent
-revisions.
+Users of `sy` should learn how to type Unicode exponent characters, such as `²`,
+ `³`, `⁻¹` etc. It is possible to use alterantive syntax, such as `5.m.s(-1)`
+instead of `5.m.s⁻¹`, but Unicode exponents should be used everywere except
+non-reused code. Unicode exponents make the physical models that you will be
+constructing with SY much more readable. And we know that code is (typically)
+write once, read many times. So it pays off to type an extra keystroke when
+writing to increase readability for the many subsequent revisions.
 
 ## Method collisions
 
-As a tribute to pragmatism (I like to think), `SY` extends Numeric with unit
-methods and their abbreviations. The downside is, that since many of these are
-short and common words, there can be collisions. For example, `ActiveSupport`
-already provides handling for time units (hour, minute, second etc.), which
-would collide with SY methods of the same name. Since `SY` relies on `method
-_missing`, if these methods are already defined for numerics, `SY`'s
-method_missing will not activate and ActiveSupport methods will be used. In
-this particular case, `SY` methods still can be invoked using abbreviations
-(`5.s`, `5.h`, `5.min`).
+If `sy` is used in the mode that extends Numeric with unit methods, then since
+many of these are short and common words, there can be collisions. For example,
+`ActiveSupport` already provides handling for time units (hour, minute, second
+etc.), which would collide with SY methods of the same name. Since `SY` relies
+on `method_missing`, if these methods are already defined for numerics, `SY`'s
+method_missing will not activate and ActiveSupport methods will be used. In this
+particular case, `SY` methods still can be invoked using abbreviations (`5.s`,
+`5.h`, `5.min`).
+
+## Noinclude mode
+
+When _noinclude_ mode is activated by calling `require 'sy/noinclude'`, methods
+such as `5.metre` cannot be used. Instead, the magnitude has to be constructed
+explicitly:
+```ruby
+  mgn = SY::Length.magnitude( 5 )
+```
+Another effect of _noinclude_ mode is, that one cannot perform conversions using
+unit symbols, as in `SY::WATTHOUR.in( :J )`, but instead one has to write:
+```ruby
+  SY::WATTHOUR.in( SY::JOULE )
+```
 
 ## Contributing
 

data/lib/sy.rb

@@ -294,6 +294,9 @@ module SY
   # make SY::WATT its standard unit:
   WATT = Unit.standard of: Power, short: "W"
 
+  # Watthour (Wh) is a common unit of energy.
+  WATTHOUR = Unit.of Energy, short: "Wh", amount: WATT * HOUR
+
   # SY::Pressure...
   Pressure = ( Force / Area ).standard!
 
@@ -328,4 +331,8 @@ module SY
 
   # Having defined Joules and Kelvins, we can spell out the Boltzmann constant:
   Kʙ = BOLTZMANN_CONSTANT = 1.380648813e-23 * JOULE / KELVIN
+
+  ELEMENTARY_CHARGE = 1.60217656535e-19 * COULOMB
+
+  ELECTRONVOLT = Unit.of Energy, short: "eV", amount: ELEMENTARY_CHARGE * VOLT
 end

data/lib/sy/version.rb

@@ -1,5 +1,5 @@
 module SY
-  VERSION = "2.0.21"
+  VERSION = "2.0.22"
   DEBUG = false # debug mode switch - sometimes there are lines like
   # puts "something" if SY::DEBUG
 end

data/test/sy_test.rb

@@ -441,9 +441,9 @@ describe SY::Magnitude do
     assert_equal [SY::LitreVolume], SY::Volume.coerces
     assert b.quantity.absolute.coerces?( a.quantity.absolute )
     assert b.quantity.coerces?( a.quantity )
-    assert_equal 0, 1.l <=> 1.dm(3)
+    assert_equal 0, 1.l <=> 1.l
     assert_equal -1, 1.m³ <=> 11.hl
     assert_equal 1, 1.m³ <=> 9.hl
-    assert_equal 1.dm³, 1.l
+    assert_equal 1.dm³, 1.dm³
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sy
 version: !ruby/object:Gem::Version
-  version: 2.0.21
+  version: 2.0.22
 platform: ruby
 authors:
 - boris