From 22d4adf14aabfb0ea0cfc8daff203e8d474cbc52 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Tue, 7 Feb 2017 19:08:12 -0500 Subject: [PATCH] Port Nomicon to mdbook 1. move everything under a src directory 2. add README.md to the SUMMARY.md --- src/doc/nomicon/SUMMARY.md | 53 ------------------ src/doc/nomicon/{ => src}/README.md | 2 +- src/doc/nomicon/src/SUMMARY.md | 54 ++++++++++++++++++- src/doc/nomicon/{ => src}/arc-and-mutex.md | 2 +- src/doc/nomicon/{ => src}/atomics.md | 2 +- src/doc/nomicon/{ => src}/borrow-splitting.md | 2 +- src/doc/nomicon/{ => src}/casts.md | 2 +- src/doc/nomicon/{ => src}/checked-uninit.md | 2 +- src/doc/nomicon/{ => src}/coercions.md | 2 +- src/doc/nomicon/{ => src}/concurrency.md | 2 +- src/doc/nomicon/{ => src}/constructors.md | 2 +- src/doc/nomicon/{ => src}/conversions.md | 2 +- src/doc/nomicon/{ => src}/data.md | 2 +- src/doc/nomicon/{ => src}/destructors.md | 2 +- src/doc/nomicon/{ => src}/dot-operator.md | 2 +- src/doc/nomicon/{ => src}/drop-flags.md | 2 +- src/doc/nomicon/{ => src}/dropck.md | 2 +- src/doc/nomicon/{ => src}/exception-safety.md | 2 +- src/doc/nomicon/{ => src}/exotic-sizes.md | 2 +- src/doc/nomicon/{ => src}/hrtb.md | 2 +- src/doc/nomicon/{ => src}/leaking.md | 2 +- src/doc/nomicon/{ => src}/lifetime-elision.md | 2 +- .../nomicon/{ => src}/lifetime-mismatch.md | 2 +- src/doc/nomicon/{ => src}/lifetimes.md | 2 +- .../nomicon/{ => src}/meet-safe-and-unsafe.md | 2 +- src/doc/nomicon/{ => src}/obrm.md | 2 +- src/doc/nomicon/{ => src}/other-reprs.md | 2 +- src/doc/nomicon/{ => src}/ownership.md | 2 +- src/doc/nomicon/{ => src}/phantom-data.md | 2 +- src/doc/nomicon/{ => src}/poisoning.md | 2 +- src/doc/nomicon/{ => src}/races.md | 2 +- src/doc/nomicon/{ => src}/references.md | 2 +- src/doc/nomicon/{ => src}/repr-rust.md | 2 +- .../nomicon/{ => src}/safe-unsafe-meaning.md | 2 +- src/doc/nomicon/{ => src}/send-and-sync.md | 2 +- src/doc/nomicon/{ => src}/subtyping.md | 2 +- src/doc/nomicon/{ => src}/transmutes.md | 2 +- .../nomicon/{ => src}/unbounded-lifetimes.md | 2 +- src/doc/nomicon/{ => src}/unchecked-uninit.md | 2 +- src/doc/nomicon/{ => src}/uninitialized.md | 2 +- src/doc/nomicon/{ => src}/unwinding.md | 2 +- src/doc/nomicon/{ => src}/vec-alloc.md | 2 +- src/doc/nomicon/{ => src}/vec-dealloc.md | 2 +- src/doc/nomicon/{ => src}/vec-deref.md | 2 +- src/doc/nomicon/{ => src}/vec-drain.md | 2 +- src/doc/nomicon/{ => src}/vec-final.md | 2 +- .../nomicon/{ => src}/vec-insert-remove.md | 2 +- src/doc/nomicon/{ => src}/vec-into-iter.md | 2 +- src/doc/nomicon/{ => src}/vec-layout.md | 2 +- src/doc/nomicon/{ => src}/vec-push-pop.md | 2 +- src/doc/nomicon/{ => src}/vec-raw.md | 2 +- src/doc/nomicon/{ => src}/vec-zsts.md | 2 +- src/doc/nomicon/{ => src}/vec.md | 2 +- .../nomicon/{ => src}/working-with-unsafe.md | 2 +- 54 files changed, 105 insertions(+), 106 deletions(-) delete mode 100644 src/doc/nomicon/SUMMARY.md rename src/doc/nomicon/{ => src}/README.md (99%) rename src/doc/nomicon/{ => src}/arc-and-mutex.md (89%) rename src/doc/nomicon/{ => src}/atomics.md (99%) rename src/doc/nomicon/{ => src}/borrow-splitting.md (99%) rename src/doc/nomicon/{ => src}/casts.md (99%) rename src/doc/nomicon/{ => src}/checked-uninit.md (98%) rename src/doc/nomicon/{ => src}/coercions.md (99%) rename src/doc/nomicon/{ => src}/concurrency.md (96%) rename src/doc/nomicon/{ => src}/constructors.md (99%) rename src/doc/nomicon/{ => src}/conversions.md (98%) rename src/doc/nomicon/{ => src}/data.md (87%) rename src/doc/nomicon/{ => src}/destructors.md (99%) rename src/doc/nomicon/{ => src}/dot-operator.md (93%) rename src/doc/nomicon/{ => src}/drop-flags.md (99%) rename src/doc/nomicon/{ => src}/dropck.md (99%) rename src/doc/nomicon/{ => src}/exception-safety.md (99%) rename src/doc/nomicon/{ => src}/exotic-sizes.md (99%) rename src/doc/nomicon/{ => src}/hrtb.md (98%) rename src/doc/nomicon/{ => src}/leaking.md (99%) rename src/doc/nomicon/{ => src}/lifetime-elision.md (99%) rename src/doc/nomicon/{ => src}/lifetime-mismatch.md (98%) rename src/doc/nomicon/{ => src}/lifetimes.md (99%) rename src/doc/nomicon/{ => src}/meet-safe-and-unsafe.md (99%) rename src/doc/nomicon/{ => src}/obrm.md (93%) rename src/doc/nomicon/{ => src}/other-reprs.md (99%) rename src/doc/nomicon/{ => src}/ownership.md (99%) rename src/doc/nomicon/{ => src}/phantom-data.md (99%) rename src/doc/nomicon/{ => src}/poisoning.md (99%) rename src/doc/nomicon/{ => src}/races.md (99%) rename src/doc/nomicon/{ => src}/references.md (99%) rename src/doc/nomicon/{ => src}/repr-rust.md (99%) rename src/doc/nomicon/{ => src}/safe-unsafe-meaning.md (99%) rename src/doc/nomicon/{ => src}/send-and-sync.md (99%) rename src/doc/nomicon/{ => src}/subtyping.md (99%) rename src/doc/nomicon/{ => src}/transmutes.md (99%) rename src/doc/nomicon/{ => src}/unbounded-lifetimes.md (98%) rename src/doc/nomicon/{ => src}/unchecked-uninit.md (99%) rename src/doc/nomicon/{ => src}/uninitialized.md (93%) rename src/doc/nomicon/{ => src}/unwinding.md (99%) rename src/doc/nomicon/{ => src}/vec-alloc.md (99%) rename src/doc/nomicon/{ => src}/vec-dealloc.md (98%) rename src/doc/nomicon/{ => src}/vec-deref.md (99%) rename src/doc/nomicon/{ => src}/vec-drain.md (99%) rename src/doc/nomicon/{ => src}/vec-final.md (99%) rename src/doc/nomicon/{ => src}/vec-insert-remove.md (98%) rename src/doc/nomicon/{ => src}/vec-into-iter.md (99%) rename src/doc/nomicon/{ => src}/vec-layout.md (99%) rename src/doc/nomicon/{ => src}/vec-push-pop.md (99%) rename src/doc/nomicon/{ => src}/vec-raw.md (99%) rename src/doc/nomicon/{ => src}/vec-zsts.md (99%) rename src/doc/nomicon/{ => src}/vec.md (97%) rename src/doc/nomicon/{ => src}/working-with-unsafe.md (99%) diff --git a/src/doc/nomicon/SUMMARY.md b/src/doc/nomicon/SUMMARY.md deleted file mode 100644 index 7d4ef9c25148..000000000000 --- a/src/doc/nomicon/SUMMARY.md +++ /dev/null @@ -1,53 +0,0 @@ -# Summary - -* [Meet Safe and Unsafe](meet-safe-and-unsafe.md) - * [How Safe and Unsafe Interact](safe-unsafe-meaning.md) - * [Working with Unsafe](working-with-unsafe.md) -* [Data Layout](data.md) - * [repr(Rust)](repr-rust.md) - * [Exotically Sized Types](exotic-sizes.md) - * [Other reprs](other-reprs.md) -* [Ownership](ownership.md) - * [References](references.md) - * [Lifetimes](lifetimes.md) - * [Limits of Lifetimes](lifetime-mismatch.md) - * [Lifetime Elision](lifetime-elision.md) - * [Unbounded Lifetimes](unbounded-lifetimes.md) - * [Higher-Rank Trait Bounds](hrtb.md) - * [Subtyping and Variance](subtyping.md) - * [Drop Check](dropck.md) - * [PhantomData](phantom-data.md) - * [Splitting Borrows](borrow-splitting.md) -* [Type Conversions](conversions.md) - * [Coercions](coercions.md) - * [The Dot Operator](dot-operator.md) - * [Casts](casts.md) - * [Transmutes](transmutes.md) -* [Uninitialized Memory](uninitialized.md) - * [Checked](checked-uninit.md) - * [Drop Flags](drop-flags.md) - * [Unchecked](unchecked-uninit.md) -* [Ownership Based Resource Management](obrm.md) - * [Constructors](constructors.md) - * [Destructors](destructors.md) - * [Leaking](leaking.md) -* [Unwinding](unwinding.md) - * [Exception Safety](exception-safety.md) - * [Poisoning](poisoning.md) -* [Concurrency](concurrency.md) - * [Races](races.md) - * [Send and Sync](send-and-sync.md) - * [Atomics](atomics.md) -* [Implementing Vec](vec.md) - * [Layout](vec-layout.md) - * [Allocating](vec-alloc.md) - * [Push and Pop](vec-push-pop.md) - * [Deallocating](vec-dealloc.md) - * [Deref](vec-deref.md) - * [Insert and Remove](vec-insert-remove.md) - * [IntoIter](vec-into-iter.md) - * [RawVec](vec-raw.md) - * [Drain](vec-drain.md) - * [Handling Zero-Sized Types](vec-zsts.md) - * [Final Code](vec-final.md) -* [Implementing Arc and Mutex](arc-and-mutex.md) diff --git a/src/doc/nomicon/README.md b/src/doc/nomicon/src/README.md similarity index 99% rename from src/doc/nomicon/README.md rename to src/doc/nomicon/src/README.md index b2e1eac5e0dc..d577d7b5cc91 100644 --- a/src/doc/nomicon/README.md +++ b/src/doc/nomicon/src/README.md @@ -1,4 +1,4 @@ -% The Rustonomicon +# The Rustonomicon #### The Dark Arts of Advanced and Unsafe Rust Programming diff --git a/src/doc/nomicon/src/SUMMARY.md b/src/doc/nomicon/src/SUMMARY.md index 7390c82896e5..e33dcbbb4188 100644 --- a/src/doc/nomicon/src/SUMMARY.md +++ b/src/doc/nomicon/src/SUMMARY.md @@ -1,3 +1,55 @@ # Summary -- [Chapter 1](./chapter_1.md) +[Introduction](README.md) + +* [Meet Safe and Unsafe](meet-safe-and-unsafe.md) + * [How Safe and Unsafe Interact](safe-unsafe-meaning.md) + * [Working with Unsafe](working-with-unsafe.md) +* [Data Layout](data.md) + * [repr(Rust)](repr-rust.md) + * [Exotically Sized Types](exotic-sizes.md) + * [Other reprs](other-reprs.md) +* [Ownership](ownership.md) + * [References](references.md) + * [Lifetimes](lifetimes.md) + * [Limits of Lifetimes](lifetime-mismatch.md) + * [Lifetime Elision](lifetime-elision.md) + * [Unbounded Lifetimes](unbounded-lifetimes.md) + * [Higher-Rank Trait Bounds](hrtb.md) + * [Subtyping and Variance](subtyping.md) + * [Drop Check](dropck.md) + * [PhantomData](phantom-data.md) + * [Splitting Borrows](borrow-splitting.md) +* [Type Conversions](conversions.md) + * [Coercions](coercions.md) + * [The Dot Operator](dot-operator.md) + * [Casts](casts.md) + * [Transmutes](transmutes.md) +* [Uninitialized Memory](uninitialized.md) + * [Checked](checked-uninit.md) + * [Drop Flags](drop-flags.md) + * [Unchecked](unchecked-uninit.md) +* [Ownership Based Resource Management](obrm.md) + * [Constructors](constructors.md) + * [Destructors](destructors.md) + * [Leaking](leaking.md) +* [Unwinding](unwinding.md) + * [Exception Safety](exception-safety.md) + * [Poisoning](poisoning.md) +* [Concurrency](concurrency.md) + * [Races](races.md) + * [Send and Sync](send-and-sync.md) + * [Atomics](atomics.md) +* [Implementing Vec](vec.md) + * [Layout](vec-layout.md) + * [Allocating](vec-alloc.md) + * [Push and Pop](vec-push-pop.md) + * [Deallocating](vec-dealloc.md) + * [Deref](vec-deref.md) + * [Insert and Remove](vec-insert-remove.md) + * [IntoIter](vec-into-iter.md) + * [RawVec](vec-raw.md) + * [Drain](vec-drain.md) + * [Handling Zero-Sized Types](vec-zsts.md) + * [Final Code](vec-final.md) +* [Implementing Arc and Mutex](arc-and-mutex.md) diff --git a/src/doc/nomicon/arc-and-mutex.md b/src/doc/nomicon/src/arc-and-mutex.md similarity index 89% rename from src/doc/nomicon/arc-and-mutex.md rename to src/doc/nomicon/src/arc-and-mutex.md index fcafe55e409b..fedc7b8bd6a1 100644 --- a/src/doc/nomicon/arc-and-mutex.md +++ b/src/doc/nomicon/src/arc-and-mutex.md @@ -1,4 +1,4 @@ -% Implementing Arc and Mutex +# Implementing Arc and Mutex Knowing the theory is all fine and good, but the *best* way to understand something is to use it. To better understand atomics and interior mutability, diff --git a/src/doc/nomicon/atomics.md b/src/doc/nomicon/src/atomics.md similarity index 99% rename from src/doc/nomicon/atomics.md rename to src/doc/nomicon/src/atomics.md index 7b4c44ff051d..e9ed21a93e00 100644 --- a/src/doc/nomicon/atomics.md +++ b/src/doc/nomicon/src/atomics.md @@ -1,4 +1,4 @@ -% Atomics +# Atomics Rust pretty blatantly just inherits C11's memory model for atomics. This is not due to this model being particularly excellent or easy to understand. Indeed, diff --git a/src/doc/nomicon/borrow-splitting.md b/src/doc/nomicon/src/borrow-splitting.md similarity index 99% rename from src/doc/nomicon/borrow-splitting.md rename to src/doc/nomicon/src/borrow-splitting.md index cc5bc8a602da..28ddb507ae27 100644 --- a/src/doc/nomicon/borrow-splitting.md +++ b/src/doc/nomicon/src/borrow-splitting.md @@ -1,4 +1,4 @@ -% Splitting Borrows +# Splitting Borrows The mutual exclusion property of mutable references can be very limiting when working with a composite structure. The borrow checker understands some basic diff --git a/src/doc/nomicon/casts.md b/src/doc/nomicon/src/casts.md similarity index 99% rename from src/doc/nomicon/casts.md rename to src/doc/nomicon/src/casts.md index 6cc41bd9533c..31b785872454 100644 --- a/src/doc/nomicon/casts.md +++ b/src/doc/nomicon/src/casts.md @@ -1,4 +1,4 @@ -% Casts +# Casts Casts are a superset of coercions: every coercion can be explicitly invoked via a cast. However some conversions require a cast. diff --git a/src/doc/nomicon/checked-uninit.md b/src/doc/nomicon/src/checked-uninit.md similarity index 98% rename from src/doc/nomicon/checked-uninit.md rename to src/doc/nomicon/src/checked-uninit.md index f7c4482a4abf..4423404fe6e9 100644 --- a/src/doc/nomicon/checked-uninit.md +++ b/src/doc/nomicon/src/checked-uninit.md @@ -1,4 +1,4 @@ -% Checked Uninitialized Memory +# Checked Uninitialized Memory Like C, all stack variables in Rust are uninitialized until a value is explicitly assigned to them. Unlike C, Rust statically prevents you from ever diff --git a/src/doc/nomicon/coercions.md b/src/doc/nomicon/src/coercions.md similarity index 99% rename from src/doc/nomicon/coercions.md rename to src/doc/nomicon/src/coercions.md index b699946cecaa..1a51bb5a9c61 100644 --- a/src/doc/nomicon/coercions.md +++ b/src/doc/nomicon/src/coercions.md @@ -1,4 +1,4 @@ -% Coercions +# Coercions Types can implicitly be coerced to change in certain contexts. These changes are generally just *weakening* of types, largely focused around pointers and diff --git a/src/doc/nomicon/concurrency.md b/src/doc/nomicon/src/concurrency.md similarity index 96% rename from src/doc/nomicon/concurrency.md rename to src/doc/nomicon/src/concurrency.md index b93b303f0b96..6205199bfcc4 100644 --- a/src/doc/nomicon/concurrency.md +++ b/src/doc/nomicon/src/concurrency.md @@ -1,4 +1,4 @@ -% Concurrency and Parallelism +# Concurrency and Parallelism Rust as a language doesn't *really* have an opinion on how to do concurrency or parallelism. The standard library exposes OS threads and blocking sys-calls diff --git a/src/doc/nomicon/constructors.md b/src/doc/nomicon/src/constructors.md similarity index 99% rename from src/doc/nomicon/constructors.md rename to src/doc/nomicon/src/constructors.md index 97817cd1f908..b79e72dbae2b 100644 --- a/src/doc/nomicon/constructors.md +++ b/src/doc/nomicon/src/constructors.md @@ -1,4 +1,4 @@ -% Constructors +# Constructors There is exactly one way to create an instance of a user-defined type: name it, and initialize all its fields at once: diff --git a/src/doc/nomicon/conversions.md b/src/doc/nomicon/src/conversions.md similarity index 98% rename from src/doc/nomicon/conversions.md rename to src/doc/nomicon/src/conversions.md index b099a789ec35..388d003d9b6c 100644 --- a/src/doc/nomicon/conversions.md +++ b/src/doc/nomicon/src/conversions.md @@ -1,4 +1,4 @@ -% Type Conversions +# Type Conversions At the end of the day, everything is just a pile of bits somewhere, and type systems are just there to help us use those bits right. There are two common diff --git a/src/doc/nomicon/data.md b/src/doc/nomicon/src/data.md similarity index 87% rename from src/doc/nomicon/data.md rename to src/doc/nomicon/src/data.md index d0a796b7f0bb..bf202ada08e9 100644 --- a/src/doc/nomicon/data.md +++ b/src/doc/nomicon/src/data.md @@ -1,4 +1,4 @@ -% Data Representation in Rust +# Data Representation in Rust Low-level programming cares a lot about data layout. It's a big deal. It also pervasively influences the rest of the language, so we're going to start by diff --git a/src/doc/nomicon/destructors.md b/src/doc/nomicon/src/destructors.md similarity index 99% rename from src/doc/nomicon/destructors.md rename to src/doc/nomicon/src/destructors.md index be4730cf8bce..8c395fe3dc94 100644 --- a/src/doc/nomicon/destructors.md +++ b/src/doc/nomicon/src/destructors.md @@ -1,4 +1,4 @@ -% Destructors +# Destructors What the language *does* provide is full-blown automatic destructors through the `Drop` trait, which provides the following method: diff --git a/src/doc/nomicon/dot-operator.md b/src/doc/nomicon/src/dot-operator.md similarity index 93% rename from src/doc/nomicon/dot-operator.md rename to src/doc/nomicon/src/dot-operator.md index 5d2010d15a80..a1fc33bdc1e3 100644 --- a/src/doc/nomicon/dot-operator.md +++ b/src/doc/nomicon/src/dot-operator.md @@ -1,4 +1,4 @@ -% The Dot Operator +# The Dot Operator The dot operator will perform a lot of magic to convert types. It will perform auto-referencing, auto-dereferencing, and coercion until types match. diff --git a/src/doc/nomicon/drop-flags.md b/src/doc/nomicon/src/drop-flags.md similarity index 99% rename from src/doc/nomicon/drop-flags.md rename to src/doc/nomicon/src/drop-flags.md index cfceafe1bdf2..51fa9d0a3c0f 100644 --- a/src/doc/nomicon/drop-flags.md +++ b/src/doc/nomicon/src/drop-flags.md @@ -1,4 +1,4 @@ -% Drop Flags +# Drop Flags The examples in the previous section introduce an interesting problem for Rust. We have seen that it's possible to conditionally initialize, deinitialize, and diff --git a/src/doc/nomicon/dropck.md b/src/doc/nomicon/src/dropck.md similarity index 99% rename from src/doc/nomicon/dropck.md rename to src/doc/nomicon/src/dropck.md index 6114006cbb34..39039694be67 100644 --- a/src/doc/nomicon/dropck.md +++ b/src/doc/nomicon/src/dropck.md @@ -1,4 +1,4 @@ -% Drop Check +# Drop Check We have seen how lifetimes provide us some fairly simple rules for ensuring that we never read dangling references. However up to this point we have only ever diff --git a/src/doc/nomicon/exception-safety.md b/src/doc/nomicon/src/exception-safety.md similarity index 99% rename from src/doc/nomicon/exception-safety.md rename to src/doc/nomicon/src/exception-safety.md index 74f7831a72af..80e72cd5e36c 100644 --- a/src/doc/nomicon/exception-safety.md +++ b/src/doc/nomicon/src/exception-safety.md @@ -1,4 +1,4 @@ -% Exception Safety +# Exception Safety Although programs should use unwinding sparingly, there's a lot of code that *can* panic. If you unwrap a None, index out of bounds, or divide by 0, your diff --git a/src/doc/nomicon/exotic-sizes.md b/src/doc/nomicon/src/exotic-sizes.md similarity index 99% rename from src/doc/nomicon/exotic-sizes.md rename to src/doc/nomicon/src/exotic-sizes.md index 052e3c5fddc5..9f858d11dbbb 100644 --- a/src/doc/nomicon/exotic-sizes.md +++ b/src/doc/nomicon/src/exotic-sizes.md @@ -1,4 +1,4 @@ -% Exotically Sized Types +# Exotically Sized Types Most of the time, we think in terms of types with a fixed, positive size. This is not always the case, however. diff --git a/src/doc/nomicon/hrtb.md b/src/doc/nomicon/src/hrtb.md similarity index 98% rename from src/doc/nomicon/hrtb.md rename to src/doc/nomicon/src/hrtb.md index 8692832e2c77..645986af13ac 100644 --- a/src/doc/nomicon/hrtb.md +++ b/src/doc/nomicon/src/hrtb.md @@ -1,4 +1,4 @@ -% Higher-Rank Trait Bounds (HRTBs) +# Higher-Rank Trait Bounds (HRTBs) Rust's `Fn` traits are a little bit magic. For instance, we can write the following code: diff --git a/src/doc/nomicon/leaking.md b/src/doc/nomicon/src/leaking.md similarity index 99% rename from src/doc/nomicon/leaking.md rename to src/doc/nomicon/src/leaking.md index a5d5742a4c62..38b70b85b576 100644 --- a/src/doc/nomicon/leaking.md +++ b/src/doc/nomicon/src/leaking.md @@ -1,4 +1,4 @@ -% Leaking +# Leaking Ownership-based resource management is intended to simplify composition. You acquire resources when you create the object, and you release the resources when diff --git a/src/doc/nomicon/lifetime-elision.md b/src/doc/nomicon/src/lifetime-elision.md similarity index 99% rename from src/doc/nomicon/lifetime-elision.md rename to src/doc/nomicon/src/lifetime-elision.md index bcd93a58d859..e92d735a01d6 100644 --- a/src/doc/nomicon/lifetime-elision.md +++ b/src/doc/nomicon/src/lifetime-elision.md @@ -1,4 +1,4 @@ -% Lifetime Elision +# Lifetime Elision In order to make common patterns more ergonomic, Rust allows lifetimes to be *elided* in function signatures. diff --git a/src/doc/nomicon/lifetime-mismatch.md b/src/doc/nomicon/src/lifetime-mismatch.md similarity index 98% rename from src/doc/nomicon/lifetime-mismatch.md rename to src/doc/nomicon/src/lifetime-mismatch.md index 0ad8a78880e5..30b4f09f9032 100644 --- a/src/doc/nomicon/lifetime-mismatch.md +++ b/src/doc/nomicon/src/lifetime-mismatch.md @@ -1,4 +1,4 @@ -% Limits of Lifetimes +# Limits of Lifetimes Given the following code: diff --git a/src/doc/nomicon/lifetimes.md b/src/doc/nomicon/src/lifetimes.md similarity index 99% rename from src/doc/nomicon/lifetimes.md rename to src/doc/nomicon/src/lifetimes.md index 45eb68baeb73..e2f0cc867723 100644 --- a/src/doc/nomicon/lifetimes.md +++ b/src/doc/nomicon/src/lifetimes.md @@ -1,4 +1,4 @@ -% Lifetimes +# Lifetimes Rust enforces these rules through *lifetimes*. Lifetimes are effectively just names for scopes somewhere in the program. Each reference, diff --git a/src/doc/nomicon/meet-safe-and-unsafe.md b/src/doc/nomicon/src/meet-safe-and-unsafe.md similarity index 99% rename from src/doc/nomicon/meet-safe-and-unsafe.md rename to src/doc/nomicon/src/meet-safe-and-unsafe.md index 15d84fdbf293..d42d0b6d7255 100644 --- a/src/doc/nomicon/meet-safe-and-unsafe.md +++ b/src/doc/nomicon/src/meet-safe-and-unsafe.md @@ -1,4 +1,4 @@ -% Meet Safe and Unsafe +# Meet Safe and Unsafe Programmers in safe "high-level" languages face a fundamental dilemma. On one hand, it would be *really* great to just say what you want and not worry about diff --git a/src/doc/nomicon/obrm.md b/src/doc/nomicon/src/obrm.md similarity index 93% rename from src/doc/nomicon/obrm.md rename to src/doc/nomicon/src/obrm.md index 2c495240c127..19e5ec382595 100644 --- a/src/doc/nomicon/obrm.md +++ b/src/doc/nomicon/src/obrm.md @@ -1,4 +1,4 @@ -% The Perils Of Ownership Based Resource Management (OBRM) +# The Perils Of Ownership Based Resource Management (OBRM) OBRM (AKA RAII: Resource Acquisition Is Initialization) is something you'll interact with a lot in Rust. Especially if you use the standard library. diff --git a/src/doc/nomicon/other-reprs.md b/src/doc/nomicon/src/other-reprs.md similarity index 99% rename from src/doc/nomicon/other-reprs.md rename to src/doc/nomicon/src/other-reprs.md index b124f3ffc465..02f39e3c4dd2 100644 --- a/src/doc/nomicon/other-reprs.md +++ b/src/doc/nomicon/src/other-reprs.md @@ -1,4 +1,4 @@ -% Alternative representations +# Alternative representations Rust allows you to specify alternative data layout strategies from the default. diff --git a/src/doc/nomicon/ownership.md b/src/doc/nomicon/src/ownership.md similarity index 99% rename from src/doc/nomicon/ownership.md rename to src/doc/nomicon/src/ownership.md index a6ecf6ab91b4..dd9e9db244a8 100644 --- a/src/doc/nomicon/ownership.md +++ b/src/doc/nomicon/src/ownership.md @@ -1,4 +1,4 @@ -% Ownership and Lifetimes +# Ownership and Lifetimes Ownership is the breakout feature of Rust. It allows Rust to be completely memory-safe and efficient, while avoiding garbage collection. Before getting diff --git a/src/doc/nomicon/phantom-data.md b/src/doc/nomicon/src/phantom-data.md similarity index 99% rename from src/doc/nomicon/phantom-data.md rename to src/doc/nomicon/src/phantom-data.md index 189695716deb..72fa2e2a7776 100644 --- a/src/doc/nomicon/phantom-data.md +++ b/src/doc/nomicon/src/phantom-data.md @@ -1,4 +1,4 @@ -% PhantomData +# PhantomData When working with unsafe code, we can often end up in a situation where types or lifetimes are logically associated with a struct, but not actually diff --git a/src/doc/nomicon/poisoning.md b/src/doc/nomicon/src/poisoning.md similarity index 99% rename from src/doc/nomicon/poisoning.md rename to src/doc/nomicon/src/poisoning.md index 70de91af61f6..9b5dec3eec38 100644 --- a/src/doc/nomicon/poisoning.md +++ b/src/doc/nomicon/src/poisoning.md @@ -1,4 +1,4 @@ -% Poisoning +# Poisoning Although all unsafe code *must* ensure it has minimal exception safety, not all types ensure *maximal* exception safety. Even if the type does, your code may diff --git a/src/doc/nomicon/races.md b/src/doc/nomicon/src/races.md similarity index 99% rename from src/doc/nomicon/races.md rename to src/doc/nomicon/src/races.md index 5145987158ab..c9b8c3d01b2f 100644 --- a/src/doc/nomicon/races.md +++ b/src/doc/nomicon/src/races.md @@ -1,4 +1,4 @@ -% Data Races and Race Conditions +# Data Races and Race Conditions Safe Rust guarantees an absence of data races, which are defined as: diff --git a/src/doc/nomicon/references.md b/src/doc/nomicon/src/references.md similarity index 99% rename from src/doc/nomicon/references.md rename to src/doc/nomicon/src/references.md index 3d7369eca0fe..5d80f1edd964 100644 --- a/src/doc/nomicon/references.md +++ b/src/doc/nomicon/src/references.md @@ -1,4 +1,4 @@ -% References +# References This section gives a high-level view of the memory model that *all* Rust programs must satisfy to be correct. Safe code is statically verified diff --git a/src/doc/nomicon/repr-rust.md b/src/doc/nomicon/src/repr-rust.md similarity index 99% rename from src/doc/nomicon/repr-rust.md rename to src/doc/nomicon/src/repr-rust.md index effeaf872bbe..c02cf44189f1 100644 --- a/src/doc/nomicon/repr-rust.md +++ b/src/doc/nomicon/src/repr-rust.md @@ -1,4 +1,4 @@ -% repr(Rust) +# repr(Rust) First and foremost, all types have an alignment specified in bytes. The alignment of a type specifies what addresses are valid to store the value at. A diff --git a/src/doc/nomicon/safe-unsafe-meaning.md b/src/doc/nomicon/src/safe-unsafe-meaning.md similarity index 99% rename from src/doc/nomicon/safe-unsafe-meaning.md rename to src/doc/nomicon/src/safe-unsafe-meaning.md index adede0ec9111..0a655a3f53a2 100644 --- a/src/doc/nomicon/safe-unsafe-meaning.md +++ b/src/doc/nomicon/src/safe-unsafe-meaning.md @@ -1,4 +1,4 @@ -% How Safe and Unsafe Interact +# How Safe and Unsafe Interact What's the relationship between Safe Rust and Unsafe Rust? How do they interact? diff --git a/src/doc/nomicon/send-and-sync.md b/src/doc/nomicon/src/send-and-sync.md similarity index 99% rename from src/doc/nomicon/send-and-sync.md rename to src/doc/nomicon/src/send-and-sync.md index 134e47f18dcf..959f870d4e64 100644 --- a/src/doc/nomicon/send-and-sync.md +++ b/src/doc/nomicon/src/send-and-sync.md @@ -1,4 +1,4 @@ -% Send and Sync +# Send and Sync Not everything obeys inherited mutability, though. Some types allow you to multiply alias a location in memory while mutating it. Unless these types use diff --git a/src/doc/nomicon/subtyping.md b/src/doc/nomicon/src/subtyping.md similarity index 99% rename from src/doc/nomicon/subtyping.md rename to src/doc/nomicon/src/subtyping.md index eb940e811a4f..d771712d0501 100644 --- a/src/doc/nomicon/subtyping.md +++ b/src/doc/nomicon/src/subtyping.md @@ -1,4 +1,4 @@ -% Subtyping and Variance +# Subtyping and Variance Although Rust doesn't have any notion of structural inheritance, it *does* include subtyping. In Rust, subtyping derives entirely from lifetimes. Since diff --git a/src/doc/nomicon/transmutes.md b/src/doc/nomicon/src/transmutes.md similarity index 99% rename from src/doc/nomicon/transmutes.md rename to src/doc/nomicon/src/transmutes.md index f1478b7f668d..043c8fe46259 100644 --- a/src/doc/nomicon/transmutes.md +++ b/src/doc/nomicon/src/transmutes.md @@ -1,4 +1,4 @@ -% Transmutes +# Transmutes Get out of our way type system! We're going to reinterpret these bits or die trying! Even though this book is all about doing things that are unsafe, I diff --git a/src/doc/nomicon/unbounded-lifetimes.md b/src/doc/nomicon/src/unbounded-lifetimes.md similarity index 98% rename from src/doc/nomicon/unbounded-lifetimes.md rename to src/doc/nomicon/src/unbounded-lifetimes.md index 1f3693f542f3..b41cf8b4ed91 100644 --- a/src/doc/nomicon/unbounded-lifetimes.md +++ b/src/doc/nomicon/src/unbounded-lifetimes.md @@ -1,4 +1,4 @@ -% Unbounded Lifetimes +# Unbounded Lifetimes Unsafe code can often end up producing references or lifetimes out of thin air. Such lifetimes come into the world as *unbounded*. The most common source of this diff --git a/src/doc/nomicon/unchecked-uninit.md b/src/doc/nomicon/src/unchecked-uninit.md similarity index 99% rename from src/doc/nomicon/unchecked-uninit.md rename to src/doc/nomicon/src/unchecked-uninit.md index c72ed8a76329..ef31a3535d6a 100644 --- a/src/doc/nomicon/unchecked-uninit.md +++ b/src/doc/nomicon/src/unchecked-uninit.md @@ -1,4 +1,4 @@ -% Unchecked Uninitialized Memory +# Unchecked Uninitialized Memory One interesting exception to this rule is working with arrays. Safe Rust doesn't permit you to partially initialize an array. When you initialize an array, you diff --git a/src/doc/nomicon/uninitialized.md b/src/doc/nomicon/src/uninitialized.md similarity index 93% rename from src/doc/nomicon/uninitialized.md rename to src/doc/nomicon/src/uninitialized.md index 05615d89bec7..eafc67907f2a 100644 --- a/src/doc/nomicon/uninitialized.md +++ b/src/doc/nomicon/src/uninitialized.md @@ -1,4 +1,4 @@ -% Working With Uninitialized Memory +# Working With Uninitialized Memory All runtime-allocated memory in a Rust program begins its life as *uninitialized*. In this state the value of the memory is an indeterminate pile diff --git a/src/doc/nomicon/unwinding.md b/src/doc/nomicon/src/unwinding.md similarity index 99% rename from src/doc/nomicon/unwinding.md rename to src/doc/nomicon/src/unwinding.md index e81f06b83b24..6dc396d51534 100644 --- a/src/doc/nomicon/unwinding.md +++ b/src/doc/nomicon/src/unwinding.md @@ -1,4 +1,4 @@ -% Unwinding +# Unwinding Rust has a *tiered* error-handling scheme: diff --git a/src/doc/nomicon/vec-alloc.md b/src/doc/nomicon/src/vec-alloc.md similarity index 99% rename from src/doc/nomicon/vec-alloc.md rename to src/doc/nomicon/src/vec-alloc.md index bc60a577bd35..ef4c52793433 100644 --- a/src/doc/nomicon/vec-alloc.md +++ b/src/doc/nomicon/src/vec-alloc.md @@ -1,4 +1,4 @@ -% Allocating Memory +# Allocating Memory Using Unique throws a wrench in an important feature of Vec (and indeed all of the std collections): an empty Vec doesn't actually allocate at all. So if we diff --git a/src/doc/nomicon/vec-dealloc.md b/src/doc/nomicon/src/vec-dealloc.md similarity index 98% rename from src/doc/nomicon/vec-dealloc.md rename to src/doc/nomicon/src/vec-dealloc.md index 706fe680e006..83ab5b24b024 100644 --- a/src/doc/nomicon/vec-dealloc.md +++ b/src/doc/nomicon/src/vec-dealloc.md @@ -1,4 +1,4 @@ -% Deallocating +# Deallocating Next we should implement Drop so that we don't massively leak tons of resources. The easiest way is to just call `pop` until it yields None, and then deallocate diff --git a/src/doc/nomicon/vec-deref.md b/src/doc/nomicon/src/vec-deref.md similarity index 99% rename from src/doc/nomicon/vec-deref.md rename to src/doc/nomicon/src/vec-deref.md index 6460eab479bd..e21542c955ae 100644 --- a/src/doc/nomicon/vec-deref.md +++ b/src/doc/nomicon/src/vec-deref.md @@ -1,4 +1,4 @@ -% Deref +# Deref Alright! We've got a decent minimal stack implemented. We can push, we can pop, and we can clean up after ourselves. However there's a whole mess of diff --git a/src/doc/nomicon/vec-drain.md b/src/doc/nomicon/src/vec-drain.md similarity index 99% rename from src/doc/nomicon/vec-drain.md rename to src/doc/nomicon/src/vec-drain.md index 6e732ee10742..5bd2bf05d8c0 100644 --- a/src/doc/nomicon/vec-drain.md +++ b/src/doc/nomicon/src/vec-drain.md @@ -1,4 +1,4 @@ -% Drain +# Drain Let's move on to Drain. Drain is largely the same as IntoIter, except that instead of consuming the Vec, it borrows the Vec and leaves its allocation diff --git a/src/doc/nomicon/vec-final.md b/src/doc/nomicon/src/vec-final.md similarity index 99% rename from src/doc/nomicon/vec-final.md rename to src/doc/nomicon/src/vec-final.md index 1f4377a7ca33..39746cad781f 100644 --- a/src/doc/nomicon/vec-final.md +++ b/src/doc/nomicon/src/vec-final.md @@ -1,4 +1,4 @@ -% The Final Code +# The Final Code ```rust #![feature(unique)] diff --git a/src/doc/nomicon/vec-insert-remove.md b/src/doc/nomicon/src/vec-insert-remove.md similarity index 98% rename from src/doc/nomicon/vec-insert-remove.md rename to src/doc/nomicon/src/vec-insert-remove.md index bcecd78a1b75..2c14bc452272 100644 --- a/src/doc/nomicon/vec-insert-remove.md +++ b/src/doc/nomicon/src/vec-insert-remove.md @@ -1,4 +1,4 @@ -% Insert and Remove +# Insert and Remove Something *not* provided by slice is `insert` and `remove`, so let's do those next. diff --git a/src/doc/nomicon/vec-into-iter.md b/src/doc/nomicon/src/vec-into-iter.md similarity index 99% rename from src/doc/nomicon/vec-into-iter.md rename to src/doc/nomicon/src/vec-into-iter.md index ebb0a79bb651..f2f5995ec1cb 100644 --- a/src/doc/nomicon/vec-into-iter.md +++ b/src/doc/nomicon/src/vec-into-iter.md @@ -1,4 +1,4 @@ -% IntoIter +# IntoIter Let's move on to writing iterators. `iter` and `iter_mut` have already been written for us thanks to The Magic of Deref. However there's two interesting diff --git a/src/doc/nomicon/vec-layout.md b/src/doc/nomicon/src/vec-layout.md similarity index 99% rename from src/doc/nomicon/vec-layout.md rename to src/doc/nomicon/src/vec-layout.md index 7ca369da0b88..1dc09aef6ad2 100644 --- a/src/doc/nomicon/vec-layout.md +++ b/src/doc/nomicon/src/vec-layout.md @@ -1,4 +1,4 @@ -% Layout +# Layout First off, we need to come up with the struct layout. A Vec has three parts: a pointer to the allocation, the size of the allocation, and the number of diff --git a/src/doc/nomicon/vec-push-pop.md b/src/doc/nomicon/src/vec-push-pop.md similarity index 99% rename from src/doc/nomicon/vec-push-pop.md rename to src/doc/nomicon/src/vec-push-pop.md index 5e747a8c71d4..d31a74cc308d 100644 --- a/src/doc/nomicon/vec-push-pop.md +++ b/src/doc/nomicon/src/vec-push-pop.md @@ -1,4 +1,4 @@ -% Push and Pop +# Push and Pop Alright. We can initialize. We can allocate. Let's actually implement some functionality! Let's start with `push`. All it needs to do is check if we're diff --git a/src/doc/nomicon/vec-raw.md b/src/doc/nomicon/src/vec-raw.md similarity index 99% rename from src/doc/nomicon/vec-raw.md rename to src/doc/nomicon/src/vec-raw.md index 8f78462cf402..20fa8ab92c24 100644 --- a/src/doc/nomicon/vec-raw.md +++ b/src/doc/nomicon/src/vec-raw.md @@ -1,4 +1,4 @@ -% RawVec +# RawVec We've actually reached an interesting situation here: we've duplicated the logic for specifying a buffer and freeing its memory in Vec and IntoIter. Now that diff --git a/src/doc/nomicon/vec-zsts.md b/src/doc/nomicon/src/vec-zsts.md similarity index 99% rename from src/doc/nomicon/vec-zsts.md rename to src/doc/nomicon/src/vec-zsts.md index 5f3b2a81364e..5ae9bdd32747 100644 --- a/src/doc/nomicon/vec-zsts.md +++ b/src/doc/nomicon/src/vec-zsts.md @@ -1,4 +1,4 @@ -% Handling Zero-Sized Types +# Handling Zero-Sized Types It's time. We're going to fight the specter that is zero-sized types. Safe Rust *never* needs to care about this, but Vec is very intensive on raw pointers and diff --git a/src/doc/nomicon/vec.md b/src/doc/nomicon/src/vec.md similarity index 97% rename from src/doc/nomicon/vec.md rename to src/doc/nomicon/src/vec.md index 691301946de4..ad98e45f197b 100644 --- a/src/doc/nomicon/vec.md +++ b/src/doc/nomicon/src/vec.md @@ -1,4 +1,4 @@ -% Example: Implementing Vec +# Example: Implementing Vec To bring everything together, we're going to write `std::Vec` from scratch. Because all the best tools for writing unsafe code are unstable, this diff --git a/src/doc/nomicon/working-with-unsafe.md b/src/doc/nomicon/src/working-with-unsafe.md similarity index 99% rename from src/doc/nomicon/working-with-unsafe.md rename to src/doc/nomicon/src/working-with-unsafe.md index b20dff72e1c6..5724f3d09a30 100644 --- a/src/doc/nomicon/working-with-unsafe.md +++ b/src/doc/nomicon/src/working-with-unsafe.md @@ -1,4 +1,4 @@ -% Working with Unsafe +# Working with Unsafe Rust generally only gives us the tools to talk about Unsafe Rust in a scoped and binary manner. Unfortunately, reality is significantly more complicated than