From a746d5c53c16d2f658755dc029a2269441434296 Mon Sep 17 00:00:00 2001
From: Romeo Valentin <romeov@stanford.edu>
Date: Sun, 19 Nov 2023 23:23:12 -0800
Subject: [PATCH] Rename ``similar_dims` to `WithDims`, same for units

---
 src/Unitful.jl   |  2 +-
 src/utils.jl     | 24 ++++++++++++------------
 test/runtests.jl |  4 ++--
 3 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/src/Unitful.jl b/src/Unitful.jl
index 02c35639..60290498 100644
--- a/src/Unitful.jl
+++ b/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
 
diff --git a/src/utils.jl b/src/utils.jl
index 13887215..cb6cf2fc 100644
--- a/src/utils.jl
+++ b/src/utils.jl
@@ -244,8 +244,8 @@ 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.
@@ -253,21 +253,21 @@ Useful to build unitful interfaces that don't contrain the numeric type of the s
 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.
@@ -275,16 +275,16 @@ 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.");
diff --git a/test/runtests.jl b/test/runtests.jl
index 648419e7..a92cc5f2 100644
--- a/test/runtests.jl
+++ b/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