UDUNITS-2
*********

This manual describes how to use the C API of the UDUNITS-2 library.
Among other things, the library allows C code to obtain a binary
representation of a unit of a physical quantity, to operate on such
units, and to convert numeric values between compatible units.

   The library comes with an extensive database of units all referenced
to the SI system of units.

   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)
<http://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.

1 Synopsis
**********

Coding:
     #include <udunits2.h>

          const char*                See ut_get_path_xml.
                                     (const char*
                                     PATH);
          ut_system*                 See ut_read_xml.
                                     (const char*
                                     PATH);
          ut_system*                 See ut_new_system.
                                     (void);
          void                       ut_free_system.
                                     (ut_system*
                                     SYSTEM);
          ut_system*                 See ut_get_system.
                                     (const ut_unit*
                                     UNIT);
          ut_unit*                   See
                                     ut_get_dimensionless_unit_one.
                                     (const
                                     ut_system* SYSTEM);
          ut_unit*                   See ut_get_unit_by_name.
                                     (const
                                     ut_system* SYSTEM, const char*
                                     NAME);
          ut_unit*                   See ut_get_unit_by_symbol.
                                     (const
                                     ut_system* SYSTEM, const char*
                                     SYMBOL);
          ut_status                  ut_set_second.
                                     (const ut_unit*
                                     SECOND);
          ut_status                  ut_add_name_prefix.
                                     (ut_system*
                                     SYSTEM, const char* NAME,
                                     double VALUE);
          ut_status                  ut_add_symbol_prefix.
                                     (ut_system*
                                     SYSTEM, const char* SYMBOL,
                                     double VALUE);
          ut_unit*                   See ut_new_base_unit.
                                     (ut_system*
                                     SYSTEM);
          ut_unit*                   See
                                     ut_new_dimensionless_unit.
                                     (ut_system*
                                     SYSTEM);
          ut_unit*                   See ut_clone.
                                     (const ut_unit*
                                     UNIT);
          void                       ut_free.
                                     (ut_unit* UNIT);
          const char*                See ut_get_name.
                                     (const ut_unit*
                                     UNIT, ut_encoding ENCODING);
          ut_status                  ut_map_name_to_unit.
                                     (const
                                     char* NAME, const ut_encoding
                                     ENCODING, const ut_unit* UNIT);
          ut_status                  ut_unmap_name_to_unit.
                                     (ut_system*
                                     SYSTEM, const char* NAME, const
                                     ut_encoding ENCODING);
          ut_status                  ut_map_unit_to_name.
                                     (const
                                     ut_unit* UNIT, const char*
                                     NAME, ut_encoding ENCODING);
          ut_status                  ut_unmap_unit_to_name.
                                     (const
                                     ut_unit* UNIT, ut_encoding
                                     ENCODING);
          const char*                See ut_get_symbol.
                                     (const ut_unit*
                                     UNIT, ut_encoding ENCODING);
          ut_status                  ut_map_symbol_to_unit.
                                     (const
                                     char* SYMBOL, const ut_encoding
                                     ENCODING, const ut_unit* UNIT);
          ut_status                  ut_unmap_symbol_to_unit.
                                     (ut_system*
                                     SYSTEM, const char* SYMBOL,
                                     const ut_encoding ENCODING);
          ut_status                  ut_map_unit_to_symbol.
                                     (const
                                     ut_unit* UNIT, const char*
                                     SYMBOL, ut_encoding ENCODING);
          ut_status                  ut_unmap_unit_to_symbol.
                                     (const
                                     ut_unit* UNIT, ut_encoding
                                     ENCODING);
          int                        ut_is_dimensionless.
                                     (const
                                     ut_unit* UNIT);
          int                        ut_same_system.
                                     (const
                                     ut_unit* UNIT1, const ut_unit*
                                     UNIT2);
          int                        ut_compare.
                                     (const ut_unit*
                                     UNIT1, const ut_unit* UNIT2);
          int                        ut_are_convertible.
                                     (const
                                     ut_unit* UNIT1, const ut_unit*
                                     UNIT2);
          cv_converter*              See ut_get_converter.
                                     (ut_unit*
                                     FROM, ut_unit* TO);
          ut_unit*                   See ut_scale.
                                     (double FACTOR,
                                     const ut_unit* UNIT);
          ut_unit*                   See ut_offset.
                                     (const ut_unit*
                                     UNIT, double OFFSET);
          ut_unit*                   See ut_offset_by_time.
                                     (const
                                     ut_unit* UNIT, double ORIGIN);
          ut_unit*                   See ut_multiply.
                                     (const ut_unit*
                                     UNIT1, const ut_unit* UNIT2);
          ut_unit*                   See ut_invert.
                                     (const ut_unit*
                                     UNIT);
          ut_unit*                   See ut_divide.
                                     (const ut_unit*
                                     NUMER, const ut_unit* DENOM);
          ut_unit*                   See ut_raise.
                                     (const ut_unit*
                                     UNIT, int POWER);
          ut_unit*                   See ut_root.(const
                                     ut_unit* UNIT, int ROOT);
          ut_unit*                   See ut_log.(double
                                     BASE, const ut_unit* REFERENCE);
          ut_unit*                   See ut_parse.
                                     (const ut_system*
                                     SYSTEM, const char* STRING,
                                     ut_encoding ENCODING);
          char*                      See ut_trim.(char*
                                     STRING, ut_encoding ENCODING);
          int                        ut_format.
                                     (const ut_unit*
                                     UNIT, char* BUF, size_t SIZE,
                                     unsigned OPTS);
          ut_status                  ut_accept_visitor.
                                     (const
                                     ut_unit* UNIT, const
                                     ut_visitor* VISITOR, void* ARG);
          double                     ut_encode_date.
                                     (int YEAR, int
                                     MONTH, int DAY);
          double                     ut_encode_clock.
                                     (int HOURS,
                                     int MINUTES, double SECONDS);
          double                     ut_encode_time.
                                     (int YEAR, int
                                     MONTH, int DAY, int HOUR, int
                                     MINUTE, double SECOND);
          void                       ut_decode_time.
                                     (double VALUE,
                                     int* YEAR, int* MONTH, int*
                                     DAY, int* HOUR, int* MINUTE,
                                     double* SECOND, double*
                                     RESOLUTION);
          ut_status                  ut_get_status.
                                     (void);
          void                       ut_set_status.
                                     (ut_status
                                     STATUS);
          int                        ut_handle_error_message.
                                     (const
                                     char* FMT, ...);
          ut_error_message_handler
                                     ut_set_error_message_handler.
                                     (ut_error_message_handler
                                     HANDLER);
          int                        ut_write_to_stderr.
                                     (const
                                     char* FMT, va_list ARGS);
          int                        ut_ignore.
                                     (const char* FMT,
                                     va_list ARGS);

          float                      cv_convert_float.
                                     (const
                                     cv_converter* CONVERTER, float
                                     VALUE);
          double                     cv_convert_double.
                                     (const
                                     cv_converter* CONVERTER, double
                                     VALUE);
          float*                     See cv_convert_floats.
                                     (const
                                     cv_converter* CONVERTER, const
                                     float* IN, size_t COUNT, float*
                                     OUT);
          double*                    See cv_convert_doubles.
                                     (const
                                     cv_converter* CONVERTER, const
                                     double* CONST in, SIZE_T count,
                                     DOUBLE* out);
          void                       cv_free.
                                     (cv_converter* CONV);

   Compiling:
     c89 -I _includedir_ ...

   Where _includedir_ is the installation-directory for C header files
