@lhncbc/ucum-lhc 4.1.8 → 5.0.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
@@ -1617,24 +1617,17 @@ var UcumLhcUtils = /*#__PURE__*/function () {
       if (valConv === undefined) valConv = 'validate';
       var resp = this.getSpecifiedUnit(uStr, valConv, suggest);
       var theUnit = resp['unit'];
-      var retObj = {};
-
-      if (!theUnit) {
-        retObj = {
-          'status': !resp['origString'] || resp['origString'] === null ? 'error' : 'invalid',
-          'ucumCode': null
-        };
-      } else {
-        retObj = {
-          'status': resp['origString'] === uStr ? 'valid' : 'invalid',
-          'ucumCode': resp['origString'],
-          'unit': {
-            'code': theUnit.csCode_,
-            'name': theUnit.name_,
-            'guidance': theUnit.guidance_
-          }
-        };
-      }
+      var retObj = !theUnit ? {
+        'ucumCode': null
+      } : {
+        'ucumCode': resp['origString'],
+        'unit': {
+          'code': theUnit.csCode_,
+          'name': theUnit.name_,
+          'guidance': theUnit.guidance_
+        }
+      };
+      retObj.status = resp.status;
 
       if (resp['suggestions']) {
         retObj['suggestions'] = resp['suggestions'];
@@ -1723,10 +1716,7 @@ var UcumLhcUtils = /*#__PURE__*/function () {
         returnObj['msg'].push('No "from" unit expression specified.');
       }
 
-      if (fromVal === null || isNaN(fromVal) || typeof fromVal !== 'number' && !intUtils_.isNumericString(fromVal)) {
-        returnObj['status'] = 'error';
-        returnObj['msg'].push('No "from" value, or an invalid "from" value, ' + 'was specified.');
-      }
+      this._checkFromVal(fromVal, returnObj);
 
       if (toUnitCode) {
         toUnitCode = toUnitCode.trim();
@@ -1817,6 +1807,120 @@ 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:
+     *  'status' indicates whether the result succeeded.  The value will be one of:
+     *    'succeeded':  the conversion was successfully calculated (which can be
+     *      true even if it was already in base units);
+     *    'invalid':  fromUnit is not a valid UCUM code;
+     *    'failed':  the conversion could not be made (e.g., if it is an "arbitrary" unit);
+     *    'error':  if an error occurred (an input or programming error)
+     *  '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.  There can also be a
+     *        message that is just informational or warning.
+     *  '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 retObj = {};
+
+      this._checkFromVal(fromVal, retObj);
+
+      if (!retObj.status) {
+        // could be set to 'error' by _checkFromVal
+        var inputUnitLookup = this.getSpecifiedUnit(fromUnit, 'validate');
+        retObj = {
+          status: inputUnitLookup.status == 'valid' ? 'succeeded' : inputUnitLookup.status
+        };
+        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.');
+          retObj.status = 'failed';
+        } else if (retObj.status == 'succeeded') {
+          var _unit$dim_;
+
+          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 (retUnitLookup.status !== 'valid') {
+            retObj.msg.push('Unable construct base unit string; tried ' + baseUnitString);
+            retObj.status = 'error';
+          } else {
+            try {
+              retObj.magnitude = retUnit.convertFrom(fromVal, unit);
+            } catch (e) {
+              retObj.msg.push(e.toString());
+              retObj.status = 'error';
+            }
+
+            if (retObj.status == 'succeeded') {
+              retObj.unitToExp = unitToExp;
+              retObj.fromUnitIsSpecial = unit.isSpecial_;
+            }
+          }
+        }
+      }
+
+      return retObj;
+    }
+    /**
+     *  Checks the given value as to whether it is suitable as a "from" value in a
+     *  unit conversion.  If it is not, the responseObj will have its status set
+     *  to 'error' and a message added.
+     * @param fromVal The value to check
+     * @param responseObj the object that will be updated if the value is not
+     *  usable.
+     */
+
+  }, {
+    key: "_checkFromVal",
+    value: function _checkFromVal(fromVal, responseObj) {
+      if (fromVal === null || isNaN(fromVal) || typeof fromVal !== 'number' && !intUtils_.isNumericString(fromVal)) {
+        responseObj.status = 'error';
+        if (!responseObj.msg) responseObj.msg = [];
+        responseObj.msg.push('No "from" value, or an invalid "from" value, ' + 'was specified.');
+      }
+    }
     /**
      * This method accepts a term and looks for units that include it as
      * a synonym - or that include the term in its name.
@@ -1862,13 +1966,18 @@ var UcumLhcUtils = /*#__PURE__*/function () {
      *  true indicates suggestions are wanted; false indicates they are not,
      *  and is the default if the parameter is not specified;
      * @returns a hash containing:
+     *   'status' will be 'valid' (uName is a valid UCUM code), 'invalid'
+     *     (the uStr is not a valid UCUM code, and substitutions or
+     *     suggestions may or may not be returned, depending on what was
+     *     requested and found); or 'error' (an input or programming error
+     *     occurred);
      *   'unit' the unit object (or null if there were problems creating the
      *     unit);
      *   'origString' the possibly updated unit string passed in;
      *   'retMsg' an array of user messages (informational, error or warning) if
      *     any were generated (IF any were generated, otherwise will be an
      *     empty array); and
-     *  'suggestions' is an array of 1 or more hash objects.  Each hash
+     *   'suggestions' is an array of 1 or more hash objects.  Each hash
      *     contains three elements:
      *       'msg' which is a message indicating what unit expression the
      *          suggestions are for;
@@ -1915,8 +2024,18 @@ var UcumLhcUtils = /*#__PURE__*/function () {
         } // end if the unit was not found as a unit name
 
       } // end if a unit expression was specified
+      // Set the status field
 
 
+      if (!retObj.unit) {
+        // No unit was found; check whether origString has a value
+        retObj.status = !retObj.origString ? 'error' : 'invalid';
+      } else {
+        // Check whether substitutions were made to the unit string in order to
+        // find the unit
+        retObj.status = retObj.origString === uName ? 'valid' : 'invalid';
+      }
+
       return retObj;
     } // end getSpecifiedUnit
 
