Skip to content

Commit edd85ab

Browse files
committed
doc: expand the <: doc string
Clear up some things, state some expected properties and limitations, add cross-references, add an academic reference, add more examples.
1 parent 47d31ac commit edd85ab

File tree

1 file changed

+31
-4
lines changed

1 file changed

+31
-4
lines changed

base/operators.jl

Lines changed: 31 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,27 @@
33
## types ##
44

55
"""
6-
<:(T1, T2)
6+
```julia
7+
<:(L, R)
8+
```
9+
10+
The subtyping predicate: test whether the type `L` may be a subtype of `R`.
11+
12+
For any type `A` and any type `B`, `A` subtypes `B` if and only if any value
13+
belonging to `A` is also of type `B`. Subtyping is reflexive and transitive,
14+
making it a *preorder*.
15+
16+
Julia is sometimes not able to prove a subtyping relation between two types, even
17+
if such a relation holds. In such a case the result of `S <: T` will be `false`
18+
even if `S` subtypes `T`. Even so, `<:` is expected to be reflexive and transitive.
19+
20+
See also: [the Manual page on types](@ref man-types), [`Union{}`](@ref),
21+
[`Any`](@ref), [`isa`](@ref).
722
8-
Subtype operator: returns `true` if and only if all values of type `T1` are
9-
also of type `T2`.
23+
Julia's subtyping relation is the topic of the paper *Julia Subtyping: A Rational
24+
Reconstruction*, published in the *Proceedings of the ACM on Programming
25+
Languages*. DOI: [`10.1145/3276483`](https://dx.doi.org/10.1145/3276483), HAL:
26+
[`hal-01882137`](https://inria.hal.science/hal-01882137).
1027
1128
# Examples
1229
```jldoctest
@@ -16,9 +33,19 @@ true
1633
julia> Vector{Int} <: AbstractArray
1734
true
1835
19-
julia> Matrix{Float64} <: Matrix{AbstractFloat}
36+
julia> Matrix{Float64} <: Matrix{AbstractFloat} # Invariance
2037
false
38+
39+
julia> Union{} <: Int # The bottom type, `Union{}`, subtypes each type.
40+
true
41+
42+
julia> Union{} <: Float32 <: AbstractFloat <: Real <: Number <: Any # Chaining
43+
true
2144
```
45+
46+
The `<:` syntax may also be used in another sense; for specifying the lower and
47+
upper bound on a parameter of a [`UnionAll`](@ref) type, see the Manual section on
48+
[UnionAll types](@ref "UnionAll Types").
2249
"""
2350
(<:)
2451

0 commit comments

Comments
 (0)