(e.g., `/usr/local/include').

   Linking:
     c89 ... -L_libdir_ -ludunits2 -lexpat ... -lm

   Where _libdir_ is the installation-directory for object code
libraries (e.g., `/usr/local/lib').

2 What's a Unit Package Good For?
*********************************

The existance of a software package is justified by what you can do
with it.  The three main things you can do with the UDUNIT-2 package are
  1. Convert numeric values between compatible units.

  2. Convert a string representation of a unit into a binary one --
     enabling the programatic manipulation of units.  There are three
     ways to do this:
        * Get the unit from a unit-system.
          This requires that you know the unit's name or symbol and
          that the unit is in a unit-system.

        * Parse a string representation of the unit into its binary representation.
          This requires that the
          string be parsable by `ut_parse()'.

        * Explicity construct the unit from subcomponent units using unit operations.

  3. Convert a binary representation of a unit into a string.
     -- enabling the printing and storing of units in a
     human-readable form.
        While the above might seem to be trivial activities, their
general availability at the time might have helped prevent the Mars
Climate Orbiter (http://en.wikipedia.org/wiki/Mars_Climate_Orbiter)
fiasco.

3 Unit-Systems
**************

A unit-system is a set of units that are all defined in terms of the
same set of base units.  In the SI system of units, for example, the
base units are the meter, kilogram, second, ampere, kelvin, mole, and
candela.  (For definitions of these base units, see
`http://physics.nist.gov/cuu/Units/current.html'.)

   In the UDUNITS-2 package, every accessible unit belongs to one and
only one unit-system.  It is not possible to convert numeric values
between units of different unit-systems.  Similarly, units belonging to
different unit-systems always compare unequal.

   There are several categories of operations on unit-systems:

3.1 Obtaining a Unit-System
===========================

Typically, you would obtain a unit-system of predefined units by reading
the default unit database using `ut_read_xml()' with a `NULL'
pathname argument.  If this doesn't quite match your needs, then there
are alternatives.  Together with the typical solution, the means for
obtaining a useful unit-system are (in order of increasing complexity):

   * Obtain the default unit-system using `ut_read_xml.
     (NULL)'.

   * Copy and customize the unit database and then call `
     ut_read_xml()' with the pathname of the customized database to
     obtain a customized unit-system.

   * Same as either of the above but then adding new units to the
     unit-system using `ut_new_base_unit()' and `
     ut_new_dimensionless_unit()'.

   * Same as the above but also deriving new units using unit operations.
     and then adding them to the unit-system
     using unit mapping.

   * Same as the above but starting with an empty unit-system obtained
     from `ut_new_system()', in which case you will definitely
     have to start with `ut_new_base_unit()' and `
     ut_new_dimensionless_unit()'.

   You should pass every unit-system pointer to `
ut_free_system()' when you no longer need the corresponding
unit-system.

 -- Function: `const char*' ut_get_path_xml `(const char* PATH,
          ut_status* status)'
     Returns the pathname of the XML-formatted unit-database
     corresponding to PATH. If PATH is non-`NULL', then it is returned;
     otherwise, if the environment variable `UDUNITS2_XML_PATH' is set,
     then its value is returned; otherwise, the pathname of the default
     unit-database is returned.  The value of `*status' indicates which
     of these possibilities occurred:

    `UT_OPEN_ARG'
          PATH is non-`NULL' and was returned.

    `UT_OPEN_ENV'
          PATH is `NULL', the environment variable `UDUNITS2_XML_PATH'
          is set, and its value was returned.

    `UT_OPEN_DEFAULT'
          PATH is `NULL', the environment variable `UDUNITS2_XML_PATH'
          is unset, and the pathname of the default unit-database was
          returned.

 -- Function: `ut_system*' ut_read_xml `(const char* PATH)'
     Reads the XML-formatted unit-database specified by PATH and
     returns the corresponding unit-sytem.  If PATH is `NULL', then the
     pathname specified by the environment variable `UDUNITS2_XML_PATH'
     is used if set; otherwise, the compile-time pathname of the
     installed, default, unit database is used.  You should pass the
     returned pointer to `ut_free_system()' when you no longer need the
     unit-system.  If an error occurs, then this function writes an
     error-message using `ut_handle_error_message()' and
     returns `NULL'.  Also, `ut_get_status()' will return one
     of the following:

    `UT_OPEN_ARG'
          PATH is non-`NULL' but the file couldn't be opened.  See
          `errno' for the reason.

    `UT_OPEN_ENV'
          PATH is `NULL' and environment variable `UDUNITS2_XML_PATH'
          is set but the file couldn't be opened.  See `errno' for the
          reason.

    `UT_OPEN_DEFAULT'
          PATH is `NULL', environment variable `UDUNITS2_XML_PATH' is
          unset, and the installed, default, unit database couldn't be
          opened.  See `errno' for the reason.

    `UT_OS'
          Operating-system error.  See `errno'.

    `UT_PARSE'
          The database file couldn't be parsed.

 -- Function: `ut_system*' ut_new_system `(void)'
     Creates and returns a new unit-system.  On success, the
     unit-system will be empty except for the dimensionless unit one.
     You should pass the returned pointer to `ut_free_system()' when you
     no longer need the unit-system.  If an error occurs, then this
     function writes an error-message using `
     ut_handle_error_message()' and returns `NULL'.  Also, `
     ut_get_status()' will return the following:

    `UT_OS'
          Operating-system error.  See `errno'.

3.2 Extracting Units from a Unit-System
=======================================

*NOTE\:* This section covers low-level access to the indidual units of a
unit-system.  General parsing of arbitrary unit specifications
is coverted in the section Parsing.

   A unit-system contains mappings from identifiers to units
(and vice versa).  Consequently, once you have a unit-system, you can
easily obtain a unit for which you know the name or symbol using the
function `ut_get_unit_by_name()' or `
ut_get_unit_by_symbol()'.

 -- Function: `ut_unit*' ut_get_unit_by_name `(const ut_system* SYSTEM,
          const char* NAME)'
     Returns the unit to which NAME maps from the unit-system
     referenced by SYSTEM or `NULL' if no such unit exists.  Name
     comparisons are case-insensitive.  If this function returns
     `NULL', then `ut_get_status()' will return one of the
     following:

    `UT_SUCCESS'
          NAME doesn't map to a unit of SYSTEM.

    `UT_BAD_ARG'
          SYSTEM or NAME is `NULL'.

     You should pass the returned unit to `ut_free()' when it is no
     longer needed.

 -- Function: `ut_unit*' ut_get_unit_by_symbol `(const ut_system*
          SYSTEM, const char* SYMBOL)'
     Returns the unit to which SYMBOL maps from the unit-system
     referenced by SYSTEM or `NULL' if no such unit exists.  Symbol
     comparisons are case-sensitive.  If this function returns `NULL',
     then `ut_get_status()' will return one of the following:

    `UT_SUCCESS'
          SYMBOL doesn't map to a unit of SYSTEM.

    `UT_BAD_ARG'
          SYSTEM or SYMBOL is `NULL'.

     You should pass the returned unit to `ut_free()' when it is no
     longer needed.

 -- Function: `ut_unit*' ut_get_dimensionless_unit_one `(const
          ut_system* SYSTEM)'
     Returns the dimensionless unit one of the unit-system referenced by
     SYSTEM.  While not necessary, the returned pointer may be passed
     to `ut_free()' when you no longer need the unit.  If SYSTEM is
     `NULL', then this function writes an error-message using `
     ut_handle_error_message()' and returns `NULL'.  Also, `
     ut_get_status()' will return `UT_BAD_ARG'.

