cfunits.Units.formatted

Units.formatted(names=None, definition=None)[source]

Formats the units attribute string in a standardised way.

The units attribute is modified in place and its new value is returned.

Parameters
names: bool, optional

Use unit names instead of symbols.

definition: bool, optional

The formatted string is given in terms of basic units instead of stopping any expansion at the highest level possible.

Returns
str or None

The formatted string. If the units have not yet been set, then None is returned.

Examples

>>> u = Units('W')
>>> u.units
'W'
>>> u.formatted(names=True)
'watt'
>>> u.formatted(definition=True)
'm2.kg.s-3'
>>> u.formatted(names=True, definition=True)
'meter^2-kilogram-second^-3'
>>> u.formatted()
'W'

>>> u = Units('dram')
>>> u.formatted(names=True)
'0.001771845 kilogram'

>>> u = Units('hours since 2100-1-1', calendar='noleap')
>>> u.formatted(names=True)
'hour since 2100-01-01 00:00:00'
>>> u.formatted()
'h since 2100-01-01 00:00:00'

Formatting is also available during object initialization:

>>> u = Units('m/s', formatted=True)
>>> u.units
'm.s-1'

>>> u = Units('dram', names=True)
>>> u.units
'0.001771845 kilogram'

>>> u = Units('Watt')
>>> u.units
'Watt'

>>> u = Units('Watt', formatted=True)
>>> u.units
'W'

>>> u = Units('Watt', names=True)
>>> u.units
'watt'

>>> u = Units('Watt', definition=True)
>>> u.units
'm2.kg.s-3'

>>> u = Units('Watt', names=True, definition=True)
>>> u.units
'meter^2-kilogram-second^-3'