# Manipulating units

## Unitful string macro

`Unitful.@u_str`

— Macro`@u_str(unit)`

String macro to easily recall units, dimensions, or quantities defined in unit modules that have been registered with `Unitful.register`

.

If the same symbol is used for a `Unitful.Units`

object defined in different modules, then the symbol found in the most recently registered module will be used.

Note that what goes inside must be parsable as a valid Julia expression. In other words, `u"N m"`

will fail if you intended to write `u"N*m"`

.

Examples:

```
julia> 1.0u"m/s"
1.0 m s^-1
julia> 1.0u"N*m"
1.0 m N
julia> u"m,kg,s"
(m, kg, s)
julia> typeof(1.0u"m/s")
Quantity{Float64, 𝐋 𝐓^-1, Unitful.FreeUnits{(m, s^-1), 𝐋 𝐓^-1, nothing}}
julia> u"ħ"
1.0545718176461565e-34 J s
```

`Unitful.register`

— Function`register(unit_module::Module)`

Makes Unitful aware of units defined in a new unit module, including making the `@u_str`

macro work with these units. By default, Unitful is itself a registered module. Note that Main is not, so if you define new units at the REPL, you will probably want to do `Unitful.register(Main)`

.

Example:

```
# somewhere in a custom units package...
module MyUnitsPackage
using Unitful
function __init__()
...
Unitful.register(MyUnitsPackage)
end
end #module
```

## Dimension and unit inspection

We define a function `dimension`

that turns, for example, `acre^2`

or `1*acre^2`

into `𝐋^4`

. We can usually add quantities with the same dimension, regardless of specific units (`FixedUnits`

cannot be automatically converted, however). Note that dimensions cannot be determined by powers of the units: `ft^2`

is an area, but so is `ac^1`

(an acre).

There is also a function `unit`

that turns, for example, `1*acre^2`

into `acre^2`

. You can then query whether the units are `FreeUnits`

, `FixedUnits`

, etc.

`Unitful.unit`

— Function```
unit(x::Quantity{T,D,U}) where {T,D,U}
unit(x::Type{Quantity{T,D,U}}) where {T,D,U}
```

Returns the units associated with a `Quantity`

or `Quantity`

type.

Examples:

```
julia> unit(1.0u"m") == u"m"
true
julia> unit(typeof(1.0u"m")) == u"m"
true
```

`unit(x::Number)`

Returns the `NoUnits`

object to indicate that ordinary numbers have no units. The unit is displayed as an empty string.

Examples:

```
julia> typeof(unit(1.0))
Unitful.FreeUnits{(), NoDims, nothing}
julia> typeof(unit(Float64))
Unitful.FreeUnits{(), NoDims, nothing}
julia> unit(1.0) == NoUnits
true
```

```
unit(x::Dates.FixedPeriod)
unit(x::Type{<:Dates.FixedPeriod})
```

Return the units that correspond to a particular period.

**Examples**

```
julia> unit(Second(15)) == u"s"
true
julia> unit(Hour) == u"hr"
true
```

`Unitful.dimension`

— Function`dimension(x::Unit)`

Returns a `Unitful.Dimensions`

object describing the given unit `x`

.

```
dimension(x::Number)
dimension(x::Type{T}) where {T<:Number}
```

Returns a `Unitful.Dimensions{()}`

object to indicate that ordinary numbers are dimensionless. This is a singleton, which we export as `NoDims`

. The dimension is displayed as an empty string.

Examples:

```
julia> typeof(dimension(1.0))
Unitful.Dimensions{()}
julia> typeof(dimension(Float64))
Unitful.Dimensions{()}
julia> dimension(1.0) == NoDims
true
```

`dimension(u::Units{U,D}) where {U,D}`

Returns a `Unitful.Dimensions`

object corresponding to the dimensions of the units, `D`

. For a dimensionless combination of units, a `Unitful.Dimensions{()}`

object is returned (`NoDims`

).

Examples:

```
julia> dimension(u"m")
𝐋
julia> typeof(dimension(u"m"))
Unitful.Dimensions{(Unitful.Dimension{:Length}(1//1),)}
julia> dimension(u"m/km")
NoDims
```

```
dimension(x::Quantity{T,D}) where {T,D}
dimension(::Type{Quantity{T,D,U}}) where {T,D,U}
```

