diff --git a/docs/design/README.md b/docs/design/README.md index a28c407952b1f..114499882e98b 100644 --- a/docs/design/README.md +++ b/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 + ## 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://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: @@ -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://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 @@ -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://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 @@ -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://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/implicit_conversions.md b/docs/design/expressions/implicit_conversions.md index dd7b464ef2d83..f906b1ce570ec 100644 --- a/docs/design/expressions/implicit_conversions.md +++ b/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. 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.