Skip to content

Commit c678b22

Browse files
committed
Talk about trait bounds in the tutorial.
1 parent 2c0f9bd commit c678b22

File tree

1 file changed

+31
-1
lines changed

1 file changed

+31
-1
lines changed

doc/tutorial.md

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1864,7 +1864,7 @@ so you could not apply `head` to a type
18641864
that does not implement `Clone`.
18651865

18661866
While most traits can be defined and implemented by user code,
1867-
two traits are automatically derived and implemented
1867+
three traits are automatically derived and implemented
18681868
for all applicable types by the compiler,
18691869
and may not be overridden:
18701870

@@ -1877,6 +1877,12 @@ These are types that do not contain anything intrinsically mutable.
18771877
Intrinsically mutable values include `@mut`
18781878
and `Cell` in the standard library.
18791879

1880+
* `'static` - Non-borrowed types.
1881+
These are types that do not contain any data whose lifetime is bound to
1882+
a particular stack frame. These are types that do not contain any
1883+
borrowed pointers, or types where the only contained borrowed pointers
1884+
have the `'static` lifetime.
1885+
18801886
> ***Note:*** These two traits were referred to as 'kinds' in earlier
18811887
> iterations of the language, and often still are.
18821888
@@ -2135,6 +2141,30 @@ select the method to call at runtime.
21352141

21362142
This usage of traits is similar to Java interfaces.
21372143

2144+
By default, each of the three storage classes for traits enforce a
2145+
particular set of built-in kinds that their contents must fulfill in
2146+
order to be packaged up in a trait object of that storage class.
2147+
2148+
* The contents of owned traits (`~Trait`) must fulfill the `Send` bound.
2149+
* The contents of managed traits (`@Trait`) must fulfill the `'static` bound.
2150+
* The contents of borrowed traits (`&Trait`) are not constrained by any bound.
2151+
2152+
Consequently, the trait objects themselves automatically fulfill their
2153+
respective kind bounds. However, this default behavior can be overridden by
2154+
specifying a list of bounds on the trait type, for example, by writing `~Trait:`
2155+
(which indicates that the contents of the owned trait need not fulfill any
2156+
bounds), or by writing `~Trait:Send+Freeze`, which indicates that in addition
2157+
to fulfilling `Send`, contents must also fulfill `Freeze`, and as a consequence,
2158+
the trait itself fulfills `Freeze`.
2159+
2160+
* `~Trait:Send` is equivalent to `~Trait`.
2161+
* `@Trait:'static` is equivalent to `@Trait`.
2162+
* `&Trait:` is equivalent to `&Trait`.
2163+
2164+
Builtin kind bounds can also be specified on closure types in the same way (for
2165+
example, by writing `fn:Freeze()`), and the default behaviours are the same as
2166+
for traits of the same storage class.
2167+
21382168
## Trait inheritance
21392169

21402170
We can write a trait declaration that _inherits_ from other traits, called _supertraits_.

0 commit comments

Comments
 (0)