Skip to content

Commit 4ba3247

Browse files
committed
Add some missing sections to the types chapter
1 parent d9c7508 commit 4ba3247

File tree

1 file changed

+62
-1
lines changed

1 file changed

+62
-1
lines changed

src/types.md

Lines changed: 62 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ these are called _primitive types_. Some of these are induvidual types:
1717
* The [machine-dependent integer types].
1818
* The [textual types] `char` and `str`.
1919

20-
There are also some primitive constructs for generic types built in to the language
20+
There are also some primitive constructs for generic types built in to the language:
2121

2222
* [Tuples]
2323
* [Arrays]
@@ -201,6 +201,18 @@ named reference to an [`enum` item](items.html#enumerations).
201201
[^enumtype]: The `enum` type is analogous to a `data` constructor declaration in
202202
ML, or a *pick ADT* in Limbo.
203203

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

206218
Nominal types — [structs](#struct-types),
@@ -247,6 +259,13 @@ operation: it involves only copying the pointer itself, that is, pointers are
247259
referencing of a [temporary value](expressions.html#temporary-lifetimes) will
248260
keep it alive during the scope of the reference itself.
249261

262+
### Mutable references (`&mut`)
263+
264+
These also point to memory owned by some other value. A mutable reference
265+
type is written `&mut type` or `&'a mut type`. A mutable reference (that
266+
hasn't been borrowed) is the only way to access the value it points to, so
267+
is not `Copy`.
268+
250269
### Raw pointers (`*const` and `*mut`)
251270

252271
Raw pointers are pointers without safety or liveness guarantees. Raw pointers
@@ -482,6 +501,48 @@ default bound for trait objects of that type. For example, `std::cell::Ref<'a,
482501
T>` contains a `T: 'a` bound, therefore trait objects of type `Ref<'a,
483502
SomeTrait>` are the same as `Ref<'a, (SomeTrait + 'a)>`.
484503

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

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

0 commit comments

Comments
 (0)