units.h File Reference

Defines units used for items in the stream, most notably time units that reference an epoch and a step size. More...

#include <stdbool.h>
#include <das2/time.h>

Include dependency graph for units.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef const char *	das_units
	Handle SI and other units, with accommodations for Epoch systems, from units.h. More...

Functions
DAS_API char *	Units_toLabel (das_units unit, char *sBuf, int nLen)
	Get label string representation das_units. More...
DAS_API das_units	Units_invert (das_units unit)
	Invert the units, most commonly used for Fourier transform results. More...
DAS_API das_units	Units_multiply (das_units ut1, das_units ut2)
	Combine units via multiplication. More...
DAS_API das_units	Units_divide (das_units a, das_units b)
	Combine units via division. More...
DAS_API das_units	Units_power (das_units unit, int power)
	Raise units to a power. More...
DAS_API das_units	Units_root (das_units unit, int root)
	Reduce units to a root. More...
DAS_API das_units	Units_interval (das_units unit)
	Get the unit type for intervals between data points of a given unit type. More...
DAS_API das_units	Units_reduce (das_units orig, double *pFactor)
	Reduce arbitrary units to the most basic know representation. More...
DAS_API bool	Units_canConvert (das_units fromUnits, das_units toUnits)
	Determine if given units are interchangeable Though not as good a solution as using UDUNITS2 works for common space physics quantities as well as SI units. More...
DAS_API double	Units_convertTo (das_units toUnits, double rVal, das_units fromUnits)
	Generic unit conversion utility. More...
DAS_API bool	Units_haveCalRep (das_units unit)
	Determine if the units in question can be converted to date-times. More...
DAS_API void	Units_convertToDt (das_time *pDt, double value, das_units epoch_units)
	Convert a value in time offset units to a calendar representation. More...
DAS_API double	Units_convertFromDt (das_units epoch_units, const das_time *pDt)
	Convert a calendar representation of a time to value in time offset units. More...
DAS_API double	Units_secondsSinceMidnight (double rVal, das_units epoch_units)
	Get seconds since midnight for some value of an epoch time unit. More...
DAS_API bool	Units_canMerge (das_units left, int op, das_units right)
	Determine if the units of values in a binary expression are compatible. More...

Detailed Description

Defines units used for items in the stream, most notably time units that reference an epoch and a step size.

Function Documentation

Units_toLabel()

DAS_API char* Units_toLabel	(	das_units	unit,
		char *	sBuf,
		int	nLen
	)

Get label string representation das_units.

This function inserts formatting characters into the unit string returned by Units_toStr(). The resulting output is suitable for use in Das2 labels For example if Units_toStr() returns:

V**2 m**-2 Hz**-1

this function would generate the string

V!a2!n m!a-2!n Hz!a-1!n

Units that are an offset from some UTC time merely return "UTC"

Parameters

unit	the unit object to convert to a label
sBuf	a buffer to hold the UTF-8 label string
nLen	the length of the buffer pointed to by sBuf

Returns

a pointer to sBuf, or NULL if nLen was too short to hold the label, or if the name contains a trailing '_' or there was more than one '_' characters in a unit name.

Units_invert()

DAS_API das_units Units_invert

(

das_units

unit

)

Invert the units, most commonly used for Fourier transform results.

Create the corresponding inverted unit from a given unit. For example seconds become Hz, milliseconds become kHz and so on. This function does not product the same output as calling:

Units_exponentiate(unit, -1, 1);

because a special lookup table is used for converting s**-1 (and related) values to Hertz.

For all other unit types, calling this function is equivalent to calling Units_exponentiate(unit, -1, 1)

Warning This function is not multi-thread safe. It alters global library state data

Parameters

unit	the input unit to invert

Returns

the inverted unit

Units_multiply()

DAS_API das_units Units_multiply	(	das_units	ut1,
		das_units	ut2
	)

Combine units via multiplication.

Examples:

Precondition

A, B -> A B

A, A -> A**2

kg m**2 s**-1, kg**-1 -> m**2 s**-1

Parameters

ut1	the first unit object
ut2	the second uint object

Returns

A new unit type which is the product of a and b.

Units_divide()

DAS_API das_units Units_divide	(	das_units	a,
		das_units	b
	)

Combine units via division.

This is just a convenience routine that has the effect of calling:

Units_multiply( a, Units_power(b, -1) );

Parameters

a	the numerator units
b	the denominator units

Returns

A new unit type which is the quotient of a divided by b

Units_power()

DAS_API das_units Units_power	(	das_units	unit,
		int	power
	)

Raise units to a power.

To invert a unit use the power -1.