Returns a `Unitful.Dimensions`

object `D`

corresponding to the dimensions of quantity `x`

. For a dimensionless `Unitful.Quantity`

, a `Unitful.Dimensions{()}`

object is returned (`NoDims`

).

Examples:

```
julia> dimension(1.0u"m")
𝐋
julia> typeof(dimension(1.0u"m/μm"))
Unitful.Dimensions{()}
```

## Unit stripping

`Unitful.ustrip`

— Function```
ustrip(u::Units, x::Quantity)
ustrip(T::Type, u::Units, x::Quantity)
```

Convert `x`

to units `u`

using `uconvert`

and return the number out the front of the resulting quantity. If `T`

is supplied, also `convert`

the resulting number into type `T`

.

This function is mainly intended for compatibility with packages that don't know how to handle quantities.

```
julia> ustrip(u"m", 1u"mm") == 1//1000
true
julia> ustrip(Float64, u"m", 2u"mm") == 0.002
true
```

`ustrip`

supports `InverseFunctions.inverse`

:

```
julia> using InverseFunctions: inverse
julia> inverse(Base.Fix1(ustrip, u"m"))(5)
5 m
```

```
ustrip(x::Number)
ustrip(x::Quantity)
```

Returns the number out in front of any units. The value of `x`

may differ from the number out front of the units in the case of dimensionless quantities, e.g. `1m/mm != 1`

. See `uconvert`

and the example below. Because the units are removed, information may be lost and this should be used with some care — see `ustrip(u,x)`

for a safer alternative.

```
julia> ustrip(2u"μm/m") == 2
true
julia> uconvert(NoUnits, 2u"μm/m") == 2//1000000
true
```

`ustrip(x::Array{Q}) where {Q <: Quantity}`

Strip units from an `Array`

by reinterpreting to type `T`

. The resulting `Array`

is a not a copy, but rather a unit-stripped view into array `x`

. Because the units are removed, information may be lost and this should be used with some care.

This function is provided primarily for compatibility purposes; you could pass the result to PyPlot, for example.

```
julia> a = [1u"m", 2u"m"]
2-element Vector{Quantity{Int64, 𝐋, Unitful.FreeUnits{(m,), 𝐋, nothing}}}:
1 m
2 m
julia> b = ustrip(a)
2-element reinterpret(Int64, ::Vector{Quantity{Int64, 𝐋, Unitful.FreeUnits{(m,), 𝐋, nothing}}}):
1
2
julia> a[1] = 3u"m"; b
2-element reinterpret(Int64, ::Vector{Quantity{Int64, 𝐋, Unitful.FreeUnits{(m,), 𝐋, nothing}}}):
3
2
```

```
ustrip(A::Diagonal)
ustrip(A::Bidiagonal)
ustrip(A::Tridiagonal)
ustrip(A::SymTridiagonal)
```

Strip units from various kinds of matrices by calling `ustrip`

on the underlying vectors.

## Unit multiplication

`Base.:*`

— Method`*(a0::Units, a::Units...)`

Given however many units, multiply them together. This is actually handled by a few different methods, since we have `FreeUnits`

, `ContextUnits`

, and `FixedUnits`

.

Collect `Unitful.Unit`

objects from the type parameter of the `Unitful.Units`

objects. For identical units including SI prefixes (i.e. `cm`

≠ `m`

), collect powers and sort uniquely by the name of the `Unit`

. The unique sorting permits easy unit comparisons.

Examples:

```
julia> u"kg*m/s^2"
kg m s^-2
julia> u"m/s*kg/s"
kg m s^-2
julia> typeof(u"m/s*kg/s") == typeof(u"kg*m/s^2")
true
```

`Base.:*`

— Method`*(a0::Dimensions, a::Dimensions...)`

Given however many dimensions, multiply them together.

Collect `Unitful.Dimension`

objects from the type parameter of the `Unitful.Dimensions`

objects. For identical dimensions, collect powers and sort uniquely by the name of the `Dimension`

.

Examples:

```
julia> u"𝐌*𝐋/𝐓^2"
𝐋 𝐌 𝐓^-2
julia> u"𝐋*𝐌/𝐓^2"
𝐋 𝐌 𝐓^-2
julia> typeof(u"𝐋*𝐌/𝐓^2") == typeof(u"𝐌*𝐋/𝐓^2")
true
```