Quantity class abstract

The abstract base class for all quantities. The Quantity class represents the value of a physical quantity and its associated dimensions. It provides methods for constructing and getting the quantity's value in arbitrary units, methods for mathematical manipulation and comparison and optional features such as arbitrary precision and uncertainty.

Definitions

from NIST's introduction to the International System of Units

A quantity in the general sense is a property ascribed to phenomena, bodies, or substances that can be quantified for, or assigned to, a particular phenomenon, body, or substance. Examples are mass and electric charge.
A quantity in the particular sense is a quantifiable or assignable property ascribed to a particular phenomenon, body, or substance. Examples are the mass of the moon and the electric charge of the proton.
A physical quantity is a quantity that can be used in the mathematical equations of science and technology.
A unit is a particular physical quantity, defined and adopted by convention, with which other particular quantities of the same kind (dimension) are compared to express their value.
The value of a physical quantity is the quantitative expression of a particular physical quantity as the product of a number and a unit, the number being its numerical value. Thus, the numerical value of a particular physical quantity depends on the unit in which it is expressed.

Immutable

Quantity instances are immutable; they may not be changed after creation. Use MutableQuantity in the quantity_ext library for situations where changing a Quantity object's value or units is required.

Value Representation, Arbitrary Precision

Quantity supports values specified by num or Number objects. Number subtypes include Real, Imaginary and Complex. Various Real subtypes are available, including Precise, which supports arbitrary precision calculations.

Uncertainty

A Quantity object optionally includes an uncertainty, as quantities are often determined by measurement and therefore are only accurate within the capabilities of the measuring devices or techniques. Internally, the uncertainty of a quantity is modeled as a Normal (Gaussian) distribution. The shape of this 'bell curve' distribution is captured by a single value: the relative standard uncertainty. This method of expressing uncertainty is used for all physical constants and is accepted for general use with all quantities (because quantities, as measurable entities, all follow the same logic for representing the uncertainty generated by the combination of values from many different experiments). The relative standard uncertainty corresponds to an approximately 68% confidence level that the quantity's value is in the stated range. For different confidence levels, alternative coverage factors may be used (k=2 ~95%; k=3 ~99%). Uncertainty calculations may be switched on or off as desired. It is automatically on if the Quantity is constructed with any uncertainty and off otherwise. The setCalcUncertainty method may be called at any point to enable/disable this capability.

Implemented types

Comparable

Implementers

Constructors

Quantity([dynamic value = Integer.zero, Units? preferredUnits, double uncert = 0.0]): This constructor sets the value (as expressed in the accompanying units) and the relative standard uncertainty. The value is may be set using any num or Number object, including Precise for arbitrary precision.
Quantity.constant(Number valueSI, Dimensions dimensions, Units? preferredUnits, double _ur): Used to construct a constant Quantity.
const
Quantity.misc([dynamic value = 0.0, Dimensions? dimensions, double uncert = 0.0]): A constructor to support miscellaneous quantities: dimensions are known, units are not.

Properties

arbitraryPrecision → bool: Whether or not this Quantity is represented using arbitrary precision.
no setter
cgs → Number: Returns the value of this quantity in alternative CGS (or centimeter-gram-second) units. MKS (meter-kilogram-second) units are preferred.
no setter
dimensions → Dimensions: Dimensions.
final
hashCode → int: The hash code is based on the value and dimensions. Uncertainty and preferred units are not considered.
no setteroverride
isScalar → bool: Whether or not this Quantity has scalar dimensions, including having no angle or solid angle dimensions.
no setter
isScalarSI → bool: Whether or not this Quantity has scalar dimensions in the strict International System of Units (SI) sense, which allows non-zero angle and solid angle dimensions.
no setter
mks → Number: Returns the value of this quantity in standard MKS (or meter-kilogram-second) units.
no setter
preferredUnits → Units?: Preferred units for display.
final
relativeUncertainty → double: The relative standard uncertainty in this Quantity object's value.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
standardUncertainty → Quantity: Returns the standard uncertainty in this Quantity object's value as a typed Quantity object.
no setter
valueSI → Number: The value of the quantity in the base units, of the International System of Units (SI).
final