For units following the canonical pattern:

A**n B**m

A new inverted unit:

A**-n B**-m

is produced.

Units_root()

DAS_API das_units Units_root	(	das_units	unit,
		int	root
	)

Reduce units to a root.

Use this to reduce units to a integer root, for example:

Units_root( "m**2", 2 ) --> "m" Units_root( "nT / cm**2" ) --> "nT**1/2 cm**-1"

Parameters

unit	The input unit
root	A positive integer greater than 0

Returns

the new unit.

Units_interval()

DAS_API das_units Units_interval

(

das_units

unit

)

Get the unit type for intervals between data points of a given unit type.

This is confusing, but basically some data points, such as calendar times and various other Das epoch based values cannot represent differences, only absolute positions. Use this to get the unit type of the subtraction of two points.

For example the units of 2017-10-14 UTC - 2017-10-13 UTC is seconds.

Parameters

unit	The unit type for which the difference type is desired

Returns

the interval unit type. Basic units such as meters have no standard epoch and thus they are just their own interval type.

Units_reduce()

DAS_API das_units Units_reduce	(	das_units	orig,
		double *	pFactor
	)

Reduce arbitrary units to the most basic know representation.

Units such as days can be represented as 86400 seconds, likewise units such as km**2 can be represented as 10e6 m**2. Use this function to reduce units to the most basic type known by this library and return the scaling factor that would be needed to convert data in the given units to the reduced units.

This handles all SI units (except candela) and allows for metric prefix names on arbitrary items, but not metric prefix symbols on arbitrary unit tyes. For example 'microcows' are reduced to '1e-6 cows', but 'μcows' are not converted to 'cows'.

Parameters

[in]	orig	the original unit type
[out]	pFactor	a pointer to a double which will hold the scaling factor, for units that are already in the most basic form this factor is 1.0.

Returns

the new UnitType, which may just be the old unit type if the given units are already in their most basic form

Units_canConvert()

DAS_API bool Units_canConvert	(	das_units	fromUnits,
		das_units	toUnits
	)

Determine if given units are interchangeable Though not as good a solution as using UDUNITS2 works for common space physics quantities as well as SI units.

Units are convertible if:

1. They are both known time offset units.
2. They have a built in conversion factor (ex: 1 day = 24 hours)
3. Both unit sets use SI units, including Hz
4. When reduced to base units the exponents of each unit are the same.

Units_convertTo()

DAS_API double Units_convertTo	(	das_units	toUnits,
		double	rVal,
		das_units	fromUnits
	)

Generic unit conversion utility.

Parameters

toUnits	The new units that the value should be represented in
rVal	The value to convert, to get a conversion factor from one unit type to another set this to 1.0.
fromUnits	The original units of the value

Note

: Thanks Wikipedia. This code incorporates the algorithm on page http://en.wikipedia.org/wiki/Julian_day

Units_haveCalRep()

DAS_API bool Units_haveCalRep

(

das_units

unit

)

Determine if the units in question can be converted to date-times.

If this function returns true, then the following functions may be used on this unit type:

Units_convertToDt() Units_convertFromDt() Units_secondsSinceMidnight() Units_getJulianDay()

Furthermore a call to Units_interval() returns a different unittype then the given units.

Parameters

unit	The units to check possible mapping to calendar dates.

Units_convertToDt()

DAS_API void Units_convertToDt	(	das_time *	pDt,
		double	value,
		das_units	epoch_units
	)

Convert a value in time offset units to a calendar representation.

Parameters

[out]	pDt	a pointer to a das_time structure to receive the broken down time.
[in]	value	the double value representing time from the epoch in some scale
[in]	epoch_units	Unit string

Units_convertFromDt()

DAS_API double Units_convertFromDt	(	das_units	epoch_units,
		const das_time *	pDt
	)

Convert a calendar representation of a time to value in time offset units.

Parameters

epoch_units	The units associated with the return value
pDt	the calendar time object from which to derive the value

Returns

the value as a floating point offset from the epoch associated with epoch_units, or DAS_FILL_VALUE on an error

Units_secondsSinceMidnight()

DAS_API double Units_secondsSinceMidnight	(	double	rVal,
		das_units	epoch_units
	)

Get seconds since midnight for some value of an epoch time unit.

Parameters

rVal	the value of the epoch time
epoch_units	so type of epoch time unit.

Returns

the number of floating point second since midnight

Units_canMerge()

DAS_API bool Units_canMerge	(	das_units	left,
		int	op,
		das_units	right
	)

Determine if the units of values in a binary expression are compatible.

Parameters

right
op
left

Returns