3.3 Adding Units to a Unit-System
=================================

If you use `ut_read_xml()', then you should not normally need to
add any new units to a unit-system.

   Because you get units via their names or symbols, adding a unit to a
unit-system actually means mapping one or more identifiers (i.e., names
or symbols) to the unit.  Thereafter, you can use `
ut_get_unit_by_name()' and `ut_get_unit_by_symbol()' to
retrieve the unit.  The mapping of identifiers to units is covered
here.

   Having said that, it is possible to create a new base or
dimensionless unit within a unit-system using `
ut_new_base_unit()' or `ut_new_dimensionless_unit()'--you'll
just also have to map identifiers to the newly-created unit in order to
be able to retrieve it later by identifier.

 -- Function: `ut_unit*' ut_new_base_unit `(ut_system* SYSTEM)'
     Creates and adds a new base-unit to the unit-system referenced by
     SYSTEM.  This function returns the new base-unit.  You should pass
     the returned pointer to `ut_free()' when you no longer need the
     unit.  If an error occurs, then this function writes an
     error-message using `ut_handle_error_message()' and
     returns `NULL'.  Also, `ut_get_status()' will return one
     of the following:

    `UT_BAD_ARG'
          SYSTEM is `NULL'.

    `UT_OS'
          Operating-system failure.  See `errno'.
     If you use `ut_read_xml()', then you should not normally
     need to call this function.

 -- Function: `ut_unit*' ut_new_dimensionless_unit `(ut_system* SYSTEM)'
     Creates and adds a new dimensionless-unit to the unit-system
     referenced by SYSTEM.  This function returns the new
     dimensionless-unit.  You should pass the returned pointer to
     `ut_free()' when you no longer need the unit.  If an error occurs,
     then this function writes an error-message using `
     ut_handle_error_message()' and returns `NULL'.  Also, `
     ut_get_status()' will return one of the following:

    `UT_BAD_ARG'
          SYSTEM is `NULL'.

    `UT_OS'
          Operating-system failure.  See `errno'.
     If you use `ut_read_xml()', then you should not normally
     need to call this function.

3.4 Adding Unit-Prefixes to a Unit-System
=========================================

A prefix is a word or symbol that is appended to the beginning of a
word or symbol that represents a unit in order to modify the value of
that unit.  For example, the prefix "kilo" in the word "kiloamperes"
changes the value from one ampere to one-thousand amperes.

   If you use `ut_read_xml()', then you should not normally
need to add any new prefixes to a unit-system.

 -- Function: `ut_status' ut_add_name_prefix `(ut_system*
          SYSTEM, const char* NAME, double VALUE)'
     Adds the name-prefix NAME with the value VALUE to the unit-system
     SYSTEM.  A name-prefix is something like "mega" or "milli".
     Comparisons between name-prefixes are case-insensitive.  This
     function returns one of the following:

    `UT_SUCCESS'
          Success.

    `UT_BAD_ARG'
          SYSTEM or NAME is `NULL', or VALUE is `0'.

    `UT_EXISTS'
          NAME already maps to a different value.

    `UT_OS'
          Operating-system failure.  See `errno'.

 -- Function: `ut_status' ut_add_symbol_prefix `(ut_system*
          SYSTEM, const char* SYMBOL, double VALUE)'
     Adds the symbol-prefix SYMBOL with the value VALUE to the
     unit-system SYSTEM.  A symbol-prefix is something like "M" or "m".
     Comparisons between symbol-prefixes are case-sensitive.  This
     function returns one of the following:

    `UT_SUCCESS'
          Success.

    `UT_BAD_ARG'
          SYSTEM or SYMBOL is `NULL', or VALUE is `0'.

    `UT_EXISTS'
          SYMBOL already maps to a different value.

    `UT_OS'
          Operating-system failure.  See `errno'.

3.5 Miscelaneous Operations on Unit-Systems
===========================================

 -- Function: `void' ut_free_system `(ut_system* SYSTEM)'
     Frees the unit-system referenced by SYSTEM.  All
     unit-to-identifier and identifier-to-unit mappings are removed.
     Use of `system' after this function returns results in undefined
     behavior.

 -- Function: `ut_status' ut_set_second `(const ut_unit*
          SECOND)'
     Sets the "second" unit of a unit-system.  This function must be
     called before the first call to `ut_offset_by_time()' for a unit
     in the same unit-system.  `ut_read_xml()' calls this
     function if the unit-system it's reading contains a unit named
     "second".  This function returns one of the following:

    `UT_SUCCESS'
          The "second" unit of SYSTEM was successfully set.

    `UT_EXISTS'
          The "second" unit of SYSTEM is set to a different unit.

    `UT_BAD_ARG'
          SECOND is `NULL'.

4 Converting Values Between Units
*********************************

