From 9fd9e8e901be6a9ff169286545296de379db18e4 Mon Sep 17 00:00:00 2001 From: Josh L Date: Wed, 10 Aug 2022 21:03:14 +0000 Subject: [PATCH 1/8] Checkpoint progress. --- docs/design/README.md | 78 +++++++++++-- .../expressions/comparison_operators.md | 12 +- docs/design/primitive_types.md | 104 ------------------ 3 files changed, 74 insertions(+), 120 deletions(-) delete mode 100644 docs/design/primitive_types.md diff --git a/docs/design/README.md b/docs/design/README.md index 5f8a2bd381a30..affce0001dbc9 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -6,6 +6,9 @@ Exceptions. See /LICENSE for license information. 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). + ## Table of contents @@ -225,16 +228,22 @@ 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 @@ -254,7 +263,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), @@ -264,12 +273,25 @@ 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 -> [#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) @@ -303,17 +325,34 @@ 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 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. > 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) @@ -347,12 +386,27 @@ selected. ### String types +> **Note:** This is provisional, no design for string types has been through the +> proposal process yet. + There are two string types: - `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. +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 @@ -435,6 +489,10 @@ generally convert into runtime values if an operation that inspects the value is performed on them. Runtime values will convert into constants or to symbolic values if constant evaluation of the runtime expression succeeds. +> **Note:** Conversion of runtime values to other phases is provisional, as are +> the semantics of r-values. See pending proposal +> [#821: Values, variables, pointers, and references](https://github.com/carbon-language/carbon-lang/pull/821). + ## Composite types ### Tuples @@ -1591,8 +1649,8 @@ type, use `UnsafeDelete`. #### `const` -**Note:** This is provisional, no design for `const` has been through the -proposal process yet. +> **Note:** This is provisional, no design for `const` has been through the +> proposal process yet. For every type `MyClass`, there is the type `const MyClass` such that: diff --git a/docs/design/expressions/comparison_operators.md b/docs/design/expressions/comparison_operators.md index 4836922bef1b0..c9835857c0e0b 100644 --- a/docs/design/expressions/comparison_operators.md +++ b/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 - `Unsigned(n)`). + `UInt(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 `Unsigned(m)`. +when comparing `Int(n)` with `UInt(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 `Unsigned(n)` to `Int(m)` or `Unsigned(m)` if `m > n`. +- From `UInt(n)` to `Int(m)` or `UInt(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)` -- `Unsigned(n)` versus `Unsigned(n)` -- `Int(n)` versus `Unsigned(n)` -- `Unsigned(n)` versus `Int(n)` +- `UInt(n)` versus `UInt(n)` +- `Int(n)` versus `UInt(n)` +- `UInt(n)` versus `Int(n)` - `Float(n)` versus `Float(n)` There will in general be multiple combinations of implicit conversions that will diff --git a/docs/design/primitive_types.md b/docs/design/primitive_types.md deleted file mode 100644 index 1307f817fd125..0000000000000 --- a/docs/design/primitive_types.md +++ /dev/null @@ -1,104 +0,0 @@ -# Primitive types - - - - - -## 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) - - - -## 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. From 35b8674671d824340278a622cb91796b667e565c Mon Sep 17 00:00:00 2001 From: Josh L Date: Wed, 10 Aug 2022 21:15:55 +0000 Subject: [PATCH 2/8] Undo changes made separately in #1975 --- docs/design/README.md | 64 ++--------- .../expressions/comparison_operators.md | 12 +- docs/design/primitive_types.md | 104 ++++++++++++++++++ 3 files changed, 118 insertions(+), 62 deletions(-) create mode 100644 docs/design/primitive_types.md diff --git a/docs/design/README.md b/docs/design/README.md index affce0001dbc9..a5b6ee8790471 100644 --- a/docs/design/README.md +++ b/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 diff --git a/docs/design/expressions/comparison_operators.md b/docs/design/expressions/comparison_operators.md index c9835857c0e0b..4836922bef1b0 100644 --- a/docs/design/expressions/comparison_operators.md +++ b/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 diff --git a/docs/design/primitive_types.md b/docs/design/primitive_types.md new file mode 100644 index 0000000000000..1307f817fd125 --- /dev/null +++ b/docs/design/primitive_types.md @@ -0,0 +1,104 @@ +# Primitive types + + + + + +## 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) + + + +## 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. From 9a1b0e3f286448e2d03656e4ada4dc2f89f9b744 Mon Sep 17 00:00:00 2001 From: Josh L Date: Wed, 10 Aug 2022 23:43:27 +0000 Subject: [PATCH 3/8] Checkpoint progress. --- docs/design/README.md | 87 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 75 insertions(+), 12 deletions(-) diff --git a/docs/design/README.md b/docs/design/README.md index a5b6ee8790471..81fd569a1c637 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -396,9 +396,6 @@ are available for representing strings with `\`s and `"`s. ## Value categories and value phases -**FIXME:** Should this be moved together with -[Types are values](#types-are-values)? - Every value has a [value category](), similar to [C++](https://en.cppreference.com/w/cpp/language/value_category), @@ -481,6 +478,10 @@ fn DoubleTuple(x: (i32, i32)) -> (i32, i32) { Tuple types are [structural](https://en.wikipedia.org/wiki/Structural_type_system). +> **Note:** This is provisional, no design for tuples has been through the +> proposal process yet. Many of these questions were discussed in dropped +> proposal [#111](https://github.com/carbon-language/carbon-lang/pull/111). + > References: [Tuples](tuples.md) ### Struct types @@ -531,6 +532,10 @@ type `Optional(T*)`. [stricter pointer provenance](https://www.ralfj.de/blog/2022/04/11/provenance-exposed.html) or restrictions on casts between pointers and integers. +> **Note:** While the syntax for points has been decided, the semantics of +> pointers is provisional, as is the syntax for optionals. See pending proposal +> [#821: Values, variables, pointers, and references](https://github.com/carbon-language/carbon-lang/pull/821). + > References: > > - Question-for-leads issue @@ -562,6 +567,10 @@ Console.Print(a[0]); > **TODO:** Slices +> **Note:** This is provisional, no design for arrays has been through the +> proposal process yet. See pending proposal +> [#1928: Arrays](https://github.com/carbon-language/carbon-lang/pull/1928). + ## Expressions Expressions describe some computed value. The simplest example would be a @@ -664,6 +673,9 @@ function or class itself is visible until the end of the enclosing scope. ## Patterns +> **Note:** This is provisional, no design for patterns has been through the +> proposal process yet. + A _pattern_ says how to receive some data that is being matched against. There are two kinds of patterns: @@ -792,6 +804,9 @@ Here `x: i64` is the pattern, which is followed by an equal sign (`=`) and the value to match, `42`. The names from [binding patterns](#binding-patterns) are introduced into the enclosing [scope](#declarations-definitions-and-scopes). +> **Note:** `let` declarations are provisional. See pending proposal +> [#821: Values, variables, pointers, and references](https://github.com/carbon-language/carbon-lang/pull/821). + ### Variable `var` declarations A `var` declaration is similar, except with `var` bindings, so `x` here is an @@ -907,6 +922,10 @@ the caller, and dereferencing using `*` in the callee. Outputs of a function should prefer to be returned. Multiple values may be returned using a [tuple](#tuples) or [struct](#struct-types) type. +> **Note:** The semantics of parameter passing are provisional. See pending +> proposal +> [#821: Values, variables, pointers, and references](https://github.com/carbon-language/carbon-lang/pull/821). + ### `auto` return type If `auto` is used in place of the return type, the return type of the function @@ -977,6 +996,9 @@ the assignment. Unlike C++, these assignments are statements, not expressions, and don't return a value. +> **Note:** The semantics of assignment are provisional. See pending proposal +> [#821: Values, variables, pointers, and references](https://github.com/carbon-language/carbon-lang/pull/821). + ### Control flow Blocks of statements are generally executed sequentially. Control-flow @@ -1103,7 +1125,13 @@ for (var step: Step in steps) { } ``` -> References: [`break`](control_flow/loops.md#break) +> References: +> +> - [`break`](control_flow/loops.md#break) +> - Proposal +> [#340: Add C++-like `while` loops](https://github.com/carbon-language/carbon-lang/pull/340) +> - Proposal +> [#353: Add C++-like `for` loops](https://github.com/carbon-language/carbon-lang/pull/353) ##### `continue` @@ -1123,7 +1151,13 @@ while (!f.EOF()) { } ``` -> References: [`continue`](control_flow/loops.md#continue) +> References: +> +> - [`continue`](control_flow/loops.md#continue) +> - Proposal +> [#340: Add C++-like `while` loops](https://github.com/carbon-language/carbon-lang/pull/340) +> - Proposal +> [#353: Add C++-like `for` loops](https://github.com/carbon-language/carbon-lang/pull/353) #### `return` @@ -1233,6 +1267,9 @@ fn Foo() -> f32 { } ``` +> **Note:** This is provisional, no design for `match` statements has been +> through the proposal process yet. + > References: > > - [Pattern matching](pattern_matching.md) @@ -1241,8 +1278,6 @@ fn Foo() -> f32 { ## User-defined types -> **TODO:** Maybe rename to "nominal types"? - ### Classes _Nominal classes_, or just @@ -1326,7 +1361,9 @@ sprocket = {.x = 2, .y = 1, .payload = "Bounce"}; > References: > -> - [Classes: Construction](classes.md#construction) +> - [Classes: Assignment](classes.md#assignment) +> - Proposal +> [#722: Nominal classes and methods](https://github.com/carbon-language/carbon-lang/pull/722) > - Proposal > [#981: Implicit conversions for aggregates](https://github.com/carbon-language/carbon-lang/pull/981) @@ -1374,6 +1411,12 @@ class Registered { This approach can also be used for types that can't be copied or moved. +> References: +> +> - [Classes: Construction](classes.md#construction) +> - Proposal +> [#722: Nominal classes and methods](https://github.com/carbon-language/carbon-lang/pull/722) + #### Methods Class type definitions can include methods: @@ -1532,7 +1575,7 @@ class DerivedFromAbstract extends AbstractClass { > References: > -> - [Inheritance](classes.md#inheritance) +> - [Classes: Inheritance](classes.md#inheritance) > - Proposal > [#777: Inheritance](https://github.com/carbon-language/carbon-lang/pull/777) > - Proposal @@ -1556,6 +1599,8 @@ names resolvable by the compiler, and don't act like forward declarations. > - [Access control for class members](classes.md#access-control) > - Question-for-leads issue > [#665: `private` vs `public` _syntax_ strategy, as well as other visibility tools like `external`/`api`/etc.](https://github.com/carbon-language/carbon-lang/issues/665) +> - Proposal +> [#777: Inheritance](https://github.com/carbon-language/carbon-lang/pull/777) > - Question-for-leads issue > [#971: Private interfaces in public API files](https://github.com/carbon-language/carbon-lang/issues/971) @@ -1595,7 +1640,7 @@ type, use `UnsafeDelete`. > References: > -> - [Destructors](classes.md#destructors) +> - [Classes: Destructors](classes.md#destructors) > - Proposal > [#1154: Destructors](https://github.com/carbon-language/carbon-lang/pull/1154) @@ -1682,6 +1727,12 @@ when returning a value from a function or by using the _move operator_ `~x`. This leaves `x` in an [unformed state](#unformed-state) and returns its old value. +> **Note:** This is provisional. The move operator was discussed but not +> proposed in accepted proposal +> [#257: Initialization of memory and variables](https://github.com/carbon-language/carbon-lang/pull/257). +> See pending proposal +> [#821: Values, variables, pointers, and references](https://github.com/carbon-language/carbon-lang/pull/821). + #### Mixins Mixins allow reuse with different trade-offs compared to @@ -1691,7 +1742,9 @@ be done using [multiple inheritance](https://en.wikipedia.org/wiki/Multiple_inheritance) in C++. -**TODO:** The design for mixins is still under development. +> **TODO:** The design for mixins is still under development. The details here +> are provisional. The mixin use case was included in accepted proposal +> [#561: Basic classes: use cases, struct literals, struct types, and future work](https://github.com/carbon-language/carbon-lang/pull/561). ### Choice types @@ -1931,7 +1984,7 @@ given name public. ### Package scope -The top-level scope in a package is the scope of the package. This means: +The top-level scope in a file is the scope of the package. This means: - Within this scope (and its sub-namespaces), all visible names from the same package appear. This includes names from the same file, names from the `api` @@ -2046,6 +2099,12 @@ P.M.Q(); > > - ["Namespaces" in "Code and name organization"](code_and_name_organization/README.md#namespaces) > - ["Package and namespace members" in "Qualified names and member access"](expressions/member_access.md#package-and-namespace-members) +> - Proposal +> [#107: Code and name organization](https://github.com/carbon-language/carbon-lang/pull/107) +> - Proposal +> [#989: Member access expressions](https://github.com/carbon-language/carbon-lang/pull/989) +> - Question-for-leads issue +> [#1136: what is the top-level scope in a source file, and what names are found there?](https://github.com/carbon-language/carbon-lang/issues/1136) ### Naming conventions @@ -2103,9 +2162,13 @@ class ContactInfo { > - [`alias` a name from an external impl](generics/details.md#external-impl) > - [`alias` a name in a named constraint](generics/details.md#named-constraints) > - Proposal +> [#107: Code and name organization](https://github.com/carbon-language/carbon-lang/pull/107) +> - Proposal > [#553: Generics details part 1](https://github.com/carbon-language/carbon-lang/pull/553) > - Question-for-leads issue > [#749: Alias syntax](https://github.com/carbon-language/carbon-lang/issues/749) +> - Proposal +> [#989: Member access expressions](https://github.com/carbon-language/carbon-lang/pull/989) ### Name lookup From f7431f0083dac5671ea700e587b6f6c24d091408 Mon Sep 17 00:00:00 2001 From: Josh L Date: Wed, 10 Aug 2022 23:54:21 +0000 Subject: [PATCH 4/8] Checkpoint progress. --- docs/design/README.md | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/docs/design/README.md b/docs/design/README.md index 81fd569a1c637..d32d876a3be8a 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -137,6 +137,7 @@ This document includes much that is provisional or placeholder. This means that the syntax used, language rules, standard library, and other aspects of the design have things that have not been decided through the Carbon process. This preliminary material fills in gaps until aspects of the design can be filled in. +Features that are provisional have been marked as such on a best-effort basis. ## Hello, Carbon @@ -2653,6 +2654,10 @@ indicate that they may not be specialized, subject to > [#920: Generic parameterized impls (details 5)](https://github.com/carbon-language/carbon-lang/pull/920) > - Proposal > [#983: Generics details 7: final impls](https://github.com/carbon-language/carbon-lang/pull/983) +> - Question-for-leads issue +> [1192: Parameterized impl syntax](https://github.com/carbon-language/carbon-lang/issues/1192) +> - Proposal +> [#1327: Generics: `impl forall`](https://github.com/carbon-language/carbon-lang/pull/1327) ### Other features @@ -2680,9 +2685,9 @@ Carbon generics have a number of other features, including: value with a type implementing an interface, and allows the functions in that interface to be called using [dynamic dispatch](https://en.wikipedia.org/wiki/Dynamic_dispatch), for some - interfaces marked "`dyn`-safe". + interfaces marked "`dyn`-safe". **Note:** Provisional. - [Variadics](generics/details.md#variadic-arguments) supports variable-length - parameter lists. + parameter lists. **Note:** Provisional. > References: > @@ -2943,6 +2948,9 @@ include: ### Importing and `#include` +> **Note:** This is provisional, no design for importing C++ has been through +> the proposal process yet. + A C++ library header file may be [imported](#imports) into Carbon using an `import` declaration of the special `Cpp` package. @@ -2979,6 +2987,9 @@ marker. ### ABI and dynamic linking +> **Note:** This is provisional, no design for this has been through the +> proposal process yet. + Carbon itself will not have a stable ABI for the language as a whole, and most language features will be designed around not having any ABI stability. Instead, we expect to add dedicated language features that are specifically designed to @@ -3005,6 +3016,9 @@ ABI compatibility. ### Operator overloading +> **Note:** This is provisional, no design for this has been through the +> proposal process yet. + [Operator overloading](#operator-overloading) is supported in Carbon, but is done by [implementing an interface](#interfaces-and-implementations) instead of defining a method or nonmember function as in C++. @@ -3044,6 +3058,9 @@ requiring changes to importers? ### Templates +> **Note:** This is provisional, no design for this has been through the +> proposal process yet. + Carbon supports both [checked and template generics](#checked-and-template-parameters). This provides a migration path for C++ template code: @@ -3072,6 +3089,9 @@ if it were a C++ template. ### Standard types +> **Note:** This is provisional, no design for this has been through the +> proposal process yet. + The Carbon integer types, like `i32` and `u64`, are considered equal to the corresponding fixed-width integer types in C++, like `int32_t` and `uint64_t`, provided by `` or ``. The basic C and C++ integer types like @@ -3136,12 +3156,21 @@ The reverse operation is also possible using a proxy object implementing a C++ abstract base class and holding a pointer to a type implementing the corresponding interface. +> References: +> +> - Proposal +> [#561: Basic classes: use cases, struct literals, struct types, and future work](https://github.com/carbon-language/carbon-lang/pull/561) +> - Proposal +> [#777: Inheritance](https://github.com/carbon-language/carbon-lang/pull/777) + ### Enums > **TODO** ## Unfinished tales +> **Note:** Everything in this section is provisional and forward looking. + ### Safety Carbon's premise is that C++ users can't give up performance to get safety. Even From 43fef191db37905cf5347ea221e90c53409b748c Mon Sep 17 00:00:00 2001 From: Josh L Date: Thu, 11 Aug 2022 00:00:13 +0000 Subject: [PATCH 5/8] Fix points -> pointers --- docs/design/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/README.md b/docs/design/README.md index d32d876a3be8a..197ccc82559f4 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -533,7 +533,7 @@ type `Optional(T*)`. [stricter pointer provenance](https://www.ralfj.de/blog/2022/04/11/provenance-exposed.html) or restrictions on casts between pointers and integers. -> **Note:** While the syntax for points has been decided, the semantics of +> **Note:** While the syntax for pointers has been decided, the semantics of > pointers is provisional, as is the syntax for optionals. See pending proposal > [#821: Values, variables, pointers, and references](https://github.com/carbon-language/carbon-lang/pull/821). From d66a6410f0c296536dd19254e52efb414b2c7636 Mon Sep 17 00:00:00 2001 From: Josh L Date: Thu, 11 Aug 2022 19:46:16 +0000 Subject: [PATCH 6/8] Clarify ABI provisionality --- docs/design/README.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/design/README.md b/docs/design/README.md index 197ccc82559f4..baeeb3967a31b 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -2987,8 +2987,8 @@ marker. ### ABI and dynamic linking -> **Note:** This is provisional, no design for this has been through the -> proposal process yet. +> **Note:** This reflects goals and plans. No specific design for the +> implementation has been through the proposal process yet. Carbon itself will not have a stable ABI for the language as a whole, and most language features will be designed around not having any ABI stability. Instead, @@ -3014,6 +3014,11 @@ available across this interop boundary will of course be restricted to what is expressible in the C ABI, and types may need explicit markers to have guaranteed ABI compatibility. +> References: +> +> - [Goals: Stable language and library ABI](https://github.com/carbon-language/carbon-lang/blob/trunk/docs/project/goals.md#stable-language-and-library-abi) +> - [#175: C++ interoperability goals: Support mixing Carbon and C++ toolchains](/proposals/p0175.md#support-mixing-carbon-and-c-toolchains) + ### Operator overloading > **Note:** This is provisional, no design for this has been through the From f4617cc05a7bf9401d2ff6166e91770fed6cb9da Mon Sep 17 00:00:00 2001 From: josh11b Date: Thu, 11 Aug 2022 13:01:24 -0700 Subject: [PATCH 7/8] Update docs/design/README.md Co-authored-by: Jon Ross-Perkins --- docs/design/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/README.md b/docs/design/README.md index baeeb3967a31b..924e686108c21 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -3016,7 +3016,7 @@ ABI compatibility. > References: > -> - [Goals: Stable language and library ABI](https://github.com/carbon-language/carbon-lang/blob/trunk/docs/project/goals.md#stable-language-and-library-abi) +> - [Goals: Stable language and library ABI non-goal](https://github.com/carbon-language/carbon-lang/blob/trunk/docs/project/goals.md#stable-language-and-library-abi) > - [#175: C++ interoperability goals: Support mixing Carbon and C++ toolchains](/proposals/p0175.md#support-mixing-carbon-and-c-toolchains) ### Operator overloading From a305428e05141d1a359a3351ff4be09004bb438e Mon Sep 17 00:00:00 2001 From: josh11b Date: Thu, 11 Aug 2022 13:05:36 -0700 Subject: [PATCH 8/8] Update docs/design/README.md Co-authored-by: Geoff Romer --- docs/design/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/README.md b/docs/design/README.md index 924e686108c21..bcb24e55805b3 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -534,7 +534,7 @@ type `Optional(T*)`. or restrictions on casts between pointers and integers. > **Note:** While the syntax for pointers has been decided, the semantics of -> pointers is provisional, as is the syntax for optionals. See pending proposal +> pointers are provisional, as is the syntax for optionals. See pending proposal > [#821: Values, variables, pointers, and references](https://github.com/carbon-language/carbon-lang/pull/821). > References: