Skip to content

Commit 3991cf4

Browse files
committed
Add some missing sections to the types chapter
2 parents 729851f + d867436 commit 3991cf4

File tree

1 file changed

+65
-3
lines changed

1 file changed

+65
-3
lines changed

src/types.md

Lines changed: 65 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -178,9 +178,6 @@ The one value constructed by the associated [struct
178178
expression](expressions.html#struct-expressions) is the only value that
179179
inhabits such a type.
180180

181-
[^structtype]: `struct` types are analogous to `struct` types in C, the
182-
*record* types of the ML family, or the *struct* types of the Lisp family.
183-
184181
[^structtype]: `struct` types are analogous to `struct` types in C, the
185182
*record* types of the ML family, or the *struct* types of the Lisp family.
186183

@@ -202,6 +199,21 @@ corresponding `enum` type, as well as the size needed to store a discriminant.
202199
Enum types cannot be denoted *structurally* as types, but must be denoted by
203200
named reference to an [`enum` item](items.html#enumerations).
204201

202+
[^enumtype]: The `enum` type is analogous to a `data` constructor declaration in
203+
ML, or a *pick ADT* in Limbo.
204+
205+
## Union types
206+
207+
A *union type* is a nominal, heterogeneous C-like union, denoted by the name of
208+
a [`union` item](items.html#unions).
209+
210+
A union contains the value of any one of its fields. Since the accessing the
211+
wrong field can cause unexpected or undefined behaviour, it requires `unsafe`,
212+
except for initializing a union and writing `Copy` fields.
213+
214+
The memory layout of a `union` is undefined by default, but the `#[repr(...)]`
215+
attribute can be used to fix a layout.
216+
205217
[^enumtype]: The `enum` type is analogous to a `data` constructor declaration in
206218
ML, or a *pick ADT* in Limbo.
207219

@@ -252,6 +264,12 @@ operation: it involves only copying the pointer itself, that is, pointers are
252264
referencing of a [temporary value](expressions.html#temporary-lifetimes) will
253265
keep it alive during the scope of the reference itself.
254266

267+
### Mutable references (`&mut`)
268+
269+
These also point to memory owned by some other value. A mutable reference type
270+
is written `&mut type` or `&'a mut type`. A mutable reference (that hasn't been
271+
borrowed) is the only way to access the value it points to, so is not `Copy`.
272+
255273
### Raw pointers (`*const` and `*mut`)
256274

257275
Raw pointers are pointers without safety or liveness guarantees. Raw pointers
@@ -490,6 +508,50 @@ objects of type `Ref<'a, SomeTrait>` are the same as `Ref<'a, (SomeTrait +
490508
example in `std::rc::Rc<T>`.
491509

492510

511+
## Dynamically sized types
512+
513+
Most types have a fixed size that is known at compile time and implement the
514+
trait [`Sized`]. A type with a size that is known only at run-time is called a
515+
_dynamically sized type_ (_DST_) or unsized type. [Slices] and [trait objects]
516+
are two of the most DSTs. Such types can only be used in certain cases:
517+
518+
* [Pointer types] to DSTs are sized but have twice the size of pointers to
519+
sized types
520+
* Pointers to slices also store the number of elements of the slice.
521+
* Pointers to trait objects also store a pointer to a vtable.
522+
* Traits may be implemented for DSTs, this means that `Self` is not assumed to
523+
implement `Sized` in trait definitions by default.
524+
* DSTs can be used as type parameters with a bound of `?Sized`
525+
* Structs may contain a DST as the last field, this makes the struct a DST as
526+
well.
527+
528+
Notably: [variables], function parameters, [const] and [static] items must be
529+
sized.
530+
531+
[`Sized`]: the-sized-trait.html
532+
[Slices]: #array-and-slice-types
533+
[trait objects]: #trait-objects
534+
[Pointer types]: #pointer-types
535+
[variables]: variables.html
536+
[const]: items.html#constant-items
537+
[static]: items.html#static-items
538+
539+
## Interior mutability
540+
541+
References prevent a value being both aliased and mutated: mutable references
542+
don't allow a value to be aliased and shared references prevent a value from
543+
being mutated. Sometimes this is too restrictive. The type
544+
[`std::cell::UnsafeCell<T>`](../std/cell/struct.UnsafeCell.html) provides an
545+
unsafe API that allows a type to own a `T` that can be mutated through a shared
546+
reference to the `UnsafeCell` (there is no change to mutable references).
547+
548+
The standard library provides a variety of different types that safely wrap
549+
this functionality. For example `std::cell::RefCell<T>` uses run-time borrow
550+
checks to ensure the usual rules around multiple references. The
551+
`std::sync::atomic` module contains types that wrap a value that is only
552+
accessed with atomic operations, allowing the value to be shared and mutated
553+
across threads.
554+
493555
## Type parameters
494556

495557
Within the body of an item that has type parameter declarations, the names of

0 commit comments

Comments
 (0)