You can convert numeric values in one unit to equivalent values in
another, compatible unit by means of a converter.  For example

     #include <udunits2.h>
     ...
         ut_unit*      from = ...;
         ut_unit*      to = ...;
         cv_converter* converter = ut_get_converter(from, to);
         double       fromValue = ...;
         double       toValue = cv_convert_double(converter, fromValue);

         cv_free(converter);

   The converter API is declared in the header-file `<converter.h>',
which is automatically included by the UDUNITS-2 header-file
(`<udunits2.h>') so you don't need to explicitly include it.

 -- Function: `int' ut_are_convertible `(const ut_unit* UNIT1, uconst
          t_unit* UNIT2)'
     Indicates if numeric values in unit UNIT1 are convertible to
     numeric values in unit UNIT2 via ut_get_converter().  In
     making this determination, dimensionless units are ignored.  This
     function returns a non-zero value if conversion is possible;
     otherwise, `0' is returned and ut_get_status() will return
     one of the following:

    `UT_BAD_ARG'
          UNIT1 or UNIT2 is `NULL'.

    `UT_NOT_SAME_SYSTEM'
          UNIT1 and UNIT2 belong to different unit-systems.

    `UT_SUCCESS'
          Conversion between the units is not possible (e.g., UNIT1
          refers to a meter and UNIT2 refers to a kilogram.

 -- Function: `cv_converter*' ut_get_converter `(ut_unit* const FROM,
          ut_unit* const TO)'
     Creates and returns a converter of numeric values in the FROM unit
     to equivalent values in the TO unit.  You should pass the returned
     pointer to `cv_free()' when you no longer need the converter.  If
     an error occurs, then this function writes an error-message using
     `ut_handle_error_message()' and returns `NULL'.  Also,
     `ut_get_status()' will return one of the following:

    `UT_BAD_ARG'
          FROM or TO is `NULL'.

    `UT_NOT_SAME_SYSTEM'
          The units FROM and TO don't belong to the same unit-system.

    `UT_MEANINGLESS'
          The units belong to the same unit-system but conversion
          between them is meaningless (e.g., conversion between seconds
          and kilograms is meaningless).

    `UT_OS'
          Operating-system failure.  See `errno'.

 -- Function: `float' cv_convert_float `(const cv_converter* CONVERTER,
          const float VALUE)'
     Converts the single floating-point value VALUE and returns the new
     value.

 -- Function: `double' cv_convert_double `(const cv_converter*
          CONVERTER, const double VALUE)'
     Converts the single double-precision value VALUE and returns the
     new value.

 -- Function: `float*' cv_convert_floats `(const cv_converter*
          CONVERTER, const float* IN, size_t COUNT, float* OUT)'
     Converts the COUNT floating-point values starting at IN, writing
     the new values starting at OUT and, as a convenience, returns OUT.
     The input and output arrays may overlap or be identical.

 -- Function: `double*' cv_convert_doubles `(const cv_converter*
          CONVERTER, const double* IN, size_t COUNT, double* OUT)'
     Converts the COUNT double-precision values starting at IN, writing
     the new values starting at OUT and, as a convenience, returns OUT.
     The input and output arrays may overlap or be identical.

 -- Function: `void' cv_free `(cv_converter* CONV)';
     Frees resources associated with the converter referenced by CONV.
     You should call this function when you no longer need the
     converter.  Use of CONV upon return results in undefined behavior.

5 Parsing a String into a Unit
******************************

