API Reference > core-frontend > QuantityFormatting > QuantityFormatter

QuantityFormatter Class

Class that supports formatting quantity values into strings and parsing strings into quantity values. This class also maintains the "active" unit system and caches FormatterSpecs and ParserSpecs for the "active" unit system to allow synchronous access to parsing and formatting values. The support unit systems are defined by UnitSystemKey and is kept in synch with the unit systems provided by the Presentation Manager on the backend. The QuantityFormatter contains a registry of quantity type definitions. These definitions implement the QuantityTypeDefinition interface, which among other things, provide default [FormatProps]$(core-quantity), and provide methods to generate both a [FormatterSpec]$(core-quantity) and a [ParserSpec]$(core-quantity). There are built-in quantity types that are identified by the QuantityType enum. CustomQuantityTypeDefinition can be registered to extend the available quantity types available by frontend tools. The QuantityFormatter also allows the default formats to be overriden.

Implements

Methods

Name Description
constructor(showMetricOrUnitSystem?: boolean | UnitSystemKey): QuantityFormatter constructor  
addAlternateLabels(key: string, ...labels: string[]): void Add one or more alternate labels for a unit - these labels are used during string parsing.  
clearAllOverrideFormats(): Promise<void> Clear formatting override for all quantity types, but only for the "active" Unit System.  
clearOverrideFormats(type: QuantityTypeArg): Promise<void> Clear any formatting override for specified quantity type, but only for the "active" Unit System.  
findFormatterSpecByQuantityType(type: QuantityTypeArg, _unused?: boolean): undefined | FormatterSpec Synchronous call to get a FormatterSpec of a QuantityType.  
findParserSpecByQuantityType(type: QuantityTypeArg): undefined | ParserSpec Synchronous call to get a ParserSpec for a QuantityType.  
findUnit(unitLabel: string, schemaName?: string, phenomenon?: string, unitSystem?: string): Promise<UnitProps> Find [UnitProp] for a specific unit label.  
findUnitByName(unitName: string): Promise<UnitProps> Find [UnitProp] for a specific unit name.  
formatQuantity(magnitude: number, formatSpec: undefined | FormatterSpec): string Generates a formatted string for a quantity given its format spec.  
generateFormatterSpecByType(type: QuantityTypeArg, formatProps: FormatProps): Promise<FormatterSpec> Asynchronous Call to get a FormatterSpec for a QuantityType.  
getConversion(fromUnit: UnitProps, toUnit: UnitProps): Promise<UnitConversion> Returns data needed to convert from one Unit to another in the same Unit Family/Phenomenon.  
getFormatPropsByQuantityType(quantityType: QuantityTypeArg, requestedSystem?: UnitSystemKey, ignoreOverrides?: boolean): undefined | FormatProps Get the cached FormatProps give a quantity type.  
getFormatterSpecByQuantityType(type: QuantityTypeArg, isImperial?: boolean): Promise<undefined | FormatterSpec> Asynchronous Call to get a FormatterSpec for a QuantityType.  
getFormatterSpecByQuantityTypeAndSystem(type: QuantityTypeArg, system?: UnitSystemKey): Promise<undefined | FormatterSpec> Asynchronous Call to get a FormatterSpec for a QuantityType and a Unit System.  
getParserSpecByQuantityType(type: QuantityTypeArg, isImperial?: boolean): Promise<undefined | ParserSpec> Asynchronous Call to get a ParserSpec for a QuantityType.  
getParserSpecByQuantityTypeAndSystem(type: QuantityTypeArg, system?: UnitSystemKey): Promise<undefined | ParserSpec> Asynchronous Call to get a ParserSpec for a QuantityType.  
getQuantityDefinition(type: QuantityTypeArg): undefined | QuantityTypeDefinition Return QuantityTypeDefinition if type has been registered.  
getQuantityTypeKey(type: QuantityTypeArg): string Converts a QuantityTypeArg into a QuantityTypeKey/string value that can be used to lookup custom and standard quantity types.  
getUnitSystemFromString(inputSystem: string, fallback?: UnitSystemKey): UnitSystemKey Get a UnitSystemKey from a string that may have been entered via a key-in.  
getUnitsByFamily(phenomenon: string): Promise<UnitProps[]> Returns all defined units for the specified Unit Family/Phenomenon.  
hasActiveOverride(type: QuantityTypeArg, checkOnlyActiveUnitSystem?: boolean): boolean Return true if the QuantityType is using an override format.  
initializeQuantityTypesRegistry(): Promise<void> Protected Method used to register all QuantityTypes defined in QuantityType enum.  
parseToQuantityValue(inString: string, parserSpec: undefined | ParserSpec): QuantityParseResult Parse input string into quantity given the ParserSpec  
registerQuantityType(entry: CustomQuantityTypeDefinition, replace?: boolean): Promise<boolean> Async call to register a CustomQuantityType and load the FormatSpec and ParserSpec for the new type.  
reinitializeFormatAndParsingsMaps(overrideFormatPropsByUnitSystem: Map<UnitSystemKey, Map<string, FormatProps>>, unitSystemKey?: UnitSystemKey, fireUnitSystemChanged?: boolean, startDefaultTool?: boolean): Promise<void> Reinitialize caches.  
resetToUseInternalUnitsProvider(): Promise<void> Async call typically used after IModel is closed to reset UnitsProvider to default one that does not require an Units schema.  
setActiveUnitSystem(isImperialOrUnitSystem: boolean | UnitSystemKey, restartActiveTool?: boolean): Promise<void> Set the Active unit system to one of the supported types.  
setOverrideFormat(type: QuantityTypeArg, overrideFormat: FormatProps): Promise<void> Set Override Format for a quantity type, but only in the "active" Unit System.  
setOverrideFormats(type: QuantityTypeArg, overrideEntry: OverrideFormatEntry): Promise<void> Set formatting override for specified quantity type, but only for the "active" Unit System.  
setUnitFormattingSettingsProvider(provider: UnitFormattingSettingsProvider): Promise<void> Set the settings provider and if not iModel specific initialize setting for user.  
setUnitsProvider(unitsProvider: UnitsProvider): Promise<void> async method to set a units provider and reload caches  

