@itwin/core-quantity 4.0.0-dev.46 → 4.0.0-dev.48

package/lib/esm/Formatter/Format.js

@@ -1,324 +1,324 @@
-/*---------------------------------------------------------------------------------------------
-* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
-* See LICENSE.md in the project root for license terms and full copyright notice.
-*--------------------------------------------------------------------------------------------*/
-/** @packageDocumentation
- * @module Quantity
- */
-import { QuantityConstants } from "../Constants";
-import { QuantityError, QuantityStatus } from "../Exception";
-import { DecimalPrecision, FormatTraits, formatTraitsToArray, FormatType, formatTypeToString, getTraitString, parseFormatTrait, parseFormatType, parsePrecision, parseScientificType, parseShowSignOption, scientificTypeToString, ShowSignOption, showSignOptionToString } from "./FormatEnums";
-import { isCustomFormatProps } from "./Interfaces";
-// cSpell:ignore ZERONORMALIZED, nosign, onlynegative, signalways, negativeparentheses
-// cSpell:ignore trailzeroes, keepsinglezero, zeroempty, keepdecimalpoint, applyrounding, fractiondash, showunitlabel, prependunitlabel, exponentonlynegative
-/** A base Format class with shared properties and functionality between quantity and ecschema-metadata Format classes
- * @beta
- */
-export class BaseFormat {
-    constructor(name) {
-        this._name = "";
-        this._roundFactor = 0.0;
-        this._type = FormatType.Decimal; // required; options are decimal, fractional, scientific, station
-        this._precision = DecimalPrecision.Six; // required
-        this._showSignOption = ShowSignOption.OnlyNegative; // options: noSign, onlyNegative, signAlways, negativeParentheses
-        this._decimalSeparator = QuantityConstants.LocaleSpecificDecimalSeparator;
-        this._thousandSeparator = QuantityConstants.LocaleSpecificThousandSeparator;
-        this._uomSeparator = " "; // optional; default is " "; defined separator between magnitude and the unit
-        this._stationSeparator = "+"; // optional; default is "+"
-        this._formatTraits = FormatTraits.Uninitialized;
-        this._spacer = " "; // optional; default is " "
-        this._includeZero = true; // optional; default is true
-        this._name = name;
-    }
-    get name() { return this._name; }
-    get roundFactor() { return this._roundFactor; }
-    set roundFactor(roundFactor) { this._roundFactor = roundFactor; }
-    get type() { return this._type; }
-    set type(formatType) { this._type = formatType; }
-    get precision() { return this._precision; }
-    set precision(precision) { this._precision = precision; }
-    get minWidth() { return this._minWidth; }
-    set minWidth(minWidth) { this._minWidth = minWidth; }
-    get scientificType() { return this._scientificType; }
-    set scientificType(scientificType) { this._scientificType = scientificType; }
-    get showSignOption() { return this._showSignOption; }
-    set showSignOption(showSignOption) { this._showSignOption = showSignOption; }
-    get decimalSeparator() { return this._decimalSeparator; }
-    set decimalSeparator(decimalSeparator) { this._decimalSeparator = decimalSeparator; }
-    get thousandSeparator() { return this._thousandSeparator; }
-    set thousandSeparator(thousandSeparator) { this._thousandSeparator = thousandSeparator; }
-    get uomSeparator() { return this._uomSeparator; }
-    set uomSeparator(uomSeparator) { this._uomSeparator = uomSeparator; }
-    get stationSeparator() { return this._stationSeparator; }
-    set stationSeparator(stationSeparator) { this._stationSeparator = stationSeparator; }
-    get stationOffsetSize() { return this._stationOffsetSize; }
-    set stationOffsetSize(stationOffsetSize) { stationOffsetSize = this._stationOffsetSize = stationOffsetSize; }
-    get formatTraits() { return this._formatTraits; }
-    set formatTraits(formatTraits) { this._formatTraits = formatTraits; }
-    get spacer() { return this._spacer; }
-    set spacer(spacer) { this._spacer = spacer ?? this._spacer; }
-    get includeZero() { return this._includeZero; }
-    set includeZero(includeZero) { this._includeZero = includeZero ?? this._includeZero; }
-    /** This method parses input string that is typically extracted for persisted JSON data and validates that the string is a valid FormatType. Throws exception if not valid. */
-    parseFormatTraits(formatTraitsFromJson) {
-        const formatTraits = (Array.isArray(formatTraitsFromJson)) ? formatTraitsFromJson : formatTraitsFromJson.split(/,|;|\|/);
-        formatTraits.forEach((formatTraitsString) => {
-            const formatTrait = parseFormatTrait(formatTraitsString, this.name);
-            this._formatTraits = this.formatTraits | formatTrait;
-        });
-    }
-    /** This method returns true if the formatTrait is set in this Format object. */
-    hasFormatTraitSet(formatTrait) {
-        return (this._formatTraits & formatTrait) === formatTrait;
-    }
-    loadFormatProperties(formatProps) {
-        this._type = parseFormatType(formatProps.type, this.name);
-        if (formatProps.precision !== undefined) {
-            if (!Number.isInteger(formatProps.precision)) // mut be an integer
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'precision' attribute. It should be an integer.`);
-            this._precision = parsePrecision(formatProps.precision, this._type, this.name);
-        }
-        if (this.type === FormatType.Scientific) {
-            if (undefined === formatProps.scientificType) // if format type is scientific and scientific type is undefined, throw
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} is 'Scientific' type therefore the attribute 'scientificType' is required.`);
-            this._scientificType = parseScientificType(formatProps.scientificType, this.name);
-        }
-        if (undefined !== formatProps.roundFactor) { // optional; default is 0.0
-            if (typeof (formatProps.roundFactor) !== "number")
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'roundFactor' attribute. It should be of type 'number'.`);
-            if (formatProps.roundFactor !== this.roundFactor) // if roundFactor isn't default value of 0.0, reassign roundFactor variable
-                this._roundFactor = formatProps.roundFactor;
-        }
-        if (undefined !== formatProps.minWidth) { // optional
-            if (!Number.isInteger(formatProps.minWidth) || formatProps.minWidth < 0) // must be a positive int
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'minWidth' attribute. It should be a positive integer.`);
-            this._minWidth = formatProps.minWidth;
-        }
-        if (FormatType.Station === this.type) {
-            if (undefined === formatProps.stationOffsetSize)
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} is 'Station' type therefore the attribute 'stationOffsetSize' is required.`);
-            if (!Number.isInteger(formatProps.stationOffsetSize) || formatProps.stationOffsetSize < 0) // must be a positive int > 0
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'stationOffsetSize' attribute. It should be a positive integer.`);
-            this._stationOffsetSize = formatProps.stationOffsetSize;
-        }
-        if (undefined !== formatProps.showSignOption) { // optional; default is "onlyNegative"
-            this._showSignOption = parseShowSignOption(formatProps.showSignOption, this.name);
-        }
-        if (undefined !== formatProps.formatTraits && formatProps.formatTraits.length !== 0) { // FormatTraits is optional
-            if (!Array.isArray(formatProps.formatTraits) && typeof (formatProps.formatTraits) !== "string") // must be either an array of strings or a string
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'formatTraits' attribute. It should be of type 'string' or 'string[]'.`);
-            this.parseFormatTraits(formatProps.formatTraits); // check that all of the options for formatTraits are valid. If now, throw
-        }
-        if (undefined !== formatProps.decimalSeparator) { // optional
-            if (typeof (formatProps.decimalSeparator) !== "string") // not a string or not a one character string
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'decimalSeparator' attribute. It should be of type 'string'.`);
-            if (formatProps.decimalSeparator.length > 1)
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'decimalSeparator' attribute. It should be an empty or one character string.`);
-            this._decimalSeparator = formatProps.decimalSeparator;
-        }
-        if (undefined !== formatProps.thousandSeparator) { // optional
-            if (typeof (formatProps.thousandSeparator) !== "string")
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'thousandSeparator' attribute. It should be of type 'string'.`);
-            if (formatProps.thousandSeparator.length > 1)
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'thousandSeparator' attribute. It should be an empty or one character string.`);
-            this._thousandSeparator = formatProps.thousandSeparator;
-        }
-        if (undefined !== formatProps.uomSeparator) { // optional; default is " "
-            if (typeof (formatProps.uomSeparator) !== "string")
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'uomSeparator' attribute. It should be of type 'string'.`);
-            if (formatProps.uomSeparator.length < 0 || formatProps.uomSeparator.length > 1)
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'uomSeparator' attribute. It should be an empty or one character string.`);
-            this._uomSeparator = formatProps.uomSeparator;
-        }
-        if (undefined !== formatProps.stationSeparator) { // optional; default is "+"
-            if (typeof (formatProps.stationSeparator) !== "string")
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'stationSeparator' attribute. It should be of type 'string'.`);
-            if (formatProps.stationSeparator.length > 1)
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'stationSeparator' attribute. It should be an empty or one character string.`);
-            this._stationSeparator = formatProps.stationSeparator;
-        }
-    }
-}
-/** A class used to define the specifications for formatting quantity values. This class is typically loaded by reading [[FormatProps]].
- * @beta
- */
-export class Format extends BaseFormat {
-    /** Constructor
-     *  @param name     The name of a format specification. TODO: make optional or remove
-     */
-    constructor(name) {
-        super(name);
-    }
-    get units() { return this._units; }
-    get hasUnits() { return this._units !== undefined && this._units.length > 0; }
-    get customProps() { return this._customProps; }
-    static isFormatTraitSetInProps(formatProps, trait) {
-        if (!formatProps.formatTraits)
-            return false;
-        const formatTraits = Array.isArray(formatProps.formatTraits) ? formatProps.formatTraits : formatProps.formatTraits.split(/,|;|\|/);
-        const traitStr = getTraitString(trait);
-        return formatTraits.find((traitEntry) => traitStr === traitEntry) ? true : false;
-    }
-    async createUnit(unitsProvider, name, label) {
-        if (name === undefined || typeof (name) !== "string" || (label !== undefined && typeof (label) !== "string")) // throws if name is undefined or name isn't a string or if label is defined and isn't a string
-            throw new QuantityError(QuantityStatus.InvalidJson, `This Composite has a unit with an invalid 'name' or 'label' attribute.`);
-        for (const unit of this.units) {
-            const unitObj = unit[0].name;
-            if (unitObj.toLowerCase() === name.toLowerCase()) // duplicate names are not allowed
-                throw new QuantityError(QuantityStatus.InvalidJson, `The unit ${unitObj} has a duplicate name.`);
-        }
-        const newUnit = await unitsProvider.findUnitByName(name);
-        if (!newUnit || !newUnit.isValid)
-            throw new QuantityError(QuantityStatus.InvalidJson, `Invalid unit name '${name}'.`);
-        this.units.push([newUnit, label]);
-    }
-    /**
-     *  Clone Format
-     */
-    clone(options) {
-        const newFormat = new Format(this.name);
-        newFormat._roundFactor = this._roundFactor;
-        newFormat._type = this._type;
-        newFormat._precision = this._precision;
-        newFormat._minWidth = this._minWidth;
-        newFormat._scientificType = this._scientificType;
-        newFormat._showSignOption = this._showSignOption;
-        newFormat._decimalSeparator = this._decimalSeparator;
-        newFormat._thousandSeparator = this._thousandSeparator;
-        newFormat._uomSeparator = this._uomSeparator;
-        newFormat._stationSeparator = this._stationSeparator;
-        newFormat._stationOffsetSize = this._stationOffsetSize;
-        newFormat._formatTraits = this._formatTraits;
-        newFormat._spacer = this._spacer;
-        newFormat._includeZero = this._includeZero;
-        newFormat._customProps = this._customProps;
-        this._units && (newFormat._units = [...this._units]);
-        if (newFormat._units) {
-            if (options?.showOnlyPrimaryUnit) {
-                if (newFormat._units.length > 1)
-                    newFormat._units.length = 1;
-            }
-        }
-        if (undefined !== options?.traits)
-            newFormat._formatTraits = options?.traits;
-        if (undefined !== options?.type)
-            newFormat._type = options.type;
-        if (undefined !== options?.precision) {
-            // ensure specified precision is valid
-            const precision = parsePrecision(options?.precision, newFormat._type, newFormat.name);
-            newFormat._precision = precision;
-        }
-        if (undefined !== options?.primaryUnit) {
-            if (options.primaryUnit.unit) {
-                const newUnits = new Array();
-                newUnits.push([options.primaryUnit.unit, options.primaryUnit.label]);
-                newFormat._units = newUnits;
-            }
-            else if (options.primaryUnit.label && newFormat._units?.length) {
-                // update label only
-                newFormat._units[0][1] = options.primaryUnit.label;
-            }
-        }
-        return newFormat;
-    }
-    /**
-     * Populates this Format with the values from the provided.
-     */
-    async fromJSON(unitsProvider, jsonObj) {
-        this.loadFormatProperties(jsonObj);
-        if (isCustomFormatProps(jsonObj))
-            this._customProps = jsonObj.custom;
-        if (undefined !== jsonObj.composite) { // optional
-            this._units = new Array();
-            if (jsonObj.composite.includeZero !== undefined) {
-                if (typeof (jsonObj.composite.includeZero) !== "boolean") // includeZero must be a boolean IF it is defined
-                    throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has a Composite with an invalid 'includeZero' attribute. It should be of type 'boolean'.`);
-                this._includeZero = jsonObj.composite.includeZero;
-            }
-            if (jsonObj.composite.spacer !== undefined) { // spacer must be a string IF it is defined
-                if (typeof (jsonObj.composite.spacer) !== "string")
-                    throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has a Composite with an invalid 'spacer' attribute. It must be of type 'string'.`);
-                if (jsonObj.composite.spacer.length > 1)
-                    throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has a Composite with an invalid 'spacer' attribute. It should be an empty or one character string.`);
-                this._spacer = jsonObj.composite.spacer;
-            }
-            if (jsonObj.composite.units !== undefined) { // if composite is defined, it must be an array with 1-4 units
-                if (!Array.isArray(jsonObj.composite.units)) { // must be an array
-                    throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has a Composite with an invalid 'units' attribute. It must be of type 'array'`);
-                }
-                if (jsonObj.composite.units.length > 0 && jsonObj.composite.units.length <= 4) { // Composite requires 1-4 units
-                    try {
-                        const createUnitPromises = [];
-                        for (const unit of jsonObj.composite.units) {
-                            createUnitPromises.push(this.createUnit(unitsProvider, unit.name, unit.label));
-                        }
-                        await Promise.all(createUnitPromises);
-                    }
-                    catch (e) {
-                        throw e;
-                    }
-                }
-            }
-            if (undefined === this.units || this.units.length === 0)
-                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has a Composite with no valid 'units'`);
-        }
-    }
-    /** Create a Format from FormatProps */
-    static async createFromJSON(name, unitsProvider, formatProps) {
-        const actualFormat = new Format(name);
-        await actualFormat.fromJSON(unitsProvider, formatProps);
-        return actualFormat;
-    }
-    /**
-     * Returns a JSON object that contain the specification for this Format.
-     */
-    toJSON() {
-        let composite;
-        if (this.units) {
-            const units = this.units.map((value) => {
-                if (undefined !== value[1])
-                    return { name: value[0].name, label: value[1] };
-                else
-                    return { name: value[0].name };
-            });
-            composite = {
-                spacer: this.spacer,
-                includeZero: this.includeZero,
-                units,
-            };
-        }
-        if (this.customProps)
-            return {
-                type: formatTypeToString(this.type),
-                precision: this.precision,
-                roundFactor: this.roundFactor,
-                minWidth: this.minWidth,
-                showSignOption: showSignOptionToString(this.showSignOption),
-                formatTraits: formatTraitsToArray(this.formatTraits),
-                decimalSeparator: this.decimalSeparator,
-                thousandSeparator: this.thousandSeparator,
-                uomSeparator: this.uomSeparator,
-                scientificType: this.scientificType ? scientificTypeToString(this.scientificType) : undefined,
-                stationOffsetSize: this.stationOffsetSize,
-                stationSeparator: this.stationSeparator,
-                composite,
-                custom: this.customProps,
-            };
-        return {
-            type: formatTypeToString(this.type),
-            precision: this.precision,
-            roundFactor: this.roundFactor,
-            minWidth: this.minWidth,
-            showSignOption: showSignOptionToString(this.showSignOption),
-            formatTraits: formatTraitsToArray(this.formatTraits),
-            decimalSeparator: this.decimalSeparator,
-            thousandSeparator: this.thousandSeparator,
-            uomSeparator: this.uomSeparator,
-            scientificType: this.scientificType ? scientificTypeToString(this.scientificType) : undefined,
-            stationOffsetSize: this.stationOffsetSize,
-            stationSeparator: this.stationSeparator,
-            composite,
-        };
-    }
-}
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module Quantity
+ */
+import { QuantityConstants } from "../Constants";
+import { QuantityError, QuantityStatus } from "../Exception";
+import { DecimalPrecision, FormatTraits, formatTraitsToArray, FormatType, formatTypeToString, getTraitString, parseFormatTrait, parseFormatType, parsePrecision, parseScientificType, parseShowSignOption, scientificTypeToString, ShowSignOption, showSignOptionToString } from "./FormatEnums";
+import { isCustomFormatProps } from "./Interfaces";
+// cSpell:ignore ZERONORMALIZED, nosign, onlynegative, signalways, negativeparentheses
+// cSpell:ignore trailzeroes, keepsinglezero, zeroempty, keepdecimalpoint, applyrounding, fractiondash, showunitlabel, prependunitlabel, exponentonlynegative
+/** A base Format class with shared properties and functionality between quantity and ecschema-metadata Format classes
+ * @beta
+ */
+export class BaseFormat {
+    constructor(name) {
+        this._name = "";
+        this._roundFactor = 0.0;
+        this._type = FormatType.Decimal; // required; options are decimal, fractional, scientific, station
+        this._precision = DecimalPrecision.Six; // required
+        this._showSignOption = ShowSignOption.OnlyNegative; // options: noSign, onlyNegative, signAlways, negativeParentheses
+        this._decimalSeparator = QuantityConstants.LocaleSpecificDecimalSeparator;
+        this._thousandSeparator = QuantityConstants.LocaleSpecificThousandSeparator;
+        this._uomSeparator = " "; // optional; default is " "; defined separator between magnitude and the unit
+        this._stationSeparator = "+"; // optional; default is "+"
+        this._formatTraits = FormatTraits.Uninitialized;
+        this._spacer = " "; // optional; default is " "
+        this._includeZero = true; // optional; default is true
+        this._name = name;
+    }
+    get name() { return this._name; }
+    get roundFactor() { return this._roundFactor; }
+    set roundFactor(roundFactor) { this._roundFactor = roundFactor; }
+    get type() { return this._type; }
+    set type(formatType) { this._type = formatType; }
+    get precision() { return this._precision; }
+    set precision(precision) { this._precision = precision; }
+    get minWidth() { return this._minWidth; }
+    set minWidth(minWidth) { this._minWidth = minWidth; }
+    get scientificType() { return this._scientificType; }
+    set scientificType(scientificType) { this._scientificType = scientificType; }
+    get showSignOption() { return this._showSignOption; }
+    set showSignOption(showSignOption) { this._showSignOption = showSignOption; }
+    get decimalSeparator() { return this._decimalSeparator; }
+    set decimalSeparator(decimalSeparator) { this._decimalSeparator = decimalSeparator; }
+    get thousandSeparator() { return this._thousandSeparator; }
+    set thousandSeparator(thousandSeparator) { this._thousandSeparator = thousandSeparator; }
+    get uomSeparator() { return this._uomSeparator; }
+    set uomSeparator(uomSeparator) { this._uomSeparator = uomSeparator; }
+    get stationSeparator() { return this._stationSeparator; }
+    set stationSeparator(stationSeparator) { this._stationSeparator = stationSeparator; }
+    get stationOffsetSize() { return this._stationOffsetSize; }
+    set stationOffsetSize(stationOffsetSize) { stationOffsetSize = this._stationOffsetSize = stationOffsetSize; }
+    get formatTraits() { return this._formatTraits; }
+    set formatTraits(formatTraits) { this._formatTraits = formatTraits; }
+    get spacer() { return this._spacer; }
+    set spacer(spacer) { this._spacer = spacer ?? this._spacer; }
+    get includeZero() { return this._includeZero; }
+    set includeZero(includeZero) { this._includeZero = includeZero ?? this._includeZero; }
+    /** This method parses input string that is typically extracted for persisted JSON data and validates that the string is a valid FormatType. Throws exception if not valid. */
+    parseFormatTraits(formatTraitsFromJson) {
+        const formatTraits = (Array.isArray(formatTraitsFromJson)) ? formatTraitsFromJson : formatTraitsFromJson.split(/,|;|\|/);
+        formatTraits.forEach((formatTraitsString) => {
+            const formatTrait = parseFormatTrait(formatTraitsString, this.name);
+            this._formatTraits = this.formatTraits | formatTrait;
+        });
+    }
+    /** This method returns true if the formatTrait is set in this Format object. */
+    hasFormatTraitSet(formatTrait) {
+        return (this._formatTraits & formatTrait) === formatTrait;
+    }
+    loadFormatProperties(formatProps) {
+        this._type = parseFormatType(formatProps.type, this.name);
+        if (formatProps.precision !== undefined) {
+            if (!Number.isInteger(formatProps.precision)) // mut be an integer
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'precision' attribute. It should be an integer.`);
+            this._precision = parsePrecision(formatProps.precision, this._type, this.name);
+        }
+        if (this.type === FormatType.Scientific) {
+            if (undefined === formatProps.scientificType) // if format type is scientific and scientific type is undefined, throw
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} is 'Scientific' type therefore the attribute 'scientificType' is required.`);
+            this._scientificType = parseScientificType(formatProps.scientificType, this.name);
+        }
+        if (undefined !== formatProps.roundFactor) { // optional; default is 0.0
+            if (typeof (formatProps.roundFactor) !== "number")
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'roundFactor' attribute. It should be of type 'number'.`);
+            if (formatProps.roundFactor !== this.roundFactor) // if roundFactor isn't default value of 0.0, reassign roundFactor variable
+                this._roundFactor = formatProps.roundFactor;
+        }
+        if (undefined !== formatProps.minWidth) { // optional
+            if (!Number.isInteger(formatProps.minWidth) || formatProps.minWidth < 0) // must be a positive int
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'minWidth' attribute. It should be a positive integer.`);
+            this._minWidth = formatProps.minWidth;
+        }
+        if (FormatType.Station === this.type) {
+            if (undefined === formatProps.stationOffsetSize)
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} is 'Station' type therefore the attribute 'stationOffsetSize' is required.`);
+            if (!Number.isInteger(formatProps.stationOffsetSize) || formatProps.stationOffsetSize < 0) // must be a positive int > 0
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'stationOffsetSize' attribute. It should be a positive integer.`);
+            this._stationOffsetSize = formatProps.stationOffsetSize;
+        }
+        if (undefined !== formatProps.showSignOption) { // optional; default is "onlyNegative"
+            this._showSignOption = parseShowSignOption(formatProps.showSignOption, this.name);
+        }
+        if (undefined !== formatProps.formatTraits && formatProps.formatTraits.length !== 0) { // FormatTraits is optional
+            if (!Array.isArray(formatProps.formatTraits) && typeof (formatProps.formatTraits) !== "string") // must be either an array of strings or a string
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'formatTraits' attribute. It should be of type 'string' or 'string[]'.`);
+            this.parseFormatTraits(formatProps.formatTraits); // check that all of the options for formatTraits are valid. If now, throw
+        }
+        if (undefined !== formatProps.decimalSeparator) { // optional
+            if (typeof (formatProps.decimalSeparator) !== "string") // not a string or not a one character string
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'decimalSeparator' attribute. It should be of type 'string'.`);
+            if (formatProps.decimalSeparator.length > 1)
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'decimalSeparator' attribute. It should be an empty or one character string.`);
+            this._decimalSeparator = formatProps.decimalSeparator;
+        }
+        if (undefined !== formatProps.thousandSeparator) { // optional
+            if (typeof (formatProps.thousandSeparator) !== "string")
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'thousandSeparator' attribute. It should be of type 'string'.`);
+            if (formatProps.thousandSeparator.length > 1)
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'thousandSeparator' attribute. It should be an empty or one character string.`);
+            this._thousandSeparator = formatProps.thousandSeparator;
+        }
+        if (undefined !== formatProps.uomSeparator) { // optional; default is " "
+            if (typeof (formatProps.uomSeparator) !== "string")
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'uomSeparator' attribute. It should be of type 'string'.`);
+            if (formatProps.uomSeparator.length < 0 || formatProps.uomSeparator.length > 1)
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'uomSeparator' attribute. It should be an empty or one character string.`);
+            this._uomSeparator = formatProps.uomSeparator;
+        }
+        if (undefined !== formatProps.stationSeparator) { // optional; default is "+"
+            if (typeof (formatProps.stationSeparator) !== "string")
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'stationSeparator' attribute. It should be of type 'string'.`);
+            if (formatProps.stationSeparator.length > 1)
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has an invalid 'stationSeparator' attribute. It should be an empty or one character string.`);
+            this._stationSeparator = formatProps.stationSeparator;
+        }
+    }
+}
+/** A class used to define the specifications for formatting quantity values. This class is typically loaded by reading [[FormatProps]].
+ * @beta
+ */
+export class Format extends BaseFormat {
+    /** Constructor
+     *  @param name     The name of a format specification. TODO: make optional or remove
+     */
+    constructor(name) {
+        super(name);
+    }
+    get units() { return this._units; }
+    get hasUnits() { return this._units !== undefined && this._units.length > 0; }
+    get customProps() { return this._customProps; }
+    static isFormatTraitSetInProps(formatProps, trait) {
+        if (!formatProps.formatTraits)
+            return false;
+        const formatTraits = Array.isArray(formatProps.formatTraits) ? formatProps.formatTraits : formatProps.formatTraits.split(/,|;|\|/);
+        const traitStr = getTraitString(trait);
+        return formatTraits.find((traitEntry) => traitStr === traitEntry) ? true : false;
+    }
+    async createUnit(unitsProvider, name, label) {
+        if (name === undefined || typeof (name) !== "string" || (label !== undefined && typeof (label) !== "string")) // throws if name is undefined or name isn't a string or if label is defined and isn't a string
+            throw new QuantityError(QuantityStatus.InvalidJson, `This Composite has a unit with an invalid 'name' or 'label' attribute.`);
+        for (const unit of this.units) {
+            const unitObj = unit[0].name;
+            if (unitObj.toLowerCase() === name.toLowerCase()) // duplicate names are not allowed
+                throw new QuantityError(QuantityStatus.InvalidJson, `The unit ${unitObj} has a duplicate name.`);
+        }
+        const newUnit = await unitsProvider.findUnitByName(name);
+        if (!newUnit || !newUnit.isValid)
+            throw new QuantityError(QuantityStatus.InvalidJson, `Invalid unit name '${name}'.`);
+        this.units.push([newUnit, label]);
+    }
+    /**
+     *  Clone Format
+     */
+    clone(options) {
+        const newFormat = new Format(this.name);
+        newFormat._roundFactor = this._roundFactor;
+        newFormat._type = this._type;
+        newFormat._precision = this._precision;
+        newFormat._minWidth = this._minWidth;
+        newFormat._scientificType = this._scientificType;
+        newFormat._showSignOption = this._showSignOption;
+        newFormat._decimalSeparator = this._decimalSeparator;
+        newFormat._thousandSeparator = this._thousandSeparator;
+        newFormat._uomSeparator = this._uomSeparator;
+        newFormat._stationSeparator = this._stationSeparator;
+        newFormat._stationOffsetSize = this._stationOffsetSize;
+        newFormat._formatTraits = this._formatTraits;
+        newFormat._spacer = this._spacer;
+        newFormat._includeZero = this._includeZero;
+        newFormat._customProps = this._customProps;
+        this._units && (newFormat._units = [...this._units]);
+        if (newFormat._units) {
+            if (options?.showOnlyPrimaryUnit) {
+                if (newFormat._units.length > 1)
+                    newFormat._units.length = 1;
+            }
+        }
+        if (undefined !== options?.traits)
+            newFormat._formatTraits = options?.traits;
+        if (undefined !== options?.type)
+            newFormat._type = options.type;
+        if (undefined !== options?.precision) {
+            // ensure specified precision is valid
+            const precision = parsePrecision(options?.precision, newFormat._type, newFormat.name);
+            newFormat._precision = precision;
+        }
+        if (undefined !== options?.primaryUnit) {
+            if (options.primaryUnit.unit) {
+                const newUnits = new Array();
+                newUnits.push([options.primaryUnit.unit, options.primaryUnit.label]);
+                newFormat._units = newUnits;
+            }
+            else if (options.primaryUnit.label && newFormat._units?.length) {
+                // update label only
+                newFormat._units[0][1] = options.primaryUnit.label;
+            }
+        }
+        return newFormat;
+    }
+    /**
+     * Populates this Format with the values from the provided.
+     */
+    async fromJSON(unitsProvider, jsonObj) {
+        this.loadFormatProperties(jsonObj);
+        if (isCustomFormatProps(jsonObj))
+            this._customProps = jsonObj.custom;
+        if (undefined !== jsonObj.composite) { // optional
+            this._units = new Array();
+            if (jsonObj.composite.includeZero !== undefined) {
+                if (typeof (jsonObj.composite.includeZero) !== "boolean") // includeZero must be a boolean IF it is defined
+                    throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has a Composite with an invalid 'includeZero' attribute. It should be of type 'boolean'.`);
+                this._includeZero = jsonObj.composite.includeZero;
+            }
+            if (jsonObj.composite.spacer !== undefined) { // spacer must be a string IF it is defined
+                if (typeof (jsonObj.composite.spacer) !== "string")
+                    throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has a Composite with an invalid 'spacer' attribute. It must be of type 'string'.`);
+                if (jsonObj.composite.spacer.length > 1)
+                    throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has a Composite with an invalid 'spacer' attribute. It should be an empty or one character string.`);
+                this._spacer = jsonObj.composite.spacer;
+            }
+            if (jsonObj.composite.units !== undefined) { // if composite is defined, it must be an array with 1-4 units
+                if (!Array.isArray(jsonObj.composite.units)) { // must be an array
+                    throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has a Composite with an invalid 'units' attribute. It must be of type 'array'`);
+                }
+                if (jsonObj.composite.units.length > 0 && jsonObj.composite.units.length <= 4) { // Composite requires 1-4 units
+                    try {
+                        const createUnitPromises = [];
+                        for (const unit of jsonObj.composite.units) {
+                            createUnitPromises.push(this.createUnit(unitsProvider, unit.name, unit.label));
+                        }
+                        await Promise.all(createUnitPromises);
+                    }
+                    catch (e) {
+                        throw e;
+                    }
+                }
+            }
+            if (undefined === this.units || this.units.length === 0)
+                throw new QuantityError(QuantityStatus.InvalidJson, `The Format ${this.name} has a Composite with no valid 'units'`);
+        }
+    }
+    /** Create a Format from FormatProps */
+    static async createFromJSON(name, unitsProvider, formatProps) {
+        const actualFormat = new Format(name);
+        await actualFormat.fromJSON(unitsProvider, formatProps);
+        return actualFormat;
+    }
+    /**
+     * Returns a JSON object that contain the specification for this Format.
+     */
+    toJSON() {
+        let composite;
+        if (this.units) {
+            const units = this.units.map((value) => {
+                if (undefined !== value[1])
+                    return { name: value[0].name, label: value[1] };
+                else
+                    return { name: value[0].name };
+            });
+            composite = {
+                spacer: this.spacer,
+                includeZero: this.includeZero,
+                units,
+            };
+        }
+        if (this.customProps)
+            return {
+                type: formatTypeToString(this.type),
+                precision: this.precision,
+                roundFactor: this.roundFactor,
+                minWidth: this.minWidth,
+                showSignOption: showSignOptionToString(this.showSignOption),
+                formatTraits: formatTraitsToArray(this.formatTraits),
+                decimalSeparator: this.decimalSeparator,
+                thousandSeparator: this.thousandSeparator,
+                uomSeparator: this.uomSeparator,
+                scientificType: this.scientificType ? scientificTypeToString(this.scientificType) : undefined,
+                stationOffsetSize: this.stationOffsetSize,
+                stationSeparator: this.stationSeparator,
+                composite,
+                custom: this.customProps,
+            };
+        return {
+            type: formatTypeToString(this.type),
+            precision: this.precision,
+            roundFactor: this.roundFactor,
+            minWidth: this.minWidth,
+            showSignOption: showSignOptionToString(this.showSignOption),
+            formatTraits: formatTraitsToArray(this.formatTraits),
+            decimalSeparator: this.decimalSeparator,
+            thousandSeparator: this.thousandSeparator,
+            uomSeparator: this.uomSeparator,
+            scientificType: this.scientificType ? scientificTypeToString(this.scientificType) : undefined,
+            stationOffsetSize: this.stationOffsetSize,
+            stationSeparator: this.stationSeparator,
+            composite,
+        };
+    }
+}
 //# sourceMappingURL=Format.js.map