UnitMap.h

Physical units are strings consisting of one or more names of known basic units, separated by '.' or ' ' (for multiplication) or '/' (for division). Each name can optionally be preceded by a standard decimal prefix, and/or followed by an (optionally signed) exponent. Example: km/s/(Mpc.s)2 is identical to km.s-1.Mpc-2.s-2

See the Unit class for more details.

The UnitMap class contains the known standard basic units, and any other basic unit defined by the user of the Unit related classes. The known units are divided into 5 different groups:

Defining units: m, kg, s, A, K, cd, mol, rad, sr, _
SI units: including a.o. Jy, AU etc)
Customary units: e.g. lb, hp, ly etc
User defined units: defined by user (e.g. Beam, KPH, KM)
Cached units: cached unit strings for speed in operations

The full list of known units can be viewed by running the tUnit test program.

There is a difference between units without a dimension (non-dimensioned I will call them), and undimensioned units. Non-dimensioned examples are "", "%"; undimensioned examples: "beam", "pixel".

Information about the contents of the unit maps can be obtained by the Bool functions (False if not present):

UnitMap::getPref("string", UnitName &) prefix
UnitMap::getUnit("string", UnitName &) search user, customary, SI (in that order)
UnitMap::getCache("string", UnitVal &) search cache

The standard units can be viewed by the following commands, which output to cout:

UnitMap::list() all prefixes and SI, Cust and User units
UnitMap::listCache() current cache contents
UnitMap::listPref() all prefixes
UnitMap::listDef() all defining units
UnitMap::listSI() all SI Units
UnitMap::listCust() all customary units
UnitMap::listUser() all user defined units

Units can be defined in the user list by:

The cache will be cleared if a user defined unit is overwritten, to make sure no old value will be used.

    UnitMap::putUser("tag", UnitVal(factor,"unit"), "full name (optional)");
       or:
    UnitMap::putUser(UnitName);

If using an explicit Unit variable (e.g. Unit a("5Bolton/beam")), the check on the legality of the given string, and the conversion to the cached canonical value in the variable 'a', is only done at creation time. This means that if the user changes the value of a unit involved by the putUser() method, the unit using it should be re-created ( a = Unit("5Bolton/beam");).

A special set of 'units' used in FITS datasets can be added by the command

	UnitMap::addFITS();

This set can be cleared from the user table by:

	UnitMap::clearFITS();

Note that Unitmap keeps track of the inclusion of the FITS inclusion, making multiple calls inexpensive. The list of current FITS units can be viewed by running the tUnit program, or looking at the FITSunit table.

Once the UnitMap::addFITS() has been run, the FITS units can be used as any other unit. In addition, a FITS unit can be translated to standard SI units by a call to Unit UnitMap::fromFITS(const Unit). Any unit that is defined as a standard FITS unit will be translated. Unknown ones will not be translated, making the way clear for having standard units in a FITS units string. A comparable toFITS() translates in the same way in the reversed direction.

The cache can be cleared by:

    UnitMap::clearCache();

Example

Check for legal prefix:

	UnitName myUnit;
	if (UnitMap::getPref("k", myUnit)) { cout << "k has value " << myUnit;}

Define a value for the unit 'beam':

    UnitMap::putUser("beam",UnitVal(C::pi * 0.1, "\"_2"),"telescope beam");

List current cache:

    UnitMap::listCache();

Motivation

Standard list available to try to enhance use of SI and related units

To Do

Some inlining (did not work first go)

Member Description

UnitMap()

Default constructor of maps

~UnitMap()

Destructor

static Bool getPref(const String &s, UnitName &name)

Check if a unit name is known, and return its value if True

Get a prefix definition from key

static Bool getCache(const String &s, UnitVal &val)

Check if a unit name is known, and return its value if True

Get a cached definition

static Bool getUnit(const String &s, UnitName &name)

Check if a unit name is known, and return its value if True

Get a standard unit definition (search order: User, Customary, SI)

static void putCache(const String &s, const UnitVal &val)

Save a definition of a full unit name in the cache (the cache will be cleared if getting too large (200 entries)

static void putUser(const String &s, const UnitVal &val)
static void putUser(const String &s, const UnitVal &val, const String &name)
static void putUser(const UnitName &name)

Define a user defined standard unit. If the unit is being redefined, and it has already been used in a user's Unit variable, the value cached in that variable will not change.

static void removeUser(const String &name)
static void removeUser(const UnitName &name)

Remove a user unit

static void clearCache()

Clear out the cache

static void addFITS()

Define FITS related unit names

static void clearFITS()

Clear FITS related units from user list

static Unit fromFITS(const Unit &un)

Translate a FITS unit to the proper units. Note that this is a translation of the string only, no conversion. Unknown FITS units are not translated. Hence any new definition of the FITS units will work ok