Properties

Name Type Description
_activeFormatSpecsByType Protected Map<string, FormatterSpec> Map of FormatSpecs for all available QuantityTypes and the active Unit System  
_activeParserSpecsByType Protected Map<string, ParserSpec> Map of ParserSpecs for all available QuantityTypes and the active Unit System  
_activeUnitSystem Protected UnitSystemKey Active UnitSystem key - must be one of "imperial", "metric", "usCustomary", or "usSurvey".  
_overrideFormatPropsByUnitSystem Protected Map<UnitSystemKey, Map<string, FormatProps>> Map of FormatSpecs that have been overriden from the default.  
_quantityTypeRegistry Protected Map<string, QuantityTypeDefinition> Registry containing available quantity type definitions.  
_unitFormattingSettingsProvider Protected undefined | UnitFormattingSettingsProvider Optional object that gets called to store and retrieve format overrides.  
activeUnitSystem Accessor ReadOnly UnitSystemKey Retrieve the active UnitSystemKey which is used to determine what formats are to be used to display quantities  
alternateUnitLabelsProvider Accessor ReadOnly AlternateUnitLabelsProvider Return the class the contain map of all alternate labels for units.  
onActiveFormattingUnitSystemChanged Readonly BeUiEvent<FormattingUnitSystemChangedArgs> Called after the active unit system is changed.  
onQuantityFormatsChanged Readonly BeUiEvent<QuantityFormatsChangedArgs> Called when the format of a QuantityType is overriden or the override is cleared.  
onUnitsProviderChanged Readonly BeUiEvent<void> Fired when the active UnitsProvider is updated.  
quantityTypesRegistry Accessor ReadOnly Map<string, QuantityTypeDefinition> Return a map that serves as a registry of all standard and custom quantity types.  
unitsProvider Accessor UnitsProvider Get/Set the active UnitsProvider class.  

Defined in

Last Updated: 20 June, 2023