Primitive types (#1975)

A few changes:
- Merge content from the `primitive_types.md` design doc into the overall design `README.md` since there was so much overlap and no need for two copies.
- Consistently spell integer types `Carbon.Int(N)` and `Carbon.UInt(N)`, including the `Carbon.` prefix and avoiding `Unsigned(N)`.
- Consistently use a comprehensive set of floating-point types.
- Incorporates #2015 into the design docs.

docs/design/README.md

@@ -9,6 +9,8 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 > **STATUS:** Up-to-date on 09-Aug-2022, including proposals up through
 > [#1327](https://github.com/carbon-language/carbon-lang/pull/1327).
 
+> FIXME: add #2015
+
 <!-- toc -->
 
 ## Table of contents
@@ -409,21 +411,27 @@ Primitive types fall into the following categories:
 
 These are made available through the [prelude](#name-lookup-for-common-types).
 
-> References: [Primitive types](primitive_types.md)
-
 ### `bool`
 
 The type `bool` is a boolean type with two possible values: `true` and `false`.
+The names `bool`, `true`, and `false` are keywords.
 [Comparison expressions](#expressions) produce `bool` values. The condition
 arguments in [control-flow statements](#control-flow), like [`if`](#if-and-else)
 and [`while`](#while), and
 [`if`-`then`-`else` conditional expressions](#expressions) take `bool` values.
 
+> References:
+>
+> -   Question-for-leads issue
+>     [#750: Naming conventions for Carbon-provided features](https://github.com/carbon-language/carbon-lang/issues/750)
+> -   Proposal
+>     [#861: Naming conventions](https://github.com/carbon-language/carbon-lang/pull/861)
+
 ### Integer types
 
-The signed-integer type with bit width `N` may be written `Carbon.Int(N)`. For
-convenience and brevity, the common power-of-two sizes may be written with an
-`i` followed by the size: `i8`, `i16`, `i32`, `i64`, or `i128`. Signed-integer
+The signed-integer type with bit width `N` may be written `iN` or
+`Carbon.Int(N)`, as long as `N` is a positive multiple of 8. For example, `i32`
+is equivalent to `Carbon.Int(32)`. Signed-integer
 [overflow](expressions/arithmetic.md#overflow-and-other-error-conditions) is a
 programming error:
 
@@ -437,25 +445,40 @@ programming error:
     to a mathematically incorrect result, such as a two's complement result or
     zero.
 
-The unsigned-integer types are: `u8`, `u16`, `u32`, `u64`, `u128`, and
-`Carbon.UInt(N)`. Unsigned integer types wrap around on overflow, we strongly
-advise that they are not used except when those semantics are desired. These
-types are intended for bit manipulation or modular arithmetic as often found in
-[hashing](https://en.wikipedia.org/wiki/Hash_function),
+The unsigned-integer types are written `uN` or `Carbon.UInt(N)`, with `N` a
+positive multiple of 8. Unsigned integer types wrap around on overflow; we
+strongly advise that they are not used except when those semantics are desired.
+These types are intended for bit manipulation or modular arithmetic as often
+found in [hashing](https://en.wikipedia.org/wiki/Hash_function),
 [cryptography](https://en.wikipedia.org/wiki/Cryptography), and
 [PRNG](https://en.wikipedia.org/wiki/Pseudorandom_number_generator) use cases.
 Values which can never be negative, like sizes, but for which wrapping does not
 make sense
 [should use signed integer types](/proposals/p1083.md#dont-let-unsigned-arithmetic-wrap).
 
+Identifiers of the form `iN` and `uN` are _type literals_, resulting in the
+corresponding type.
+
+Not all operations will be supported for all bit sizes. For example, division
+may be limited to integers of at most 128 bits due to LLVM limitations.
+
+> **Open question:** Bit-field ([1](https://en.wikipedia.org/wiki/Bit_field),
+> [2](https://en.cppreference.com/w/cpp/language/bit_field)) support will need
+> some way to talk about non-multiple-of-eight-bit integers, even though Carbon
+> will likely not support pointers to those types.
+
 > References:
 >
 > -   Question-for-leads issue
 >     [#543: pick names for fixed-size integer types](https://github.com/carbon-language/carbon-lang/issues/543)
+> -   Question-for-leads issue
+>     [#750: Naming conventions for Carbon-provided features](https://github.com/carbon-language/carbon-lang/issues/750)
 > -   Proposal
->     [#820: Implicit conversions](https://github.com/carbon-language/carbon-lang/pull/820)
+>     [#861: Naming conventions](https://github.com/carbon-language/carbon-lang/pull/861)
 > -   Proposal
 >     [#1083: Arithmetic expressions](https://github.com/carbon-language/carbon-lang/pull/1083)
+> -   Proposal
+>     [#2015: Numeric type literal syntax](https://github.com/carbon-language/carbon-lang/pull/2015)
 
 #### Integer literals
 
@@ -489,19 +512,38 @@ represent that value.
 
 ### Floating-point types
 
-Floating-point types in Carbon have IEEE 754 semantics, use the round-to-nearest
+Floating-point types in Carbon have IEEE-754 semantics, use the round-to-nearest
 rounding mode, and do not set any floating-point exception state. They are named
-with an `f` and the number of bits: `f16`, `f32`, `f64`, and `f128`.
-[`BFloat16`](primitive_types.md#bfloat16) is also provided.
+with a _type literals_, consisting of `f` and the number of bits, which must be
+a multiple of 8. The type literal `fN` results in the type `Carbon.Float(N)`.
+These types will always be available:
+[`f16`](https://en.wikipedia.org/wiki/Half-precision_floating-point_format),
+[`f32`](https://en.wikipedia.org/wiki/Single-precision_floating-point_format),
+and
+[`f64`](https://en.wikipedia.org/wiki/Double-precision_floating-point_format).
+Other sizes may be available, depending on the platform, such as
+[`f80`](https://en.wikipedia.org/wiki/Extended_precision),
+[`f128`](https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format),
+or
+[`f256`](https://en.wikipedia.org/wiki/Octuple-precision_floating-point_format).
+
+Carbon also supports the
+[`BFloat16`](https://en.wikipedia.org/wiki/Bfloat16_floating-point_format)
+format, a 16-bit truncation of a "binary32" IEEE-754 format floating point
+number.
 
 > References:
 >
 > -   Question-for-leads issue
 >     [#543: pick names for fixed-size integer types](https://github.com/carbon-language/carbon-lang/issues/543)
+> -   Question-for-leads issue
+>     [#750: Naming conventions for Carbon-provided features](https://github.com/carbon-language/carbon-lang/issues/750)
 > -   Proposal
->     [#820: Implicit conversions](https://github.com/carbon-language/carbon-lang/pull/820)
+>     [#861: Naming conventions](https://github.com/carbon-language/carbon-lang/pull/861)
 > -   Proposal
 >     [#1083: Arithmetic expressions](https://github.com/carbon-language/carbon-lang/pull/1083)
+> -   Proposal
+>     [#2015: Numeric type literal syntax](https://github.com/carbon-language/carbon-lang/pull/2015)
 
 #### Floating-point literals
 
@@ -546,6 +588,18 @@ There are two string types:
 -   `StringView` - a read-only reference to a byte sequence treated as
     containing UTF-8 encoded text.
 
+There is an [implicit conversion](expressions/implicit_conversions.md) from
+`String` to `StringView`.
+
+> References:
+>
+> -   Question-for-leads issue
+>     [#750: Naming conventions for Carbon-provided features](https://github.com/carbon-language/carbon-lang/issues/750)
+> -   Proposal
+>     [#820: Implicit conversions](https://github.com/carbon-language/carbon-lang/pull/820)
+> -   Proposal
+>     [#861: Naming conventions](https://github.com/carbon-language/carbon-lang/pull/861)
+
 #### String literals
 
 String literals may be written on a single line using a double quotation mark

docs/design/expressions/implicit_conversions.md

@@ -83,7 +83,7 @@ members in a derived class pointer versus in a base class pointer.
 
 ### Examples
 
-Conversion from `i32` to `Vector(int)` by forming a vector of N zeroes is
+Conversion from `i32` to `Vector(i32)` by forming a vector of N zeroes is
 lossless but not semantics-preserving.
 
 Conversion from `i32` to `f32` by rounding to the nearest representable value is
@@ -106,12 +106,12 @@ The following implicit numeric conversions are available:
 -   `fN` -> `fM` if `M` > `N`
 -   `iN` or `uN` -> `fM` if every value of type `iN` or `uN` can be represented
     in `fM`:
-    -   `i12` or `u11` (or smaller) -> `f16`
-    -   `i25` or `u24` (or smaller) -> `f32`
-    -   `i54` or `u53` (or smaller) -> `f64`
-    -   `i65` or `u64` (or smaller) -> `f80` (x86 only)
-    -   `i114` or `u113` (or smaller) -> `f128` (if available)
-    -   `i238` or `u237` (or smaller) -> `f256` (if available)
+    -   `i8` or `u8` -> `f16`
+    -   `i24` or `u24` (or smaller) -> `f32`
+    -   `i48` or `u48` (or smaller) -> `f64`
+    -   `i64` or `u64` (or smaller) -> `f80` (x86 only)
+    -   `i112` or `u112` (or smaller) -> `f128` (if available)
+    -   `i232` or `u232` (or smaller) -> `f256` (if available)
 
 In each case, the numerical value is the same before and after the conversion.
 An integer zero is translated into a floating-point positive zero.

docs/design/primitive_types.md

@@ -1,104 +0,0 @@
-# Primitive types
-
-<!--
-Part of the Carbon Language project, under the Apache License v2.0 with LLVM
-Exceptions. See /LICENSE for license information.
-SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
--->
-
-<!-- toc -->
-
-## Table of contents
-
--   [TODO](#todo)
--   [Overview](#overview)
-    -   [Integers](#integers)
-    -   [Floats](#floats)
-    -   [BFloat16](#bfloat16)
--   [Open questions](#open-questions)
-    -   [Primitive types as code vs built-in](#primitive-types-as-code-vs-built-in)
-    -   [String view vs owning string](#string-view-vs-owning-string)
-    -   [Syntax for wrapping operations](#syntax-for-wrapping-operations)
-    -   [Non-power-of-two sizes](#non-power-of-two-sizes)
-
-<!-- tocstop -->
-
-## TODO
-
-This is a skeletal design, added to support [the overview](README.md). It should
-not be treated as accepted by the core team; rather, it is a placeholder until
-we have more time to examine this detail. Please feel welcome to rewrite and
-update as appropriate.
-
-## Overview
-
-These types are fundamental to the language as they aren't either formed from or
-modifying other types. They also have semantics that are defined from first
-principles rather than in terms of other operations. These will be made
-available through the [prelude package](README.md#name-lookup-for-common-types).
-
--   `bool` - a boolean type with two possible values: `true` and `false`.
--   Signed and unsigned 64-bit integer types:
-    -   Standard sizes are available, both signed and unsigned, including `i8`,
-        `i16`, `i32`, `i64`, and `i128`, and `u8`, `u16`, `u32`, `u64`, and
-        `u128`.
-    -   Signed overflow in either direction is an error.
--   Floating points type with semantics based on IEEE-754.
-    -   Standard sizes are available, including `f16`, `f32`, and `f64`.
-    -   [`BFloat16`](primitive_types.md#bfloat16) is also provided.
--   `String` - a byte sequence treated as containing UTF-8 encoded text.
-    -   `StringView` - a read-only reference to a byte sequence treated as
-        containing UTF-8 encoded text.
-
-The names `bool`, `true`, and `false` are keywords, and identifiers of the form
-`i[0-9]*`, `u[0-9]*`, and `f[0-9*]` are _type literals_, resulting in the
-corresponding type.
-
-### Integers
-
-Integer types can be either signed or unsigned, much like in C++. Signed
-integers are represented using 2's complement and notionally modeled as
-unbounded natural numbers. Signed overflow in either direction is an error.
-Specific sizes are available, for example: `i8`, `u16`, `i32`, and `u128`.
-
-There is an upper bound on the size of an integer, most likely initially set to
-128 bits due to LLVM limitations.
-
-### Floats
-
-Floating point types are based on the binary floating point formats provided by
-IEEE-754. `f16`, `f32`, `f64` and, if available, `f128` correspond exactly to
-those sized IEEE-754 formats, and have the semantics defined by IEEE-754.
-
-### BFloat16
-
-Carbon also supports the
-[`BFloat16`](https://en.wikipedia.org/wiki/Bfloat16_floating-point_format)
-format, a 16-bit truncation of a "binary32" IEEE-754 format floating point
-number.
-
-## Open questions
-
-### Primitive types as code vs built-in
-
-There are open questions about the extent to which these types should be defined
-in Carbon code rather than special. Clearly they can't be directly implemented
-w/o help, but it might still be useful to force the programmer-observed
-interface to reside in code. However, this can cause difficulty with avoiding
-the need to import things gratuitously.
-
-### String view vs owning string
-
-The right model of a string view versus an owning string is still very much
-unsettled.
-
-### Syntax for wrapping operations
-
-Open question around allowing special syntax for wrapping operations (even on
-signed types) and/or requiring such syntax for wrapping operations on unsigned
-types.
-
-### Non-power-of-two sizes
-
-Supporting non-power-of-two sizes is likely needed to have a clean model for
-bitfields, but requires more details to be worked out around memory access.