@@ -2419,8 +2538,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 +2561,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;
+      var fromMag = fromUnit.magnitude_;
+      var x;
 
-          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 (fromCnv != null) {
+        // turn num * fromUnit.magnitude into its ratio scale equivalent,
+        // e.g., convert Celsius to Kelvin
+        var fromFunc = _ucumFunctions.default.forName(fromCnv);
 
-            x = fromFunc.cnvFrom(num * fromUnit.cnvPfx_) * fromMag; //x = fromFunc.cnvFrom(num * fromMag) * fromUnit.cnvPfx_;
-          } else {
-            x = num * fromMag;
-          }
-
-          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 +2797,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 +2831,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 +3390,7 @@ var UnitString = /*#__PURE__*/function () {
         if (intUtils_.isIntegerUnit(finalUnit) || typeof finalUnit === 'number') {
           finalUnit = new Unit({
             'csCode_': origString,
+            'ciCode_': origString,
             'magnitude_': finalUnit,
             'name_': origString
           });
@@ -4392,24 +4503,30 @@ var UnitString = /*#__PURE__*/function () {
       if (!befAnnoText && !aftAnnoText) {
         var tryBrackets = '[' + annoText.substring(1, annoText.length - 1) + ']';
 
-        var mkUnitRet = this._makeUnit(tryBrackets, origString); // If we got back a unit, assign it to the returned unit, and add
-        // a message to advise the user that brackets should enclose the code
+        var mkUnitRet = this._makeUnit(tryBrackets, origString); // Nearly anything inside braces is valid, so we don't want to change the
+        // unit, but we can put the found unit in the message as a sort of
+        // warning.
 
 
         if (mkUnitRet[0]) {
-          retUnit = mkUnitRet[0];
-          origString = origString.replace(annoText, tryBrackets);
-          this.retMsg_.push("".concat(annoText, " is not a valid unit expression, but ") + "".concat(tryBrackets, " is.\n") + this.vcMsgStart_ + "".concat(tryBrackets, " (").concat(retUnit.name_, ")").concat(this.vcMsgEnd_));
-        } // Otherwise assume that this should be interpreted as a 1
-        else {
-            // remove error message generated for trybrackets
-            if (this.retMsg_.length > msgLen) {
-              this.retMsg_.pop();
-            }
-
-            uCode = 1;
-            retUnit = 1;
+          retUnit = uCode;
+          this.retMsg_.push("".concat(annoText, " is a valid unit expression, but ") + "did you mean ".concat(tryBrackets, " (").concat(mkUnitRet[0].name_, ")?"));
+        } else {
+          // remove error message generated for trybrackets
+          if (this.retMsg_.length > msgLen) {
+            this.retMsg_.pop();
           }
+        } // This is the case where the string is only this annotation.
+        // Create and return a unit object, as we do for numeric units in
+        // parseString.
+
+
+        retUnit = new Unit({
+          'csCode_': annoText,
+          'ciCode_': annoText,
+          'magnitude_': 1,
+          'name_': annoText
+        });
       } // end if it's only an annotation
       else {
           // if there's text before and no text after, assume the text before
@@ -4494,6 +4611,7 @@ var UnitString = /*#__PURE__*/function () {
       if (intUtils_.isIntegerUnit(finalUnit)) {
         finalUnit = new Unit({
           'csCode_': finalUnit,
+          'ciCode_': finalUnit,
           'magnitude_': Number(finalUnit),
           'name_': finalUnit
         });
@@ -4509,6 +4627,7 @@ var UnitString = /*#__PURE__*/function () {
         if (intUtils_.isIntegerUnit(nextUnit)) {
           nextUnit = new Unit({
             'csCode_': nextUnit,
+            'ciCode_': nextUnit,
             'magnitude_': Number(nextUnit),
             'name_': nextUnit
           });
@@ -4734,6 +4853,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 +4898,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": "5.0.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

@@ -130,19 +130,12 @@ export class UcumLhcUtils {
 
     let resp = this.getSpecifiedUnit(uStr, valConv, suggest);
     let theUnit = resp['unit'];
-    let retObj = {};
-    if (!theUnit) {
-      retObj = {'status': (!resp['origString'] || resp['origString'] === null) ?
-                           'error' : 'invalid',
-                'ucumCode': null};
-    }
-    else {
-      retObj = {'status': resp['origString'] === uStr ? 'valid': 'invalid',
-                'ucumCode': resp['origString'],
-                'unit': {'code': theUnit.csCode_,
-                         'name': theUnit.name_,
-                         'guidance': theUnit.guidance_ }};
-    }
+    let retObj = !theUnit ? {'ucumCode': null} :
+      {'ucumCode': resp['origString'],
+       'unit': {'code': theUnit.csCode_,
+                'name': theUnit.name_,
+                'guidance': theUnit.guidance_ }};
+    retObj.status = resp.status;
     if (resp['suggestions']) {
       retObj['suggestions'] = resp['suggestions'];
     }
@@ -228,12 +221,7 @@ export class UcumLhcUtils {
       returnObj['status'] = 'error';
       returnObj['msg'].push('No "from" unit expression specified.');
     }
-    if (fromVal === null || isNaN(fromVal) || (typeof fromVal !== 'number' &&
-        !intUtils_.isNumericString(fromVal))) {
-      returnObj['status'] = 'error';
-      returnObj['msg'].push('No "from" value, or an invalid "from" value, ' +
-                         'was specified.');
-    }
+    this._checkFromVal(fromVal, returnObj);
     if (toUnitCode) {
       toUnitCode = toUnitCode.trim();
     }
@@ -337,6 +325,110 @@ 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:
+   *  'status' indicates whether the result succeeded.  The value will be one of:
+   *    'succeeded':  the conversion was successfully calculated (which can be
+   *      true even if it was already in base units);
+   *    'invalid':  fromUnit is not a valid UCUM code;
+   *    'failed':  the conversion could not be made (e.g., if it is an "arbitrary" unit);
+   *    'error':  if an error occurred (an input or programming error)
+   *  '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.  There can also be a
+   *        message that is just informational or warning.
+   *  '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 retObj = {};
+    this._checkFromVal(fromVal, retObj);
+    if (!retObj.status) { // could be set to 'error' by _checkFromVal
+      let inputUnitLookup = this.getSpecifiedUnit(fromUnit, 'validate');
+      retObj = {status: inputUnitLookup.status == 'valid' ? 'succeeded' : inputUnitLookup.status};
+      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.');
+        retObj.status = 'failed';
+      }
+      else if (retObj.status == 'succeeded') {
+        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 (retUnitLookup.status !== 'valid') {
+          retObj.msg.push('Unable construct base unit string; tried '+baseUnitString);
+          retObj.status = 'error';
+        }
+        else {
+          try {
+            retObj.magnitude = retUnit.convertFrom(fromVal, unit);
+          }
+          catch (e) {
+            retObj.msg.push(e.toString());
+            retObj.status = 'error';
+          }
+          if (retObj.status == 'succeeded') {
+            retObj.unitToExp = unitToExp;
+            retObj.fromUnitIsSpecial = unit.isSpecial_;
+          }
+        }
+      }
+    }
+    return retObj;
+  }
+
+
+  /**
+   *  Checks the given value as to whether it is suitable as a "from" value in a
+   *  unit conversion.  If it is not, the responseObj will have its status set
+   *  to 'error' and a message added.
+   * @param fromVal The value to check
+   * @param responseObj the object that will be updated if the value is not
+   *  usable.
+   */
+  _checkFromVal(fromVal, responseObj) {
+    if (fromVal === null || isNaN(fromVal) || (typeof fromVal !== 'number' &&
+        !intUtils_.isNumericString(fromVal))) {
+      responseObj.status = 'error';
+      if (!responseObj.msg)
+        responseObj.msg = [];
+      responseObj.msg.push('No "from" value, or an invalid "from" value, ' +
+                         'was specified.');
+    }
+  }
+
+
   /**
    * This method accepts a term and looks for units that include it as
    * a synonym - or that include the term in its name.
@@ -380,13 +472,18 @@ export class UcumLhcUtils {
    *  true indicates suggestions are wanted; false indicates they are not,
    *  and is the default if the parameter is not specified;
    * @returns a hash containing:
+   *   'status' will be 'valid' (uName is a valid UCUM code), 'invalid'
+   *     (the uStr is not a valid UCUM code, and substitutions or
+   *     suggestions may or may not be returned, depending on what was
+   *     requested and found); or 'error' (an input or programming error
+   *     occurred);
    *   'unit' the unit object (or null if there were problems creating the
    *     unit);
    *   'origString' the possibly updated unit string passed in;
    *   'retMsg' an array of user messages (informational, error or warning) if
    *     any were generated (IF any were generated, otherwise will be an
    *     empty array); and
-   *  'suggestions' is an array of 1 or more hash objects.  Each hash
+   *   'suggestions' is an array of 1 or more hash objects.  Each hash
    *     contains three elements:
    *       'msg' which is a message indicating what unit expression the
    *          suggestions are for;
@@ -441,6 +538,17 @@ export class UcumLhcUtils {
       } // end if the unit was not found as a unit name
     } // end if a unit expression was specified
 
+    // Set the status field
+    if (!retObj.unit) {
+      // No unit was found; check whether origString has a value
+      retObj.status = !retObj.origString ? 'error' : 'invalid';
+    }
+    else {
+      // Check whether substitutions were made to the unit string in order to
+      // find the unit
+      retObj.status = retObj.origString === uName ? 'valid': 'invalid';
+    }
+
     return retObj;
 
   } // end getSpecifiedUnit
@@ -512,7 +620,3 @@ export class UcumLhcUtils {
 UcumLhcUtils.getInstance = function(){
   return new UcumLhcUtils();
 } ;
-
-
-
-