Define what "safe"means (#347)

Fixes: rdar://126308272

Author: amartini51

TSPL.docc/LanguageGuide/TheBasics.md

@@ -21,19 +21,28 @@ Swift introduces advanced types such as tuples.
 Tuples enable you to create and pass around groupings of values.
 You can use a tuple to return multiple values from a function as a single compound value.
 
-Swift also introduces optional types,
-which handle the absence of a value.
-Optionals say either “there *is* a value, and it equals *x*”
+Swift handles the absence of a value
+using optional types.
+Optionals say either “there *is* a value, which is *x*”
 or “there *isn't* a value at all”.
-
-Swift is a *type-safe* language,
-which means the language helps you to be clear about the types of values your code can work with.
+Optionals ensure that code always
+checks whether a value is missing before using the value,
+and non-optional values are guaranteed to never be missing.
+
+Swift is a safe language,
+which means it makes it easier for you find and fix several categories of bugs
+as early as possible during the development process,
+and lets you guarantee that certain kinds of bugs can't happen.
+Type safety enables you to be clear about
+the types of values your code works with.
 If part of your code requires a `String`,
 type safety prevents you from passing it an `Int` by mistake.
-Likewise, type safety prevents you from
-accidentally passing an optional `String`
-to a piece of code that requires a non-optional `String`.
-Type safety helps you catch and fix errors as early as possible in the development process.
+Memory safety ensures that you work with valid data only,
+not uninitialized memory or deinitialized objects,
+and ensures that you work with that data in safe ways ---
+even in programs that run multiple pieces of code at the same time.
+Swift performs most of its safety checks while building your code,
+and in some cases performs additional checks while your code is running.
 
 ## Constants and Variables
 
@@ -561,17 +570,28 @@ Swift provides two signed floating-point number types:
 
 ## Type Safety and Type Inference
 
-Swift is a *type-safe* language.
-A type safe language encourages you to be clear about
-the types of values your code can work with.
-If part of your code requires a `String`, you can't pass it an `Int` by mistake.
+Every value in a Swift program has a type.
+Every place you store a value ---
+including constants, variables, and properties ---
+also has a type.
+You might write the type explicitly using a type annotation,
+or Swift might infer the type from an initial value.
+Every place in your code where you provide a value,
+that value's type must match the place you use it.
+For example,
+if part of your code requires a `String`,
+you can't pass it an `Int` by mistake.
+This kind of checking makes Swift a *type-safe* language.
 
-Because Swift is type safe,
-it performs *type checks* when compiling your code
+A type safe language encourages you to be clear about
+the types of values your code works with.
+Values of one type are never implicitly converted to another type.
+However, some types can be explicitly converted.
+When building code,
+Swift checks the code for type safety
 and flags any mismatched types as errors.
-This enables you to catch and fix errors as early as possible in the development process.
 
-Type-checking helps you avoid errors when you're working with different types of values.
+Type checking helps you avoid errors when you're working with different types of values.
 However, this doesn't mean that you have to specify the type of
 every constant and variable that you declare.
 If you don't specify the type of value you need,
@@ -1000,8 +1020,6 @@ they were initialized with Boolean literal values.
 As with `Int` and `Double` above,
 you don't need to declare constants or variables as `Bool`
 if you set them to `true` or `false` as soon as you create them.
-Type inference helps make Swift code more concise and readable
-when it initializes constants or variables with other values whose type is already known.
 
 Boolean values are particularly useful when you work with conditional statements
 such as the `if` statement:
@@ -1076,7 +1094,7 @@ if i == 1 {
 -->
 
 The result of the `i == 1` comparison is of type `Bool`,
-and so this second example passes the type-check.
+and so this second example passes the type checking.
 Comparisons like `i == 1` are discussed in <doc:BasicOperators>.
 
 As with other examples of type safety in Swift,
@@ -1778,6 +1796,58 @@ if let definiteString = assumedString {
   ```
 -->
 
+## Memory Safety
+
+In addition to the checks that prevent type mismatches,
+described above in <doc:TheBasics#Type-Safety-and-Type-Inference>,
+Swift also protects code against working with invalid memory.
+This protection is known as *memory safety*
+and includes the following requirements:
+
+- Values are set before being read.
+  The protection against interacting with uninitialized regions of memory
+  is also known as *definite initialization*.
+- Arrays and buffers are accessed only at valid indexes.
+  The protection against out-of-bounds access
+  is also known as *bounds safety*.
+- Memory is accessed only during the value’s lifetime.
+  The protection against use-after-free errors
+  is also known as *lifetime safety*.
+- Access to memory overlaps only in provably safe ways.
+  The protection against possible data races in concurrent code
+  is also known as *thread safety*.
+
+If you've worked in languages that don't provide these guarantees,
+you may be familiar with some of the errors and bugs
+named in the list above.
+If you haven't encountered these issues, that's ok;
+safe code in Swift avoids these problems.
+For information about how Swift ensures you set initial values,
+see <doc:Initialization>,
+for information about how Swift checks memory safety in concurrent code,
+see <doc:Concurrency>,
+and for information about how Swift checks overlapping accesses to memory,
+see <doc:MemorySafety>.
+
+Sometimes you need to work outside of the bounds of safety ---
+for example, because of limitations of the language or standard library ---
+so Swift also provides unsafe versions of some APIs.
+When you use types or methods whose name includes words such as
+"unsafe", "unchecked", or "unmanaged",
+you take on the responsibility for safety.
+
+Safe code in Swift can still encounter errors and unexpected failures,
+which might stop the program's execution.
+Safety doesn't ensure that your code runs to completion.
+Swift provides several ways to indicate and recover from errors,
+discussed in <doc:TheBasics#Error-Handling>
+and <doc:TheBasics#Assertions-and-Preconditions> below.
+However, in some cases,
+the *only* safe way to handle an error is to stop execution.
+If you need to guarantee that a service never unexpected stops,
+incorporate fault tolerance into its overall architecture,
+so it can recover from any of its components stopping unexpectedly.
+
 ## Error Handling
 
 You use *error handling* to respond to error conditions