Methods

abs() → Quantity: Returns the absolute value of this Quantity. If the value of this Quantity is not negative it is returned directly.
calcExpandedUncertainty(double k) → Quantity: Returns the expanded uncertainty for coverage factor, k, in this Quantity's value as a typed Quantity object.
compareTo(dynamic q2) → int: Compares this Quantity to q2 by comparing MKS values. The Quantities need not have the same dimensions.
override
inverse() → Quantity: Determines the inverse of the quantity represented by this object, creating and returning a Quantity object (which may have different dimensions and therefore be of a different type). This object is not modified.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
outputText(StringBuffer buffer, {UncertaintyFormat uncertFormat = UncertaintyFormat.none, bool symbols = true, NumberFormat? numberFormat}) → void: Appends a String representation of this Quantity to the buffer using the preferred units and number format. If no preferred units have been specified, then MKS units are used. Uncertainty in the value of the Quantity is optionally shown as a plus/minus value in the same units.
randomSample() → Quantity: Randomly generates a Quantity from this Quantity's value and uncertainty. The uncertainty is represented by a Normal (Gaussian) continuous distribution.
sqrt() → Quantity: Returns a Quantity that represents the square root of this Quantity, in terms of both value and dimensions (for example, if this Quantity were an Area of 16 square meters, a Length of 4 meters will be returned).
toJson() → Map<String, dynamic>: Support dart:convert stringify.
toString() → String: Returns a String representation of this Quantity using the preferredUnits. If no preferred units have been specified, then MKS units are used.
override
valueInUnits(Units? units) → Number: Gets the Quantity's value in the specified units. If units is null, the MKS value is returned. If not null, units must have dimensions compatible with this Quantity or a DimensionsException will be thrown.

Operators

operator *(dynamic multiplier) → Quantity: Returns the product of this quantity and multiplier, which is expected to be either a Quantity, num or Number object. All other types will cause a QuantityException to be thrown.
operator +(dynamic addend) → Quantity: Returns the sum of this Quantity and addend.
operator -(dynamic subtrahend) → Quantity: Returns the difference of this Quantity and subtrahend or (this - q2).
operator /(dynamic divisor) → Quantity: Returns the quotient of this quantity and divisor, including both value and dimensions.
operator <(Quantity other) → bool: Determines whether on not this Quantity is less than a specified Quantity by comparing their MKS values. The two Quantities need not be of the same type or dimensions.
operator <=(Quantity other) → bool: Determines whether on not this Quantity is less than or equal to a specified Quantity by comparing their MKS values. The two Quantities need not be of the same type or dimensions.
operator ==(Object obj) → bool: Returns true if this Quantity is equal to obj. Two Quantity objects are considered equal if their MKS values and dimensions are equal. Only values and dimensions are considered; other attributes such as uncertainty and preferred units are ignored.
override
operator >(Quantity other) → bool: Determines whether on not this Quantity is greater than a specified Quantity by comparing their MKS values. The two Quantities need not be of the same type or dimensions.
operator >=(Quantity other) → bool: Determines whether on not this Quantity is greater than or equal to a specified Quantity by comparing their MKS values. The two Quantities need not be of the same type or dimensions.
operator ^(dynamic exponent) → Quantity: Returns this Quantity raised to the power of exponent.
operator unary-() → Quantity: The unary minus operator returns a Quantity whose value is the negative of this Quantity's value.

Static Methods

calcRelativeCombinedUncertaintySumDiff(Quantity q1, Quantity q2, Number valueSI) → double: Calculates the relative combined uncertainty resulting from the addition or subtraction of two Quantities.