cf.FieldAncillary.match_by_units

FieldAncillary.match_by_units(*units, exact=True)[source]

Whether or not the construct has given units.

New in version 3.0.0.

See also

match, match_by_identity, match_by_property, match_by_naxes

Parameters
units: optional

Units to be compared.

Units are specified by a string or compiled regular expression (e.g. 'km', 'm s-1', re.compile('^kilo'), etc.) or a Units object (e.g. Units('km'), Units('m s-1'), etc.).

If no units are provided then there is always a match.

exact: bool, optional

If False then a match occurs if the construct’s units are equivalent to any of those given by units. For example, metres and are equivelent to kilometres. By default, a match only occurs if the construct’s units are exactly one of those given by units. Note that the format of the units is not important, i.e. ‘m’ is exactly the same as ‘metres’ for this purpose.

Returns
bool

Whether or not there is a match.

Examples:

>>> f.units
'metres'
>>> f.match_by_units('metres')
True
>>> f.match_by_units('m')
True
>>> f.match_by_units(Units('m'))
True
>>> f.match_by_units('m', 'kilogram')
True
>>> f.match_by_units('km', exact=False)
True
>>> f.match_by_units(cf.Units('km'), exact=False)
True
>>> f.match_by_units(re.compile('^met'))
True
>>> f.match_by_units(cf.Units('km'))
False
>>> f.match_by_units(cf.Units('kg m-2'))
False