Undo changes made separately in carbon-language#1975

docs/design/README.md

@@ -228,22 +228,16 @@ 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
@@ -263,7 +257,7 @@ programming error:
     zero.
 
 The unsigned-integer types are: `u8`, `u16`, `u32`, `u64`, `u128`, and
-`Carbon.UInt(N)`. Unsigned integer types wrap around on overflow; we strongly
+`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),
@@ -273,25 +267,12 @@ 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 `i[0-9]+` and `u[0-9]+` are _type literals_, resulting
-in the corresponding type.
-
-There is an upper bound on the size of an integer, most likely initially set to
-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 may need a
-> more convenient way to spell non-power-of-two-bits integers than
-> `Carbon.Int(N)` and `Carbon.UInt(N)`.
-
 > 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
->     [#861: Naming conventions](https://github.com/carbon-language/carbon-lang/pull/861)
+>     [#820: Implicit conversions](https://github.com/carbon-language/carbon-lang/pull/820)
 > -   Proposal
 >     [#1083: Arithmetic expressions](https://github.com/carbon-language/carbon-lang/pull/1083)
 
@@ -325,34 +306,17 @@ 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`](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).
-Identifiers of the form `f[0-9]+` are _type literals_, resulting in the
-corresponding type.
-
-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.
+with an `f` and the number of bits: `f16`, `f32`, `f64`, and `f128`.
+[`BFloat16`](primitive_types.md#bfloat16) is also provided.
 
 > 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
->     [#861: Naming conventions](https://github.com/carbon-language/carbon-lang/pull/861)
+>     [#820: Implicit conversions](https://github.com/carbon-language/carbon-lang/pull/820)
 > -   Proposal
 >     [#1083: Arithmetic expressions](https://github.com/carbon-language/carbon-lang/pull/1083)
 
@@ -395,18 +359,6 @@ 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/comparison_operators.md

@@ -115,14 +115,14 @@ if (m > 1 == n > 1) {
 Built-in comparisons are permitted in three cases:
 
 1.  When both operands are of standard Carbon integer types (`Int(n)` or
-    `UInt(n)`).
+    `Unsigned(n)`).
 2.  When both operands are of standard Carbon floating-point types (`Float(n)`).
 3.  When one operand is of floating-point type and the other is of integer type,
     if all values of the integer type can be exactly represented in the
     floating-point type.
 
 In each case, the result is the mathematically-correct answer. This applies even
-when comparing `Int(n)` with `UInt(m)`.
+when comparing `Int(n)` with `Unsigned(m)`.
 
 For example:
 
@@ -148,7 +148,7 @@ these rules and are [discussed separately](#comparisons-with-constants).
 We support the following [implicit conversions](implicit_conversions.md):
 
 -   From `Int(n)` to `Int(m)` if `m > n`.
--   From `UInt(n)` to `Int(m)` or `UInt(m)` if `m > n`.
+-   From `Unsigned(n)` to `Int(m)` or `Unsigned(m)` if `m > n`.
 -   From `Float(n)` to `Float(m)` if `m > n`.
 -   From `Int(n)` to `Float(m)` if `Float(m)` can represent all values of
     `Int(n)`.
@@ -166,9 +166,9 @@ similar types, and then performing a comparison on those types. The target types
 for these implicit conversions are, for each suitable value `n`:
 
 -   `Int(n)` versus `Int(n)`
--   `UInt(n)` versus `UInt(n)`
--   `Int(n)` versus `UInt(n)`
--   `UInt(n)` versus `Int(n)`
+-   `Unsigned(n)` versus `Unsigned(n)`
+-   `Int(n)` versus `Unsigned(n)`
+-   `Unsigned(n)` versus `Int(n)`
 -   `Float(n)` versus `Float(n)`
 
 There will in general be multiple combinations of implicit conversions that will

docs/design/primitive_types.md

@@ -0,0 +1,104 @@
+# 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.