# 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.0545718001391127e-34 J s

#
** Unitful.register** —

*Function*.

register(unit_module::Module)

Makes the `@u_str`

macro aware of units defined in new unit modules. 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 a `Unitful.FreeUnits{(), NoDims}`

object to indicate that ordinary numbers have no units. This is a singleton, which we export as `NoUnits`

. 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

#
** Unitful.dimension** —

*Method*.

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

#
** Unitful.dimension** —

*Method*.

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{()}

#
** Unitful.dimension** —

*Method*.

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{()}

#
** Unitful.dimension** —

*Method*.

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(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 Array{Quantity{Int64,ð,Unitful.FreeUnits{(m,),ð,nothing}},1}: 1 m 2 m julia> b = ustrip(a) 2-element reinterpret(Int64, ::Array{Quantity{Int64,ð,Unitful.FreeUnits{(m,),ð,nothing}},1}): 1 2 julia> a[1] = 3u"m"; b 2-element reinterpret(Int64, ::Array{Quantity{Int64,ð,Unitful.FreeUnits{(m,),ð,nothing}},1}): 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