Here's an example of parsing a string representation of a unit into its
binary representation:

     #include <stdlib.h>
     #include <udunits2.h>
     ...
         ut_system*   unitSystem = See ut_read_xml(NULL).;
         const char* string = "kg.m2/s3";
         ut_unit*     watt = See ut_parse.(unitSystem, string, UT_ASCII);

         if (watt == NULL) {
             /* Unable to parse string. */
         }
         else {
             /* Life is good. */
         }

 -- Function: `ut_unit*' ut_parse `(const ut_system* SYSTEM, const
          char* STRING, ut_encoding ENCODING)'
     Returns the binary unit representation corresponding to the string
     unit representation STRING in the character-set ENCODING using the
     unit-system SYSTEM.  STRING must have no leading or trailing
     whitespace (see `ut_trim()').  If an error occurs, then
     this function returns `NULL' and `ut_get_status()' will
     return one of the following:

    `UT_BAD_ARG'
          SYSTEM or STRING is `NULL'.

    `UT_SYNTAX'
          STRING contained a syntax error.

    `UT_UNKNOWN'
          STRING contained an unknown identifier.

    `UT_OS'
          Operating-system failure.  See `errno' for the reason.

     You should pass the returned unit to `ut_free()' when it is no
     longer needed.

 -- Function: `size_t' ut_trim `(char* STRING, ut_encoding ENCODING)'
     Removes all leading and trailing whitespace from the
     NUL-terminated string STRING.  Returns STRING, which is modified
     if it contained leading or trailing whitespace.

6 Unit Syntax
*************

For the most part, the UDUNITS-2 package follows the syntax for
unit-strings promulgated by the US National Institute for Standards and
Technology (NIST).  Details, of which, can be found at
`http://physics.nist.gov/cuu/Units/index.html'.  The one general
exception to this is the invention of a syntax for "offset"-units
(e.g., the definition of the degree Celsius is "K @ 273.15").

6.1 Unit Specification Examples
===============================

     String Type   Using Names             Using       Comment
                                           Symbols
     --------------------------------------------------------------------------------------------------------
     Simple        meter                   m
     Raised        meter^2                 m2          higher precedence than multiplying or dividing
     Product       newton meter            N.m
     Quotient      meter per second        m/s
     Scaled        60 second               60 s
     Prefixed      kilometer               km
     Offset        kelvin from 273.15      K @ 273.15  lower precedence than multiplying or dividing
     Logarithmic   lg(re milliwatt)        lg(re mW)   "lg" is base 10, "ln" is base e, and "lb" is base 2
     Grouped       (5 meter)/(30 second)   (5 m)/(30
                                           s)

The above may be combined, e.g., "0.1 lg(re m/(5 s)^2) @ 50".

   You may also look at the `<def>' elements in the units database
to see examples of string unit specifications.

   You may use the `udunits2 (udunits2prog).' utility to
experiment with string unit specifications.

6.2 Unit Grammar
================

Here is the unit-syntax understood by the UDUNITS-2 package.  Words
printed _Thusly_ indicate non-terminals; words printed THUSLY indicate
terminals; and words printed <thusly> indicate lexical elements.

     _Unit-Spec: one of_
             nothing
             _Shift-Spec_

     _Shift-Spec: one of_
             _Product-Spec_
             _Product-Spec_ SHIFT REAL
             _Product-Spec_ SHIFT INT
             _Product-Spec_ SHIFT _Timestamp_

     _Product-Spec: one of_
             _Power-Spec_
             _Product-Spec_ _Power-Spec_
             _Product-Spec_ MULTIPLY _Power-Spec_
             _Product-Spec_ DIVIDE _Power-Spec_

     _Power-Spec: one of_
             _Basic-Spec_
             _Basic-Spec_ INT
             _Basic-Spec_ EXPONENT
             _Basic-Spec_ RAISE INT

     _Basic-Spec: one of_
             ID
             "(" _Shift-Spec_ ")"
             LOGREF _Product_Spec_ ")"
             _Number_

     _Number: one of_
             INT
             REAL

     _Timestamp: one of_
             DATE
             DATE CLOCK
             DATE CLOCK CLOCK
             DATE CLOCK INT
             DATE CLOCK ID
             TIMESTAMP
             TIMESTAMP INT
             TIMESTAMP ID

     SHIFT:
             <space>* <shift_op> <space>*

     <shift_op>: one of
             "@"
             "after"
             "from"
             "since"
             "ref"

     REAL:
             the usual floating-point format

     INT:
             the usual integer format

     MULTIPLY: one of
             "-"
             "."
             "*"
             <space>+
             <centered middot>

     DIVIDE:
             <space>* <divide_op> <space>*

     <divide_op>: one of
             per
             PER
             "/"

     EXPONENT:
             ISO-8859-9 or UTF-8 encoded exponent characters

     RAISE: one of
             "^"
             "**"

     ID: one of
             <id>
             "%"
             "'"
             "\""
             degree sign
             greek mu character

     <id>:
             <alpha> <alphanum>*

     <alpha>:
             [A-Za-z_]
             ISO-8859-1 alphabetic characters
             non-breaking space

     <alphanum>: one of
             <alpha>
             <digit>

     <digit>:
             [0-9]

     LOGREF:
             <log> <space>* <logref>

     <log>: one of
             "log"
             "lg"
             "ln"
             "lb"

     <logref>:
             "(" <space>* <re> ":"? <space>*

     DATE:
             <year> "-" <month> ("-" <day>)?

     <year>:
             [+-]?[0-9]{1,4}

     <month>:
             "0"?[1-9]|1[0-2]

     <day>:
             "0"?[1-9]|[1-2][0-9]|"30"|"31"

     CLOCK:
             <hour> ":" <minute> (":" <second>)?

     TIMSTAMP:
             <year> (<month> <day>?)? "T" <hour> (<minute> <second>?)?

     <hour>:
             [+-]?[0-1]?[0-9]|2[0-3]

     <minute>:
             [0-5]?[0-9]

     <second>:
             (<minute>|60) (\.[0-9]*)?

7 Formatting a Unit into a String
*********************************

Use the `ut_format()' function to obtain the string
representation of a binary unit.  For example, the following gets the
definition of the unit "watt" in ASCII characters using unit-symbols
rather than unit-names:

     ut_unit*     watt = ...;
     char        buf[128];
     unsigned    opts = See UT_ASCII. | UT_DEFINITION;
     int         len = See ut_format.(watt, buf, sizeof(buf), opts);

     if (len == -1) {
         /* Couldn't get string */
     }
     else if (len == sizeof(buf)) {
         /* Entire buffer used: no terminating NUL */
     }
     else {
         /* Have string with terminating NUL */
     }

 -- Function: `int' ut_format `(const ut_unit* UNIT, char* BUF, size_t
          SIZE, unsigned OPTS)'
     Formats the unit UNIT (i.e., returns its string representation)
     into the buffer pointed-to by BUF of size SIZE.  The argument OPTS
     specifies how the formatting is to be done and is a bitwise OR of
     a ut_encoding value and zero or more of the following:

    `UT_NAMES'
          Use unit names instead of symbols.

    `UT_DEFINITION'
          The formatted string should be the definition of UNIT in terms
          of basic-units instead of stopping any expansion at the
          highest level possible.

     On success, this function returns either the number of bytes -
     excluding the terminating `NUL' - that were written into `buf' or
     the number of bytes that _would have been written_. The difference
     is due to the runtime `snprinf()' function that was used.

     On failure, this function returns `-1' and ut_get_status()
     will return one of the following:

    `UT_BAD_ARG'
          UNIT or BUF is `NULL', or OPTS contains the bit patterns of
          both `UT_LATIN1' and `UT_UTF8'.

    `UT_CANT_FORMAT'
          UNIT can't be formatted in the desired manner (e.g., OPTS
          contains `UT_ASCII' but UNIT doesn't have an identifier in
          that character-set or OPTS doesn't contain UT_NAMES and a
          necessary symbol doesn't exist).

8 Unit Operations
*****************

You can use unit operations to construct new units, get information
about units, or compare units.

8.1 Unary Unit Operations
=========================

 -- Function: `void' ut_free `(ut_unit* UNIT)'
     Frees resources associated with UNIT.  You should invoke this
     function on every unit that you no longer need.  Use of UNIT upon
     return from this function results in undefined behavior.

 -- Function: `ut_unit*' ut_scale `(double FACTOR, const ut_unit* UNIT)'
     Returns a unit equivalent to another unit scaled by a numeric
     factor.  For example:
          const ut_unit*   meter = ...
          const ut_unit*   kilometer = ut_scale(1000, meter);
     The returned unit is equivalent to UNIT multiplied by FACTOR.  You
     should pass the returned pointer to `ut_free()' when you
     no longer need the unit.

 -- Function: `ut_unit*' ut_offset `(const ut_unit* UNIT, double
          OFFSET)'
     Returns a unit equivalent to another unit relative to a particular
     origin.  For example:
          const ut_unit*   kelvin = ...
          const ut_unit*   celsius = ut_offset(kelvin, 273.15);
     The returned unit is equivalent to UNIT with an origin of OFFSET.
     You should pass the returned pointer to `ut_free()' when
     you no longer need the unit.  If an error occurs, then this
     function returns `NULL' and `ut_get_status()' will return
     one of the following:

    `UT_BAD_ARG'
          UNIT is `NULL'.

    `UT_OS'
          Operating-system error.  See `errno' for the reason.

 -- Function: `ut_unit*' ut_offset_by_time `(const ut_unit* const UNIT,
          const double ORIGIN)'
     Returns a timestamp-unit equivalent to the time unit UNIT
     referenced to the time-origin ORIGIN (as returned by `
     ut_encode_time()').  For example:
          const ut_unit*   second = ...
          const ut_unit*   secondsSinceTheEpoch =
              ut_offset_by_time(second, ut_encode_time(1970, 1, 1, 0, 0, 0.0));
     Leap seconds are not taken into account.  You should pass the
     returned pointer to `ut_free()' when you no longer need
     the unit.  If an error occurs, then this function returns `NULL'
     and `ut_get_status()' will return one of the following:

    `UT_BAD_ARG'
          UNIT is `NULL'.

    `UT_OS'
          Operating-system error.  See `errno' for the reason.

    `UT_MEANINGLESS'
          Creation of a timestamp unit based on UNIT is not meaningful.
          It might not be a time-unit, for example.

    `UT_NO_SECOND'
          The associated unit-system doesn't contain a "second" unit.
          See `ut_set_second()'.

     *CAUTION:* The timestamp-unit was created to be analogous to, for
     example, the degree celsius--but for the time dimension.  I've
     come to believe, however, that creating such a unit was a mistake,
     primarily because users try to use the unit in ways for which it
     was not designed (such as converting dates in a calendar whose
     year is exactly 365 days long).  Such activities are much better
     handled by a dedicated calendar package.  Please be careful about
     using timestamp-units.  See also the section on The Handling of Time.

 -- Function: `ut_unit*' ut_invert `(const ut_unit* UNIT)'
     Returns the inverse (i.e., reciprocal) of the unit UNIT.  This
     convenience function is equal to `ut_raise(UNIT,-1).'.
     You should pass the returned pointer to `
     ut_free()' when you no longer need the unit.  If an error occurs,
     then this function writes an error-message using `
     ut_handle_error_message()' and returns `NULL'.  Also, `
     ut_get_status()' will return one of the following:

    `UT_BAD_ARG'
          UNIT is `NULL'.

    `UT_OS'
          Operating-system error. See `errno' for the reason.

 -- Function: `ut_unit*' ut_raise `(const ut_unit* UNIT, int POWER)'
     Returns the unit equal to unit UNIT raised to the power POWER.
     You should pass the returned pointer to `ut_free()' when you no
     longer need the unit.  If an error occurs, then this function
     writes an error-message using `ut_handle_error_message()'
     and returns `NULL'.  Also, `ut_get_status()' will return
     one of the following:

    `UT_BAD_ARG'
          UNIT is `NULL'.

    `UT_OS'
          Operating-system error. See `errno' for the reason.

 -- Function: `ut_unit*' ut_root `(const ut_unit* UNIT, int ROOT)'
     Returns the unit equal to the ROOT root of unit UNIT.  You should
     pass the returned pointer to `ut_free()' when you no longer need
     the unit.  If an error occurs, then this function writes an
     error-message using `ut_handle_error_message()' and
     returns `NULL'.  Also, `ut_get_status()' will return one
     of the following:

    `UT_BAD_ARG'
          UNIT is `NULL'.

    `UT_MEANINGLESS'
          It's meaningless to take the given root of the given unit.
          This could be because the resulting unit would have
          fractional (i.e., non-integral) dimensionality, or because
          the unit is, for example, a logarithmic unit.

    `UT_OS'
          Operating-system error. See `errno' for the reason.

 -- Function: `ut_unit*' ut_log `(double BASE, const ut_unit*
          REFERENCE)'
     Returns the logarithmic unit corresponding to the logarithmic base
     BASE and a reference level specified as the unit REFERENCE.  For
     example, the following creates a decibel unit with a one milliwatt
     reference level:
               const ut_unit* milliWatt = ...;
               const ut_unit* bel_1_mW = ut_log(10.0, milliWatt);

               if (bel_1_mW != NULL) {
                   const ut_unit* decibel_1_mW = See ut_scale.(0.1, bel_1_mW);

                   See ut_free.(bel_1_mW);   /* no longer needed */

                   if (decibel_1_mW != NULL) {
                       /* Have decibel unit with 1 mW reference */
                       ...
                       See ut_free.(decibel_1_mW);
                   }                 /* "decibel_1_mW" allocated */
               }
     You should pass the returned pointer to `ut_free()' when you no
     longer need the unit.  If an error occurs, then this function
     writes an error-message using `ut_handle_error_message()'
     and returns `NULL'.  Also, `ut_get_status()' will return
     one of the following:

    `UT_BAD_ARG'
          REFERENCE is `NULL'.

    `UT_OS'
          Operating-system error. See `errno' for the reason.

    `UT_BAD_ARG'
          BASE is invalid (e.g., it must be greater than one).

 -- Function: `const char*' ut_get_name `(const ut_unit* UNIT,
          ut_encoding ENCODING)'
     Returns the name to which the unit referenced by UNIT maps in the
     character-encoding specified by ENCODING.  If this function
     returns `NULL', then `ut_get_status()' will return one of
     the following:

    `UT_BAD_ARG'
          NAME is `NULL'.

    `UT_SUCCESS'
          UNIT doesn't map to a name in the given character-set.

 -- Function: `const char*' ut_get_symbol `(const ut_unit* UNIT,
          ut_encoding ENCODING)'
     Returns the symbol to which the unit referenced by UNIT maps in the
     character-encoding specified by ENCODING.  If this function
     returns `NULL', then `ut_get_status()' will return one of
     the following:

    `UT_BAD_ARG'
          SYMBOL is `NULL'.

    `UT_SUCCESS'
          UNIT doesn't map to a symbol in the given character-set.

 -- Function: `ut_system*' ut_get_system `(const ut_unit* UNIT)'
     Returns the unit-system to which the unit referenced by UNIT
     belongs.  If UNIT is `NULL', then this function writes an
     error-message using `ut_handle_error_message()' and
     returns `NULL'.  Also, `ut_get_status()' will return
     `UT_BAD_ARG'.

 -- Function: `int' ut_is_dimensionless `(const ut_unit* UNIT)'
     Indicates if unit UNIT is dimensionless (like "radian").  This
     function returns a non-zero value if the unit is dimensionfull;
     otherwise, `0' is returned and ut_get_status() will return
     one of the following:

    `UT_BAD_ARG'
          UNIT1 is `NULL'.

    `UT_SUCCESS'
          The unit is dimensionless.

 -- Function: `ut_unit*' ut_clone `(const ut_unit* UNIT)'
     Returns a copy of the unit referenced by UNIT.  You should pass
     the returned pointer to `ut_free()' when you no longer need the
     unit.  If an error occurs, then this function writes an
     error-message using `ut_handle_error_message()' and
     returns `NULL'.  Also, `ut_get_status()' will return one
     of the following:

    `UT_BAD_ARG'
          UNIT is `NULL'.

    `UT_OS'
          Operating-system failure.  See `errno'.
     If you use `ut_read_xml()', then you should not normally
     need to call this function.

 -- Function: `ut_status' ut_accept_visitor `(const ut_unit*
          UNIT, const ut_visitor.* VISITOR, void*
          ARG)'
     Accepts the visitor VISITOR to the unit UNIT.  The argument ARG is
     passed to the visitor's functions.  This function returns one of
     the following:

    `UT_BAD_ARG'
          VISITOR or UNIT is `NULL'.

    `UT_VISIT_ERROR'
          An error occurred in VISITOR while visiting UNIT.

    `UT_SUCCESS'
          Success.

 -- Data type: ut_visitor int foo(int) int bar(int, int)
     You pass a pointer to a data object of this type if and when you
     call `ut_accept_visitor()'.  It contains the following
     pointers to functions that implement your unit-visitor:

    `ut_status (*visit_basic)(const ut_unit* UNIT, void* ARG);'
          Visits the basic-unit UNIT.  A basic-unit is a base unit like
          "meter" or a non-dimensional but named unit like "radian".
          This function returns `UT_SUCCESS.' on and
          only on success.

    `ut_status (*visit_product)(const ut_unit* UNIT, int COUNT, const ut_unit* const* BASICUNITS, const int* POWERS, void* ARG);'
          Visits the product-unit UNIT.  The product-unit is a product
          of the COUNT basic-units referenced by BASICUNITS, each
          raised to their respective, non-zero power in POWERS.  This
          function returns `UT_SUCCESS.' on and only
          on success.

    `ut_status (*visit_galilean)(const ut_unit* UNIT, double SCALE, const ut_unit* UNDERLYINGUNIT, double ORIGIN, void* arg);'
          Visits the Galilean-unit UNIT.  The Galilean-unit has the
          underlying unit UNDERLYINGUNIT and either the non-unity scale
          factor SCALE or the non-zero origin ORIGIN, or both.  This
          function returns `UT_SUCCESS.' on and only
          on success.

    `ut_status (*visit_timestamp)(const ut_unit* UNIT, const ut_unit* TIMEUNIT, double ORIGIN, void* ARG);'
          Visits the timestamp-unit UNIT.  The timestamp-unit has the
          underlying unit of time TIMEUNIT and the `
          ut_encode_time()'-encoded time-origin ORIGIN.  This
          function returns `UT_SUCCESS.' on and only
          on success.

    `ut_status (*visit_logarithmic)(const ut_unit* UNIT, double BASE, const ut_unit* REFERENCE, void* ARG);'
          Visits the logarithmic-unit UNIT.  The logarithmic-unit has
          the logarithmic base BASE and the reference-level is
          specified by the unit REFERENCE.  This function returns
          `UT_SUCCESS.' on and only on success.

