From e0702e4b9a262e1d901319d4d5c6062284bc8569 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Thu, 19 Dec 2019 14:00:49 -0500 Subject: [PATCH] Add more links --- src/exotic-sizes.md | 4 +++- src/safe-unsafe-meaning.md | 24 ++++++++++++++---------- src/what-unsafe-does.md | 3 ++- 3 files changed, 19 insertions(+), 12 deletions(-) diff --git a/src/exotic-sizes.md b/src/exotic-sizes.md index 1e8e7a0..ffb07e5 100644 --- a/src/exotic-sizes.md +++ b/src/exotic-sizes.md @@ -20,7 +20,7 @@ information that "completes" them (more on this below). There are two major DSTs exposed by the language: * trait objects: `dyn MyTrait` -* slices: `[T]`, `str`, and others +* slices: [`[T]`], [`str`], and others A trait object represents some type that implements the traits it specifies. The exact original type is *erased* in favor of runtime reflection @@ -194,3 +194,5 @@ should behave. [dst-issue]: https://github.com/rust-lang/rust/issues/26403 [extern-types]: https://github.com/rust-lang/rfcs/blob/master/text/1861-extern-types.md +[`str`]: ../std/primitive.str.html +[`[T]`]: ../std/primitive.slice.html diff --git a/src/safe-unsafe-meaning.md b/src/safe-unsafe-meaning.md index e231384..8ee2baf 100644 --- a/src/safe-unsafe-meaning.md +++ b/src/safe-unsafe-meaning.md @@ -24,19 +24,19 @@ maintains the contracts the trait requires. You can use `unsafe` on a block to declare that all unsafe actions performed within are verified to uphold the contracts of those operations. For instance, -the index passed to `slice::get_unchecked` is in-bounds. +the index passed to [`slice::get_unchecked`][get_unchecked] is in-bounds. You can use `unsafe` on a trait implementation to declare that the implementation -upholds the trait's contract. For instance, that a type implementing `Send` is +upholds the trait's contract. For instance, that a type implementing [`Send`] is really safe to move to another thread. The standard library has a number of unsafe functions, including: -* `slice::get_unchecked`, which performs unchecked indexing, allowing - memory safety to be freely violated. -* `mem::transmute` reinterprets some value as having a given type, bypassing - type safety in arbitrary ways (see [conversions] for details). -* Every raw pointer to a sized type has an `offset` method that +* [`slice::get_unchecked`][get_unchecked], which performs unchecked indexing, + allowing memory safety to be freely violated. +* [`mem::transmute`][transmute] reinterprets some value as having a given type, + bypassing type safety in arbitrary ways (see [conversions] for details). +* Every raw pointer to a sized type has an [`offset`][ptr_offset] method that invokes Undefined Behavior if the passed offset is not ["in bounds"][ptr_offset]. * All FFI (Foreign Function Interface) functions are `unsafe` to call because the other language can do arbitrary operations that the Rust compiler can't check. @@ -65,11 +65,11 @@ relationship between Safe and Unsafe Rust. Safe Rust inherently has to trust that any Unsafe Rust it touches has been written correctly. On the other hand, Unsafe Rust has to be very careful about trusting Safe Rust. -As an example, Rust has the `PartialOrd` and `Ord` traits to differentiate +As an example, Rust has the [`PartialOrd`] and [`Ord`] traits to differentiate between types which can "just" be compared, and those that provide a "total" ordering (which basically means that comparison behaves reasonably). -`BTreeMap` doesn't really make sense for partially-ordered types, and so it +[`BTreeMap`] doesn't really make sense for partially-ordered types, and so it requires that its keys implement `Ord`. However, `BTreeMap` has Unsafe Rust code inside of its implementation. Because it would be unacceptable for a sloppy `Ord` implementation (which is Safe to write) to cause Undefined Behavior, the Unsafe @@ -156,4 +156,8 @@ of the sort of care that must be taken, and what contracts Unsafe Rust must upho [`GlobalAlloc`]: ../std/alloc/trait.GlobalAlloc.html [conversions]: conversions.html [ptr_offset]: ../std/primitive.pointer.html#method.offset - +[get_unchecked]: ../std/primitive.slice.html#method.get_unchecked +[transmute]: ../std/mem/fn.transmute.html +[`PartialOrd`]: ../std/cmp/trait.PartialOrd.html +[`Ord`]: ../std/cmp/trait.Ord.html +[`BTreeMap`]: ../std/collections/struct.BTreeMap.html diff --git a/src/what-unsafe-does.md b/src/what-unsafe-does.md index 7f13f93..984cb50 100644 --- a/src/what-unsafe-does.md +++ b/src/what-unsafe-does.md @@ -39,7 +39,7 @@ language cares about is preventing the following things: (i.e., it must not be read from uninitialized memory) * a `str` that isn't valid UTF-8 * a type with custom invalid values that is one of those values, such as a - `NonNull` that is null. (Requesting custom invalid values is an unstable + [`NonNull`] that is null. (Requesting custom invalid values is an unstable feature, but some stable libstd types, like `NonNull`, make use of it.) "Producing" a value happens any time a value is assigned, passed to a @@ -85,3 +85,4 @@ these problems are considered impractical to categorically prevent. [uninitialized memory]: uninitialized.html [race]: races.html [target features]: ../reference/attributes/codegen.html#the-target_feature-attribute +[`NonNull`]: ../std/ptr/struct.NonNull.html