cf.DomainAncillary.match_by_units

DomainAncillary.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: str or re.Pattern or Units, optional

Units to be compared.

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

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 equivalent 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