8.2 Binary Unit Operations
==========================

Binary unit operations act on two units.

   *NOTE\:* The functions `ut_are_convertible()' and `
ut_get_converter()' are also binary unit operations but are
documented elsewhere.

 -- Function: `ut_unit*' ut_multiply `(const ut_unit* UNIT1, const
          ut_unit* UNIT2)'
     Returns the result of multiplying unit UNIT1 by unit UNIT2.  You
     should pass the pointer to ut_free() when you no longer
     need the unit On failure, this function returns `NULL' and
     ut_get_status() will return one of the following:

    `UT_BAD_ARG'
          UNIT1 or UNIT2 is `NULL'.

    `UT_NOT_SAME_SYSTEM'
          UNIT1 and UNIT2 belong to different unit-systems.

    `UT_OS'
          Operating-system error. See ERRNO for the reason.

 -- Function: `ut_unit*' ut_divide `(const ut_unit* NUMER, const
          ut_unit* DENOM)'
     Returns the result of dividing unit NUMER by unit DENOM.  You
     should pass the pointer to ut_free() when you no longer
     need the unit On failure, this function returns `NULL' and
     ut_get_status() will return one of the following:

    `UT_BAD_ARG'
          NUMER or DENOM is `NULL'.

    `UT_NOT_SAME_SYSTEM'
          UNIT1 and UNIT2 belong to different unit-systems.

    `UT_OS'
          Operating-system error. See `errno' for the reason.

 -- Function: `int' ut_compare `(const ut_unit* UNIT1, const ut_unit*
          UNIT2)'
     Compares two units.  Returns a value less than, equal to, or
     greater than zero as UNIT1 is considered less than, equal to, or
     greater than UNIT2, respectively.  Units from different
     unit-systems never compare equal.  The value zero is also
     returned if both unit pointers are `NULL'.

 -- Function: `int' ut_same_system `(const ut_unit* UNIT1, const
          ut_unit* UNIT2)'
     Indicates if two units belong to the same unit-system.  This
     function returns a non-zero value if the two units belong to the
     same unit-system; otherwise, `0' is returned and
     ut_get_status() will return one of the following:

    `UT_BAD_ARG'
          UNIT1 or UNIT2 is `NULL'.

    `UT_SUCCESS'
          The units belong to different unit-systems.

