Header Units.h

Detailed Description

Provides prototypes for manipulation of units and declares extern constants for the basic and derived SI units.

Author

J. T. Whelan john..nosp@m.whel.nosp@m.an@li.nosp@m.go.o.nosp@m.rg

Synopsis

#include <lal/Units.h>

This header provides prototypes for functions to manipulate the LALUnit structure. It also defines extern constants for a set of predefined units, which are designed to make the structure easier to use. For instance, to determine whether a quantity has units of strain per root hertz, one constructs the unit "strain per root hertz" from the predefined lalStrainUnit and lalHertzUnit constant structures using the XLALUnitRaiseRAT4() and XLALUnitMultiply() functions, then compares that to the unit structure in question using the XLALUnitCompare() function.

The LALUnit datatype itself is included in the header LALDatatypes.h, and defines a unit in terms of an integer power of ten multiplier along with rational powers of the basic SI units (meters, kilograms, seconds, Amperes, and Kelvins) and two custom units (strain and ADC counts).

XLAL interface to Units.h functions

XLALUnitAsString() converts a LALUnit structure into a character string of maximum length length (including NUL termination) representation of the units. The inverse function, XLALParseUnitString() parses a character string to produce a LALUnit structure; if output is NULL, memory for the output is allocated. If the input string is NULL or is empty then the output units are dimensionless: lalDimensionlessUnit.

XLALUnitNormalize() puts a LALUnit structure into normal form by simplifying all unit exponent fractions to their simplest form.

XLALUnitCompare() compares two LALUnit structures: they are the same if their normal forms are identical.

XLALUnitMultiply() multiplies two LALUnit structures. The result is put into normal form.

XLALUnitRaiseRAT4() raises a LALUnit structure to a rational power given by the RAT4 structure power. XLALUnitRaiseINT2() raises a LALUnit structure to an integer power power. XLALUnitSquare() produces the square of a LALUnit structure. XLALUnitSqrt() produces the square-root of a LALUnit structure.

Return Values

XLALUnitAsString() returns the pointer to the input string, which is populated with the unit string if successful. If there is a failure, XLALUnitAsString() returns a NULL pointer and xlalErrno is set to one of the following values: XLAL_EFAULT if one of the input pointers is NULL or XLAL_EBADLEN if the length of the string is insufficent for the unit string.

XLALParseUnitString() returns the pointer output upon return or a pointer to newly allocated memory if output was NULL; on failure, XLALParseUnitString returns NULL and sets xlalErrno to one of the following values: XLAL_ENOMEM if the routine was unable to allocate memory for the output or XLAL_EFAILED if the routine was unable to parse the unit string.

XLALUnitNormalize() returns 0 upon success or XLAL_FAILURE if the input pointer is NULL, in which case xlalErrno is set to XLAL_EFAULT

XLALUnitCompare() returns 0 if the the normal form of the two unit structures are the same or > 0 if they are different. It returns XLAL_FAILURE and xlalErrno is set to XLAL_EFAULT if one of the input pointers is NULL.

XLALUnitMultiply(), XLALUnitRaiseRAT4(), XLALUnitRaiseINT2(), XLALUnitSquare() and XLALUnitSqrt() all return a pointer to the output unit structure output upon success or NULL upon failure. If there is a failure, xlalErrno is set to one of the following values: XLAL_EFAULT if one of the input pointers is NULL, XLAL_ERANGE if one of the unit powers exceeds the allowed range, or XLAL_EINVAL (for the raise functions only) if the unit power would not be an integer.

Modules
	Module UnitDefs.c
	Defines basic and derived SI units and a function to produce a text string corresponding to a unit structure.
	Module UnitNormalize.c
	Brings an LALUnit structure into standard form by reducing all of the rational exponents into LCD form.
	Module UnitRaise.c
	Raises an LALUnit structure to a specified rational power.
	Module UnitMultiply.c
	Multiplies two LALUnit structures.
	Module UnitCompare.c
	Function to compare two LALUnit structures.

Files
file	UnitsTest.c
	Test Suite for unit manipulation programs.