Document Number interface

[BeastyBlacksmith]

I think it would be good to document what methods needs to be defined for a type to behave as a Number.
Last time I had to do this it took me quite some try and error to get the methods.

I ended up with the following

• +, -, *, / 3 each ( (T,T), (T,Any), (Any,T) )
• ==, hash, <
• promote_rule, convert
• rem, signed, typemax
• show, Constructor

That works in my usecase, but I am still unsure if this is "correct" or it its lacking something.
If I got it right, a Number is something that can be used in basic arithmetic, can be compared, and needs some basic rules to be usable in julia.

Maybe Number is too broad and it would need to be further devided.

[StefanKarpinski]

Number isn't really an interface—you don't have to implement anything. It's a subtype of Any which allows you to easily opt into various behaviors like arithmetic promotion that are useful fur numbers.

[rafaqz]

Is it not really an interface, or just a very complicated undocumented interface with a lot of opt-in methods?

It's something that gets extended semi-regularly by packages - I guess there's a big crossover between what e.g Unitful.jl and DualNumbers.jl implement. There is even a package that extends the whole interface in one go using a few methods:
https://github.com/SimonDanisch/AbstractNumbers.jl

So it's odd that there is no documentation at all to help doing that. I can read those packages, but what implemented for the needs of their custom types, and what is just generic? it's hard to say at a glance. I tend to think of Number as an interface, Real too. A nested documentation of the methods that apply to the abstract type hierarchy below Number would be very useful.

Also, some fallback methods like number in AbstractNumbers.jl would make it really easy to extend the interface. A lot of the methods in e.g. DualNumbers.jl are just forwarding value anyway:
https://github.com/JuliaDiff/DualNumbers.jl/blob/master/src/dual.jl#L163-L190

[StefanKarpinski]

Mathematically, I'm not sure what interface all numbers share. They should support equality comparison, but that's hardly specific to numbers and has a generic fallback definition. Are all numbers addable? Maybe but that seems like something that may not make sense for all things we may want to call numbers. They certainly aren't all multipliable or subtractable or divisible. Promotion and conversion to other number types may or may not make sense. Remainder, conversion to signed integers and typemax absolutely aren't sensible for many kinds of numbers. Being showable is useful for any kind of object but definitely not specific to numbers and all objects are showable by default already. What is the context in which someone needs to know what the interface for a number is?

[rafaqz]

I'll rephrase this and make it about the language, I am not qualified to discuss the mathematical meaning!

For example, what if you had to define a wrapper Number that could hold any other kind of Number, but had no specific mathematical properties of it's own.

Then the number interface is the set of Base julia methods that the wrapper type would need to forward to the wrapped Numbers it held to ensure that the great majority of objects <: Number would work in the Base Julia methods that they would usually work in, when they weren't wrapped in another object.

That's what I'm getting at by the interface - there is a specific set of Base methods that you would forward. It's pretty much what AbstractNumbers.jl is doing.

And I agree, within that set are methods that specific number types may or may not choose to implement.

[StefanKarpinski]

Ok, that makes more sense to me. It seems like something that can be computed with reflection.

[brainandforce]

Bumping this (accidentally duplicated the issue, but this was something discussed at JuliaCon 2025). Aside from the issue of what functions to implement, there are also issues of how numbers and certain functions should be correctly implemented:

• How to handle types that do not represent zero: in my package SignType.jl, Sign only represents +1 and -1, so what should zero(Sign) return? (I picked false as a strong zero, since Sign(+) is a strong one and Sign(-) is a strong negative one.)
• How to correctly implement promotion rules for numeric types: I ran into a pitfall which resulted in my promotion rules being invalid and potentially creating unbounded numbers of method ambiguities (promote_rule: forbid method definitions which may cause ambiguity for unknown types #55866).
• Should convert(T, x) always match the constructor for a Number? I have good reason not to in CliffordNumbers.jl, and the distinction is explained in the Julia docs, but all Julia Number types exhibit this behavior, and it's unclear whether it's permissible to deviate from this or what assumptions might be broken if this isn't the case.