Skip to content

Commit a3636cb

Browse files
nsajkovtjnash
authored andcommitted
doc: expand the <: doc string (JuliaLang#53001)
Clear up some things, state some expected properties and limitations, add cross-references, add more examples. Co-authored-by: Jameson Nash <vtjnash@gmail.com>
1 parent 32e32d5 commit a3636cb

File tree

1 file changed

+40
-4
lines changed

1 file changed

+40
-4
lines changed

base/operators.jl

+40-4
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,25 @@
33
## types ##
44

55
"""
6-
<:(T1, T2)
6+
<:(T1, T2)::Bool
77
8-
Subtype operator: returns `true` if and only if all values of type `T1` are
9-
also of type `T2`.
8+
Subtyping relation, defined between two types. In Julia, a type `S` is said to be a
9+
*subtype* of a type `T` if and only if we have `S <: T`.
10+
11+
For any type `L` and any type `R`, `L <: R` implies that any value `v` of type `L`
12+
is also of type `R`. I.e., `(L <: R) && (v isa L)` implies `v isa R`.
13+
14+
The subtyping relation is a *partial order*. I.e., `<:` is:
15+
16+
* *reflexive*: for any type `T`, `T <: T` holds
17+
18+
* *antisymmetric*: for any type `A` and any type `B`, `(A <: B) && (B <: A)`
19+
implies `A == B`
20+
21+
* *transitive*: for any type `A`, any type `B` and any type `C`;
22+
`(A <: B) && (B <: C)` implies `A <: C`
23+
24+
See also info on [Types](@ref man-types), [`Union{}`](@ref), [`Any`](@ref), [`isa`](@ref).
1025
1126
# Examples
1227
```jldoctest
@@ -16,9 +31,30 @@ true
1631
julia> Vector{Int} <: AbstractArray
1732
true
1833
19-
julia> Matrix{Float64} <: Matrix{AbstractFloat}
34+
julia> Matrix{Float64} <: Matrix{AbstractFloat} # `Matrix` is invariant
2035
false
36+
37+
julia> Tuple{Float64} <: Tuple{AbstractFloat} # `Tuple` is covariant
38+
true
39+
40+
julia> Union{} <: Int # The bottom type, `Union{}`, subtypes each type.
41+
true
42+
43+
julia> Union{} <: Float32 <: AbstractFloat <: Real <: Number <: Any # Operator chaining
44+
true
2145
```
46+
47+
The `<:` keyword also has several syntactic uses which represent the same subtyping relation,
48+
but which do not execute the operator or return a Bool:
49+
50+
* To specify the lower bound and the upper bound on a parameter of a
51+
[`UnionAll`](@ref) type in a [`where`](@ref) statement.
52+
53+
* To specify the lower bound and the upper bound on a (static) parameter of a
54+
method, see [Parametric Methods](@ref).
55+
56+
* To define a subtyping relation while declaring a new type, see [`struct`](@ref)
57+
and [`abstract type`](@ref).
2258
"""
2359
(<:)
2460

0 commit comments

Comments
 (0)