Switch from as_u to uconvert

- Motive: for consistency with Unitful
- Also, we make the first argument the symbolic quantity

Author: MilesCranmer

README.md

@@ -207,9 +207,9 @@ julia> expand_units(x^2)
 8.987551787368176e16 m² s⁻⁴
 ```
 
-You can also convert a quantity in regular base SI units to symbolic units with `as_u`:
+You can also convert a quantity in regular base SI units to symbolic units with `uconvert`:
 ```julia
-julia> as_u(5e-9u"m", us"nm") # can also write 5e-9u"m" |> as_u(us"nm")
+julia> uconvert(us"nm", 5e-9u"m") # can also write 5e-9u"m" |> uconvert(us"nm")
 5.0 nm
 ```
 

docs/src/examples.md

@@ -30,7 +30,7 @@ julia> p = sqrt(2 * m_e * (E - Φ)) # momentum of ejected electrons
 julia> λ = h / p # wavelength of ejected electrons
 3.029491247878056e-9 m
 
-julia> as_u(λ, us"nm") # return answer in nanometers
+julia> uconvert(us"nm", λ) # return answer in nanometers
 3.0294912478780556 nm
 ```
 Since units are automatically propagated, we can verify the dimension of our answer and all intermediates.

docs/src/symbolic_units.md

@@ -20,8 +20,8 @@ To convert a quantity to its regular base SI units, use `expand_units`:
 expand_units
 ```
 
-To convert a quantity in regular base SI units to corresponding symbolic units, use `as_u`:
+To convert a quantity in regular base SI units to corresponding symbolic units, use `uconvert`:
 
 ```@docs
-as_u
+uconvert
 ```

src/DynamicQuantities.jl

@@ -5,7 +5,7 @@ export AbstractQuantity, AbstractDimensions
 export Quantity, Dimensions, SymbolicDimensions, QuantityArray, DimensionError
 export ustrip, dimension
 export ulength, umass, utime, ucurrent, utemperature, uluminosity, uamount
-export uparse, @u_str, sym_uparse, @us_str, expand_units, as_u
+export uparse, @u_str, sym_uparse, @us_str, expand_units, uconvert
 
 include("fixed_rational.jl")
 include("types.jl")

src/symbolic_dimensions.jl

@@ -98,38 +98,40 @@ end
 
 Expand the symbolic units in a quantity to their base SI form.
 In other words, this converts a `Quantity` with `SymbolicDimensions`
-to one with `Dimensions`.
+to one with `Dimensions`. The opposite of this function is `uconvert`,
+for converting to specific symbolic units, or `convert(Quantity{<:Any,<:SymbolicDimensions}, q)`,
+for assuming SI units as the output symbols.
 """
 function expand_units(q::Q) where {T,R,D<:SymbolicDimensions{R},Q<:AbstractQuantity{T,D}}
     return convert(constructor_of(Q){T,Dimensions{R}}, q)
 end
 expand_units(q::QuantityArray) = expand_units.(q)
 
 """
-    as_u(q::AbstractQuantity{<:Any, <:Dimensions}, qout::AbstractQuantity{<:Any, <:SymbolicDimensions})
-    as_u(q::AbstractQuantity{<:Any, <:Dimensions}, ustr::String)
+    uconvert(qout::AbstractQuantity{<:Any, <:SymbolicDimensions}, q::AbstractQuantity{<:Any, <:Dimensions})
+    uconvert(ustr::String, q::AbstractQuantity{<:Any, <:Dimensions})
 
 Convert a quantity `q` with base SI units to the symbolic units of `qout`, for `q` and `qout` with compatible units.
 Mathematically, the result has value `q / expand_units(qout)` and units `dimension(qout)`. 
 For string input, `qout` is created by parsing `ustr` as a symbolic unit, i.e. `qout = sym_uparse(ustr)`.
 """
-function as_u(q::AbstractQuantity{<:Any, <:Dimensions}, qout::AbstractQuantity{<:Any, <:SymbolicDimensions})
+function uconvert(qout::AbstractQuantity{<:Any, <:SymbolicDimensions}, q::AbstractQuantity{<:Any, <:Dimensions})
     qout_expanded = expand_units(qout)
     dimension(q) == dimension(qout_expanded) || throw(DimensionError(q, qout_expanded))
     return new_quantity(typeof(qout), ustrip(q) / ustrip(qout_expanded), dimension(qout))
 end
-as_u(q::AbstractQuantity{<:Any, <:Dimensions}, ustr::String) = as_u(q, sym_uparse(ustr)) 
+uconvert(ustr::String, q::AbstractQuantity{<:Any, <:Dimensions}) = uconvert(sym_uparse(ustr), q) 
 
 """
-    as_u(qout::AbstractQuantity{<:Any, <:SymbolicDimensions})
-    as_u(ustr::String)
+    uconvert(qout::AbstractQuantity{<:Any, <:SymbolicDimensions})
+    uconvert(ustr::String)
 
 Create a function that converts an input quantity `q` with base SI units to the symbolic units of `qout`, i.e 
-a function equivalent to `q -> as_u(q, qout)`.
+a function equivalent to `q -> uconvert(qout, q)`.
 For string input, `qout` is created by parsing `ustr` as a symbolic unit, i.e. `qout = sym_uparse(ustr)`.
 """
-as_u(qout::AbstractQuantity{<:Any, <:SymbolicDimensions}) = Base.Fix2(as_u, qout)
-as_u(ustr::String) = Base.Fix2(as_u, ustr)
+uconvert(qout::AbstractQuantity{<:Any, <:SymbolicDimensions}) = Base.Fix1(uconvert, qout)
+uconvert(ustr::String) = uconvert(sym_uparse(ustr))
 
 Base.copy(d::SymbolicDimensions) = SymbolicDimensions(copy(getfield(d, :nzdims)), copy(getfield(d, :nzvals)))
 function Base.:(==)(l::SymbolicDimensions, r::SymbolicDimensions)

test/unittests.jl

@@ -569,8 +569,8 @@ end
     @test us"Constants.h" != us"h"
     @test expand_units(us"Constants.h") == u"Constants.h"
 
-    @test as_u(5e-9u"m", us"nm") ≈ as_u(5e-9u"m", "nm") ≈ (5e-9u"m" |> as_u(us"nm")) ≈ (5e-9u"m" |> as_u("nm")) ≈ 5us"nm"
-    @test_throws DimensionError as_u(5e-9u"m", us"nm * J")
+    @test uconvert(us"nm", 5e-9u"m") ≈ uconvert("nm", 5e-9u"m") ≈ (5e-9u"m" |> uconvert(us"nm")) ≈ (5e-9u"m" |> uconvert("nm")) ≈ 5us"nm"
+    @test_throws DimensionError uconvert(us"nm * J", 5e-9u"m")
 
     # Actually expands to:
     @test dimension(us"Constants.h")[:m] == 2