Merge pull request #62 from SymbolicML/rename-expand-units

Deprecate `expand_units` -> `uexpand`

Author: MilesCranmer

README.md

@@ -187,10 +187,10 @@ julia> q^2
 ```
 
 You can convert to regular SI base units with
-`expand_units`:
+`uexpand`:
 
 ```julia
-julia> expand_units(q^2)
+julia> uexpand(q^2)
 1.0e6 kg² s⁻⁴
 ```
 
@@ -203,7 +203,7 @@ julia> x = us"Constants.c * Hz"
 julia> x^2
 1.0 Hz² c²
 
-julia> expand_units(x^2)
+julia> uexpand(x^2)
 8.987551787368176e16 m² s⁻⁴
 ```
 

docs/src/symbolic_units.md

@@ -14,10 +14,10 @@ units are `sym_uparse` and `us_str`:
 sym_uparse
 ```
 
-To convert a quantity to its regular base SI units, use `expand_units`:
+To convert a quantity to its regular base SI units, use `uexpand`:
 
 ```@docs
-expand_units
+uexpand
 ```
 
 To convert a quantity in regular base SI units to corresponding symbolic units, use `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, uconvert
+export uparse, @u_str, sym_uparse, @us_str, uexpand, uconvert
 
 include("fixed_rational.jl")
 include("types.jl")
@@ -17,6 +17,9 @@ include("constants.jl")
 include("uparse.jl")
 include("symbolic_dimensions.jl")
 
+include("deprecated.jl")
+export expand_units
+
 import PackageExtensionCompat: @require_extensions
 import .Units
 import .Constants

src/deprecated.jl

@@ -0,0 +1 @@
+Base.@deprecate expand_units(q) uexpand(q)

src/symbolic_dimensions.jl

@@ -32,7 +32,7 @@ are so many unit symbols).
 
 You can convert a quantity using `SymbolicDimensions` as its dimensions
 to one which uses `Dimensions` as its dimensions (i.e., base SI units)
-`expand_units`.
+`uexpand`.
 """
 struct SymbolicDimensions{R} <: AbstractDimensions{R}
     nzdims::Vector{INDEX_TYPE}
@@ -94,37 +94,37 @@ function Base.convert(::Type{Quantity{T,D}}, q::Quantity{<:Any,<:SymbolicDimensi
 end
 
 """
-    expand_units(q::Quantity{<:Any,<:SymbolicDimensions})
+    uexpand(q::Quantity{<:Any,<:SymbolicDimensions})
 
 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`. 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}}
+function uexpand(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)
+uexpand(q::QuantityArray) = uexpand.(q)
 # TODO: Make the array-based one more efficient
 
 """
     uconvert(qout::AbstractQuantity{<:Any, <:SymbolicDimensions}, 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)`. 
+Mathematically, the result has value `q / uexpand(qout)` and units `dimension(qout)`. 
 """
 function uconvert(qout::AbstractQuantity{<:Any, <:SymbolicDimensions}, q::AbstractQuantity{<:Any, <:Dimensions})
     @assert isone(ustrip(qout)) "You passed a quantity with a non-unit value to uconvert."
-    qout_expanded = expand_units(qout)
+    qout_expanded = uexpand(qout)
     dimension(q) == dimension(qout_expanded) || throw(DimensionError(q, qout_expanded))
     new_val = ustrip(q) / ustrip(qout_expanded)
     new_dim = dimension(qout)
     return new_quantity(typeof(q), new_val, new_dim)
 end
 function uconvert(qout::AbstractQuantity{<:Any,<:SymbolicDimensions}, q::QuantityArray{<:Any,<:Any,<:Dimensions})
     @assert isone(ustrip(qout)) "You passed a quantity with a non-unit value to uconvert."
-    qout_expanded = expand_units(qout)
+    qout_expanded = uexpand(qout)
     dimension(q) == dimension(qout_expanded) || throw(DimensionError(q, qout_expanded))
     new_array = ustrip(q) ./ ustrip(qout_expanded)
     new_dim = dimension(qout)

test/unittests.jl

@@ -545,19 +545,19 @@ end
     @test q == 1.5 * us"km" / us"s"
     @test typeof(q) <: Quantity{Float64,<:SymbolicDimensions}
     @test string(dimension(q)) == "s⁻¹ km"
-    @test expand_units(q) == 1.5u"km/s"
+    @test uexpand(q) == 1.5u"km/s"
     @test string(dimension(us"Constants.au^1.5")) == "au³ᐟ²"
-    @test string(dimension(expand_units(us"Constants.au^1.5"))) == "m³ᐟ²"
-    @test expand_units(2.3us"Constants.au^1.5") ≈ 2.3u"Constants.au^1.5"
+    @test string(dimension(uexpand(us"Constants.au^1.5"))) == "m³ᐟ²"
+    @test uexpand(2.3us"Constants.au^1.5") ≈ 2.3u"Constants.au^1.5"
     @test iszero(dimension(us"1.0")) == true
-    @test expand_units(inv(us"Constants.au")) ≈ 1/u"Constants.au"
+    @test uexpand(inv(us"Constants.au")) ≈ 1/u"Constants.au"
     @test dimension(inv(us"s") * us"km") == dimension(us"km/s")
     @test dimension(inv(us"s") * us"m") != dimension(us"km/s")
-    @test dimension(expand_units(inv(us"s") * us"m")) == dimension(expand_units(us"km/s"))
+    @test dimension(uexpand(inv(us"s") * us"m")) == dimension(uexpand(us"km/s"))
 
     f2(i::Int) = us"s"^i
     @inferred f2(5)
-    @test expand_units(f2(5)) == u"s"^5
+    @test uexpand(f2(5)) == u"s"^5
 
     @test_throws ErrorException sym_uparse("'c'")
 
@@ -567,7 +567,7 @@ end
     @test dimension(us"h")[:h] == 1
 
     @test us"Constants.h" != us"h"
-    @test expand_units(us"Constants.h") == u"Constants.h"
+    @test uexpand(us"Constants.h") == u"Constants.h"
 
     # Actually expands to:
     @test dimension(us"Constants.h")[:m] == 2
@@ -589,6 +589,10 @@ end
     sym5 = dimension(us"km/s")
     VERSION >= v"1.8" &&
         @test_throws "rad is not available as a symbol" sym5.rad
+
+    # Test deprecated method
+    q = 1.5us"km/s"
+    @test expand_units(q) == uexpand(q)
 end
 
 @testset "uconvert" begin
@@ -601,7 +605,7 @@ end
     @test dimension(qs)[:kg] == 0
     @test dimension(qs)[:g] == 0
     @test dimension(qs)[:M_sun] == 1
-    @test expand_units(qs) ≈ 5.0 * q
+    @test uexpand(qs) ≈ 5.0 * q
 
     # Refuses to convert to non-unit quantities:
     @test_throws AssertionError uconvert(1.2us"m", 1.0u"m")
@@ -886,8 +890,8 @@ end
         z_ar = randn(32)
         z = QuantityArray(z_ar, us"Constants.h * km/s")
         z_expanded = QuantityArray(z_ar .* u"Constants.h * km/s")
-        @test typeof(expand_units(z)) == typeof(z_expanded)
-        @test all(expand_units(z) .≈ z_expanded)
+        @test typeof(uexpand(z)) == typeof(z_expanded)
+        @test all(uexpand(z) .≈ z_expanded)
         io = IOBuffer()
         Base.showarg(io, z, true)
         msg = String(take!(io))