feat: two-arg ustrip

Author: MilesCranmer

src/arrays.jl

@@ -125,6 +125,11 @@ end
 
 @inline ustrip(A::QuantityArray) = A.value
 @inline ustrip(A::AbstractArray{<:UnionAbstractQuantity}) = ustrip.(A)
+@inline function ustrip(unit::UnionAbstractQuantity, q::QuantityArray)
+    dimension(unit) == dimension(q) || throw(DimensionError(unit, q))
+    conversion_factor = ustrip(dimension(q) / unit)
+    return ustrip(q) .* conversion_factor
+end
 @inline dimension(A::QuantityArray) = A.dimensions
 
 array_type(::Type{<:QuantityArray{T,N,D,Q,V}}) where {T,N,D,Q,V} = V

src/utils.jl

@@ -388,6 +388,36 @@ Remove the units from a quantity.
 ustrip(::AbstractDimensions) = error("Cannot remove units from an `AbstractDimensions` object.")
 @inline ustrip(q) = q
 
+"""
+    ustrip(unit::UnionAbstractQuantity, q::UnionAbstractQuantity)
+    ustrip(unit::UnionAbstractQuantity, q::AbstractArray{<:UnionAbstractQuantity})
+
+Convert quantity `q` to the units specified by `unit`, then strip the units.
+This is equivalent to `ustrip(q / unit)`, but also verifies the dimensions are compatible.
+
+# Examples
+```julia
+julia> ustrip(u"km", 1000u"m")
+1.0
+
+julia> ustrip(u"s", 1u"minute")
+60.0
+
+julia> ustrip(u"km", [1000u"m", 2000u"m"])
+2-element Vector{Float64}:
+ 1.0
+ 2.0
+```
+"""
+@inline function ustrip(unit::UnionAbstractQuantity, q::UnionAbstractQuantity)
+    dimension(unit) == dimension(q) || throw(DimensionError(unit, q))
+    return ustrip(q / unit)
+end
+@inline function ustrip(unit::UnionAbstractQuantity, q::AbstractArray{<:UnionAbstractQuantity})
+    all(qi -> dimension(qi) == dimension(unit), q) || throw(DimensionError(unit, q))
+    return @. ustrip(q / unit)
+end
+
 """
     dimension(q::AbstractQuantity)
     dimension(q::AbstractGenericQuantity)