UDUNITS 2.2.28 Documentation

This manual describes the UDUNITS-2 package, which contains a C library for units of physical quantities and a unit-definition and value-conversion utility.

Introduction

The UDUNITS-2 package provides support for units of physical quantities. Its three main components are:

1. udunits2lib a C library for units of physical quantities;
2. udunits2prog a utility for obtaining the definition of a unit and for converting numeric values between compatible units; and
3. extensive database of units

How This Package Differs from the Original UDUNITS-1 Package

The UDUNIT-2 package differs from the UDUNITS-1 package in the following ways:

• Support for non-ASCII characters: The UDUNITS-1 package only supports the ASCII character set. The UDUNITS-2 package supports the following character sets: ASCII, ISO 8859-1 (Latin-1), and the UTF-8 encoding of ISO 10646 (Unicode). This means that unit string specifications like "µ°F·Ω⁻¹" are now supported (your viewer must support UTF-8 to display this string correctly).
• Support for logarithmic units: The unit string specification "0.1 lg(re 1 mW)" specifies a deciBel unit with a one milliwatt reference level. Such units are fully integrated into the package and all meaningful operations and conversions are supported.
• Persistent value converters: It is now possible to obtain a converter data-object, which can be used to convert numeric values in one unit to numeric values in another, compatible unit. The values can be float, double, or one-dimensional arrays of floats or doubles.
• Improved API: Due to the above changes, it was not possible to keep the application programming interface (API) of the UDUNITS-1 package. The new interface, however, is easily understood and easy to use. To support backward comptibility, the package does contain a version 1 C API, which uses the version 2 library.
• XML unit database: The unit database is encoded using human-readable XML rather than a custom format. The XML parser included in the package supports an <import> element to allow easy and convenient customization.
• No Fortran or Perl API: Interfaces for these languages have not yet been created. Contact support-udunits@unidata.ucar.edu if you are interested in helping to create these interfaces.

One thing that has not changed is that almost all unit string specifications understood by the UDUNITS-1 package are also understood by the UDUNITS-2 package. One exception is the symbol g, which in version 1 of the package was associated with standard free fall (a unit of acceleration) but which is associated with the unit gram in version 2 of the package.

3 Installing this Package

3.1 Prerequisites for This Package

The Expat library and header-files must be installed. Look for the library "libexpat" and the header-file "expat.h".

If this package is to be tested (which is optional), then the CUnit library and header-files must be installed. Look for the library "libcunit" and the header-files "CUnit/CUnit.h" and "CUnit/Basic.h".

If this package is to be built on a Windows system, then the CMake and MinGW packages must be installed. Look for the utility "cmake" and the directory/folder "MinGW".

3.2 Installing from a Binary Distribution

Currently, only an RPM binary distribution is supported.

Download the distribution by browsing to the Unidata UDUNITS-2 at https://artifacts.unidata.ucar.edu/service/rest/repository/browse/rpm-udunits/udunits/ or by executing, for example, the following commands:

cd ~/Downloads
wget https://artifacts.unidata.ucar.edu/repository/rpm-udunits/udunits/udunits-2.2.28-x86_64.rpm

Install the distribution. For example,

sudo rpm --install [--prefix=/opt/udunits] ~/Downloads/udunits-2.2.28-x86_64.rpm

where the argument in square brackets is optional. The default installation directory is /usr/local.

3.3 Installing from a Source Distribution

3.3.1 Installing from source on Unix

Download the source by browsing to the Unidata UDUNITS-2 at https://artifacts.unidata.ucar.edu/service/rest/repository/browse/downloads-udunits/ or by executing, for example, the following commands:

cd ~/Downloads
curl -O https://artifacts.unidata.ucar.edu/repository/downloads-udunits/udunits-2.2.28.tar.gz

Unpack the distribution in an appropriate place. For example,

cd /opt
sudo pax -rz < ~/Downloads/udunits-2.2.28.tar.gz

Build and install the package. For example

cd udunits2-2.2.28
./configure [--prefix=install_prefix] >&configure.log
make all [check] install [install-html] [install-pdf]

where the arguments in square brackets are optional. The default installation prefix is the parent directory of the source directory.

3.3.2 Installing from source on Windows

Download the source by browsing to the Unidata UDUNITS-2 at https://artifacts.unidata.ucar.edu/service/rest/repository/browse/downloads-udunits/ or by executing, for example, the following commands:

cd C:\Users\current_user\Downloads
curl -O https://artifacts.unidata.ucar.edu/repository/downloads-udunits/udunits-2.2.28.zip

Unpack the distribution by opening the downloaded file and extracting the contents to, for example, the user’s "Downloads" folder. Note that, by default, the extractor might create an extra top-level folder with a duplicate name. Remove the extra folder from the destination path if this is the case – either before or after extraction.

Build and install the package using cmake(1). For example

cd C:\Users\current_user\Downloads\udunits2-2.2.28
mkdir build
cd build
cmake [-D CMAKE_INSTALL_PREFIX=install_prefix] ..
make all install

where the argument in square brackets is optional. The default installation folder is the parent folder of the source folder.

4 Unit Library

See (udunits2lib)UDUNITS Library, for details on this package’s unit library.

5 Unit Utility

See (udunits2prog)UDUNITS Utility, for details on this package’s unit utility.

6 The Units Database

The database for the UDUNITS-2 package comprises one XML file containing unit prefixes and four XML files containing unit definitions:

• SI unit prefixes
• SI base units
• SI derived units
• Units accepted for use with the SI
• Non-SI units

7 Support for this Package

The home-page for this package can be found at http://www.unidata.ucar.edu/software/udunits/.

Bug reports should be sent to support-udunits@unidata.ucar.edu.

Index

License

Copyright 2014 University Corporation for Atmospheric Research and contributors. All rights reserved.

This software was developed by the Unidata Program Center of the University Corporation for Atmospheric Research (UCAR) https://www.unidata.ucar.edu.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the names of the development group, the copyright holders, nor the names of contributors may be used to endorse or promote products derived from this software without specific prior written permission.
4. This license shall terminate automatically and you may no longer exercise any of the rights granted to you by this license as of the date you commence an action, including a cross-claim or counterclaim, against the copyright holders or any contributor alleging that this software infringes a patent. This termination provision shall not apply for an action alleging patent infringement by combinations of this software with other software or hardware.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE SOFTWARE.