# Unitted Functions¶

A function which handles UnitArrays and UnitScalars is a unitted function. Unitted functions are created with the has_units() decorator. The units can be specified by passing arguments to the decorator or by constructing a special docstring.

## Decorator arguments¶

from numpy import array
from scimath.units.api import has_units
from scimath.units.length import feet, meter
@has_units(inputs="a:an array:units=ft;b:array:units=ft",
outputs="result:an array:units=m")
""" Add two arrays in ft and convert them to m.

"""
return (a + b) * feet / meter

To use has_units with decorator arguments, pass string arguments “inputs” and (optionally) “outputs”. See the has_units() docstring or visit the User Reference page for details on the syntax.

## Formatted docstring¶

from scimath.units.api import has_units, UnitArray
@has_units
""" Add two arrays in ft and convert them to m.

Parameters
----------
a : array : units=ft
An array
b : array : units=ft
Another array

Returns
-------
c : array : units=m
c = a + b
"""
return (a + b) * feet / meter

Using the has_units decorator with a docstring has the benefit of using a ReST-compatible format, so the unitting specification doubles as a documentation entry. See the has_units() docstring or visit the User Reference page for details on the syntax. The example above produces the following documentation entry when built with Sphinx:

## Unitted function output¶

In the examples above, we told add() to expect two values, a and b and convert them to feet for use in the function. Then we specified that the output would be in meters. Inside the function, a and b are not unitted, and the function is responsible for the conversion. (Remember our caveat regarding conversion factors.)

Unitted functions can accept either regular Python objects (of the appropriate type) or the equivalent unitted objects. The return type depends on what it was passed.

0.9144000000000001

In this case, add() accepted two integer arguments in feet, added them and returned an integer value in meters.