Primitive types

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:/carbon-language/carbon-lang/pull/1327).
 
+> FIXME: add #2015
+
 <!-- toc -->
 
 ## Table of contents
@@ -229,21 +231,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:/carbon-language/carbon-lang/issues/750)
+> - Proposal
+> [#861: Naming conventions](https:/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:
 
@@ -257,25 +265,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:/carbon-language/carbon-lang/issues/543)
+> - Question-for-leads issue
+> [#750: Naming conventions for Carbon-provided features](https:/carbon-language/carbon-lang/issues/750)
 > - Proposal
-> [#820: Implicit conversions](https:/carbon-language/carbon-lang/pull/820)
+> [#861: Naming conventions](https:/carbon-language/carbon-lang/pull/861)
 > - Proposal
 > [#1083: Arithmetic expressions](https:/carbon-language/carbon-lang/pull/1083)
+> - Proposal
+> [#2015: Numeric type literal syntax](https:/carbon-language/carbon-lang/pull/2015)
 
 #### Integer literals
 
@@ -307,19 +330,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:/carbon-language/carbon-lang/issues/543)
+> - Question-for-leads issue
+> [#750: Naming conventions for Carbon-provided features](https:/carbon-language/carbon-lang/issues/750)
 > - Proposal
-> [#820: Implicit conversions](https:/carbon-language/carbon-lang/pull/820)
+> [#861: Naming conventions](https:/carbon-language/carbon-lang/pull/861)
 > - Proposal
 > [#1083: Arithmetic expressions](https:/carbon-language/carbon-lang/pull/1083)
+> - Proposal
+> [#2015: Numeric type literal syntax](https:/carbon-language/carbon-lang/pull/2015)
 
 #### Floating-point literals
 
@@ -360,6 +402,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:/carbon-language/carbon-lang/issues/750)
+> - Proposal
+> [#820: Implicit conversions](https:/carbon-language/carbon-lang/pull/820)
+> - Proposal
+> [#861: Naming conventions](https:/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.