9 Mapping Between Identifiers and Units
***************************************

Within a unit-system, you can map an identifier to a unit and vice
versa.  If an identifier maps to a unit, then the unit can be retrieved
from the unit-system via the identifier.  Similarly, if a unit maps to
an identifier, then the unit can be printed using the identifier.

   There a two kinds of identifiers: names and symbols.

9.1 Names
=========

You can map a name to a unit and vice versa.  If you use `
ut_read_xml()', then you shouldn't normally need to do this.

 -- Function: `ut_status' ut_map_name_to_unit `(const char*
          NAME, const ut_encoding ENCODING, const ut_unit* UNIT)'
     Maps the name referenced by NAME, in character-set ENCODING, to
     the unit referenced by UNIT in the unit-system that contains UNIT.
     This function returns one of the following:

    `UT_SUCCESS'
          Success.

    `UT_BAD_ARG'
          NAME or UNIT is `NULL'.

    `UT_OS'
          Operating-system failure.  See `errno'.

    `UT_EXISTS'
          NAME already maps to a different unit.

 -- Function: `ut_status' ut_unmap_name_to_unit `(ut_system*
          SYSTEM, const char* NAME, const ut_encoding ENCODING)'
     Removes any mapping from name NAME, in character-set ENCODING, to
     a unit in unit-system SYSTEM.  This function returns one of the
     following:

    `UT_SUCCESS'
          Success.

    `UT_BAD_ARG'
          SYSTEM or NAME is `NULL'.

 -- Function: `ut_status' ut_map_unit_to_name `(const ut_unit*
          UNIT, const char* NAME, ut_encoding ENCODING)'
     Maps the unit UNIT to the name NAME, which is in character-set
     ENCODING, in the unit-system that contains the unit.  This
     function returns one of the following:

    `UT_SUCCESS'
          Success.

    `UT_BAD_ARG'
          UNIT or NAME is `NULL', or NAME is not in the character-set
          ENCODING.

    `UT_OS'
          Operating-system failure.  See `errno'.

    `UT_EXISTS'
          UNIT already maps to a different name.

 -- Function: `ut_status' ut_unmap_unit_to_name `(const
          ut_unit* UNIT, ut_encoding ENCODING)'
     Removes any mapping from unit UNIT to a name in character-set
     ENCODING from the unit-system that contains the unit.  This
     function returns one of the following:

    `UT_SUCCESS'
          Success.

    `UT_BAD_ARG'
          UNIT is `NULL'.

9.2 Symbols
===========

You can map a symbol to a unit and vice versa.  If you use `
ut_read_xml()', then you shouldn't normally need to do this.

 -- Function: `ut_status' ut_map_symbol_to_unit `(const char*
          SYMBOL, const ut_encoding ENCODING, const ut_unit* UNIT)'
     Maps the symbol referenced by SYMBOL, in character-set ENCODING,
     to the unit referenced by UNIT in the unit-system that contains
     UNIT.  This function returns one of the following:

    `UT_SUCCESS'
          Success.

    `UT_BAD_ARG'
          SYMBOL or UNIT is `NULL'.

    `UT_OS'
          Operating-system failure.  See `errno'.

    `UT_EXISTS'
          SYMBOL already maps to a different unit.

 -- Function: `ut_status' ut_unmap_symbol_to_unit `(ut_system*
          SYSTEM, const char* SYMBOL, const ut_encoding ENCODING)'
     Removes any mapping from symbol SYMBOL, in character-set ENCODING,
     to a unit in unit-system SYSTEM.  This function returns one of the
     following:

    `UT_SUCCESS'
          Success.

    `UT_BAD_ARG'
          SYSTEM or SYMBOL is `NULL'.

 -- Function: `ut_status' ut_map_unit_to_symbol `(const
          ut_unit* UNIT, const char* SYMBOL, ut_encoding ENCODING)'
     Maps the unit UNIT to the symbol SYMBOL, which is in character-set
     ENCODING, in the unit-system that contains the unit.  This
     function returns one of the following:

    `UT_SUCCESS'
          Success.

    `UT_BAD_ARG'
          UNIT or SYMBOL is `NULL'.

    `UT_BAD_ARG'
          Symbol SYMBOL is not in the character-set ENCODING.

    `UT_OS'
          Operating-system failure.  See `errno'.

    `UT_EXISTS'
          UNIT already maps to a different symbol.

 -- Function: `ut_status' ut_unmap_unit_to_symbol `(const
          ut_unit* UNIT, ut_encoding ENCODING)'
     Removes any mapping from unit UNIT to a symbol in character-set
     ENCODING from the unit-system that contains the unit.  This
     function returns one of the following:

    `UT_SUCCESS'
          Success.

    `UT_BAD_ARG'
          UNIT is `NULL'.

10 The Handling of Time
***********************

You should use a true calendar package rather than the UDUNITS-2 package
to handle time.  Having said that, many people use the time-handling
capabilities of the UDUNITS-2 package because it supports "units" like
"`seconds since 1970-01-01'".  You should be aware, however, that the
hybrid Gregorian/Julian calendar used by the UDUNITS-2 package _cannot
be changed_.  Dates on or after 1582-10-15 are assumed to be Gregorian
dates; dates before that are assumed to be Julian dates.  In particular,
the year 1 BCE is immediately followed by the year 1 CE.

   In general, the UDUNITS-2 package handles time by encoding it as
