



Units documentation

[Units](#) 

 stable

 

Basics

* [Introduction](index.html#document-introduction/index)

	+ [Why?](index.html#why)

		- [Design Requirements](index.html#design-requirements)

			* [How It Works](index.html#document-introduction/how)

			* [Testing](index.html#document-introduction/testing)

			* [Sources of Unit String Definitions](index.html#document-introduction/sources)

			* [Converter App](index.html#document-introduction/converter)

* [Installation and Linking](index.html#document-installation/index)

	+ [Header Only Use](index.html#header-only-use)

	+ [Compiled Usage](index.html#compiled-usage)

	+ [Standalone Library](index.html#standalone-library)

		- [Unit Library CMake Reference](index.html#document-installation/cmake_variables)

			* [CMake variables](index.html#cmake-variables)

			* [CMake Targets](index.html#cmake-targets)

			* [Example](index.html#example)

* [User Guide](index.html#document-user-guide/index)

	+ [Units](index.html#document-user-guide/units)

		- [Basic Unit Types](index.html#basic-unit-types)

			* [Derived Units](index.html#derived-units)

		- [Basic operations](index.html#basic-operations)

		- [Comparison Operators](index.html#comparison-operators)

		- [Methods](index.html#methods)

			* [Special Units](index.html#document-user-guide/special_units)

			* [Custom Units](index.html#document-user-guide/custom_units)

			* [Equation Units](index.html#document-user-guide/equation_units)

			* [Custom Counting Units](index.html#document-user-guide/custom_count_units)

	+ [Measurements](index.html#document-user-guide/measurements)

		- [Precise measurements](index.html#precise-measurements)

	+ [Fixed Measurements](index.html#document-user-guide/fixed_measurements)

		- [Relationship with numbers](index.html#relationship-with-numbers)

		- [Interactions with measurement](index.html#interactions-with-measurement)

	+ [Uncertain Measurements](index.html#document-user-guide/uncertain_measurements)

		- [Constructors](index.html#constructors)

		- [Additional operators](index.html#additional-operators)

		- [String operations](index.html#string-operations)

	+ [Units From Strings](index.html#document-user-guide/from_string)

		- [Unit Strings](index.html#unit-strings)

		- [Measurement strings](index.html#measurement-strings)

		- [Uncertain Measurements](index.html#uncertain-measurements)

	+ [Units To Strings](index.html#document-user-guide/to_string)

		- [Advanced Usage](index.html#advanced-usage)

		- [Stream Operators](index.html#stream-operators)

		- [Underlying Conversion Map Access](index.html#underlying-conversion-map-access)

	+ [Math Operations](index.html#document-user-guide/math_operations)

		- [Type traits](index.html#type-traits)

		- [Rounding and Truncation](index.html#rounding-and-truncation)

		- [Trigonometric functions](index.html#trigonometric-functions)

		- [Multiplies and divides](index.html#multiplies-and-divides)

		- [Others](index.html#others)

	+ [Commodities](index.html#document-user-guide/commodities)

		- [Methods](index.html#methods)

			* [Custom Commodities](index.html#custom-commodities)

		- [Commodities to names](index.html#commodities-to-names)

		- [String To Commodities](index.html#string-to-commodities)

		- [Defined Commodities](index.html#defined-commodities)

	+ [User defined units](index.html#document-user-guide/user_defined_units)

		- [Defining a custom unit](index.html#defining-a-custom-unit)

		- [Input File](index.html#input-file)

		- [Other Library Operations](index.html#other-library-operations)

		- [Notes on units and threads](index.html#notes-on-units-and-threads)

	+ [Physical constants](index.html#document-user-guide/Physical_constants)

		- [Defined constants](index.html#defined-constants)

		- [Planck Units](index.html#planck-units)

		- [Atomic units](index.html#atomic-units)

		- [Numbers](index.html#numbers)

		- [Planetary masses](index.html#planetary-masses)

		- [From Strings](index.html#from-strings)

		- [Uncertainties](index.html#uncertainties)

	+ [Defined Units](index.html#document-user-guide/defined_units)

		- [Listing of Units](index.html#listing-of-units)

			* [Base Units](index.html#base-units)

			* [Specialized units](index.html#specialized-units)

			* [Numerical Units](index.html#numerical-units)

			* [Derived SI Units](index.html#derived-si-units)

			* [Extra SI related units](index.html#extra-si-related-units)

			* [Centimeter-Gram-Second system](index.html#centimeter-gram-second-system)

			* [Conventional Electrical Units](index.html#conventional-electrical-units)

			* [Meter Gram Force System](index.html#meter-gram-force-system)

			* [Meter Tonne Second system](index.html#meter-tonne-second-system)

			* [Additional Time units](index.html#additional-time-units)

			* [International customary Units](index.html#international-customary-units)

			* [Avoirdupois units](index.html#avoirdupois-units)

			* [Troy Units](index.html#troy-units)

			* [United States Customary Units](index.html#united-states-customary-units)

			* [FDA and metric measures](index.html#fda-and-metric-measures)

			* [Canadian Units](index.html#canadian-units)

			* [Australia Units](index.html#australia-units)

			* [Imperial or British Units](index.html#imperial-or-british-units)

			* [Apothecaries System](index.html#apothecaries-system)

			* [Nautical Units](index.html#nautical-units)

			* [Japanese traditional Units](index.html#japanese-traditional-units)

			* [Chinese Traditional Units](index.html#chinese-traditional-units)

			* [Typographic units](index.html#typographic-units)

			* [Distance Units](index.html#distance-units)

			* [Area Units](index.html#area-units)

			* [Mass Units](index.html#mass-units)

			* [Volume Units](index.html#volume-units)

			* [Angle Units](index.html#angle-units)

			* [Directional Units](index.html#directional-units)

			* [Temperature Units](index.html#temperature-units)

			* [Pressure Units](index.html#pressure-units)

			* [Power Units](index.html#power-units)

			* [Energy Units](index.html#energy-units)

			* [Power system Units](index.html#power-system-units)

			* [Equation type Units](index.html#equation-type-units)

			* [Textile related Units](index.html#textile-related-units)

			* [Clinical Units](index.html#clinical-units)

			* [Laboratory Units](index.html#laboratory-units)

			* [Data Units](index.html#data-units)

			* [Computation units](index.html#computation-units)

			* [Special units](index.html#special-units)

			* [Other Units](index.html#other-units)

			* [Climate Units](index.html#climate-units)

			* [Speed Units](index.html#speed-units)

		- [Units in the units namespace](index.html#units-in-the-units-namespace)

	+ [Custom Units](index.html#document-user-guide/custom_units)

		- [Custom units in Use](index.html#custom-units-in-use)

		- [Implementation Details](index.html#implementation-details)

	+ [Custom Counting Units](index.html#document-user-guide/custom_count_units)

		- [Custom count units in Use](index.html#custom-count-units-in-use)

		- [Implementation details](index.html#implementation-details)

	+ [Unit Domains](index.html#document-user-guide/Unit_domains)

		- [Available Domains](index.html#available-domains)

		- [Domain Specific Units](index.html#domain-specific-units)

			* [UCUM](index.html#ucum)

			* [Astronomy](index.html#astronomy)

			* [Cooking](index.html#cooking)

			* [Surveying](index.html#surveying)

			* [Nuclear](index.html#nuclear)

			* [Climate](index.html#climate)

			* [US customary](index.html#us-customary)

			* [All domains](index.html#all-domains)

		- [Specifying the domain](index.html#specifying-the-domain)

	+ [Conversion Flags](index.html#document-user-guide/conversion_flags)

		- [Unit\_from\_string flags](index.html#unit-from-string-flags)

			* [Indications for use](index.html#indications-for-use)

		- [to\_string Flags](index.html#to-string-flags)

			* [Default flags](index.html#default-flags)

	+ [Special Units](index.html#document-user-guide/special_units)

		- [Default Unit](index.html#default-unit)

		- [Error Unit](index.html#error-unit)

		- [Invalid Unit](index.html#invalid-unit)

		- [one](index.html#one)

	+ [Equation Units](index.html#document-user-guide/equation_units)

		- [Equation Value conversions](index.html#equation-value-conversions)

* [Application Notes](index.html#document-application_notes/index)

	+ [Strain](index.html#document-application_notes/strain)

		- [Method 1](index.html#method-1)

		- [Method 2](index.html#method-2)

		- [Method 3](index.html#method-3)

		- [Discussion](index.html#discussion)

* [The Low Level Details of the Units library](index.html#document-details/index)

	+ [Unit base class](index.html#document-details/unit_base)

		- [Math operations](index.html#math-operations)

			* [Power and Root and Inv functions](index.html#power-and-root-and-inv-functions)

		- [Getters](index.html#getters)

		- [Modifiers](index.html#modifiers)

		- [Comparisons](index.html#comparisons)

	+ [Commodity Details](index.html#document-details/commodities)

* [Units on the Web](index.html#document-web/index)

	+ [Rest API](index.html#rest-api)

[Units](#)

* 

* Units documentation

* [Edit on GitHub](https://github.com/LLNL/units/blob/7917f5f2cfefdcc90b5085ade91761d06df74e59/docs/index)

---

Welcome to The units library user guide and documentation![¶](#welcome-to-the-units-library-user-guide-and-documentation "Permalink to this headline")

======================================================================================================================================================

The Units library provides a means of working with units of measurement at runtime, including conversion to and from strings. It provides a small number of types for working with units and measurements and operations necessary for user input and output with units.

This software was developed for use in [LLNL/GridDyn](https://github.com/LLNL/GridDyn), and [HELICS](https://github.com/GMLC-TDC/HELICS) and is currently a work in progress (though getting close). Namespaces, function names, and code organization is subject to change though is fairly stable at this point, input is welcome.

[![codecov](https://codecov.io/gh/LLNL/units/branch/main/graph/badge.svg)](https://codecov.io/gh/LLNL/units) [![Azure](https://dev.azure.com/phlptp/units/_apis/build/status/LLNL.units?branchName=main)](https://dev.azure.com/phlptp/units/_build/latest?definitionId=1&branchName=main) [![Circle CI](https://circleci.com/gh/LLNL/units.svg?style=svg)](https://circleci.com/gh/LLNL/units) [![License](https://img.shields.io/badge/License-BSD-blue.svg)](https://github.com/GMLC-TDC/HELICS-src/blob/main/LICENSE)

The [Introduction](index.html#introduction) is a discussion about the why? and How the library came together and a generally what it does and how it was tested.

The [Installation and Linking](index.html#installation-and-linking) guide is a discussion about linking and using the library, and the [User Guide](index.html#user-guide) is the

how-to about how to use the software library. For the details see Details and to try out some of the string conversions check out [Units on the Web](index.html#units-on-the-web)

Finally [Application Notes](index.html#application-notes) contains some discussions on particular applications and usages.

Introduction[¶](#introduction "Permalink to this headline")

-----------------------------------------------------------

### Why?[¶](#why "Permalink to this headline")

So why have another units library? This was something we poked at for a while before writing the library.

There are number of other well designed C++ libraries but none of them met our needs. Some needs are pretty general, and others specific to power systems and electrical engineering.

#### Design Requirements[¶](#design-requirements "Permalink to this headline")

* have a units type that can be used in virtual function calls

* Handle unit conversions

* handle Per Unit operations and unit conversions

* handle complex units easily like $/puMw/hr

* Operate on strings with conversion to and from strings

Previously the library we were using met these requirements but only for a very limited set of units. This library functioned but was nearing the limits of maintainability and operation as new units were needed and other conversions were required which required adding direct conversions between the classes of units and the code was getting to be a mess. So, looking around, many of the existing unit libraries in C++ represent individual units as an individual type. This works wonderfully if you can know all the types you want to use ahead of time. In our case, many of the conversions depended on configuration or input files so the units being converted were not known at compile time. A few were but in general they were not. That led to an issue of how to do you pass that unit to a function that is meant to hide the internal unit in use, so having a type per unit did not seem functional from a coding or structural perspective.

Many of the dimensional analysis libraries, actually all as far as I can tell in C++, do not support string conversions. There are a few examples in Java or Python, but our code is written in C++ so that didn’t seem workable either. Which led to the conclusion that this library is needed and some additional design considerations.

* A small single compact type to represent all units (no bigger than a double) if we wanted to use it in a number of contexts.

* Another measurement type that was interoperable with doubles and numbers. Many numerical calculations came from a real array and numeric solver libraries so there is no opportunity to modify those types. Which means, we need double operations with measurements if we want to use them.

* constexpr as much as possible since many units are known at compile time and we need to be able to generate complex units from other simpler units.

* The library should be compatible with a broad range of compilers including some older ones back to GCC 4.7.

* a fairly expansive list of predefined units to simplify operation

Speaking with others, a few items and contexts came up such as recipes, trade documents, other software package unit representations, standardized string representation. Sometimes a lot of precision is needed, other times this is not the case.

And it would be nice to be able to deal with uncertainties in measurements, commodities, and containers.

##### How It Works[¶](#how-it-works "Permalink to this headline")

Given the design requirements the choice was how to make a class that could represent physical units. The desire for it to be a compact class drove the decision to somewhat limit what could be represented to physically realizable units.

###### Unit Representation[¶](#unit-representation "Permalink to this headline")

The unit class consists of a multiplier and a representation of base units.

The seven SI units + radians + currency units + count units. In addition a unit has 4 flags, per-unit for per unit or ratio units. One flag[i\_flag] that is a representation of imaginary units, one flags for a variety of purposes and to differentiate otherwise similar units[e\_flag]. And a flag to indicate an equation unit. Due to the requirement that the base units fit into a 4 byte type the represented powers of the units are limited. The list below shows the bit representation range and observed range of use in equations and observed usage

* meter:[-8,+7] :normal range [-4,+4], intermediate ops [-6,+6]

* kilogram:[-4,+3] :normal range [-1,+1], intermediate ops [-2,+2]

* second:[-8,+7] :normal range [-4,+4], intermediate ops [-6,+6]

* ampere:[-4,+3] :normal range [-2,+2]

* kelvin:[-4,+3] :normal range [-4,+1]

* mole:[-2,+1] :normal range [-1,+1]

* candela:[-2,+1] :normal range [-1,+1]

* currency:[-2,+1] :normal range [-1,+1]

* count:[-2,+1] :normal range [-1,+1]

* radians:[-4,+3] :normal range [-2,+2]

These ranges were chosen to represent nearly all physical quantities that could be found in various disciplines we have encountered.

* [SI units Publication guidelines](https://physics.nist.gov/cuu/pdf/sp811.pdf)

##### Testing[¶](#testing "Permalink to this headline")

The Code for the units library is put through a series of CI tests before being merged.

Current tests include running on CI systems.

###### Unit Tests[¶](#unit-tests "Permalink to this headline")

The units library has a series of units tests that are executed as part of the CI builds and when developing. They are built using Google test module. The module is downloaded if the tests are built. It uses Release 1.10 from the google test github repository

1. examples\_test A simple executable that loads up some different types of measurements and does a few checks directly, it is mainly to test linking and has some useful features for helping with the code coverage measures.

2. fuzz\_issue\_tests tests a set of past fuzzing failures, including, errors, glitches, timeouts, round trip failures, and some round trip failures with particular flags.

3. test\_all\_unit\_base **DO NOT RUN THIS TEST** it will take a very long time it does an exhaustive test of all possible unit bases to make sure the string conversion round trip works. I haven’t actually executed it all yet.

4. test\_commodities Run test using the commodity related functions and operations on precise\_unit’s

5. test\_conversions1 a series of tests about specific conversions, such as temperature, SI prefixes, extended SI units, and some other general operations about conversions

6. test\_conversions2 run through a series of test units and conversion from one of the converter websites, there are number of files that get used that contain known conversions

7. test\_equation\_units direct testing of the established equation units

8. test\_leadingNumbers run a bunch of checks on the leading number processing for units and measurements, convert a leading string into a numerical value

9. test\_measurement a series of tests on measurement objects including operations and comparisons, and construction

10. test\_measurement\_strings a few tests on the basic to and from string operations for measurements

11. test\_pu tests of pu units and conversions

12. test\_random\_round\_trip randomly pick a few 32 bit number, assume they are a unit and do a string conversion and interpretation on them and make sure they produce the same thing

13. test\_ucum a series of tests coming from [UCUM](https://github.com/lhncbc/ucum-lhc) the units library tries to handle all official strings and a majority of the full names, and aliases

14. test\_udunits a series of tests and test files coming from [UDUNITS-2](https://github.com/Unidata/UDUNITS-2) Not all the units convert, some never will since they are ambiguous but we will probably allow a few more over time

15. test\_uncertain\_measurements test uncertain measurement operations using examples taken from web sources

16. test\_unit\_ops test operations on units, including mathematical expressions and comparison operators

17. test\_unit\_strings Unit strings test conversion to and from strings

18. test\_defined\_units tests checking all the unit string maps for duplicates and conflicts and correct sizing

19. test\_google\_units run some checks to ensure support for many units supported by google unit translation

20. test\_math run some tests on the extra mathematical operations found in units\_math.hpp

21. test\_siunits run some tests of SI specific units and prefixes

###### CI systems[¶](#ci-systems "Permalink to this headline")

####### Azure[¶](#azure "Permalink to this headline")

1. GCC 7.4 C++14 (Azure native Linux)

1. GCC 7.4 C++14 (Azure native Linux) with shared library build

1. AppleClang 11.0 (Xcode 11.3) C++17

1. AppleClang 11.0 (Xcode 11.3) C++11

1. MSVC 2019 C++17

1. MSVC 2019 C++11

1. MSVC 2022 C++20

1. GCC 4.8 C++11

1. GCC 7 C++11

1. GCC 7 C++14

1. GCC 8 C++17

1. GCC 9 C++17

1. GCC 12 C++20

1. Clang 3.4 C++11

1. Clang 3.5 C++11

1. Clang 8 C++14

1. Clang 9 C++17

1. Clang 14 C++20

1. Clang-tidy (both main library and tests)

####### Circle-CI[¶](#circle-ci "Permalink to this headline")

1. Clang 14, Thread Sanitizer

2. Clang 14, Address, undefined behavior sanitizer

3. Clang 14, Memory Sanitizer

4. Clang 8, Fuzzing library – run a couple of defined fuzzing tests from scratch to check for any anomalous situations. There are currently two fuzzers, the first test the units\_from\_string, and the second tests the measurement\_from string. It first converts the fuzzing sequence, then if it is a valid sequence, converts it to a string, then converts that string back to a measurement or unit and makes sure the two measurements or units are identical. Any string sequence which doesn’t work is captured and tested.

####### GitHub Actions[¶](#github-actions "Permalink to this headline")

1. CodeQl

1. Coverage (ubuntu 22.04 image C++11, C++14, C++17, C++20, 32 and 64 bit unit base)

1. CPPLINT

1. Quick CMAKE checks for all supported versions of cmake

####### Codecov[¶](#codecov "Permalink to this headline")

Try to maintain the library at 100% coverage.

####### Pre-commit[¶](#pre-commit "Permalink to this headline")

Runs clang-format and many other checks for repo cleanliness

##### Sources of Unit String Definitions[¶](#sources-of-unit-string-definitions "Permalink to this headline")

The string processing tests and strings supported came from a number of different sources.

##### Converter App[¶](#converter-app "Permalink to this headline")

As a simple example and potentially useful tool we made the converter app. It is a command line application that can be built as part of the units library to convert units given on the command line.

```

$ ./unit_convert 10 m ft

32.8084

$ ./unit_convert ten meters per second mph

22.3694

$ ./unit_convert --full ten meters per second mph

ten meters per second = 22.3694 mph

$ ./unit_convert --simplified ten meters per second miles/hour

10 m/s = 22.3694 mph

$ ./unit_convert -s four hundred seventy-three kilograms per hour pounds/min

473 kg/hr = 17.3798 lb/min

$ ./unit_convert -s 22 british fathoms *

10 british fathoms = 18.288 m

```

basically there are two options –full,-f and –simplified,-s a measurement which will take an arbitrary number of strings and a final string as a unit to convert to. It outputs the conversion and if specified the surrounding measurement and units either simplified or in the original. Using \* or <base> in place of the unit string will result in converting the measurement to base units.

```

$ ./unit_convert --help

application to perform a conversion of a value from one unit to another

Usage: unit_convert [OPTIONS] measure... convert

Positionals:

 measure [TEXT ...] ... REQUIRED

 measurement to convert .e.g '57.4 m', 'two thousand GB' '45.7\*22.2 feet^3/s^2'

 convert TEXT REQUIRED the units to convert the measurement to

Options:

 -h,--help Print this help message and exit

 -f,--full specify that the output should include the measurement and units

 -s,--simplified simplify the units using the units library to_string functions and print the conversion string like full. This option will take precedence over --full

 --measurement [TEXT ...] ... REQUIRED

 measurement to convert .e.g '57.4 m', 'two thousand GB' '45.7\*22.2 feet^3/s^2'

 --convert TEXT REQUIRED the units to convert the measurement to

```

Installation and Linking[¶](#installation-and-linking "Permalink to this headline")

-----------------------------------------------------------------------------------

The units library supports a header only mode and a compiled mode. One of the strengths of the library is the string processing which is only available in the compiled mode. Other additions from the compiled mode are the root operations on units and measurements. The header only mode includes the unit and measurement classes conversions between them and the definition library.

### Header Only Use[¶](#header-only-use "Permalink to this headline")

The header only portion of the library can simply be copied and used. There are 3 headers units\_decl.hpp declares the underlying classes. unit\_defintions.hpp declares constants for many of the units, and units.hpp which is the primary public interface to units. If units.hpp is included in another file and the variable UNITS\_HEADER\_ONLY is defined then none of the functions that require the cpp files are defined. These header files can simply be included in your project and used with no additional building required. The UNITS\_HEADER\_ONLY definition is needed otherwise linking errors will result.

### Compiled Usage[¶](#compiled-usage "Permalink to this headline")

The second part is a few cpp files that can add some additional functionality. The primary additions from the cpp file are an ability to take roots of units and measurements and convert to and from strings. These files can be built as a standalone static library, a shared library or an object library, or included in the source code of whatever project want to use them. The code should build with an C++11 compiler. C++14 is recommended if possible to allow some additional function to be constexpr. Most of the library is tagged with constexpr so can be run at compile time to link units that are known at compile time. General Unit numerical conversions are not at compile time, so will have a run-time cost. A quick\_convert function is available to do simple conversions. with a requirement that the units have the same base and not be an equation unit. The cpp code also includes some functions for commodities and will eventually have r20 and x12 conversions, though this is not complete yet.

### Standalone Library[¶](#standalone-library "Permalink to this headline")

The units library can be built as a standalone library with either the static or shared library and installed like a typical package.

#### Unit Library CMake Reference[¶](#unit-library-cmake-reference "Permalink to this headline")

There are a few CMake variables that control the build process, they can be altered to change how the units library is built and what exactly is built.

##### CMake variables[¶](#cmake-variables "Permalink to this headline")

* BUILD\_TESTING : Generate CMake Variable controlling whether to build the tests or not

* UNITS\_ENABLE\_TESTS : Does the same thing as BUILD\_TESTING

* UNITS\_BUILD\_STATIC\_LIBRARY: Controls whether a static library should be built or not

* UNITS\_BUILD\_SHARED\_LIBRARY: Controls whether to build a shared library or not, only one or none of UNITS\_BUILD\_STATIC\_LIBRARY and UNITS\_BUILD\_SHARED\_LIBRARY can be enabled at one time.

* BUILD\_SHARED\_LIBS: Controls the defaults for the previous two options, overriding them takes precedence

* UNITS\_BUILD\_FUZZ\_TARGETS: If set to ON, the library will try to compile the fuzzing targets for clang libFuzzer

* UNITS\_BUILD\_WEB\_SERVER: If set to ON, build a webserver, This uses boost::beast and requires boost 1.70 or greater to build it also requires CMake 3.12 or greater

* UNITS\_BUILD\_CONVERTER\_APP: enables building a simple command line converter application that can convert units from the command line

* UNITS\_ENABLE\_EXTRA\_COMPILER\_WARNINGS: Turn on bunch of extra compiler warnings, on by default

* UNITS\_ENABLE\_ERROR\_ON\_WARNINGS: Mostly useful in some testing contexts but will turn on Werror so any normal warnings generate an error.

* CMAKE\_CXX\_STANDARD: Compile with a particular C++ standard, valid values are 11, 14, 17, 20, and likely 23 though that isn’t broadly supported. Will set to 14 by default if not otherwise specified

* UNITS\_BINARY\_ONLY\_INSTALL: Just install shared libraries and executables, no headers or static libs or packaging information

* UNITS\_CLANG\_TIDY: Enable the clang tidy tests as part of the build

* UNITS\_CLANG\_TIDY\_OPTIONS: options that get passed to clang tidy when enabled

* UNITS\_BASE\_TYPE: Set to uint64\_t for expanded base-unit power support. This increases the size of a unit by 4 Bytes.

* UNITS\_DOMAIN: Specify a default domain to use for string conversions. Can be either a name from the domains namespace such as domains::surveying or one of ‘COOKING’, ‘ASTRONOMY’, ‘NUCLEAR’, ‘SURVEYING’, ‘USE\_CUSTOMARY’, ‘CLIMATE’, or ‘UCUM’.

* UNITS\_DEFAULT\_MATCH\_FLAGS: Specify an integer value for the default match flags to be used for conversion

* UNITS\_DISABLE\_NON\_ENGLISH\_UNITS: the library includes a number of non-english units that can be converted from strings, these can be disabled by setting UNITS\_DISABLE\_NON\_ENGLISH\_UNITS to ON or setting the definition in the C++ code.

* UNITS\_NAMESPACE: The top level namespace of the library, defaults to units.

When compiling with C++17 (or higher), this can be set to, e.g., mynamespace::units to avoid name clashes with other libraries defining units.

* UNITS\_INSTALL: This is set to ON normally but defaults to OFF if used as a subproject. This controls whether anything gets installed by the install target.

* UNITS\_CMAKE\_PROJECT\_NAME: This is set to UNITS by default. If using this in a package manager or wish to rename the project this variable can be set to another name to change the name of the package. This will change the install path and cmake target names. For example setting -DUNITS\_CMAKE\_PROJECT\_NAME=LLNL-UNITS will create cmake project llnl-units::units, and llnl-units::header\_only and will install in a llnl-units directory with appropriate cmake files.

If compiling as part of a subproject then a few other options are useful

* UNITS\_HEADER\_ONLY: Only generate the header only target, sets UNITS\_BUILD\_STATIC\_LIBRARY and UNITS\_BUILD\_SHARED\_LIBRARY to OFF

* UNITS\_INSTALL: enable the install instructions of the library

* UNITS\_BUILD\_OBJECT\_LIBRARY: Generate an object library that can be used as part of other builds. Only one of UNITS\_BUILD\_SHARED\_LIBRARY, UNITS\_BUILD\_STATIC\_LIBRARY, or UNITS\_BUILD\_OBJECT\_LIBRARY can be set to ON. If more than one are set, the shared library and object library settings take precedence over the static library.

* UNITS\_LIBRARY\_EXPORT\_COMMAND: If desired the targets for the units library can be merged into an root project target list by modifying this variable. The use cases for this are rare, but if this is something you want to do this variable should be set to something like EXPORT rootProjectTargets. It defaults to “EXPORT unitsTargets”

##### CMake Targets[¶](#cmake-targets "Permalink to this headline")

If you are using the library as a submodule or importing the package there are a couple targets that can be used depending on the build. NOTE: these can be changed using UNITS\_CMAKE\_PROJECT\_NAME.

* units::units will be set to the library being built, either the shared, static, or object

* units::header\_only is a target for the headers if UNITS\_HEADER\_ONLY CMake variable is set, then only this target is generated. This target is always created.

##### Example[¶](#example "Permalink to this headline")

As part of the [HELICS](https://github.com/GMLC-TDC/HELICS) library the units library is used as a submodule it is included by the following code

```

# so units cpp exports to the correct target export

set(UNITS\_INSTALL OFF CACHE INTERNAL "")

if(NOT CMAKE\_CXX\_STANDARD)

 set(CMAKE\_CXX\_STANDARD 17) # Supported values are ``11``, ``14``, and ``17``.

endif()

set(UNITS\_BUILD\_OBJECT\_LIBRARY OFF CACHE INTERNAL "")

set(UNITS\_BUILD\_STATIC\_LIBRARY ON CACHE INTERNAL "")

set(UNITS\_BUILD\_SHARED\_LIBRARY OFF CACHE INTERNAL "")

set(UNITS\_BUILD\_CONVERTER\_APP OFF CACHE INTERNAL "")

set(UNITS\_BUILD\_WEBSERVER OFF CACHE INTERNAL "")

set(UNITS\_CLANG\_TIDY\_OPTIONS "" CACHE INTERNAL "")

set(UNITS\_BUILD\_FUZZ\_TARGETS OFF CACHE INTERNAL "")

add\_subdirectory(

 "${PROJECT\_SOURCE\_DIR}/ThirdParty/units" "${PROJECT\_BINARY\_DIR}/ThirdParty/units"

)

set\_target\_properties(units PROPERTIES FOLDER Extern)

hide\_variable(UNITS\_HEADER\_ONLY)

hide\_variable(UNITS\_BUILD\_OBJECT\_LIBRARY)

hide\_variable(UNITS\_NAMESPACE)

```

Then the target linked by

```

target\_link\_libraries(helics\_common PUBLIC HELICS::utilities units::units)

```

User Guide[¶](#user-guide "Permalink to this headline")

-------------------------------------------------------

The Units library user guide is an in depth look at how to use the C++ library and its functionality, covering the basic types in the library and operations with them.

The guide covers the basic types and what operations are available on them, as well as a lot of details on how to use the library.

### Units[¶](#units "Permalink to this headline")

#### Basic Unit Types[¶](#basic-unit-types "Permalink to this headline")

There are two basic units classes

units and precise\_units They both include a units\_base see [Unit base class](index.html#unit-base-class) for the details.

units has a single precision floating point multiplier and the units\_base object. The precise\_unit type uses a double precision floating point multiplier and includes commodity. The commodity is represented by a 32-bit code. See [Commodities](index.html#commodities) for more details on how that is used and defined.

The simplest way to start is by using one of the [Defined Units](index.html#defined-units) All standard units are defined and many non-standard ones as well.

The Basics of units are the seven SI base units:

* the kilogram (kg), for mass.

* the second (s), for time.

* the kelvin (K), for temperature.

* the ampere (A), for electric current.

* the mole (mol), for the amount of a substance.

* the candela (cd), for luminous intensity.

* the meter (m), for distance.

In addition to the base SI units a couple additional bases are defined:

* radian(rad), for angular measurement

* Currency ($), for monetary values

* Count (cnt), for single object counting

Currency may seem like a unusual choice in units but numbers involving prices are encountered often enough in various disciplines that it is useful to include as part of a unit.

Technically count and radians are not units, they are representations of real things. A radian is a representation of rotation around a circle and is therefore distinct from a true unitless quantity even though there are no physical measurements associated with either.

And count and mole are theoretically equivalent though as a practical matter using moles for counts of things is a bit odd for example 1 GB of data is ~1.6605\*10^-15 mol of data. So they are used in different context and don’t mix very often, the convert functions can convert between them if necessary.

The structure also defines some flags:

* per-unit, indicating per unit units

* i\_flag, general flag and complex quantity

* e\_flag, general unit discriminant

* equation, indicator that the unit is an equation unit.

##### Derived Units[¶](#derived-units "Permalink to this headline")

A vast majority of physical units can be constructed using these bases, as well as many non-physical units. The entire structure for the units fits into 4 bytes to meet the design requirement for a compact type. This required a detailed evaluation of what physical units and combinations of them were in use in different scientific and commercial disciplines, The following list represents the range of allowed values chosen as the representation and those required by known and observed physical quantities.

* meter:[-8,+7] :normal range [-4,+4], intermediate ops [-6,+6]

* kilogram:[-4,+3] :normal range [-1,+1], intermediate ops [-2,+2]

* second:[-8,+7] :normal range [-4,+4], intermediate ops [-6,+6]

* ampere:[-4,+3] :normal range [-2,+2]

* kelvin:[-4,+3] :normal range [-4,+1]

* mole:[-2,+1] :normal range [-1,+1]

* candela:[-2,+1] :normal range [-1,+1]

* currency:[-2,+1] :normal range [-1,+1]

* count:[-2,+1] :normal range [-1,+1]

* radians:[-4,+3] :normal range [-2,+2]

For example the kilogram is rarely used in a squared context, so it has a normal range of between -1 and 1. But in intermediate mathematical operations it is squared on occasion, so we needed to be able represent that without overflow. Since without getting extraordinary complex we are limited to whole bit representation that infers a two’s complement notation of 2 bits is [-2,-1] for 3 bits [-4,+3], and for 4 bits [-8,+7]. So for kilograms 3 bits were used. The pu flag was determined to be required by the initial design considerations, and a flag value also turned out to be required by library design requirements. The equation and e\_flag flags came a little later in the library development but turned out to be very useful in representing other kinds of units and discriminating between some units.

#### Basic operations[¶](#basic-operations "Permalink to this headline")

Some mathematical operations between units are supported. \* and / with units produce a new unit.

```

auto new\_unit=m/s;

auto another=new\_unit\*s;

//another == m

```

produces a new\_unit equivalent to meters/second.

#### Comparison Operators[¶](#comparison-operators "Permalink to this headline")

Units also support the comparison operators ==, and !=.The other comparison operators are not supported as it is somewhat undefined whether m > kg or many other comparison like that. The inequality is the inverse of equality, but the equality operator is an interesting subject. The unit component is relatively straightforward that part is the base units, if those are not equivalent then the answer is false. However there is a floating point component to the unit representing a multiplier. And floating point equality is treacherous. What is done is a rounding operation with a range. Basically units are assuming to have 6 decimal digits of precision, while precise\_units have 13. So units will result in equality as long as the first X significant digits in the multiplier are equivalent and the unit\_base is equal. this can’t be a specific range since the power of the multiplier is wide ranging this parsecs to picometers and all the base of meters.

#### Methods[¶](#methods "Permalink to this headline")

Frequently units need to raised to some power. Units have a pow(int) method to accomplish this.

```

auto area\_unit=m.pow(2);

```

The ^ will not work due to precedence rules in C++. If an operator for ‘^’ were defined an operation such as m/s^2 would produce meters squared per second squared which is probably not what is expected. Therefore best not to define the operator and use a function instead.

##### Special Units[¶](#special-units "Permalink to this headline")

There are a few defined units that are special in some fashion, and can be used as sentinel values or have special operations associated with them.

###### Default Unit[¶](#default-unit "Permalink to this headline")

The defunit unit is allowed to be converted to any other unit. it is equivalent of per-unit\*i\_flag The main use case is in the convert functions and makes a good

###### Error Unit[¶](#error-unit "Permalink to this headline")

```

auto error\_unit=unit(detail::unit\_data(nullptr));

```

###### Invalid Unit[¶](#invalid-unit "Permalink to this headline")

An invalid unit is any unit that is either the error unit or has a NaN in the multiplier. This is the unit returned from a string conversion if the string does not describe a unit or measurement.

###### one[¶](#one "Permalink to this headline")

The default constructor for unit and precise\_unit is empty unit data and 1.0 in the multiplier.

There are also precise versions of these values in the precise namespace

##### Custom Units[¶](#custom-units "Permalink to this headline")

The units library defines 1023 special custom units. These are custom units intended to specify a specific type of unit which doesn’t have a normal unit base definition. The key idea behind the custom units is that they can be multiplied, divided by some normal powers of distance, mass, or time units and can be inverted

In strings these can be represented by “CXUN[X]” Where X is some number between 0 and 1023.

In C++ code they can be generated by

```

precise\_unit new\_cxc\_unit=generate\_custom\_unit(code);

```

A set of checks and queries is available to check for custom\_units.

* bool precise::custom::is\_custom\_unit(detail::unit\_data udata);

* bool precise::custom::is\_custom\_unit\_inverted(detail::unit\_data udata);

* unsigned short precise::custom::custom\_unit\_number(detail::unit\_data udata);

These checks will operate regardless of any m/kg/s unit combination or inverted units.

###### Custom units in Use[¶](#custom-units-in-use "Permalink to this headline")

there are a few custom count units in use for specific clinical units Many of these units defy conversion to other known units but are used in pharmacological contexts

So there is no translation to other units and cannot be converted except to multiple of the same unit. There are often well established tests for these units but no good way to convert them to other units. Many of these units come from [UCUM](https://unitsofmeasure.org/ucum.html).

* custom\_unit(37): is [hounsfield units](https://radiopaedia.org/articles/hounsfield-unit?lang=us) used it CT and radiology

* many units in UCUM are defined like [MPL’U] or [mclg’U] for this context they define some unit which doesn’t interact with other units in any known fashion. The notion used in the units library for string translations is that these define custom units. Rather than individually define the library takes a hash of the part of the unit coming before the ‘U]’ and generates a 10 bit hash. That 10 bit hash is used as the custom code for the units.

* custom\_unit(77): is global warming potential related to climate operations

* custom\_unit(78): is global temperature change potential

The other custom units are available for use or the one with known definition can be use if there is no domain conflicts.

The primary usage of these is for units that are procedurally defined and often used in the context of per mass or per volume or per time.

###### Implementation Details[¶](#implementation-details "Permalink to this headline")

Custom units use a combination of nearly all the different fields in the unit\_base class, with the exception of count and radians. Based on the definitions used the custom units can be taken as per length/area/volume/mass/second with no issues. Some of the unit fields are used for defining an index and others are used purely for identification purposes.

##### Equation Units[¶](#equation-units "Permalink to this headline")

The use of an equation flag in the unit\_base defines a set of equation units. These are specific units where the relationship with other units is defined through an equation rather than a specific multiplier. There are 31 available equation units. Equation units use up the flags, count, and radian fields. All other units are left alone for defining the underlying units of the equation unit. So the equation specifier defines and equation rather than a specific unit.

equation types 0-15 deal with logarithms in some way, 16-31 are undefined or represent some common scale type units

to extract the equation type

- unsigned short precise::custom::eq\_type(detail::unit\_data udata);

Current equation definitions

* 0: log10(x)

* 1: nepers

* 2: bels

* 3: decibels

* 4: -log10(x)

* 5: -log10(x)/2.0

* 6: -log10(x)/3.0

* 7: -log10(x)/log10(50000)

* 8: log2(x)

* 9: ln(x)

* 10: log10(x)

* 11: 10\*log10(x)

* 12: 2\*log10(x)

* 13: 20\*log10(x)

* 14: log10(x)/log10(3)

* 15: 0.5\*ln(x)

* 16: UNDEFINED

* 17: UNDEFINED

* 18: UNDEFINED

* 19: UNDEFINED

* 20: UNDEFINED

* 21: UNDEFINED

* 22: saffir-simpson hurricane wind scale

* 23: Beaufort wind scale

* 24: Fujita scale

* 25: UNDEFINED

* 26: UNDEFINED

* 27: Prism diopter-100.0\*tan(x)

* 28: UNDEFINED

* 29: Moment magnitude scale for earthquakes (richter)

* 30: Energy magnitude scale for earthquakes

* 31: UNDEFINED

The wind scales are not very accurate since they match up a slightly fuzzier notion to actual wind speed. There are general charts and the equations in use utilize a polynomial to approximate them to a continuous scale. So the units when used are generally convertible to a velocity unit such as m/s. There are currently 10 undefined equation units available if needed.

###### Equation Value conversions[¶](#equation-value-conversions "Permalink to this headline")

The actual definitions of the equations are found in the unit::precise::equation namespace. Two functions are provided that convert values from equation values to units and vice versa.

* double convert\_equnit\_to\_value(double val, detail::unit\_data UT)

* double convert\_value\_to\_equnit(double val, detail::unit\_data UT)

also since some equation unit definitions depend on whether the actual units are power or magnitude values, there is a helper function to help determine this.

bool is\_power\_unit(detail::unit\_data UT)

This applies in the neper, bel, and decibel units.

##### Custom Counting Units[¶](#custom-counting-units "Permalink to this headline")

The units library defines 16 special counting units. These are custom counting units intended to specify a specific type of event. The key idea behind the custom counting units is that they can be multiplied, divided by any powers of distance, mass, currency, or time units and can be inverted. The primary usage of these is for units that are procedurally defined and often used in the context of per mass or per volume or per time or per $.

In strings these can be represented by “CXCUN[X]” Where X is some number between 0 and 15.

In C++ code they can be generated by

```

precise\_unit new\_cxc\_unit=generate\_custom\_count\_unit(code);

```

A set of checks and queries is available to check for custom\_count\_units.

* bool precise::custom::is\_custom\_count\_unit(detail::unit\_data udata);

* bool precise::custom::is\_custom\_count\_unit\_inverted(detail::unit\_data udata);

* unsigned short precise::custom::custom\_count\_unit\_number(detail::unit\_data udata);

These checks will operate regardless of any m/kg/s unit combination or inverted units. Underlying this is a set of codes and unit powers that would be extremely odd to encounter in normal use.

###### Custom count units in Use[¶](#custom-count-units-in-use "Permalink to this headline")

there are a few custom count units in use for specific clinical units Many of these units defy conversion to other known units but are used in pharmacological contexts

So there is no translation to other units and cannot be converted except to multiple of the same unit. There are often well established tests for these units but no good way to convert them to other units. Many of these units come from [UCUM](https://unitsofmeasure.org/ucum.html).

* custom\_count\_unit(0): is used for specific count units with commodities of some kind for string translation

* custom\_count\_unit(1): is Arbitrary Unit which has a clinical definition of some kind

* custom\_count\_unit(2): is [International Unit](https://en.wikipedia.org/wiki/International_unit)

* custom\_count\_unit(3): is [Index of reactivity](http://finto.fi/ucum/en/page/r394) which has a clinical definition

* custom\_count\_unit(4): is [limit of flocculation](http://finto.fi/ucum/en/page/r404) which has a clinical definition

* custom\_count\_unit(5): is [HPF](https://medical-dictionary.thefreedictionary.com/high-power+field) or High Power field which is related to microscopy

* 6-15 are not currently in use.

The other custom units are available for use or the one with known definition can be use if there is no domain conflicts.

###### Implementation details[¶](#implementation-details "Permalink to this headline")

Custom count units utilizes the flags, candela, ampere, and Kelvin fields to make use of some non-physical unit definitions for a more useful purpose.

### Measurements[¶](#measurements "Permalink to this headline")

The combination of a value and unit is known as a measurement. In the units library they are constructed by multiplying or dividing a unit by a numerical value.

```

measurement meas=10.0\*m;

measurement meas2=5.3/s;

```

They can also be constructed via the constructor

```

measurement meas(10.0, kg);

measurement meas2(2.7, MW);

```

There are two kinds of measurements the regular measurement which uses a double precision floating point for the value and a precise\_measurement which uses a double and a precise\_unit.

In terms of size the measurement class is 16 Bytes and the precise\_measurement is 24 bytes.

#### Precise measurements[¶](#precise-measurements "Permalink to this headline")

A precise measurement includes a double for the value and a precise\_unit to represent the unit. Most of the string conversion routines to measurement produce a precise\_measurement.

the measurement\_cast operation will convert a precise\_measurement into a regular measurements.

```

precise\_measurement mp(10.0, precise::kg);

measurement meas2=measurement\_cast(mp);

```

### Fixed Measurements[¶](#fixed-measurements "Permalink to this headline")

The primary difference between fixed\_measurement and measurement is the idea that in a fixed\_measurement the unit part is a constant. It does not change. Therefore any addition or subtraction operation will produce another measurement with the same units. It also allows for interaction and comparisons with numerical types since the unit is known. This is unlike measurements where comparison and addition and subtraction operations with numbers are not allowed. Otherwise the behavior and operations are identical between measurement and fixed\_measurement and likewise between fixed\_precise\_measurement and precise\_measurement

#### Relationship with numbers[¶](#relationship-with-numbers "Permalink to this headline")

Because the unit associated with a fixed measurement is fixed. It becomes legitimate to work with singular real valued numbers.

```

fixed\_measurement dist(10, m);

if (dist>10.0) //this has meaning because the units of dist is known.

{

 //all other operators are defined with doubles

}

dist=dist+3.0; // dist is now 13 meters

dist-=2.0; // dist is now 11 meters

dist=5.0; // dist is now 5 meters

```

#### Interactions with measurement[¶](#interactions-with-measurement "Permalink to this headline")

Fixed measurements have an implicit conversion to [Measurements](index.html#measurements), so all the methods that work with measurement work with fixed\_measurements. The construction of a fixed\_measurement from measurement is explicit. Likewise fixed\_precise\_measurement` have an implicit conversion to precise\_measurement, so all the methods that work with precise\_measurement work with fixed\_precise\_measurements. The construction of a fixed\_measurement from measurement is explicit.

### Uncertain Measurements[¶](#uncertain-measurements "Permalink to this headline")

The units library supports a class of measurements including an uncertainty measurement.

For Example 3.0±0.2m would indicate a measurement of 3.0 meters with an uncertainty of 0.2 m.

All operations are supported

The propagation of uncertainty follow the root sum of squares methods outlined [Here](http://lectureonline.cl.msu.edu/~mmp/labs/error/e2.htm).

There are methods available such as simple\_divide, simple\_product, simple\_sum and simple\_subtract that just sum the uncertainties. The method in use in the regular operators assume that the measurements used in the mathematical operation are independent, and should use the sum of squares methods. A more thorough explanation can be found [at this location](http://web.mit.edu/fluids-modules/www/exper_techniques/2.Propagation_of_Uncertaint.pdf).

The structure of an uncertain measurement consists of a float for the measurement value and a float for the uncertainty, and unit for the unit of the measurement.

#### Constructors[¶](#constructors "Permalink to this headline")

There are a number of different constructors for an uncertain measurement aimed at specify the uncertainty and measurement in different ways.

* constexpr uncertain\_measurement() default constructor with 0 values for the value and uncertainty and a one for the unit.

* constexpr uncertain\_measurement(<float|double> val, <float|double> uncertainty, unit base) : specify the parameters with values.

* constexpr uncertain\_measurement(<float|double> val, unit base): Just specify the value and unit, assume 0.0 uncertainty.

* constexpr uncertain\_measurement(measurement val, float uncertainty) noexcept : construct from a measurement and uncertainty value.

* uncertain\_measurement(measurement val, measurement uncertainty) noexcept: construct from a measurement value and uncertainty measurement. The uncertainty is converted to the same units as the value measurement.

#### Additional operators[¶](#additional-operators "Permalink to this headline")

Beyond the operations used in [Measurements](index.html#measurements), there are some specific functions related to getting and setting the uncertainty.

* uncertain\_measurement& uncertainty(<double|float> newUncertainty) : Will set the uncertainty value as a numerical value.

* uncertain\_measurement& uncertainty(const measurement &newUncerrtainty): will set the uncertainty as a measurement in specific units.

* double uncertainty(): Will get the current numerical value of the uncertainty

* double uncertainty\_as(units): will get the value of the uncertainty in specific units.

* float uncertainty\_f(): will get the value of the uncertainty as a single precision floating point value.

* constexpr measurement uncertainty\_measurement(): will return a measurement containing the uncertainty.

* double fractional\_uncertainty(): will get the fractional uncertainty value. which is uncertainty/|value|.

#### String operations[¶](#string-operations "Permalink to this headline")

The units library has some functions to extract an uncertain\_measurement from a string

- uncertain\_measurement\_from\_string(const std::string &ustring, std::uint64\_t match\_flags=0)

The from string operation searches for an uncertainty marker then splits the string into two parts. It then uses the measurement from string operation on both halves of the string and forms an uncertain measurement from them depending on whether both halves have units and or values. Allowed uncertainty marker strings include [“+/-”, “±”, “&plusmn;”, “+-”, “<u>+</u>”, “&#xB1;”, “&pm;”, ” \pm “]. These possibilities include unicode and ascii values and some sequences used in latex and html.

For Example all the following string will produce the same uncertain\_measurement

* “3.1±0.3 m/s”

* “3.1 +/- 0.3 m/s”

* “3.1 &pm; 0.3 m/s”

* “3.1 m/s ±0.3 m/s”

* “3.1 m/s ±0.3”

* “3.1 meters per second ±0.3 m/s”

* “3.1 m/s +- 0.3\*60 meters per minute”

* “3.1(3) m/s”

The last form is known as [concise notation](https://physics.nist.gov/cgi-bin/cuu/Info/Constants/definitions.html).

The match flags are the same as would be used for converting [Measurements](index.html#measurements)

### Units From Strings[¶](#units-from-strings "Permalink to this headline")

The units library contains a few functions to generate various types from string representations

* precise\_unit unit\_from\_string(const std::string& ustring, std::uint32\_t flags=0) : will generate a precise\_unit based on the data in the string

* unit unit\_cast\_from\_string(const std::string& ustring, std::uint32\_t flags=0): will generate a unit based on the data in the string

* precise\_measurement measurement\_from\_string(const std::string& ustring, std::uint32\_t flags=0): will generate a precise\_measurement from the data in the string

* measurement measurement\_cast\_from\_string(const std::string& ustring, std::uint32\_t flags=0): will generate a measurement from the data in the string

* uncertain\_measurement uncertain\_measurement\_from\_string(const std::string& ustring, std::uint32\_t flags=0): will generate an uncertain\_measurement from the data in the string

The general form is to take a string and optionally a flag object. See [Conversion Flags](index.html#conversion-flags) for a detailed description of the flags. Generally it is fine to leave off the flag argument.

#### Unit Strings[¶](#unit-strings "Permalink to this headline")

in general the unit string conversion is intended to be as flexible as possible. just about any unit normally written can be converted.

For example

* “m/s”

* “meter/second”

* “meter/s”

* “metre/s”

* “meters/s”

* “meters per second”

* “metres per second”

* “m per sec”

* “meterpersecond”

* “METERS/s”

* “m\*s^-1”

* “meters\*seconds^(-1)”

* “(second/meter)^(-1)”

* “100 centimeters / 1000 ms”

Will all produce the unit of meters per second. As a note there are quite a few more units that can be converted from strings than are listed in the [Defined Units](index.html#defined-units).

Numbers are supported and become part of the unit. “99 feet” would create a new unit with a definition of 99 ft. The multiplier stored would include the conversion from meters to feet\*99. This allows for arbitrary unit definitions.

The + operator also works if the units on both sides have the same base for example 3 ft + 2 in would be the equivalent of 38 inches. If the units do not have the same base + is interpreted as a multiplication.

#### Measurement strings[¶](#measurement-strings "Permalink to this headline")

The conversion from a string to measurement looks for a leading number before the unit. The “99 feet” in the previous example would then get a measurement value of 99 and the unit would be feet. The measurement from string function also can interpret written numbers such as “three thousand four hundred and twenty-seven miles” This should get correctly read as 3427 miles.

The conversion function also handles a few cases where the unit symbol is written before the value such as currency $27.92 would be a value of 27.92 with the currency unit.

#### Uncertain Measurements[¶](#uncertain-measurements "Permalink to this headline")

Similarly to Measurement strings, uncertain measurements can also be converted from strings see [Uncertain Measurements](index.html#uncertain-measurements) for additional details on the formats supported.

### Units To Strings[¶](#units-to-strings "Permalink to this headline")

All the class in the units library can be given as an argument to a to\_string function. This function converts the units or value into a std::string that is representative of the unit or measurement. In all cases the primary aim of the to\_string is to generate a string that the corresponding \*\_from\_string function will recognize and convert back to the original unit. The secondary aim is to generate string that is human readable in standard notation. While this is achieved for many common units there is some work left to do to make it better.

For example

```

measurement density=10.0\*kg/m.pow(3);

measurement meas2=2.7\*puMW;

auto str1=to\_string(density);

auto str2=to\_string(meas2);

// from google tests

EXPECT\_EQ(str1, "10 kg/m^3");

EXPECT\_EQ(str2, "2.7 puMW");

```

```

uncertain\_measurement um1(10.0, 0.4, m);

auto str = to\_string(um1);

EXPECT\_EQ(str, "10+/-0.4 m");

```

Uncertain measurement string conversions make some attempt to honor significant digits based on the uncertainty.

#### Advanced Usage[¶](#advanced-usage "Permalink to this headline")

The to\_string function also takes a second argument which is a std::uint64\_t match\_flags in all cases this default to 0, it is currently unused though will be used in the future to allow some fine tuning of the output in specific cases. In the near future a flag to allow utf 8 output strings will convert certain units to more common utf8 symbols such as unit Powers and degree symbols, and a few others. The output string would default to ascii only characters.

#### Stream Operators[¶](#stream-operators "Permalink to this headline")

Output stream operators are NOT included in the library. It was debatable to include them or not but there would be a lot of additional overloads that would add quite a bit of code to the header files, that in most cases is not necessary so the decision was made to exclude them. The to\_string operations provide most of the capabilities with some additional flexibility, and if needed for a particular use case can be added to the user code in a simple fashion

```

namespace units{

 std::ostream& operator<<(std::ostream& os, const precise\_unit& u)

 {

 os << to\_string(u);

 return os;

 }

} // namespace units

```

Any of the types in the units library with a to\_string operation can be handled in the same way. Depending on the compiler, placing the operator in the namespace may or may not be necessary.

#### Underlying Conversion Map Access[¶](#underlying-conversion-map-access "Permalink to this headline")

The underlying conversion maps may be accessed by users if desired.

To access them a compile time definition needs to be added to the build ENABLE\_UNIT\_MAP\_ACCESS

```

#ifdef ENABLE\_UNIT\_MAP\_ACCESS

namespace detail {

 const std::unordered\_map<std::string, precise\_unit>& getUnitStringMap();

 const std::unordered\_map<unit, const char\*>& getUnitNameMap();

}

#endif

```

These may be useful for building a GUI or smart lookup or some other operations. getUnitStringMap() returns a map of known unit strings, and getUnitNameMap() is a mapping of common units back to strings as a building block for the to\_string operation.

### Math Operations[¶](#math-operations "Permalink to this headline")

Additional mathematical operations on measurements are available in the unit\_math.hpp header these are header only so no additional compilation is required. The intention of this header is to match operations from the cmath header available in the standard library. These are all template functions which will work for any measurement type.

#### Type traits[¶](#type-traits "Permalink to this headline")

The header includes a few type traits used in the header file and potentially useful elsewhere including

* is\_unit : true if the type is a unit (unit or precise\_unit)

* is\_measurement : true if the type is one of the defined measurement types

* is\_precise\_measurement : true if the type is one of the defined precise measurement type

#### Rounding and Truncation[¶](#rounding-and-truncation "Permalink to this headline")

These operations will effect only the value part of the measurement

* round

* trunc

* ceil

* floor

#### Trigonometric functions[¶](#trigonometric-functions "Permalink to this headline")

Trigonometric operations will operate only if the measurement is convertible to radians

* sin

* cos

* tan

#### Multiplies and divides[¶](#multiplies-and-divides "Permalink to this headline")

Division and multiplication operators for measurements that have support for per\_unit measurement

* multiplies : works like \* except when one of the measurements is per\_unit and they have the same unit base, then they remove the per unit

* divides : works like / except if both measurements have the same base then the result has a per\_unit unit

See [Strain](index.html#strain) for examples on usage

#### Others[¶](#others "Permalink to this headline")

Other common mathematical expressions found in <cmath>

* fmod : return the floating point modulus of a division operation as long as division is a valid operation

* hypot : works for two and three measurements or floating point values as long as addition is a valid operation.

* cbrt : works similarly to the sqrt operation

### Commodities[¶](#commodities "Permalink to this headline")

the precise\_unit class can represent commodities as well as units. The commodity is represented by a 32 bit unsigned number that codes a variety of commodities.

The actual representation is still undergoing some change so expect this to change going forward. See [Commodity Details](index.html#commodity-details) for more details.

#### Methods[¶](#methods "Permalink to this headline")

There are a few available methods for dealing with commodity codes and string translation

* std::uint32\_t getCommodity(std::string comm) - will get a commodity from a string.

* std::string getCommodityName(std::uint32\_t commodity) - will translate a commodity code into a string

##### Custom Commodities[¶](#custom-commodities "Permalink to this headline")

* void addCustomCommodity(std::string comm, std::uint32\_t code) - Add a custom commodity code using a string and code

* void clearCustomCommodities() - clear all current user defined commodities

* void disableCustomCommodities() - Turn off the use of custom commodities

* void enableCustomCommodities() - Turn on the ability to add and check custom commodities for later access

#### Commodities to names[¶](#commodities-to-names "Permalink to this headline")

The getCommodityName methods has 4 stages and will return from any successful stage.

1. Check custom commodities if allowed

2. Check standardized commodity names

3. Check for special codes for name storage (short names <=5 ascii lower case characters are stored directly in the code)

4. generate string “CXCOMM[<code>]”

#### String To Commodities[¶](#string-to-commodities "Permalink to this headline")

The getCommodity method works nearly the opposite of getCommodityName.

1. Check custom commodities if allowed

2. Check standardized commodity codes

3. Check for string “CXCOMM[<code>]”

4. Check for special codes for name storage (short names <=5 ascii lower case characters are stored directly in the code)

5. Generate a hash code of the string and if allowed store it as a custom commodity

#### Defined Commodities[¶](#defined-commodities "Permalink to this headline")

The list of commodities is still in development. Generally [`traded commodities<https://en.wikipedia.org/wiki/List\_of\_traded\_commodities>`\_](#id1) are available as well as a few others that are used in clinical definitions or other uses as part of unit definition standards. In the future this list will more generally expand to match international trade tables. See [`commodities.cpp<https://github.com/LLNL/units/blob/master/units/commodities.cpp>`\_](#id3) for details on the exact list.

### User defined units[¶](#user-defined-units "Permalink to this headline")

The units library has support for user defined units and [Commodities](index.html#commodities). These interact with the \*\_from\_string and to\_string operations to allow custom conversions and definitions.

#### Defining a custom unit[¶](#defining-a-custom-unit "Permalink to this headline")

The basic function for adding a custom unit is addUserDefinedUnit(string name, precise\_unit un)

For example from a test in the library

```

precise\_unit idgit(4.754, mol/m.pow(2));

addUserDefinedUnit("idgit", idgit);

auto ipm=unit\_from\_string("idgit/min");

EXPECT\_EQ(ipm, idgit / min);

auto str = to\_string(ipm);

EXPECT\_EQ(str, "idgit/min");

str = to\_string(ipm.inv());

EXPECT\_EQ(str, "min/idgit");

```

Basically user defined units can interact with the string conversion functions just like any other unit defined in the library. A user defined unit gets priority when converting to a string as well including when squared or cubed as part of a compound unit. For example from the test cases:

```

addUserDefinedUnit("angstrom", units::precise::distance::angstrom);

auto str = to\_string(units::unit\_from\_string("us / angstrom^2"));

EXPECT\_EQ(str, "us/angstrom^2");

str = to\_string(units::unit\_from\_string("us / angstrom"));

EXPECT\_EQ(str, "us/angstrom");

```

If only an ability to interpret strings is needed the addUserDefinedInputUnit can be used

```

precise\_unit idgit(4.754, mol/m.pow(2));

addUserDefinedInputUnit("idgit", idgit);

auto ipm = unit\_from\_string("idgit/min");

EXPECT\_EQ(ipm, idgit / min);

auto str = to\_string(ipm);

EXPECT\_EQ(str.find("idgit"), std::string::npos);

EXPECT\_NE(str.find("kat") , std::string::npos);

```

If only output strings are needed the addUserDefinedOutputUnit can be used

```

precise\_unit idgit(4.754, mol / m.pow(2));

addUserDefinedOutputUnit("idgit", idgit);

auto ipm = unit\_from\_string("idgit/min");

//this is not able to be read since idgit is undefined as an input

EXPECT\_NE(ipm, idgit / min);

auto str = to\_string(idgit/min);

/\*\* output only should make this work\*/

EXPECT\_EQ(str,"idgit/min");

```

The output unit can be used when the interpreter works fine but the string output doesn’t do what you want it to do.

A unit can be removed from the user defined unit set via removeUserDefinedUnit

```

 auto ipm=unit\_from\_string("idgit/min");

EXPECT\_EQ(ipm, idgit / min);

auto str = to\_string(ipm);

EXPECT\_EQ(str, "idgit/min");

str = to\_string(ipm.inv());

EXPECT\_EQ(str, "min/idgit");

removeUserDefinedUnit("idgit");

EXPECT\_FALSE(is\_valid(unit\_from\_string("idgit/min")));

```

The removal also works for user defined units specified via addUserDefinedInputUnit or addUserDefinedOutputUnit

#### Input File[¶](#input-file "Permalink to this headline")

Sometimes it is useful to have a larger library of units in this case the std::string definedUnitsFromFile(const std::string& filename) can be used to load a number of units at once.

The file format is quite simple.

# at the beginning of a line indicates a comment

other wise

```

# comment

meeter == meter

meh == meeter per hour

# => indicates input only unit

     mehmeh => meh/s

# <= indicates output only unit

     hemhem => s/meh

```

or

```

# comment

yodles=73 counts

# comment

"yeedles", 19 yodles

yimdles; dozen yeedles

```

or

```

# test the quotes for inclusion

"bl==p"=18.7 cups

# test single quotes for inclusion

'y,,p',9 tons

# ignore just one quote

'np==14 kg

# escaped quotes

"j\"\""= 13.5 W

# escaped quotes

'q""'= 15.5 W

```

The basic rule is that one of [<=,;] will separate a definition name from a unit definition. If the next character after the separator is an ‘=’ it is ignored. If it is a ‘>’ it implies input only definition. If the separator is an ‘<=’ then it is output only. Otherwise it calls addUserDefinedUnit for each definition. The function is declared noexcept and will return a string with each error separated by a newline. So if the result string is empty() there were no errors.

#### Other Library Operations[¶](#other-library-operations "Permalink to this headline")

* clearUserDefinedUnits() will erase all previously defined units

* disableUserDefinedUnits() will disable the use of user defined units

* enableUserDefinedUnits() will enable their use if they had been disabled, they are enabled by default.

#### Notes on units and threads[¶](#notes-on-units-and-threads "Permalink to this headline")

The user defined units usage flag is an atomic variable but the modification of the user defined library are not thread safe, so if threads are needed make all the changes in one thread before using it in other threads, or protect the calls with a separate mutex. The disable and enable functions trigger an atomic variable that enables the use of user defined units in the string translation functions. disableUserDefinedUnits() also turns off the ability to specify new user defined units but does not erase those already defined.

### Physical constants[¶](#physical-constants "Permalink to this headline")

The units library comes with a number of physical constants with appropriate units defined.

All the physical constants are specified as [Precise measurements](index.html#precise-measurements) and in the namespace units::constants

In general the most recent definition was chosen which includes the 2019 redefinition of some SI units this matches with the rest of the library and the defined units.

Inspiration for the different constants was taken from [wikipedia](https://en.wikipedia.org/wiki/List_of_physical_constants) and [NIST](https://physics.nist.gov/cuu/Constants/index.html).

Defined constants. The [2019 redefinition](https://www.nist.gov/si-redefinition/meet-constants) of the SI system was used where applicable. All [common constants](https://physics.nist.gov/cgi-bin/cuu/Category?view=html&Frequently+used+constants.x=87&Frequently+used+constants.y=18) listed from NIST are included

#### Defined constants[¶](#defined-constants "Permalink to this headline")

Values are taken from [NIST 2018 CODATA](https://physics.nist.gov/cuu/Constants/Table/allascii.txt) unless otherwise noted

* Standard gravity - g0

* Gravitational constant - G

* Speed of light - c

* Elementary Charge (2019 redefinition) - e

* hyperfine structure transition frequency of the caesium-133 atom - fCs

* fine structure constant - alpha

* Planck constant (2019 redefinition) - h

* Reduced Planck constant (2019 redefinition) - hbar

* Boltzman constant (2019 redefinition) - k

* Avogadros constant (2019 redefinition) - Na

* Luminous efficiency - kcd

* Permittivity of free space - eps0

* Permeability of free space - mu0

* Gas Constant - R

* Stephan Boltzmann constant -s

* Hubble constant 69.8 km/s/Mpc - H0

* Mass of an electron - me

* Mass of a proton - mp

* Bohr Radius - a0

* Faraday’s constant - F

* Atomic mass constant - mu

* Conductance quantum - G0

* Josephson constant - Kj

* Magnetic flux quantum - phi0

* von Kiltzing constant - Rk

* Rydberg constant - Rinf

#### Planck Units[¶](#planck-units "Permalink to this headline")

These units are found in the units::constants::planck namespace and include

length, mass, time, charge, and temperature.

#### Atomic units[¶](#atomic-units "Permalink to this headline")

These physical constants are values related to an electron or [atomic measurements](https://www.bipm.org/en/publications/si-brochure/table7.html)

They include length, mass, time, charge- same as e above, energy, and action. The atomic constants are defined in the units::constants::atomic namespace.

#### Numbers[¶](#numbers "Permalink to this headline")

There are a few numbers that are used in the library and include definitions in the units::constants namespace. They are represented as doubles and are defined as constexpr

* pi (3.14159265358979323846)

* tau (2.0\*pi)

* invalid\_conversion (signaling NaN)

* infinity

* standard\_gravity the numerical value of g0, earth standard gravity in m/s/sec

* speed\_of\_light The numerical value of the speed of light in m/s

The last two are used in several other units and some conversions so it seemed better to just define the numerical value and use that rather than use the same number in several places.

#### Planetary masses[¶](#planetary-masses "Permalink to this headline")

The masses of some of the solar system bodies are included in units::constants::Planetary::mass

* solar

* earth

* moon

* jupiter

* mars

#### From Strings[¶](#from-strings "Permalink to this headline")

All constants listed here are available for conversion from strings by wrapping in brackets For example the luminous efficiency would be converted to a unit by using [kcd] The planck constants are available as [planck::XXXXX] or planckXXXXXX and the atomic constants are available as `[atomic::XXXX]

#### Uncertainties[¶](#uncertainties "Permalink to this headline")

Certain physical constants have uncertainties associated with them and have an additional uncertain\_measurement associated with them see uncertain\_measurments.

These can be found in the units::constants::uncertain namespace and include:

* Gravitational constant - G

* Permittivity of free space - eps0

* Permeability of free space - u0

* Hubble constant 69.8 km/s/Mpc - H0

* Mass of an electron - me

* Mass of a proton - mp

* Atomic mass constant - mu

* mass of nuetron - mn

* Rydberg constant - Rinf

* fine structure constant - alpha

*NOTE: A few of the uncertain constants have more precision than supported in uncertain\_measurments but were included for completeness*

### Defined Units[¶](#defined-units "Permalink to this headline")

The units library comes with two sets of units predefined. They are all located in [src/units/unit\_definitions.hpp](https://github.com/LLNL/units/blob/master/units/unit_definitions.hpp).

The definitions come in two flavors a precise\_unit and a regular unit. All the precise units are defined in the namespace units::precise

All the units are defined as a constexpr values. The choice of which units to define is somewhat arbitrary and guided by the authors experience and the origins of the library in power systems and electrical engineering in the US.

Units that the author has actually encountered in work or life are included and in cases where there might be conflicts depending on the location preference was given to the US customary definition, though international systems take priority.

#### Listing of Units[¶](#listing-of-units "Permalink to this headline")

The most common units are defined in the namespace units::precise and others are defined in subnamespaces.

##### Base Units[¶](#base-units "Permalink to this headline")

Most base units have two definitions that are equivalent

* meter, m

* kilogram, kg

* second, s

* Ampere, A

* Kelvin, K

* mol

* candela, cd

* currency

* count

* pu

* iflag

* eflag

* radian, rad

##### Specialized units[¶](#specialized-units "Permalink to this headline")

Some specialized units are defined for use in conversion applications or for making handling string conversions a little easier

* defunit - special unit that signifies conversion to any other units is possible

* invalid - special unit that conversion has failed

* error - an error unit

##### Numerical Units[¶](#numerical-units "Permalink to this headline")

Sometimes it is useful to have pure numerical units, often for multiplication with other units such as hundred\*kg or something like that which becomes a single unit with 100 kg.

* one

* ten

* hundred

* percent (0.01)

* infinite

* nan

Also included in this category are [SI prefixes](https://physics.nist.gov/cuu/Units/prefixes.html)

deci, centi,milli, micro, nano, pico, femto, atto, zepto, yocto, ronto, quecto, deka, hecto, kilo, mega, giga, tera, peta, exa, hecto, zetta, yotta,rotta, quetta.

and SI data prefixes

kibi, mebi, gibi, tebi, pebi, exbi, zebi, yobi

##### Derived SI Units[¶](#derived-si-units "Permalink to this headline")

There are many units that used in combination with the SI system that are derived from the base units

* hertz, Hz

* volt, V

* Pa (pascal, on some systems this is defined as something else so the definition(pascal) is skipped)

* newton, N

* joule, J

* watt, W

* coulomb, C

* farad, F

* siemens, S

* weber, Wb

* tesla, T

* henry, H

* lumen, lm

* lux, lx

* becquerel, Bq

* gray, Gy

* sievert, Sv

* katal, kat

* sr

##### Extra SI related units[¶](#extra-si-related-units "Permalink to this headline")

A few units that are not officially part of the SI but are [accepted](https://physics.nist.gov/cuu/Units/outside.html) for use with the SI system, along with a few other SI units with prefixes that are commonly used.

* mg

* g

* mL

* L

* nm

* mm

* km

* cm

* bar

##### Centimeter-Gram-Second system[¶](#centimeter-gram-second-system "Permalink to this headline")

The [CGS](https://en.wikipedia.org/wiki/Centimetre%E2%80%93gram%E2%80%93second_system_of_units) system is a variant on the metric system. Units from the CGS system are included under the namespace units::precise::cgs.

* eng

* dyn

* barye

* gal

* poise

* stokes

* kayser

* oersted

* gauss

* debye

* maxwell

* biot

* gilbert

* stilb

* lambert

* phot

* curie

* roentgen

* REM

* RAD

* emu

* langley

* unitpole

* statC\_charge

* statC\_flux

* abOhm

* abFarad

* abHenry

* abVolt

* statV

* statT

* statHenry

* statOhm

* statFarad

##### Conventional Electrical Units[¶](#conventional-electrical-units "Permalink to this headline")

defined in namespace units::precise::conventional

* volt90

* ampere90

* watt90

* henry90

* coulomb90

* farad90

* ohm90

##### Meter Gram Force System[¶](#meter-gram-force-system "Permalink to this headline")

defined in namespace units::precise::gm

* pond

* hyl

* at

* poncelet

* PS

##### Meter Tonne Second system[¶](#meter-tonne-second-system "Permalink to this headline")

Defined in namespace units::precise::MTS

* sthene

* pieze

* thermie

##### Additional Time units[¶](#additional-time-units "Permalink to this headline")

Defined in namespace units::precise::time, units marked with \* are also defined in the units::precise.

* min\*

* ms\*

* ns\*

* hr\*

* h\*

* day\*

* week

* yr\* (8760 hr)

* fortnight

* sday - sidereal day

* syr - sidereal year

* at - mean tropical year

* aj - mean julian year

* ag - mean gregorian year

* year - aliased to median calendar year (365 days) which is the standard for SI

* mos - synodal (lunar) month

* moj - mean julian month

* mog - mean gregorian month

##### International customary Units[¶](#international-customary-units "Permalink to this headline")

These are traditional units that have some level of international definition

Defined in namespace units::precise::i

* grain

* point

* pica

* inch

* foot

* yard

* mile

* league

* hand

* cord

* board\_foot

* mil

* circ\_mil

A few units have short symbols defined in unit::precise

in, ft, yd, mile. These alias to the international definition.

##### Avoirdupois units[¶](#avoirdupois-units "Permalink to this headline")

Avoirdupois units are another common international standard of units for weight and volumes. The units are defined in units::precise::av

* dram

* ounce

* pound

* hundredweight

* longhundredweight

* ton

* longton

* stone

* lbf

* ozf

* slug

* poundal

A few common units have symbols defined in units::precise lb, ton, oz, lbf and these alias to the Avoirdupois equivalent.

##### Troy Units[¶](#troy-units "Permalink to this headline")

Most commonly for precious metals a few units are defined in units::precise::troy, with a basis in the international grain.

* pennyweight

* oz

* pound

##### United States Customary Units[¶](#united-states-customary-units "Permalink to this headline")

These are traditional units defined in the United States, for survey or common usage.

Defined in unit::precise::us.

* foot

* inch

* mil

* yard

* rod

* chain

* link

* furlong

* mile

* league

* acre\*

* homestead

* section

* township

* minim

* dram

* floz

* tbsp

* tsp

* pinch

* dash

* shot

* gill

* cup

* pint

* quart

* gallon

* flbarrel - liquid barrel

* barrel

* hogshead

* cord

* fifth

A few US customary units are defined in specific namespaces to distinguish them from other forms

US customary dry measurements are defined in units::precise::us::dry

* pint

* quart

* gallon

* peck

* bushel

* barrel

* sack

* strike

Some grain measures used in markets and commodities are defined in units::precise::us::grain.

When commodities are a little more developed this will be defined with appropriate commodity included.

* bushel\_corn

* bushel\_wheat

* bushel\_barley

* bushel\_oats

Some survey units are defined in units::precise::us::engineers to distinguish them from others

* chain

* link

The unit gal (gallon) is also defined in units::precise since that is pretty common to use.

##### FDA and metric measures[¶](#fda-and-metric-measures "Permalink to this headline")

The food and drug administration has defined some customary units in metric terms for use in medicine. These are defined in units::precise::metric

Also included are some other customary units that have a metric definition.

* tbsp

* tsp

* floz

* cup

* cup\_uslegal

* carat

##### Canadian Units[¶](#canadian-units "Permalink to this headline")

Some Canadian definitions of customary units defined in units::precise::canada

* tbsp

* tsp

* cup

* cup\_trad

* gallon

* grain::bushel\_oats

##### Australia Units[¶](#australia-units "Permalink to this headline")

Traditional Australian units defined in units::precise::australia

* tbsp

* tsp

* cup

##### Imperial or British Units[¶](#imperial-or-british-units "Permalink to this headline")

Traditional british or imperial units, defined in units::precise::imp.

* inch

* foot

* thou

* barleycorn

* rod

* chain

* link

* pace

* yard

* furlong

* league

* mile

* nautical\_mile

* knot

* acre

* perch

* rood

* gallon

* quart

* pint

* gill

* cup

* floz

* tbsp

* tsp

* barrel

* peck

* bushel

* dram

* minim

* drachm

* stone

* hundredweight

* ton

* slug

##### Apothecaries System[¶](#apothecaries-system "Permalink to this headline")

Used in pharmaceutical contexts the apothecaries system of units is defined in units::precise::apothecaries.

* floz ( same as imperial version )

* minim

* scruple

* drachm

* ounce

* pound

* pint

* gallon

* metric\_ounce

##### Nautical Units[¶](#nautical-units "Permalink to this headline")

Some units defined in context of marine travel defined in units::precise::nautical

* fathom

* cable

* mile

* knot

* league

##### Japanese traditional Units[¶](#japanese-traditional-units "Permalink to this headline")

Some traditional Japanese units are included for historical interest in units::precise::japan

* shaku

* sun

* ken

* tsubo

* sho

* kan

* go

* cup

##### Chinese Traditional Units[¶](#chinese-traditional-units "Permalink to this headline")

Some traditional Chinese units are included for historical interest in units::precise::chinese

* jin

* liang

* qian

* li

* cun

* chi

* zhang

##### Typographic units[¶](#typographic-units "Permalink to this headline")

Units used in typesetting and typography are included in units::precise::typographic

Subsets of the units depending on the location are in subnamespaces

###### units::precise::typographic::american[¶](#units-precise-typographic-american "Permalink to this headline")

* line

* point

* pica

* twip

###### units::precise::typographic::printers[¶](#units-precise-typographic-printers "Permalink to this headline")

* point

* pica

###### units::precise::typographic::french[¶](#units-precise-typographic-french "Permalink to this headline")

* point

* ligne

* pouce

* didot

* cicero

* pied

* toise

###### units::precise::typographic::metric[¶](#units-precise-typographic-metric "Permalink to this headline")

* point

* quart

###### units::precise::typographic::IN[¶](#units-precise-typographic-in "Permalink to this headline")

l’Imprimerie nationale

* point

* pica

###### units::precise::typographic::tex[¶](#units-precise-typographic-tex "Permalink to this headline")

* point

* pica

###### units::precise::typographic::postscript[¶](#units-precise-typographic-postscript "Permalink to this headline")

* point

* pica

###### units::precise::typographic::dtp[¶](#units-precise-typographic-dtp "Permalink to this headline")

This is the modern standard or as close to such a thing as exists

* point

* pica

* twip

* line

###### units::precise::typographic[¶](#units-precise-typographic "Permalink to this headline")

Values taken from dtp namespace

* point

* pica

##### Distance Units[¶](#distance-units "Permalink to this headline")

Some additional distance units are defined in units::precise::distance

* ly

* au

* au\_old

* angstrom

* parsec

* smoot

* cubit

* longcubit

* arpent\_us

* arpent\_fr

* xu

##### Area Units[¶](#area-units "Permalink to this headline")

Some additional units defining an area units::precise::area

* are

* hectare

* barn

* arpent

##### Mass Units[¶](#mass-units "Permalink to this headline")

Some additional units defining a mass units::precise::mass

* quintal

* ton\_assay

* longton\_assay

* Da

* u

* tonne

t is included in the units::precise namespace as a metric tonne

##### Volume Units[¶](#volume-units "Permalink to this headline")

Some additional units defining a volume units::precise::volume

* stere

* acre\_foot

* drum

##### Angle Units[¶](#angle-units "Permalink to this headline")

A few units defining angles are defined in units::precise::angle.

* deg\*

* gon

* grad

* arcmin

* arcsec

* brad - binary radian (1/256 of a circle)

##### Directional Units[¶](#directional-units "Permalink to this headline")

A few cardinal directional units are defined in units::precise::direction, these make use of the i\_flag and a numerical value

* east

* north

* south

* west

##### Temperature Units[¶](#temperature-units "Permalink to this headline")

A few units related to temperature systems, defined in units::precise::temperature

* celsius, degC\*

* fahrenheit, degF\*

* rankine, degR

* reaumur

##### Pressure Units[¶](#pressure-units "Permalink to this headline")

Some units related to pressure are defined in units::precise::pressure

* psi

* inHg

* mmHg

* torr

* inH2O

* mmH2O

* atm - standard atmosphere

* att - technical atmosphere

##### Power Units[¶](#power-units "Permalink to this headline")

Some units related to power are defined in units::precise::power

* hpE - electric Horsepower

* hpI - international horsepower

* hpS - steam horesepower

* hpM - mechanical horsepower

the unit hp is aliased in the units::precise namespace to power::hpI

##### Energy Units[¶](#energy-units "Permalink to this headline")

Some units related to energy are defined in units::precise::energy

* kWh

* MWh

* eV

* kcal

* cal\_4 - calorie at 4 deg C

* cal\_15 - calorie at 15 deg C

* cal\_28 - calorie at 28 deg C

* cal\_mean - mean calorie

* cal\_it - international table calorie

* cal\_th - thermochemical calorie

* btu\_th - thermochemical BTU

* btu\_39 - BTU at 39 deg C

* btu\_59 - BTU at 59 deg C

* btu\_60 - BTU at 60 deg C

* btu\_mean - mean BTU

* btu\_it - international table BTU

* btu\_iso - rounded btu\_it

* quad

* tonc - cooling ton

* therm\_us

* therm\_br

* therm\_ec

* EER - energy efficiency ratio

* SG - specific gravity

* ton\_tnt

* boe - barrel of oil equivalent

* foeb

* hartree

* tonhour

* tce - ton of coal equivalent

* lge - liter of gasoline equivalent

in the units::precise namespace

* btu = energy::but\_it

* cal = energy::cal\_th

* kWh = energy::kWh

* MWh = energy::MWh

##### Power system Units[¶](#power-system-units "Permalink to this headline")

Some additional units related to power systems and electrical engineering

in units::precise::electrical namespace

* MW

* VAR - W\*i\_flag

* MVAR

* kW

* kVAR

* mW

* puMW

* puV

* puHz

* MJ

* puOhm

* puA

* kV

* mV

* mA

##### Equation type Units[¶](#equation-type-units "Permalink to this headline")

Equation units are explained more thoroughly in [Equation Units](index.html#equation-units) Some of the specific common equation units are defined in the namespace units::precise::log.

* neper

* logE - natural logarithm

* neperA - neper of amplitude unit

* neperP - neper of a power unit

* logbase10

* bel

* belP - bel of a power based unit

* dBP

* belA - bel of an amplitude based unit

* dBA - dB of an amplitude based unit

* logbase2

* dB

* neglog10

* neglog100

* neglog1000

* neglog50000

* B\_SPL

* B\_V

* B\_mV

* B\_uV

* B\_10nV

* B\_W

* B\_kW

* dB\_SPL

* dB\_V

* dB\_mV

* dB\_uV

* dB\_10nV

* dB\_W

* dB\_kW

* dB\_Z - radar reflectivity

* BZ - radar reflectivity

##### Textile related Units[¶](#textile-related-units "Permalink to this headline")

Units related to the textile industry in namespace units::precise::textile.

* tex

* denier

* span

* finger

* nail

##### Clinical Units[¶](#clinical-units "Permalink to this headline")

Units related to clinical medicine in namespace units::precise::clinical.

* pru

* woodu

* diopter

* prism\_diopter

* mesh

* charriere

* drop

* met

* hounsfield

##### Laboratory Units[¶](#laboratory-units "Permalink to this headline")

Units used in laboratory settings in namespace units::precise::laboratory.

* svedberg

* HPF

* LPF

* enzyme\_unit

* IU

* arbU - arbitrary unit

* IR - index of reactivity

* Lf - Limit of flocculation

* PFU

* pH

* molarity

* molality

##### Data Units[¶](#data-units "Permalink to this headline")

Units related to computer data and storage in units::precise::data

* bit\*

* nibble

* byte

* kB\*

* MB\*

* GB\*

* kiB

* MiB

* GiB

* bit\_s - Shannon bit for information theory

* shannon

* hartley

* ban

* dit

* deciban

* nat

* trit

* digits

B is defined as byte in units::precise

##### Computation units[¶](#computation-units "Permalink to this headline")

Units related to computation units::precise::computation.

* flop

* flops

* mips

##### Special units[¶](#special-units "Permalink to this headline")

Some special units that were not otherwise characterized in namespace units::precise::special.

* ASD - amplitude spectral density

* moment\_magnitude - moment magnitude for earthquake scales (related to richter scale)

* moment\_energy

* sshws - saffir simpson hurricane wind scale

* beaufort - Beaufort wind scale

* fujita - Fujita scale for tornados

* mach - mach number(multiplier of the speed of sound)

* rootHertz - square root of Hertz, this is a special handling unit that triggers some specific behavior to handle it.

* rootMeter - square root of meter, this is a special handling unit that triggers some specific behavior to handle it.

##### Other Units[¶](#other-units "Permalink to this headline")

General purpose other units not otherwise categorical in namespace units::precise::other

* ppm - part per million

* ppb - part per billion

* candle

* faraday

* rpm\* - revolution per minute

* CFM - cubic feet per minute

* MegaBuck - $1,000,000

* GigaBuck - $1,000,000,000

##### Climate Units[¶](#climate-units "Permalink to this headline")

Units related to climate in namespace units::precise::climate

* gwp - global warming potential

* gtp - global temperature potential

##### Speed Units[¶](#speed-units "Permalink to this headline")

mph and mps are defined in units::precise since they are pretty common

#### Units in the units namespace[¶](#units-in-the-units-namespace "Permalink to this headline")

Regular units are defined in the units namespace. The general rule is that any units with a definition directly in units::precise has an analog nonprecise unit in the units namespace.

One addition is that any unit defined in precise::electrical also is defined in units this has to do with the origins of the library in power systems.

### Unit Domains[¶](#unit-domains "Permalink to this headline")

There are some ambiguous unit symbols. Different fields use the same symbol to mean different things. In the units library the definition has defaulted to SI standard definition with two known ambiguities. the symbol ‘a’ is used for are, the symbol rad refers to radians.

However there are occasions where the units from one field or another are desired. The units library applies the notion of a unit domain which can be passed to the unit\_flags argument for any string conversion, for a few select units this will change the resulting from a string.

#### Available Domains[¶](#available-domains "Permalink to this headline")

thus far 5 specific unit domains have been defined they are in the

units::domains namespace.

* ucum – THE UNIFIED CODE FOR UNITS OF MEASURE

* cooking – units and symbols commonly used for recipes

* astronomy – units and symbols used in astronomy

* nuclear – units and symbols used in nuclear or particle physics

* surveying – units and symbols used in surveying in the United states

* us\_customary – units and symbols traditionally used in the us(combination of cooking and surveying)

* climate – units and symbols used in climate science

* allDomains – this domain does all the above domains where not mutually exclusive. So mostly a combination of ucum and astronomy/nuclear with a few us customary units IT is not recommended to use this but provided for the combinations

The only units and symbols using the domain are those that might be ambiguous or contradictory to the ST definition. The specific units affected are defined in the next section.

#### Domain Specific Units[¶](#domain-specific-units "Permalink to this headline")

These are unit definitions affected by specifying a specific unit domain

##### UCUM[¶](#ucum "Permalink to this headline")

* B – bel vs Byte

* a – julian year vs are

##### Astronomy[¶](#astronomy "Permalink to this headline")

* am – arc minute vs attometer

* as – arc second vs attosecond

* year – mean tropical year vs median calendar year

##### Cooking[¶](#cooking "Permalink to this headline")

* C – cup vs coulomb

* T – Tablespoon vs Tesla

* c – cup vs speed of light

* t – teaspoon vs metric tonne

* TB – Tablespoon vs TeraByte

* smi – smidgen vs square mile

* scruple – slightly different definition when used in cooking context

* ds – dessertspoon vs deci second

##### Surveying[¶](#surveying "Permalink to this headline")

* ‘ and all variants refer to feet vs arcmin

* ‘’ and all variants refer to inches vs arcsec

##### Nuclear[¶](#nuclear "Permalink to this headline")

* rad radiation absorbed dose vs radian

* rd same as rad vs rod

##### Climate[¶](#climate "Permalink to this headline")

* kt kilo-tonne vs karat

##### US customary[¶](#us-customary "Permalink to this headline")

Combination of surveying and cooking

##### All domains[¶](#all-domains "Permalink to this headline")

Combination of all of the above

More units will likely be added to this as the need arises

#### Specifying the domain[¶](#specifying-the-domain "Permalink to this headline")

The domain can be specified in the unit\_flag string supplied to the unit\_from\_string operation.

```

auto unit1=units::unit\_from\_string(unitString,nuclear\_units)

```

when used as part of the flags argument the definitions are in the unit\_conversion\_flags enumeration

* strict\_ucum

* cooking\_units

* astronomy\_units

* surveying\_units

* nuclear\_units

* climate\_units

* us\_customary\_units

A default domain can also be specified though

```

setUnitsDomain(code);

```

with the code using one of those found in the units::domains namespace.

this domain will be used unless another is specified through the match flags. This function return the previous domain which can be used if only setting the value temporarily.

The default domain can be set at compile time through the UNITS\_DEFAULT\_DOMAIN definition

```

#define UNITS\_DEFAULT\_DOMAIN units::domains::astronomy

#include "units/units.hpp"

```

In CMake this field can be defined and will be directly translated. The UNITS\_DOMAIN CMake variable can also be used to specify a domain as a string like UCUM or COOKING and have it appropriately translate.

See [Unit Library CMake Reference](index.html#unit-library-cmake-reference) for more details.

### Conversion Flags[¶](#conversion-flags "Permalink to this headline")

The units\_from\_string and to\_string operations take an optional flags argument. This controls certain aspects of the conversion process. In most cases this can be left to default unless very specific needs arise.

#### Unit\_from\_string flags[¶](#unit-from-string-flags "Permalink to this headline")

* default\_conversions – no\_flags, so using the default operations

* case\_insensitive –perform case insensitive matching for UCUM case insensitive matching

* single\_slash –specify that there is a single numerator and denominator only a single slash in the unit operations

* strict\_si –input units are strict SI

* strict\_ucum –input units are matching UCUM standard

* cooking\_units –input units for cooking and recipes are prioritized

* astronomy\_units –input units for astronomy are prioritized

* surveying\_units –input units for surveying are prioritized

* nuclear\_units –input units for nuclear physics and radiation are prioritized

* climate\_units –input units for climate sciences

* us\_customary\_units – input units for us customary measurements are prioritized(same as cooking\_units | surveying\_units)

* numbers\_only –indicate that only numbers should be matched in the first segments, mostly applies only to power operations

* no\_recursion –don’t recurse through the string

* not\_first\_pass –indicate that is not the first pass

* no\_per\_operators –skip matching “per”

* no\_locality\_modifiers –skip locality modifiers

* no\_of\_operator –skip dealing with “of”

* no\_addition – skip trying unit addition

* no\_commodities –skip commodity checks

* skip\_partition\_check –skip the partition check algorithm

* skip\_si\_prefix\_check –skip checking for SI prefixes

* skip\_code\_replacements –don’t do some code and sequence replacements

* minimum\_partition\_size2 –specify that any unit partitions must be greater or equal to 2 characters

* minimum\_partition\_size3 –specify that any unit partitions must be greater or equal to 3 characters

* minimum\_partition\_size4 –specify that any unit partitions must be greater or equal to 4 characters

* minimum\_partition\_size5 –specify that any unit partitions must be greater or equal to 5 characters

* minimum\_partition\_size6 –specify that any unit partitions must be greater or equal to 6 characters

* minimum\_partition\_size7 –specify that any unit partitions must be greater or equal to 7 characters

##### Indications for use[¶](#indications-for-use "Permalink to this headline")

The case\_insensitive flag should be used to ignore capitalization completely. It is targeted at the UCUM upper case specification but is effective for all situations where case should be ignored.

The library is by nature somewhat flexible in capitalization patterns, because of this some strings are allowed that otherwise would not be if SI were strictly followed. For example: Um would match to micro meters which should not if being exacting to the SI standard. The strict\_si flag prevents some not all of these instances, and whether others can be disabled is being investigated.

The single\_slash flag is targeted at a few specific programs which use the format of a single slash marking the separation of numerator from denominator.

strict\_ucum, cooking\_units, astronomy\_units, surveying\_units, nuclear\_units, climate\_units and us\_customary\_units are part of the domain system and can change the unit matched.

The remainder of the flags are somewhat self explanatory and are primarily used as part of the string conversion program to prevent infinite recursion. The no\_commodities or no\_per\_operator may be used if it is known those do not apply for a slight increase in performance. The no\_recursion or skip\_partition\_check can be use if only simple strings are passed to speed up the process somewhat.

The minimum partition size flags can be used to restrict how much partitioning it does which can reduce the possibility of “false positives” or unwanted unit matches on the strings

All the flags can be “or”ed to make combinations such as minimum\_partition\_size4|astronomy\_units|no\_of\_operator

#### to\_string Flags[¶](#to-string-flags "Permalink to this headline")

* disable\_large\_power\_strings - if the units definition allows large powers this flag can disable the use of them in the output string.

The to\_string flags can be combined with the other conversion flags without issue.

##### Default flags[¶](#default-flags "Permalink to this headline")

Flags will normally default to 0U however they can be modified through setDefaultFlags. This function returns the previous value in case it is needed to swap them temporarily.

The flags can be retrieved via getDefaultFlags() This function is automatically called if no flag argument is passed. The initial value can be set through a compile time or build time option UNITS\_DEFAULT\_MATCH\_FLAGS.

Application Notes[¶](#application-notes "Permalink to this headline")

---------------------------------------------------------------------

This folder is a collection of some example code snippets and discussions applied to various situations

### Strain[¶](#strain "Permalink to this headline")

Strain is an interesting unit in that it is a dimensionless unit. The most common expression is in in/in or mm/mm often defined as ε. The effects of strain are pretty small so µε is also pretty common.

It is the fractional change in length. There are a several ways to represent this in the units library depending on the needs for a particular situation.

#### Method 1[¶](#method-1 "Permalink to this headline")

The first way is simply as a ratio.

```

measurement deltaLength=0.00001\*m;

measurement length=1\*m;

auto strain=deltaLength/length;

EXPECT\_EQ(to\_string(strain), "1e-05");

//applied to a 10 ft bar

auto distortion=strain\*(10\*ft);

EXPECT\_EQ(to\_string(distortion), "0.0001 ft");

```

The main issue that there is no distinction between a strain measurement and any other ratio, but in many cases that is fine.

#### Method 2[¶](#method-2 "Permalink to this headline")

The default defined unit of strain in the units library uses per unit meters as a basis. The multiplies and divides methods in the units math library can take per unit flag into account when doing the multiplication to get the original units back.

The advantages of this are that strain becomes a distinctive unit from all other ratio units. Volumetric or area strain can be represented in the same way. It does have the disadvantage of requiring the multiplies

```

#include <units/units\_math.hpp> //for multiplies

precise\_measurement strain=1e-05\*default\_unit("strain");

EXPECT\_EQ(to\_string(strain), "1e-05 strain");

//applied to a 10 ft bar

auto distortion=multiplies(strain,(10\*ft));

EXPECT\_EQ(to\_string(distortion), "0.0001 ft");

```

```

#include <units/units\_math.hpp> //for multiplies divides

measurement deltaLength=0.00001\*m;

measurement length=1\*m;

auto strain=divides(deltaLength,length);

EXPECT\_EQ(to\_string(strain), "1e-05 strain");

//applied to a 10 ft bar

auto distortion=multiplies(strain,(10\*ft));

EXPECT\_EQ(to\_string(distortion), "0.0001 ft");

```

#### Method 3[¶](#method-3 "Permalink to this headline")

The third potential method is to use one of the indicator flags to define a unit for strain. This can work in cases where there is no other potential conflicts with the flag and you need the \* operator to work.

```

precise\_unit ustrain(1e-6,eflag); // microstrain

addUserDefinedUnit("ustrain",ustrain);

precise\_measurement strain=45.7\*ustrain;

EXPECT\_EQ(to\_string(strain), "45.7 ustrain");

//applied to a 10 m bar

auto distortion=strain\*(10\*m);

EXPECT\_DOUBLE\_EQ(distortion.value\_as(precise::mm),0.457);

```

The advantages of this are that the there is no per unit values to handle. The disadvantage is that the eflag needs to be handled particularly when dealing with strings. If it is just dealing with computations this is less of an issue.

So this method can work fine in some cases.

#### Discussion[¶](#discussion "Permalink to this headline")

There are several ways to represent strain or any other ratio unit that is derived from particular unit cancellations. All have advantages and disadvantages in particular situations and the method of choice will come down to the expected use cases.

The library chooses the per unit method as it maintains the source units, but other choices are free to choose if they work better in particular situations.

The Low Level Details of the Units library[¶](#the-low-level-details-of-the-units-library "Permalink to this headline")

-----------------------------------------------------------------------------------------------------------------------

### Unit base class[¶](#unit-base-class "Permalink to this headline")

The unit base class is a bitmap comprising segments of a 32 bit number. all the bits are defined

the underlying definition is a set of bit fields that cover a full 32 bit unsigned integer

```

// needs to be defined for the full 32 bits

 signed int meter\_ : 4;

 signed int second\_ : 4; // 8

 signed int kilogram\_ : 3;

 signed int ampere\_ : 3;

 signed int candela\_ : 2; // 16

 signed int kelvin\_ : 3;

 signed int mole\_ : 2;

 signed int radians\_ : 3; // 24

 signed int currency\_ : 2;

 signed int count\_ : 2; // 28

 unsigned int per\_unit\_ : 1;

 unsigned int i\_flag\_ : 1; // 30

 unsigned int e\_flag\_ : 1; //

 unsigned int equation\_ : 1; // 32

```

The default constructor sets all the fields to 0. But this is private and only accessible from friend classes like units.

The main constructor looks like

```

constexpr unit\_data(

 int meter,

 int kilogram,

 int second,

 int ampere,

 int kelvin,

 int mole,

 int candela,

 int currency,

 int count,

 int radians,

 unsigned int per\_unit,

 unsigned int flag,

 unsigned int flag2,

 unsigned int equation)

```

an alternative constructor

```

explicit constexpr unit\_data(std::nullptr\_t);

```

sets all the fields to 1

#### Math operations[¶](#math-operations "Permalink to this headline")

When multiplying two base units the powers are added.

For the flags. The e\_flag and i\_flag are added, effectively an Xor while the pu and equation are ORed.

For division the units are subtracted, while the operations on the flags are the same.

##### Power and Root and Inv functions[¶](#power-and-root-and-inv-functions "Permalink to this headline")

For power operations all the individual powers of the base units are multiplied by the power number.

The pu and equation flags are passed through. For even powers the i\_flag and e\_flag are set to 0, and odd powers they left as is.

For root operations, First a check if the root is valid, if not the error unit is returned. If it is a valid root all the powers are divided by the root power. The Pu flag is left as is, the i\_flag and e\_flag are treated the same is in the pow function and the equations flag is set to 0.

There is one exception to the above rules. There is a special unit for √Hz it is a combination of some i\_flag and e\_flag and a high power of the seconds unit. This unit is used in amplitude spectral density and comes up on occasion in some engineering contexts. There is some special logic in the power function that does the appropriate things such the square of √Hz= Hz. If a low power of seconds is multiplied or divided by the special unit it still does the appropriate thing. But √Hz\*√Hz will not generate the expected result. √Hz is a singular unique unit and the only coordinated result is a power operation to remove it. √Hz unit base itself uses a power of (-5) on the seconds and sets the i\_flag and e\_flag.

The inverse function is equivalent to pow(-1), and just inverts the unit\_data.

#### Getters[¶](#getters "Permalink to this headline")

The unit data type supports getters for the different fields all these are constexpr methods

* meter(): return the meter power

* kg(): return the kilogram power

* second(): return the seconds power

* ampere(): return the ampere power

* kelvin(): return the kelvin power

* mole(): return the mole power

* candela(): return the candela power

* currency(): return the currency power

* count(): return the count power

* radian(): return the radian power

* is\_per\_unit(): returns true if the unit\_base has the per\_unit flag set

* is\_equation(): returns true if the unit\_base has the equation field set

* has\_i\_flag(): returns true if the i\_flag is set

* has\_e\_flag(): returns true if the e\_flag is set

* empty(): will check if the unit\_data has any of the base units set, flags are ignored.

* unit\_type\_count: will count the number of base units with a non-zero power

#### Modifiers[¶](#modifiers "Permalink to this headline")

there are a few methods will generate a new unit based on an existing one the methods are constexpr

* add\_per\_unit(): will set the per\_unit flag

* add\_i\_flag(): will set the i\_flag

* add\_e\_flag(): will set the e\_flag

The method clear\_flags is the only non-const method that modifies a unit\_data in place.

#### Comparisons[¶](#comparisons "Permalink to this headline")

Unit data support the == and != operators. these check all fields.

There are a few additional comparison functions that are also available.

* equivalent\_non\_counting(unit\_base other) : will return true if all the units but the counting units are equal, the counting units are mole, radian, and count.

* has\_same\_base(unit\_base other): will return true if all the units bases are equivalent. So the flags can be different.

### Commodity Details[¶](#commodity-details "Permalink to this headline")

The precise\_unit class includes an unsigned 32 bit field that represents a commodity of some kind.

Units on the Web[¶](#units-on-the-web "Permalink to this headline")

-------------------------------------------------------------------

You can try out the string conversions through the units

[Webserver](../_static/convert.html)

This page allows you to enter a measurement string and a unit string for conversion.

The measurement string can be of any form with a number and units

* 10 m

* hundred pounds

* 45.673 GB

* dozen feet

the unit string should be some unit that is convertible from the measurement units:

* inches

* troy oz

* kiB

* british fathoms

The conversion also supports mathematical operations see [Units From Strings](index.html#units-from-strings) for additional details on string conversions. The units can also be set to \*`or `<base> to convert the measurement to base units.

### Rest API[¶](#rest-api "Permalink to this headline")

The units web server does not serve files, it generates all responses on the fly. There are 3 URI indicators it responds to beyond the root page.

* /convert : responds with an html page

* /convert\_trivial : responds with the results as a simple text

* /convert\_json : responds with a json string containing the requested conversions and the results.

For example in Linux or anything with curl

```

$ curl -s "13.52.135.81/convert\_trivial?measurement=10%20tons&units=lb"

20000

$ curl -s "13.52.135.81/convert\_json?measurement=10%20tons&units=lb"

{

"request\_measurement":"",

"request\_units":"lb"",

"measurement":"",

"units":"lb"",

"value":"nan"

}

 $ curl -s "13.52.135.81/convert\_json?measurement=ten%20meterspersecond&units=feetperminute&caction=to\_string"

{

"request\_measurement":"ten meterspersecond",

"request\_units":"feetperminute",

"measurement":"10 m/s",

"units":"ft/min",

"value":"1968.5"

}

```

This works with POST or GET methods. The caction field can be set to “to\_string” this will “simplify” the units in the result or at least use the internal to\_string operations to convert to an interpretable string in more accessible units.





Units Library String Conversions

Units Library String Conversions

================================

[Source](https://github.com/LLNL/units)

[Documentation](https://units.readthedocs.io/en/latest/index.html)

-----------------------------------------------------------------------------------------------------------

 Measurement string:  

  

 E.g. "25 m", "ten tons", "3.252Tesla", "237uL"

   

  

convert to:  

  

 E.g. "inches", "lb", "Gauss", "tsp"

   

 "use '\*' to convert to base units

   

  

