@lhncbc/ucum-lhc 4.1.8 → 4.2.0

package/browser-dist/ucum-lhc.js

@@ -86,14 +86,14 @@ var Ucum = {
    * displaying messages on a web site; should be blank when output is
    * to a file.
    */
-  openEmphHTML_: '<span class="emphSpan">',
+  openEmphHTML_: ' <span class="emphSpan">',
 
   /**
    * Closing HTML used to emphasize portions of error messages.  Used when
    * displaying messages on a web site; should be blank when output is
    * to a file.
    */
-  closeEmphHTML_: '</span>',
+  closeEmphHTML_: '</span> ',
 
   /**
    * Message that is displayed when annotations are included in a unit
@@ -1817,6 +1817,81 @@ var UcumLhcUtils = /*#__PURE__*/function () {
       return returnObj;
     } // end convertUnitTo
 
+    /**
+     *  Converts the given unit string into its base units, their exponents, and
+     *  a magnitude, and returns that data.
+     * @param fromUnit the unit string to be converted to base units information
+     * @param fromVal the number of "from" units to be converted
+     * @returns an object with the properties:
+     *  'msg': an array of one or more messages, if the string is invalid or
+     *        an error occurred, indicating the problem, or a suggestion of a
+     *        substitution such as the substitution of 'G' for 'Gauss', or
+     *        an empty array if no messages were generated.  If this is not empty,
+     *        no other information will be returned.
+     *  'magnitude': the new value when fromVal units of fromUnits is expressed in the base units.
+     *  'fromUnitIsSpecial': whether the input unit fromUnit is a "special unit"
+     *         as defined in UCUM.  This means there is some function applied to convert
+     *         between fromUnit and the base units, so the returned magnitude is likely not
+     *         useful as a scale factor for other conversions (i.e., it only has validity
+     *         and usefulness for the input values that produced it).
+     *  'unitToExp': a map of base units in uStr to their exponent
+     */
+
+  }, {
+    key: "convertToBaseUnits",
+    value: function convertToBaseUnits(fromUnit, fromVal) {
+      var inputUnitLookup = this.getSpecifiedUnit(fromUnit, 'validate');
+      var retObj = {};
+      var unit = inputUnitLookup.unit;
+      retObj.msg = inputUnitLookup.retMsg || [];
+
+      if (!unit) {
+        var _inputUnitLookup$retM;
+
+        if (((_inputUnitLookup$retM = inputUnitLookup.retMsg) === null || _inputUnitLookup$retM === void 0 ? void 0 : _inputUnitLookup$retM.length) == 0) retObj.msg.push('Could not find unit information for ' + fromUnit);
+      } else if (unit.isArbitrary_) {
+        retObj.msg.push('Arbitrary units cannot be converted to base units or other units.');
+      } else if (retObj.msg.length == 0) {
+        var _unit$dim_, _retUnitLookup$retMsg;
+
+        var unitToExp = {};
+        var dimVec = (_unit$dim_ = unit.dim_) === null || _unit$dim_ === void 0 ? void 0 : _unit$dim_.dimVec_;
+        var baseUnitString = '1';
+
+        if (dimVec) {
+          var dimVecIndexToBaseUnit = UnitTables.getInstance().dimVecIndexToBaseUnit_;
+
+          for (var i = 0, len = dimVec.length; i < len; ++i) {
+            var exp = dimVec[i];
+
+            if (exp) {
+              unitToExp[dimVecIndexToBaseUnit[i]] = exp;
+              baseUnitString += '.' + dimVecIndexToBaseUnit[i] + exp;
+            }
+          }
+        } // The unit might have a conversion function, which has to be applied; we
+        // cannot just assume unit_.magnitude_ is the magnitude in base units.
+
+
+        var retUnitLookup = this.getSpecifiedUnit(baseUnitString, 'validate'); // There should not be any error in retUnitLookup, unless there is a bug.
+
+        var retUnit = retUnitLookup.unit;
+        if (!retUnit && ((_retUnitLookup$retMsg = retUnitLookup.retMsg) === null || _retUnitLookup$retMsg === void 0 ? void 0 : _retUnitLookup$retMsg.length) == 0) retObj.msg.push('Unable construct base unit string; tried ' + baseUnitString);else {
+          try {
+            retObj.magnitude = retUnit.convertFrom(fromVal, unit);
+          } catch (e) {
+            retObj.msg.push(e.toString());
+          }
+
+          if (retObj.msg.length == 0) {
+            retObj.unitToExp = unitToExp;
+            retObj.fromUnitIsSpecial = unit.isSpecial_;
+          }
+        }
+      }
+
+      return retObj;
+    }
     /**
      * This method accepts a term and looks for units that include it as
      * a synonym - or that include the term in its name.
@@ -2419,8 +2494,8 @@ var Unit = /*#__PURE__*/function () {
     key: "convertFrom",
     value: function convertFrom(num, fromUnit) {
       var newNum = 0.0;
-      if (this.isArbitrary_) throw new Error("Attempt to convert arbitrary unit ".concat(this.name_));
-      if (fromUnit.isArbitrary_) throw new Error("Attempt to convert to arbitrary unit ".concat(fromUnit.name_)); // reject request if both units have dimensions that are not equal
+      if (this.isArbitrary_) throw new Error("Attempt to convert to arbitrary unit \"".concat(this.csCode_, "\""));
+      if (fromUnit.isArbitrary_) throw new Error("Attempt to convert arbitrary unit \"".concat(fromUnit.csCode_, "\"")); // reject request if both units have dimensions that are not equal
 
       if (fromUnit.dim_ && this.dim_ && !fromUnit.dim_.equals(this.dim_)) {
         // check first to see if a mole<->mass conversion is appropriate
@@ -2442,40 +2517,28 @@ var Unit = /*#__PURE__*/function () {
       }
 
       var fromCnv = fromUnit.cnv_;
-      var fromMag = fromUnit.magnitude_; // If the same conversion function is specified for both units, which
-      // includes neither unit having a conversion function, multiply the
-      // "from" unit's magnitude by the number passed in and then divide
-      // that result by this unit's magnitude.  Do this for units with
-      // and without dimension vectors.  PROBLEM with 2 non-commensurable
-      // units with no dimension vector or function, e.g., byte to mol
-
-      if (fromCnv === this.cnv_) {
-        newNum = num * fromMag / this.magnitude_;
-      } // else use a function to get the number to be returned
-      else {
-          var x = 0.0;
-
-          if (fromCnv != null) {
-            // turn num * fromUnit.magnitude into its ratio scale equivalent,
-            // e.g., convert Celsius to Kelvin
-            var fromFunc = _ucumFunctions.default.forName(fromCnv);
+      var fromMag = fromUnit.magnitude_;
+      var x;
 
-            x = fromFunc.cnvFrom(num * fromUnit.cnvPfx_) * fromMag; //x = fromFunc.cnvFrom(num * fromMag) * fromUnit.cnvPfx_;
-          } else {
-            x = num * fromMag;
-          }
+      if (fromCnv != null) {
+        // turn num * fromUnit.magnitude into its ratio scale equivalent,
+        // e.g., convert Celsius to Kelvin
+        var fromFunc = _ucumFunctions.default.forName(fromCnv);
 
-          if (this.cnv_ != null) {
-            // turn mag * origUnit on ratio scale into a non-ratio unit,
-            // e.g. convert Kelvin to Fahrenheit
-            var toFunc = _ucumFunctions.default.forName(this.cnv_);
+        x = fromFunc.cnvFrom(num * fromUnit.cnvPfx_) * fromMag; //x = fromFunc.cnvFrom(num * fromMag) * fromUnit.cnvPfx_;
+      } else {
+        x = num * fromMag;
+      }
 
-            newNum = toFunc.cnvTo(x / this.magnitude_) / this.cnvPfx_;
-          } else {
-            newNum = x / this.magnitude_;
-          }
-        } // end if either unit has a conversion function
+      if (this.cnv_ != null) {
+        // turn mag * origUnit on ratio scale into a non-ratio unit,
+        // e.g. convert Kelvin to Fahrenheit
+        var toFunc = _ucumFunctions.default.forName(this.cnv_);
 
+        newNum = toFunc.cnvTo(x / this.magnitude_) / this.cnvPfx_;
+      } else {
+        newNum = x / this.magnitude_;
+      }
 
       return newNum;
     } // end convertFrom
@@ -2690,6 +2753,7 @@ var Unit = /*#__PURE__*/function () {
       else if (unit2.cnv_ != null) {
           if (!retUnit.dim_ || retUnit.dim_.isZero()) {
             retUnit.cnvPfx_ = unit2.cnvPfx_ * retUnit.magnitude_;
+            retUnit.magnitude_ = unit2.magnitude_;
             retUnit.cnv_ = unit2.cnv_;
           } else throw new Error("Attempt to multiply non-ratio unit ".concat(unit2.name_));
         } // end if unit2 has a conversion function
@@ -2723,7 +2787,9 @@ var Unit = /*#__PURE__*/function () {
       // if (!retUnit.isMole_)
       //   retUnit.isMole_ = unit2.isMole_ ;
 
-      if (!retUnit.isArbitrary_) retUnit.isArbitrary_ = unit2.isArbitrary_;
+      if (!retUnit.isArbitrary_) retUnit.isArbitrary_ = unit2.isArbitrary_; // Likewise for special units
+
+      if (!retUnit.isSpecial_) retUnit.isSpecial_ = unit2.isSpecial_;
       return retUnit;
     } // end multiplyThese
 
@@ -3280,6 +3346,7 @@ var UnitString = /*#__PURE__*/function () {
         if (intUtils_.isIntegerUnit(finalUnit) || typeof finalUnit === 'number') {
           finalUnit = new Unit({
             'csCode_': origString,
+            'ciCode_': origString,
             'magnitude_': finalUnit,
             'name_': origString
           });
@@ -4494,6 +4561,7 @@ var UnitString = /*#__PURE__*/function () {
       if (intUtils_.isIntegerUnit(finalUnit)) {
         finalUnit = new Unit({
           'csCode_': finalUnit,
+          'ciCode_': finalUnit,
           'magnitude_': Number(finalUnit),
           'name_': finalUnit
         });
@@ -4509,6 +4577,7 @@ var UnitString = /*#__PURE__*/function () {
         if (intUtils_.isIntegerUnit(nextUnit)) {
           nextUnit = new Unit({
             'csCode_': nextUnit,
+            'ciCode_': nextUnit,
             'magnitude_': Number(nextUnit),
             'name_': nextUnit
           });
@@ -4734,6 +4803,11 @@ var UnitTablesFactory = /*#__PURE__*/function () {
      */
 
     this.massDimIndex_ = 0;
+    /**
+     *  Map of indices in the dimension vector to base unit symbols.
+     */
+
+    this.dimVecIndexToBaseUnit_ = {};
   }
   /**
    * Provides the number of unit objects written to the tables, using the
@@ -4774,6 +4848,17 @@ var UnitTablesFactory = /*#__PURE__*/function () {
       } catch (err) {// do nothing - throws error if the property is null
         // and that's OK here.
       }
+
+      if (theUnit.isBase_) {
+        var dimVec = theUnit.dim_.dimVec_;
+        var nonZeroIndex;
+
+        for (var i = 0, len = dimVec.length; nonZeroIndex == undefined && i < len; ++i) {
+          if (dimVec[i] != 0) nonZeroIndex = i;
+        }
+
+        this.dimVecIndexToBaseUnit_[nonZeroIndex] = theUnit.csCode_;
+      }
     } // end addUnit
 
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lhncbc/ucum-lhc",
-  "version": "4.1.8",
+  "version": "4.2.0",
   "description": "Implements Unified Code for Units of Measure (UCUM) functions in a javascript library",
   "main": "source-cjs/ucumPkg.js",
   "homepage": "https://lhncbc.github.io/ucum-lhc/",

package/source/config.js

@@ -24,6 +24,7 @@ export var Ucum = {
    */
   dimLen_: 7,
 
+
   /**
    *  The characters used as valid operators in a UCUM unit expression,
    *  where '.' is for multiplication and '/' is for division.
@@ -63,14 +64,14 @@ export var Ucum = {
    * displaying messages on a web site; should be blank when output is
    * to a file.
    */
-  openEmphHTML_ : '<span class="emphSpan">',
+  openEmphHTML_ : ' <span class="emphSpan">',
 
   /**
    * Closing HTML used to emphasize portions of error messages.  Used when
    * displaying messages on a web site; should be blank when output is
    * to a file.
    */
-  closeEmphHTML_ : '</span>' ,
+  closeEmphHTML_ : '</span> ' ,
 
   /**
    * Message that is displayed when annotations are included in a unit

package/source/ucumLhcUtils.js

@@ -337,6 +337,76 @@ export class UcumLhcUtils {
   } // end convertUnitTo
 
 
+  /**
+   *  Converts the given unit string into its base units, their exponents, and
+   *  a magnitude, and returns that data.
+   * @param fromUnit the unit string to be converted to base units information
+   * @param fromVal the number of "from" units to be converted
+   * @returns an object with the properties:
+   *  'msg': an array of one or more messages, if the string is invalid or
+   *        an error occurred, indicating the problem, or a suggestion of a
+   *        substitution such as the substitution of 'G' for 'Gauss', or
+   *        an empty array if no messages were generated.  If this is not empty,
+   *        no other information will be returned.
+   *  'magnitude': the new value when fromVal units of fromUnits is expressed in the base units.
+   *  'fromUnitIsSpecial': whether the input unit fromUnit is a "special unit"
+   *         as defined in UCUM.  This means there is some function applied to convert
+   *         between fromUnit and the base units, so the returned magnitude is likely not
+   *         useful as a scale factor for other conversions (i.e., it only has validity
+   *         and usefulness for the input values that produced it).
+   *  'unitToExp': a map of base units in uStr to their exponent
+   */
+  convertToBaseUnits(fromUnit, fromVal) {
+    let inputUnitLookup = this.getSpecifiedUnit(fromUnit, 'validate');
+    let retObj = {};
+    let unit = inputUnitLookup.unit;
+    retObj.msg = inputUnitLookup.retMsg || [];
+    if (!unit) {
+      if (inputUnitLookup.retMsg?.length == 0)
+        retObj.msg.push('Could not find unit information for '+fromUnit);
+    }
+    else if (unit.isArbitrary_) {
+      retObj.msg.push('Arbitrary units cannot be converted to base units or other units.');
+    }
+    else if (retObj.msg.length == 0) {
+      let unitToExp = {};
+      let dimVec = unit.dim_?.dimVec_
+      let baseUnitString = '1';
+      if (dimVec) {
+        let dimVecIndexToBaseUnit = UnitTables.getInstance().dimVecIndexToBaseUnit_;
+        for (let i=0, len=dimVec.length; i<len; ++i) {
+          let exp = dimVec[i];
+          if (exp) {
+            unitToExp[dimVecIndexToBaseUnit[i]] = exp;
+            baseUnitString += '.' + dimVecIndexToBaseUnit[i] + exp;
+          }
+        }
+      }
+
+      // The unit might have a conversion function, which has to be applied; we
+      // cannot just assume unit_.magnitude_ is the magnitude in base units.
+      let retUnitLookup = this.getSpecifiedUnit(baseUnitString, 'validate');
+      // There should not be any error in retUnitLookup, unless there is a bug.
+      let retUnit = retUnitLookup.unit;
+      if (!retUnit && retUnitLookup.retMsg?.length == 0)
+        retObj.msg.push('Unable construct base unit string; tried '+baseUnitString);
+      else {
+        try {
+          retObj.magnitude = retUnit.convertFrom(fromVal, unit);
+        }
+        catch (e) {
+          retObj.msg.push(e.toString());
+        }
+        if (retObj.msg.length == 0) {
+          retObj.unitToExp = unitToExp;
+          retObj.fromUnitIsSpecial = unit.isSpecial_;
+        }
+      }
+    }
+    return retObj;
+  }
+
+
   /**
    * This method accepts a term and looks for units that include it as
    * a synonym - or that include the term in its name.

package/source/unit.js

@@ -340,6 +340,7 @@ export class Unit {
     return match ;
   }// end of fullEquals
 
+
   /**
    * This returns the value of the property named by the parameter
    * passed in.
@@ -380,9 +381,9 @@ export class Unit {
     let newNum = 0.0 ;
 
     if (this.isArbitrary_)
-      throw (new Error(`Attempt to convert arbitrary unit ${this.name_}`));
+      throw (new Error(`Attempt to convert to arbitrary unit "${this.csCode_}"`));
     if (fromUnit.isArbitrary_)
-      throw (new Error(`Attempt to convert to arbitrary unit ${fromUnit.name_}`));
+      throw (new Error(`Attempt to convert arbitrary unit "${fromUnit.csCode_}"`));
 
     // reject request if both units have dimensions that are not equal
     if (fromUnit.dim_ && this.dim_ && !(fromUnit.dim_.equals(this.dim_))) {
@@ -410,39 +411,27 @@ export class Unit {
     let fromCnv = fromUnit.cnv_ ;
     let fromMag = fromUnit.magnitude_ ;
 
-    // If the same conversion function is specified for both units, which
-    // includes neither unit having a conversion function, multiply the
-    // "from" unit's magnitude by the number passed in and then divide
-    // that result by this unit's magnitude.  Do this for units with
-    // and without dimension vectors.  PROBLEM with 2 non-commensurable
-    // units with no dimension vector or function, e.g., byte to mol
-    if (fromCnv === this.cnv_) {
-      newNum = (num * fromMag) / this.magnitude_;
+    let x;
+    if (fromCnv != null) {
+      // turn num * fromUnit.magnitude into its ratio scale equivalent,
+      // e.g., convert Celsius to Kelvin
+      let fromFunc = funcs.forName(fromCnv);
+      x = fromFunc.cnvFrom(num * fromUnit.cnvPfx_) * fromMag;
+      //x = fromFunc.cnvFrom(num * fromMag) * fromUnit.cnvPfx_;
     }
-    // else use a function to get the number to be returned
     else {
-      let x = 0.0 ;
-      if (fromCnv != null) {
-        // turn num * fromUnit.magnitude into its ratio scale equivalent,
-        // e.g., convert Celsius to Kelvin
-        let fromFunc = funcs.forName(fromCnv);
-        x = fromFunc.cnvFrom(num * fromUnit.cnvPfx_) * fromMag;
-        //x = fromFunc.cnvFrom(num * fromMag) * fromUnit.cnvPfx_;
-      }
-      else {
-        x = num * fromMag;
-      }
+      x = num * fromMag;
+    }
 
-      if (this.cnv_ != null) {
-        // turn mag * origUnit on ratio scale into a non-ratio unit,
-        // e.g. convert Kelvin to Fahrenheit
-        let toFunc = funcs.forName(this.cnv_);
-        newNum = toFunc.cnvTo(x / this.magnitude_) / this.cnvPfx_;
-      }
-      else {
-        newNum = x / this.magnitude_;
-      }
-    } // end if either unit has a conversion function
+    if (this.cnv_ != null) {
+      // turn mag * origUnit on ratio scale into a non-ratio unit,
+      // e.g. convert Kelvin to Fahrenheit
+      let toFunc = funcs.forName(this.cnv_);
+      newNum = toFunc.cnvTo(x / this.magnitude_) / this.cnvPfx_;
+    }
+    else {
+      newNum = x / this.magnitude_;
+    }
 
     return newNum;
 
@@ -666,6 +655,7 @@ export class Unit {
     else if (unit2.cnv_ != null) {
       if (!retUnit.dim_ || retUnit.dim_.isZero()) {
         retUnit.cnvPfx_ = unit2.cnvPfx_ * retUnit.magnitude_;
+        retUnit.magnitude_ = unit2.magnitude_;
         retUnit.cnv_ = unit2.cnv_ ;
       }
       else
@@ -716,8 +706,12 @@ export class Unit {
     // via an arithmetic operation.  Taint accordingly
     // if (!retUnit.isMole_)
     //   retUnit.isMole_ = unit2.isMole_ ;
-     if (!retUnit.isArbitrary_)
-       retUnit.isArbitrary_ = unit2.isArbitrary_;
+    if (!retUnit.isArbitrary_)
+      retUnit.isArbitrary_ = unit2.isArbitrary_;
+
+    // Likewise for special units
+    if (!retUnit.isSpecial_)
+      retUnit.isSpecial_ = unit2.isSpecial_;
 
     return retUnit ;
 

package/source/unitString.js

@@ -218,6 +218,7 @@ export class UnitString {
       if (intUtils_.isIntegerUnit(finalUnit) || typeof finalUnit === 'number') {
         finalUnit = new Unit({
           'csCode_': origString,
+          'ciCode_': origString,
           'magnitude_': finalUnit,
           'name_': origString
         });
@@ -1442,7 +1443,7 @@ export class UnitString {
 
     let finalUnit = uArray[0]['un'];
     if (intUtils_.isIntegerUnit(finalUnit)) {
-      finalUnit = new Unit({'csCode_' : finalUnit,
+      finalUnit = new Unit({'csCode_' : finalUnit, 'ciCode_' : finalUnit,
         'magnitude_' : Number(finalUnit),
         'name_' : finalUnit}) ;
     }
@@ -1453,7 +1454,7 @@ export class UnitString {
     for (let u2 = 1; (u2 < uLen) && !endProcessing; u2++) {
       let nextUnit = uArray[u2]['un'];
       if (intUtils_.isIntegerUnit(nextUnit)) {
-        nextUnit = new Unit({'csCode_' : nextUnit ,
+        nextUnit = new Unit({'csCode_' : nextUnit, 'ciCode_' : nextUnit,
           'magnitude_' : Number(nextUnit),
           'name_': nextUnit});
       }

package/source/unitTables.js

@@ -97,6 +97,11 @@ class UnitTablesFactory {
      * @type integer
      */
     this.massDimIndex_ = 0;
+
+    /**
+     *  Map of indices in the dimension vector to base unit symbols.
+     */
+    this.dimVecIndexToBaseUnit_ = {};
   }
 
 
@@ -138,6 +143,15 @@ class UnitTablesFactory {
       // and that's OK here.
     }
 
+    if (theUnit.isBase_) {
+      const dimVec = theUnit.dim_.dimVec_;
+      let nonZeroIndex;
+      for (let i=0, len=dimVec.length; nonZeroIndex==undefined && i<len; ++i) {
+        if (dimVec[i] != 0)
+          nonZeroIndex = i;
+      }
+      this.dimVecIndexToBaseUnit_[nonZeroIndex] = theUnit.csCode_;
+    }
   } // end addUnit
 
 

package/source-cjs/config.js

@@ -65,14 +65,14 @@ var Ucum = {
    * displaying messages on a web site; should be blank when output is
    * to a file.
    */
-  openEmphHTML_: '<span class="emphSpan">',
+  openEmphHTML_: ' <span class="emphSpan">',
 
   /**
    * Closing HTML used to emphasize portions of error messages.  Used when
    * displaying messages on a web site; should be blank when output is
    * to a file.
    */
-  closeEmphHTML_: '</span>',
+  closeEmphHTML_: '</span> ',
 
   /**
    * Message that is displayed when annotations are included in a unit

package/source-cjs/config.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../source/config.js"],"names":["Ucum","dimLen_","validOps_","codeSep_","valMsgStart_","valMsgEnd_","cnvMsgStart_","cnvMsgEnd_","openEmph_","closeEmph_","openEmphHTML_","closeEmphHTML_","bracesMsg_","needMoleWeightMsg_","csvCols_","inputKey_","specUnits_"],"mappings":";;;;;;;AAAA;;;;;;;AAQO,IAAIA,IAAI,GAAG;AAEhB;;;;;;AAMA;;AAEA;;;;;;AAMAC,EAAAA,OAAO,EAAE,CAhBO;;AAkBhB;;;;AAIAC,EAAAA,SAAS,EAAE,CAAC,GAAD,EAAM,GAAN,CAtBK;;AAyBhB;;;;AAIAC,EAAAA,QAAQ,EAAG,IA7BK;AA+BhB;AACAC,EAAAA,YAAY,EAAG,eAhCC;AAiChBC,EAAAA,UAAU,EAAG,GAjCG;AAkChBC,EAAAA,YAAY,EAAG,uBAlCC;AAmChBC,EAAAA,UAAU,EAAG,GAnCG;;AAsClB;;;;;AAKEC,EAAAA,SAAS,EAAG,KA3CI;;AA6ChB;;;;;AAKAC,EAAAA,UAAU,EAAG,KAlDG;;AAoDhB;;;;;AAKAC,EAAAA,aAAa,EAAG,yBAzDA;;AA2DhB;;;;;AAKAC,EAAAA,cAAc,EAAG,SAhED;;AAkEhB;;;;AAIAC,EAAAA,UAAU,EAAG,8DACA,6DADA,GAEA,iCAxEG;;AA0EhB;;;;;AAKAC,EAAAA,kBAAkB,EAAG,0DACA,uDADA,GAEA,8CAjFL;;AAmFhB;;;;AAIAC,EAAAA,QAAQ,EAAG;AACT,2BAAwB,SADf;AAET,sBAAmB,gBAFV;AAGT,sBAAmB,OAHV;AAIT,gBAAa,WAJJ;AAKT,cAAW,SALF;AAMT,gBAAa,WANJ;AAOT,gBAAa;AAPJ,GAvFK;;AAiGhB;;;AAGAC,EAAAA,SAAS,EAAG,qBApGI;;AAsGhB;;;;;;;AAOCC,EAAAA,UAAU,EAAG;AAAE,gBAAa,gBAAf;AACE,uBAAoB;AADtB;AA7GE,CAAX","sourcesContent":["/*\n * This defines the namespace for the UCUM classes and provides\n * a place for the definition of global variables and constants.\n *\n * The javascript for this UCUM implementation uses syntax as\n * defined by the ECMAScript 6 standard\n */\n\nexport var Ucum = {\n\n  /**\n   *  Flag indicating whether or not we're using case sensitive labels\n   *  I don't think we need this.  I think we're just going with\n   *  case sensitive, per Clem.   Gunther's code has this flag, but I\n   *  am removing it, at least for now.  lm, 6/2016\n   */\n  //caseSensitive_: true ,\n\n  /**\n   *  The number of elements in a Dimension array.   Currently this\n   *  is set as a configuration variable, but when we get to the point\n   *  of loading the unit definitions from a file, this value will be\n   *  set from that.\n   */\n  dimLen_: 7,\n\n  /**\n   *  The characters used as valid operators in a UCUM unit expression,\n   *  where '.' is for multiplication and '/' is for division.\n   */\n  validOps_: ['.', '/'],\n\n\n  /**\n   * The string used to separate a unit code and unit name when they\n   * are displayed together\n   */\n  codeSep_ : ': ',\n\n  // Message text variations for validation methods and conversion methods\n  valMsgStart_ : 'Did you mean ',\n  valMsgEnd_ : '?' ,\n  cnvMsgStart_ : 'We assumed you meant ',\n  cnvMsgEnd_ : '.',\n\n\n/**\n   * Default opening string used to emphasize portions of error messages.\n   * Used when NOT displaying messages on a web site, i.e., for output\n   * from the library methods or to a file.\n   */\n  openEmph_ : ' ->',\n\n  /**\n   * Default closing string used to emphasize portions of error messages.\n   * Used when NOT displaying messages on a web site, i.e., for output\n   * from the library methods or to a file.\n   */\n  closeEmph_ : '<- ' ,\n\n  /**\n   * Opening HTML used to emphasize portions of error messages.  Used when\n   * displaying messages on a web site; should be blank when output is\n   * to a file.\n   */\n  openEmphHTML_ : '<span class=\"emphSpan\">',\n\n  /**\n   * Closing HTML used to emphasize portions of error messages.  Used when\n   * displaying messages on a web site; should be blank when output is\n   * to a file.\n   */\n  closeEmphHTML_ : '</span>' ,\n\n  /**\n   * Message that is displayed when annotations are included in a unit\n   * string, to let the user know how they are interpreted.\n   */\n  bracesMsg_ : 'FYI - annotations (text in curly braces {}) are ignored, ' +\n               'except that an annotation without a leading symbol implies ' +\n               'the default unit 1 (the unity).',\n\n  /**\n   * Message that is displayed or returned when a conversion is requested\n   * for two units where (only) a mass<->moles conversion is appropriate\n   * but no molecular weight was specified.\n   */\n  needMoleWeightMsg_ : 'Did you wish to convert between mass and moles?  The ' +\n                       'molecular weight of the substance represented by the ' +\n                       'units is required to perform the conversion.',\n\n  /**\n   * Hash that matches unit column names to names used in the csv file\n   * that is submitted to the data updater.\n   */\n  csvCols_ : {\n    'case-sensitive code' : 'csCode_',\n    'LOINC property' : 'loincProperty_',\n    'name (display)' : 'name_',\n    'synonyms' : 'synonyms_',\n    'source' : 'source_',\n    'category' : 'category_',\n    'Guidance' : 'guidance_'\n  } ,\n\n  /**\n   * Name of the column in the csv file that serves as the key\n   */\n  inputKey_ : 'case-sensitive code' ,\n\n  /**\n   * Special codes that contain operators within brackets.  The operator\n   * within these codes causes them to parse incorrectly if they are preceded\n   * by a prefix, because the parsing algorithm splits them up on the operator.\n   * So we use this object to identify them and substitute placeholders to\n   * avoid that.\n   */\n   specUnits_ : { 'B[10.nV]' : 'specialUnitOne',\n                  '[m/s2/Hz^(1/2)]' : 'specialUnitTwo'}\n} ;\n\n\n"],"file":"config.js"}
+{"version":3,"sources":["../source/config.js"],"names":["Ucum","dimLen_","validOps_","codeSep_","valMsgStart_","valMsgEnd_","cnvMsgStart_","cnvMsgEnd_","openEmph_","closeEmph_","openEmphHTML_","closeEmphHTML_","bracesMsg_","needMoleWeightMsg_","csvCols_","inputKey_","specUnits_"],"mappings":";;;;;;;AAAA;;;;;;;AAQO,IAAIA,IAAI,GAAG;AAEhB;;;;;;AAMA;;AAEA;;;;;;AAMAC,EAAAA,OAAO,EAAE,CAhBO;;AAmBhB;;;;AAIAC,EAAAA,SAAS,EAAE,CAAC,GAAD,EAAM,GAAN,CAvBK;;AA0BhB;;;;AAIAC,EAAAA,QAAQ,EAAG,IA9BK;AAgChB;AACAC,EAAAA,YAAY,EAAG,eAjCC;AAkChBC,EAAAA,UAAU,EAAG,GAlCG;AAmChBC,EAAAA,YAAY,EAAG,uBAnCC;AAoChBC,EAAAA,UAAU,EAAG,GApCG;;AAuClB;;;;;AAKEC,EAAAA,SAAS,EAAG,KA5CI;;AA8ChB;;;;;AAKAC,EAAAA,UAAU,EAAG,KAnDG;;AAqDhB;;;;;AAKAC,EAAAA,aAAa,EAAG,0BA1DA;;AA4DhB;;;;;AAKAC,EAAAA,cAAc,EAAG,UAjED;;AAmEhB;;;;AAIAC,EAAAA,UAAU,EAAG,8DACA,6DADA,GAEA,iCAzEG;;AA2EhB;;;;;AAKAC,EAAAA,kBAAkB,EAAG,0DACA,uDADA,GAEA,8CAlFL;;AAoFhB;;;;AAIAC,EAAAA,QAAQ,EAAG;AACT,2BAAwB,SADf;AAET,sBAAmB,gBAFV;AAGT,sBAAmB,OAHV;AAIT,gBAAa,WAJJ;AAKT,cAAW,SALF;AAMT,gBAAa,WANJ;AAOT,gBAAa;AAPJ,GAxFK;;AAkGhB;;;AAGAC,EAAAA,SAAS,EAAG,qBArGI;;AAuGhB;;;;;;;AAOCC,EAAAA,UAAU,EAAG;AAAE,gBAAa,gBAAf;AACE,uBAAoB;AADtB;AA9GE,CAAX","sourcesContent":["/*\n * This defines the namespace for the UCUM classes and provides\n * a place for the definition of global variables and constants.\n *\n * The javascript for this UCUM implementation uses syntax as\n * defined by the ECMAScript 6 standard\n */\n\nexport var Ucum = {\n\n  /**\n   *  Flag indicating whether or not we're using case sensitive labels\n   *  I don't think we need this.  I think we're just going with\n   *  case sensitive, per Clem.   Gunther's code has this flag, but I\n   *  am removing it, at least for now.  lm, 6/2016\n   */\n  //caseSensitive_: true ,\n\n  /**\n   *  The number of elements in a Dimension array.   Currently this\n   *  is set as a configuration variable, but when we get to the point\n   *  of loading the unit definitions from a file, this value will be\n   *  set from that.\n   */\n  dimLen_: 7,\n\n\n  /**\n   *  The characters used as valid operators in a UCUM unit expression,\n   *  where '.' is for multiplication and '/' is for division.\n   */\n  validOps_: ['.', '/'],\n\n\n  /**\n   * The string used to separate a unit code and unit name when they\n   * are displayed together\n   */\n  codeSep_ : ': ',\n\n  // Message text variations for validation methods and conversion methods\n  valMsgStart_ : 'Did you mean ',\n  valMsgEnd_ : '?' ,\n  cnvMsgStart_ : 'We assumed you meant ',\n  cnvMsgEnd_ : '.',\n\n\n/**\n   * Default opening string used to emphasize portions of error messages.\n   * Used when NOT displaying messages on a web site, i.e., for output\n   * from the library methods or to a file.\n   */\n  openEmph_ : ' ->',\n\n  /**\n   * Default closing string used to emphasize portions of error messages.\n   * Used when NOT displaying messages on a web site, i.e., for output\n   * from the library methods or to a file.\n   */\n  closeEmph_ : '<- ' ,\n\n  /**\n   * Opening HTML used to emphasize portions of error messages.  Used when\n   * displaying messages on a web site; should be blank when output is\n   * to a file.\n   */\n  openEmphHTML_ : ' <span class=\"emphSpan\">',\n\n  /**\n   * Closing HTML used to emphasize portions of error messages.  Used when\n   * displaying messages on a web site; should be blank when output is\n   * to a file.\n   */\n  closeEmphHTML_ : '</span> ' ,\n\n  /**\n   * Message that is displayed when annotations are included in a unit\n   * string, to let the user know how they are interpreted.\n   */\n  bracesMsg_ : 'FYI - annotations (text in curly braces {}) are ignored, ' +\n               'except that an annotation without a leading symbol implies ' +\n               'the default unit 1 (the unity).',\n\n  /**\n   * Message that is displayed or returned when a conversion is requested\n   * for two units where (only) a mass<->moles conversion is appropriate\n   * but no molecular weight was specified.\n   */\n  needMoleWeightMsg_ : 'Did you wish to convert between mass and moles?  The ' +\n                       'molecular weight of the substance represented by the ' +\n                       'units is required to perform the conversion.',\n\n  /**\n   * Hash that matches unit column names to names used in the csv file\n   * that is submitted to the data updater.\n   */\n  csvCols_ : {\n    'case-sensitive code' : 'csCode_',\n    'LOINC property' : 'loincProperty_',\n    'name (display)' : 'name_',\n    'synonyms' : 'synonyms_',\n    'source' : 'source_',\n    'category' : 'category_',\n    'Guidance' : 'guidance_'\n  } ,\n\n  /**\n   * Name of the column in the csv file that serves as the key\n   */\n  inputKey_ : 'case-sensitive code' ,\n\n  /**\n   * Special codes that contain operators within brackets.  The operator\n   * within these codes causes them to parse incorrectly if they are preceded\n   * by a prefix, because the parsing algorithm splits them up on the operator.\n   * So we use this object to identify them and substitute placeholders to\n   * avoid that.\n   */\n   specUnits_ : { 'B[10.nV]' : 'specialUnitOne',\n                  '[m/s2/Hz^(1/2)]' : 'specialUnitTwo'}\n} ;\n\n\n"],"file":"config.js"}

package/source-cjs/ucumLhcUtils.js

@@ -333,6 +333,76 @@ class UcumLhcUtils {
     return returnObj;
   } // end convertUnitTo
 
+  /**
+   *  Converts the given unit string into its base units, their exponents, and
+   *  a magnitude, and returns that data.
+   * @param fromUnit the unit string to be converted to base units information
+   * @param fromVal the number of "from" units to be converted
+   * @returns an object with the properties:
+   *  'msg': an array of one or more messages, if the string is invalid or
+   *        an error occurred, indicating the problem, or a suggestion of a
+   *        substitution such as the substitution of 'G' for 'Gauss', or
+   *        an empty array if no messages were generated.  If this is not empty,
+   *        no other information will be returned.
+   *  'magnitude': the new value when fromVal units of fromUnits is expressed in the base units.
+   *  'fromUnitIsSpecial': whether the input unit fromUnit is a "special unit"
+   *         as defined in UCUM.  This means there is some function applied to convert
+   *         between fromUnit and the base units, so the returned magnitude is likely not
+   *         useful as a scale factor for other conversions (i.e., it only has validity
+   *         and usefulness for the input values that produced it).
+   *  'unitToExp': a map of base units in uStr to their exponent
+   */
+
+
+  convertToBaseUnits(fromUnit, fromVal) {
+    let inputUnitLookup = this.getSpecifiedUnit(fromUnit, 'validate');
+    let retObj = {};
+    let unit = inputUnitLookup.unit;
+    retObj.msg = inputUnitLookup.retMsg || [];
+
+    if (!unit) {
+      if (inputUnitLookup.retMsg?.length == 0) retObj.msg.push('Could not find unit information for ' + fromUnit);
+    } else if (unit.isArbitrary_) {
+      retObj.msg.push('Arbitrary units cannot be converted to base units or other units.');
+    } else if (retObj.msg.length == 0) {
+      let unitToExp = {};
+      let dimVec = unit.dim_?.dimVec_;
+      let baseUnitString = '1';
+
+      if (dimVec) {
+        let dimVecIndexToBaseUnit = UnitTables.getInstance().dimVecIndexToBaseUnit_;
+
+        for (let i = 0, len = dimVec.length; i < len; ++i) {
+          let exp = dimVec[i];
+
+          if (exp) {
+            unitToExp[dimVecIndexToBaseUnit[i]] = exp;
+            baseUnitString += '.' + dimVecIndexToBaseUnit[i] + exp;
+          }
+        }
+      } // The unit might have a conversion function, which has to be applied; we
+      // cannot just assume unit_.magnitude_ is the magnitude in base units.
+
+
+      let retUnitLookup = this.getSpecifiedUnit(baseUnitString, 'validate'); // There should not be any error in retUnitLookup, unless there is a bug.
+
+      let retUnit = retUnitLookup.unit;
+      if (!retUnit && retUnitLookup.retMsg?.length == 0) retObj.msg.push('Unable construct base unit string; tried ' + baseUnitString);else {
+        try {
+          retObj.magnitude = retUnit.convertFrom(fromVal, unit);
+        } catch (e) {
+          retObj.msg.push(e.toString());
+        }
+
+        if (retObj.msg.length == 0) {
+          retObj.unitToExp = unitToExp;
+          retObj.fromUnitIsSpecial = unit.isSpecial_;
+        }
+      }
+    }
+
+    return retObj;
+  }
   /**
    * This method accepts a term and looks for units that include it as
    * a synonym - or that include the term in its name.