Rename `similar_dims to WithDims, same for units

Author: RomeoV

src/Unitful.jl

@@ -27,7 +27,7 @@ import LinearAlgebra: istril, istriu, norm
 import Random
 
 export logunit, unit, absoluteunit, dimension, uconvert, ustrip, upreferred
-export similar_units, similar_dims
+export WithUnits, WithDims
 export @dimension, @derived_dimension, @refunit, @unit, @affineunit, @u_str
 export Quantity, DimensionlessQuantity, NoUnits, NoDims
 

src/utils.jl

@@ -244,47 +244,47 @@ struct DimensionError <: Exception
 end
 
 """
-    similar_dims(q::Quantity)
-    similar_dims(u::Units)
+    WithDims(q::Quantity)
+    WithDims(u::Units)
 Returns a type of [`Unitful.Quantity`](@ref) with the dimensions contrained to the
 dimension of `q` or `u`.
 Useful to build unitful interfaces that don't contrain the numeric type of the specific unit.
 
 Examples:
 
 ```jldoctest
-julia> circumference_of_square(side::similar_dims(u"m")) = 4*side;
+julia> circumference_of_square(side::WithDims(u"m")) = 4*side;
 julia> circumference_of_square((1//2)m)  # works
 2//1 m
 julia> circumference_of_square((1//2)km)  # also works
 2//1 km
 ```
 
-See also [`Unitful.similar_units`](@ref).
+See also [`Unitful.WithUnits`](@ref).
 """
-similar_dims(q::Quantity)  = Quantity{T, dimension(q),         U} where {T<:Real, U<:Unitlike}
-similar_dims(u::Units)     = Quantity{T, dimension(u),         U} where {T<:Real, U<:Unitlike}
+WithDims(q::Quantity)  = Quantity{T, dimension(q),         U} where {T<:Real, U<:Unitlike}
+WithDims(u::Units)     = Quantity{T, dimension(u),         U} where {T<:Real, U<:Unitlike}
 
 """
-    similar_units(q::Quantity)
-    similar_units(u::Units)
+    WithUnits(q::Quantity)
+    WithUnits(u::Units)
 Returns a type of [`Unitful.Quantity`](@ref) with the dimensions and units contrained to the
 dimension and units of `q` or `u`.
 Useful to build unitful interfaces that don't contrain the numeric type.
 
 Examples:
 
 ```jldoctest
-julia> circumference_of_square(side::similar_units(u"m")) = 4*side;
+julia> circumference_of_square(side::WithUnits(u"m")) = 4*side;
 julia> circumference_of_square((1//2)m)  # works
 2//1 m
 julia> # circumference_of_square((1//2)km)  # doesn't work, constrained to exactly meters
 ```
 
-See also [`Unitful.similar_dims`](@ref).
+See also [`Unitful.WithDims`](@ref).
 """
-similar_units(q::Quantity) = Quantity{T, dimension(q),   unit(q)} where {T<:Real}
-similar_units(u::Units)    = Quantity{T, dimension(u), typeof(u)} where {T<:Real}
+WithUnits(q::Quantity) = Quantity{T, dimension(q),   unit(q)} where {T<:Real}
+WithUnits(u::Units)    = Quantity{T, dimension(u), typeof(u)} where {T<:Real}
 
 Base.showerror(io::IO, e::DimensionError) =
     print(io, "DimensionError: $(e.x) and $(e.y) are not dimensionally compatible.");

test/runtests.jl

@@ -2080,8 +2080,8 @@ Base.OrderStyle(::Type{Num}) = Base.Unordered()
     # Test that @generated functions work with Quantities + custom types (#231)
     @test uconvert(u"°C", Num(373.15)u"K") == Num(100)u"°C"
 end
-area_of_circle(radius::similar_dims(u"m")) = pi*radius^2
-area_of_square(side::similar_units(u"m")) = side^2
+area_of_circle(radius::WithDims(u"m")) = pi*radius^2
+area_of_square(side::WithUnits(u"m")) = side^2
 
 @testset "Unitful interfaces" begin
     @test area_of_circle(Num(1.0)u"m") ≈ pi*m^2