# 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, Dimensions:{ð ð^-1}, Units:{m s^-1}} 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.Units{(), Dimensions{()}}`

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{(),Unitful.Dimensions{()}} julia> typeof(unit(Float64)) Unitful.FreeUnits{(),Unitful.Dimensions{()}} 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.

Examples:

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

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.

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.

Examples:

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

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.

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.

Examples:

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

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.

Examples:

julia> dimension(1.0u"m") ð julia> typeof(dimension(1.0u"m/Îžm")) Unitful.Dimensions{()}

## Unit stripping

#
** Unitful.ustrip** —

*Function*.

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.

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

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