double-precision value, which can then be acted upon arithmetically.

 -- Function: `double' ut_encode_time `(int YEAR, int MONTH, int DAY,
          int HOUR, int MINUTE, double SECOND)'
     Encodes a time as a double-precision value.  This convenience
     function is equivalent to
          See ut_encode_date.(YEAR,MONTH,DAY) + See ut_encode_clock.(HOUR,MINUTE,SECOND)

 -- Function: `double' ut_encode_date `(int YEAR, int MONTH, int DAY)'
     Encodes a date as a double-precision value.  You probably won't
     use this function.  Dates on or after 1582-10-15 are assumed to be
     Gregorian dates; dates before that are assumed to be Julian dates.
     In particular, the year 1 BCE is immediately followed by the year
     1 CE.

 -- Function: `double' ut_encode_clock `(int HOUR, int MINUTE, double
          SECOND)'
     Encodes a clock-time as a double-precision value.  You probably
     won't use this function.

 -- Function: `void' ut_decode_time `(double TIME, int* YEAR, int*
          MONTH, int* DAY, int* HOUR, int* MINUTE, double* SECOND,
          double* RESOLUTION)'
     Decodes a time from a double-precision value into its individual
     components.  The variable referenced by RESOLUTION will be set to
     the resolution (i.e., uncertainty) of the time in seconds.

11 Error Handling
*****************

Error-handling in the units module has two aspects: the status of the
last operation performed by the module and the handling of
error-messages:

11.1 Status of Last Operation
=============================

UDUNITS-2 functions set their status by calling `
ut_set_status()'.  You can use the function `ut_get_status()'
to retrieve that status.

 -- Function: `ut_status' ut_get_status `(void)'
     Returns the value specified in the last call to `
     ut_set_status()'

 -- Function: `void' ut_set_status `(see ut_status STATUS)'
     Set the status of the units module to STATUS.

 -- Data type: ut_status
     This enumeration has the following values:

    `UT_SUCCESS'
          Success

    `UT_BAD_ARG'
          An argument violates the the function's contract (e.g., it's
          `NULL').

    `UT_EXISTS'
          Unit, prefix, or identifier already exists

    `UT_NO_UNIT'
          No such unit exists

    `UT_OS'
          Operating-system error.  See `errno' for the reason.

    `UT_NOT_SAME_SYSTEM'
          The units belong to different unit-systems

    `UT_MEANINGLESS'
          The operation on the unit or units is meaningless

    `UT_NO_SECOND'
          The unit-system doesn't have a unit named "second"

    `UT_VISIT_ERROR'
          An error occurred while visiting a unit

    `UT_CANT_FORMAT'
          A unit can't be formatted in the desired manner

    `UT_SYNTAX'
          String unit representation contains syntax error

    `UT_UNKNOWN'
          String unit representation contains unknown word

    `UT_OPEN_ARG'
          Can't open argument-specified unit database

    `UT_OPEN_ENV'
          Can't open environment-specified unit database

    `UT_OPEN_DEFAULT'
          Can't open installed, default, unit database

    `UT_PARSE'
          Error parsing unit database

11.2 Error-Messages
===================

 -- Function: `int' ut_handle_error_message `(const char* FMT, ...)'
     Handles the error-message corresponding to the format-string FMT
     and any subsequent arguments referenced by it.  The interpretation
     of the formatting-string is identical to that of the UNIX function
     `printf()'.  On success, this function returns the number of bytes
     in the error-message; otherwise, this function returns `-1'.

     Use the function `ut_set_error_message_handler()' to
     change how error-messages are handled.

 -- Function: `ut_error_message_handler'
ut_set_error_message_handler `(see ut_error_message_handler
          HANDLER)'
     Sets the function that handles error-messages and returns the
     previous error-message handler.  The initial error-message handler
     is `ut_write_to_stderr()'.

 -- Function: `int' ut_write_to_stderr `(const char* FMT, va_list ARGS)'
     Writes the variadic error-message corresponding to
     formatting-string FMT and arguments ARGS to the standard-error
     stream and appends a newline.  The interpretation of the
     formatting-string is identical to that of the UNIX function
     `printf()'.  On success, this function returns the number of bytes
     in the error-message; otherwise, this function returns `-1'.

 -- Function: `int' ut_ignore `(const char* FMT, va_list ARGS)'
     Does nothing.  In particular, it ignores the variadic error-message
     corresponding to formatting-string FMT and arguments ARGS.  Pass
     this function to `ut_set_error_message_handler()' when you
     don't want the unit module to print any error-messages.

 -- Data type: ut_error_message_handler
     This is the type of an error-message handler.  It's definition is
          typedef int (*ut_error_message_handler)(const char* fmt, va_list args);

12 The Units Database
*********************

The database of units that comes with the UDUNITS-2 package is an
XML-formatted file that is based on the SI system of units.  It
contains the names and symbols of most of the units that you will ever
encounter.  The pathname of the installed file is
`_datadir_/udunits2.xml', where _datadir_ is the installation-directory
for read-only, architecture-independent data (e.g., `/usr/local/share').
This pathname is the default that `ut_read_xml()' uses.

   Naturally, because the database is a regular file, it can be edited
to add new units or remove existing ones.  Be very careful about doing
this, however, because you might lose the benefit of exchanging
unit-based information with others who haven't modified their database.

13 Data Types
*************

The data types `ut_visitor', `ut_status', and `
ut_error_message_handler' are documented elsewhere.

 -- Data type: ut_encoding
     This enumeration has the following values:

    `UT_ASCII'
          US ASCII (http://en.wikipedia.org/wiki/Ascii) character-set.

    `UT_ISO_8859_1'
          The ISO-8859-1 (http://en.wikipedia.org/wiki/Iso-8859-1)
          character-set.

    `UT_LATIN1'
          Synonym for `UT_ISO_8859_1'.

    `UT_UTF8'
          The UTF-8 (http://en.wikipedia.org/wiki/Utf-8) encoding of
          the Unicode character-set.