From a586d3cc6b02c7ae72e2161c8674aa3800d8da1f Mon Sep 17 00:00:00 2001 From: Mason Protter Date: Sun, 3 Mar 2024 02:16:51 +0100 Subject: [PATCH] Clarify docstring for `zero`, `one`, and `oneunit`. (#52107) spurred by a conversation on Slack where someone was thrown off wondering why `zero(Vector{Int})` errors, but `zero(Int)` is fine. --------- Co-authored-by: Sukera <11753998+Seelengrab@users.noreply.github.com> Co-authored-by: Max Horn Co-authored-by: Simon Byrne --- base/number.jl | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/base/number.jl b/base/number.jl index 923fc907d4038..39908222027c1 100644 --- a/base/number.jl +++ b/base/number.jl @@ -287,7 +287,12 @@ map(f, x::Number, ys::Number...) = f(x, ys...) zero(x) zero(::Type) -Get the additive identity element for the type of `x` (`x` can also specify the type itself). +Get the additive identity element for `x`. If the additive identity can be deduced +from the type alone, then a type may be given as an argument to `zero`. + +For example, `zero(Int)` will work because the additive identity is the same for all +instances of `Int`, but `zero(Vector{Int})` is not defined because vectors of different +lengths have different additive identities. See also [`iszero`](@ref), [`one`](@ref), [`oneunit`](@ref), [`oftype`](@ref). @@ -314,9 +319,12 @@ zero(::Type{Union{}}, slurp...) = Union{}(0) one(T::type) Return a multiplicative identity for `x`: a value such that -`one(x)*x == x*one(x) == x`. Alternatively `one(T)` can -take a type `T`, in which case `one` returns a multiplicative -identity for any `x` of type `T`. +`one(x)*x == x*one(x) == x`. If the multiplicative identity can +be deduced from the type alone, then a type may be given as +an argument to `one` (e.g. `one(Int)` will work because the +multiplicative identity is the same for all instances of `Int`, +but `one(Matrix{Int})` is not defined because matrices of +different shapes have different multiplicative identities.) If possible, `one(x)` returns a value of the same type as `x`, and `one(T)` returns a value of type `T`. However, this may @@ -354,9 +362,10 @@ one(::Type{Union{}}, slurp...) = Union{}(1) oneunit(x::T) oneunit(T::Type) -Return `T(one(x))`, where `T` is either the type of the argument or -(if a type is passed) the argument. This differs from [`one`](@ref) for -dimensionful quantities: `one` is dimensionless (a multiplicative identity) +Return `T(one(x))`, where `T` is either the type of the argument, or +the argument itself in cases where the `oneunit` can be deduced from +the type alone. This differs from [`one`](@ref) for dimensionful +quantities: `one` is dimensionless (a multiplicative identity) while `oneunit` is dimensionful (of the same type as `x`, or of type `T`). # Examples