Values, variables, pointers, and references

docs/design/control_flow/return.md

@@ -80,8 +80,8 @@ fn MaybeDraw(should_draw: bool) -> () {
 
 ### `returned var`
 
-[Variables](../variables.md) may be declared with a `returned` statement. Its
-syntax is:
+[Local variables](../values.md#binding-patterns-and-local-variables-with-let-and-var)
+may be declared with a `returned` statement. Its syntax is:
 
 > `returned` _var statement_
 

docs/design/expressions/README.md

@@ -61,10 +61,27 @@ graph BT
     unqualifiedName["x"]
     click unqualifiedName "https://github.com/carbon-language/carbon-lang/blob/trunk/docs/design/expressions/README.md#unqualified-names"
 
+    top((" "))
+
     memberAccess>"x.y<br>
-                    x.(...)"]
+                  x.(...)<br>
+                  x->y<br>
+                  x->(...)"]
     click memberAccess "https://github.com/carbon-language/carbon-lang/blob/trunk/docs/design/expressions/member_access.md"
 
+    constType["const T"]
+    click pointer-type "https://github.com/carbon-language/carbon-lang/blob/trunk/docs/design/expressions/type_operators.md"
+
+    pointerType>"T*"]
+    click pointer-type "https://github.com/carbon-language/carbon-lang/blob/trunk/docs/design/expressions/type_operators.md"
+
+    %% FIXME: Need to switch unary operators from a left/right associativity to
+    %% a "repeated" marker, as we only have one direction for associativity and
+    %% that is wrong in this specific case.
+    pointer>"*x<br>
+             &x<br>"]
+    click pointer "https://github.com/carbon-language/carbon-lang/blob/trunk/docs/design/expressions/pointer.md"
+
     negation["-x"]
     click negation "https://github.com/carbon-language/carbon-lang/blob/trunk/docs/design/expressions/arithmetic.md"
 
@@ -124,15 +141,22 @@ graph BT
 
     expressionEnd["x;"]
 
-    memberAccess --> parens & braces & unqualifiedName
-    negation --> memberAccess
-    complement --> memberAccess
+    top --> parens & braces & unqualifiedName
+
+    constType --> top
+    pointerType --> constType
+    as --> pointerType
+
+    memberAccess --> top
+    pointer --> memberAccess
+    negation --> pointer
+    complement --> pointer
     unary --> negation & complement
     %% Use a longer arrow here to put `not` next to `and` and `or`.
-    not -----> memberAccess
-    multiplication & modulo & as & bitwise_and & bitwise_or & bitwise_xor & shift --> unary
+    not -------> memberAccess
+    as & multiplication & modulo & bitwise_and & bitwise_or & bitwise_xor & shift --> unary
     addition --> multiplication
-    comparison --> modulo & addition & as & bitwise_and & bitwise_or & bitwise_xor & shift
+    comparison --> as & addition & modulo & bitwise_and & bitwise_or & bitwise_xor & shift
     logicalOperand --> comparison & not
     and & or --> logicalOperand
     logicalExpression --> and & or
@@ -179,12 +203,14 @@ keyword and is not preceded by a period (`.`).
 
 ### Qualified names and member access
 
-A _qualified name_ is a word that appears immediately after a period. Qualified
-names appear in the following contexts:
+A _qualified name_ is a word that appears immediately after a period or
+rightward arrow. Qualified names appear in the following contexts:
 
 -   [Designators](/docs/design/classes.md#literals): `.` _word_
 -   [Simple member access expressions](member_access.md): _expression_ `.`
     _word_
+-   [Simple pointer member access expressions](member_access.md): _expression_
+    `->` _word_
 
 ```
 var x: auto = {.hello = 1, .world = 2};
@@ -194,6 +220,10 @@ var x: auto = {.hello = 1, .world = 2};
 x.hello = x.world;
   ^^^^^     ^^^^^ qualified name
 ^^^^^^^   ^^^^^^^ member access expression
+
+x.hello = (&x)->world;
+                ^^^^^ qualified name
+          ^^^^^^^^^^^ pointer member access expression
 ```
 
 Qualified names refer to members of an entity determined by the context in which
@@ -231,6 +261,7 @@ complex than a single _word_, a compound member access expression can be used,
 with parentheses around the member name:
 
 -   _expression_ `.` `(` _expression_ `)`
+-   _expression_ `->` `(` _expression_ `)`
 
 ```
 interface I { fn F[self: Self](); }
@@ -241,34 +272,40 @@ impl X as I { fn F[self: Self]() {} }
 fn Q(x: X) { x.(I.F)(); }
 ```
 
+Either simple or compound member access can be part of a _pointer_ member access
+expression when an `->` is used instead of a `.`, where _expression_ `->` _..._
+is syntactic sugar for `(` `*` _expression_ `)` `.` _..._.
+
 ## Operators
 
 Most expressions are modeled as operators:
 
-| Category   | Operator                        | Syntax    | Function                                                              |
-| ---------- | ------------------------------- | --------- | --------------------------------------------------------------------- |
-| Arithmetic | [`-`](arithmetic.md) (unary)    | `-x`      | The negation of `x`.                                                  |
-| Bitwise    | [`^`](bitwise.md) (unary)       | `^x`      | The bitwise complement of `x`.                                        |
-| Arithmetic | [`+`](arithmetic.md)            | `x + y`   | The sum of `x` and `y`.                                               |
-| Arithmetic | [`-`](arithmetic.md) (binary)   | `x - y`   | The difference of `x` and `y`.                                        |
-| Arithmetic | [`*`](arithmetic.md)            | `x * y`   | The product of `x` and `y`.                                           |
-| Arithmetic | [`/`](arithmetic.md)            | `x / y`   | `x` divided by `y`, or the quotient thereof.                          |
-| Arithmetic | [`%`](arithmetic.md)            | `x % y`   | `x` modulo `y`.                                                       |
-| Bitwise    | [`&`](bitwise.md)               | `x & y`   | The bitwise AND of `x` and `y`.                                       |
-| Bitwise    | [`\|`](bitwise.md)              | `x \| y`  | The bitwise OR of `x` and `y`.                                        |
-| Bitwise    | [`^`](bitwise.md) (binary)      | `x ^ y`   | The bitwise XOR of `x` and `y`.                                       |
-| Bitwise    | [`<<`](bitwise.md)              | `x << y`  | `x` bit-shifted left `y` places.                                      |
-| Bitwise    | [`>>`](bitwise.md)              | `x >> y`  | `x` bit-shifted right `y` places.                                     |
-| Conversion | [`as`](as_expressions.md)       | `x as T`  | Converts the value `x` to the type `T`.                               |
-| Comparison | [`==`](comparison_operators.md) | `x == y`  | Equality: `true` if `x` is equal to `y`.                              |
-| Comparison | [`!=`](comparison_operators.md) | `x != y`  | Inequality: `true` if `x` is not equal to `y`.                        |
-| Comparison | [`<`](comparison_operators.md)  | `x < y`   | Less than: `true` if `x` is less than `y`.                            |
-| Comparison | [`<=`](comparison_operators.md) | `x <= y`  | Less than or equal: `true` if `x` is less than or equal to `y`.       |
-| Comparison | [`>`](comparison_operators.md)  | `x > y`   | Greater than: `true` if `x` is greater than to `y`.                   |
-| Comparison | [`>=`](comparison_operators.md) | `x >= y`  | Greater than or equal: `true` if `x` is greater than or equal to `y`. |
-| Logical    | [`and`](logical_operators.md)   | `x and y` | A short-circuiting logical AND: `true` if both operands are `true`.   |
-| Logical    | [`or`](logical_operators.md)    | `x or y`  | A short-circuiting logical OR: `true` if either operand is `true`.    |
-| Logical    | [`not`](logical_operators.md)   | `not x`   | Logical NOT: `true` if the operand is `false`.                        |
+| Category   | Operator                            | Syntax    | Function                                                              |
+| ---------- | ----------------------------------- | --------- | --------------------------------------------------------------------- |
+| Pointer    | [`*`](pointer_operators.md) (unary) | `*x`      | Pointer dereference: the object pointed to by `x`.                    |
+| Pointer    | [`&`](pointer_operators.md) (unary) | `&x`      | Address-of: a pointer to the object `x`.                              |
+| Arithmetic | [`-`](arithmetic.md) (unary)        | `-x`      | The negation of `x`.                                                  |
+| Bitwise    | [`^`](bitwise.md) (unary)           | `^x`      | The bitwise complement of `x`.                                        |
+| Arithmetic | [`+`](arithmetic.md)                | `x + y`   | The sum of `x` and `y`.                                               |
+| Arithmetic | [`-`](arithmetic.md) (binary)       | `x - y`   | The difference of `x` and `y`.                                        |
+| Arithmetic | [`*`](arithmetic.md)                | `x * y`   | The product of `x` and `y`.                                           |
+| Arithmetic | [`/`](arithmetic.md)                | `x / y`   | `x` divided by `y`, or the quotient thereof.                          |
+| Arithmetic | [`%`](arithmetic.md)                | `x % y`   | `x` modulo `y`.                                                       |
+| Bitwise    | [`&`](bitwise.md)                   | `x & y`   | The bitwise AND of `x` and `y`.                                       |
+| Bitwise    | [`\|`](bitwise.md)                  | `x \| y`  | The bitwise OR of `x` and `y`.                                        |
+| Bitwise    | [`^`](bitwise.md) (binary)          | `x ^ y`   | The bitwise XOR of `x` and `y`.                                       |
+| Bitwise    | [`<<`](bitwise.md)                  | `x << y`  | `x` bit-shifted left `y` places.                                      |
+| Bitwise    | [`>>`](bitwise.md)                  | `x >> y`  | `x` bit-shifted right `y` places.                                     |
+| Conversion | [`as`](as_expressions.md)           | `x as T`  | Converts the value `x` to the type `T`.                               |
+| Comparison | [`==`](comparison_operators.md)     | `x == y`  | Equality: `true` if `x` is equal to `y`.                              |
+| Comparison | [`!=`](comparison_operators.md)     | `x != y`  | Inequality: `true` if `x` is not equal to `y`.                        |
+| Comparison | [`<`](comparison_operators.md)      | `x < y`   | Less than: `true` if `x` is less than `y`.                            |
+| Comparison | [`<=`](comparison_operators.md)     | `x <= y`  | Less than or equal: `true` if `x` is less than or equal to `y`.       |
+| Comparison | [`>`](comparison_operators.md)      | `x > y`   | Greater than: `true` if `x` is greater than to `y`.                   |
+| Comparison | [`>=`](comparison_operators.md)     | `x >= y`  | Greater than or equal: `true` if `x` is greater than or equal to `y`. |
+| Logical    | [`and`](logical_operators.md)       | `x and y` | A short-circuiting logical AND: `true` if both operands are `true`.   |
+| Logical    | [`or`](logical_operators.md)        | `x or y`  | A short-circuiting logical OR: `true` if either operand is `true`.    |
+| Logical    | [`not`](logical_operators.md)       | `not x`   | Logical NOT: `true` if the operand is `false`.                        |
 
 The binary arithmetic and bitwise operators also have
 [compound assignment](/docs/design/assignment.md) forms. These are statements

docs/design/expressions/indexing.md

@@ -23,14 +23,17 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 ## Overview
 
 Carbon supports indexing using the conventional `a[i]` subscript syntax. When
-`a` is an l-value, the result of subscripting is always an l-value, but when `a`
-is an r-value, the result can be an l-value or an r-value, depending on which
+`a` is a
+[durable reference expression](/docs/design/values.md#durable-reference-expressions),
+the result of subscripting is also a durable reference expression, but when `a`
+is a [value expression](/docs/design/values.md#value-expressions), the result
+can be a durable reference expression or a value expression, depending on which
 interface the type implements:
 
--   If subscripting an r-value produces an r-value result, as with an array, the
-    type should implement `IndexWith`.
--   If subscripting an r-value produces an l-value result, as with C++'s
-    `std::span`, the type should implement `IndirectIndexWith`.
+-   If subscripting a value expression produces a value expression, as with an
+    array, the type should implement `IndexWith`.
+-   If subscripting a value expression produces a durable reference expression,
+    as with C++'s `std::span`, the type should implement `IndirectIndexWith`.
 
 `IndirectIndexWith` is a subtype of `IndexWith`, and subscript expressions are
 rewritten to method calls on `IndirectIndexWith` if the type is known to
@@ -39,6 +42,19 @@ implement that interface, or to method calls on `IndexWith` otherwise.
 `IndirectIndexWith` provides a final blanket `impl` of `IndexWith`, so a type
 can implement at most one of those two interfaces.
 
+The `Addr` methods of these interfaces, which are used to form durable reference
+expressions on indexing, must return a pointer and work similarly to the
+[pointer dereference customization interface](/docs/design/values.md#dereferencing-customization).
+The returned pointer is then dereferenced by the language to form the reference
+expression referring to the pointed-to object. These methods must return a raw
+pointer, and do not automatically chain with customized dereference interfaces.
+
+**Open question:** It's not clear that the lack of chaining is necessary, and it
+might be more expressive for the pointer type returned by the `Addr` methods to
+be an associated type with a default to allow types to produce custom
+pointer-like types on their indexing boundary and have them still be
+automatically dereferenced.
+
 ## Details
 
 A subscript expression has the form "_lhs_ `[` _index_ `]`". As in C++, this
@@ -61,13 +77,15 @@ interface IndirectIndexWith(SubscriptType:! type) {
 ```
 
 A subscript expression where _lhs_ has type `T` and _index_ has type `I` is
-rewritten based on the value category of _lhs_ and whether `T` is known to
+rewritten based on the expression category of _lhs_ and whether `T` is known to
 implement `IndirectIndexWith(I)`:
 
 -   If `T` implements `IndirectIndexWith(I)`, the expression is rewritten to
     "`*((` _lhs_ `).(IndirectIndexWith(I).Addr)(` _index_ `))`".
--   Otherwise, if _lhs_ is an l-value, the expression is rewritten to "`*((`
-    _lhs_ `).(IndexWith(I).Addr)(` _index_ `))`".
+-   Otherwise, if _lhs_ is a
+    [_durable reference expression_](/docs/design/values.md#durable-reference-expressions),
+    the expression is rewritten to "`*((` _lhs_ `).(IndexWith(I).Addr)(` _index_
+    `))`".
 -   Otherwise, the expression is rewritten to "`(` _lhs_ `).(IndexWith(I).At)(`
     _index_ `)`".
 
@@ -136,3 +154,5 @@ Carbon API.
 
 -   Proposal
     [#2274: Subscript syntax and semantics](https://github.com/carbon-language/carbon-lang/pull/2274)
+-   Proposal
+    [#2006: Values, variables, and pointers](https://github.com/carbon-language/carbon-lang/pull/2006)

docs/design/expressions/member_access.md

@@ -29,9 +29,12 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 ## Overview
 
 A _qualified name_ is a [word](../lexical_conventions/words.md) that is preceded
-by a period. The name is found within a contextually determined entity:
+by a period or a rightward arrow. The name is found within a contextually
+determined entity:
 
 -   In a member access expression, this is the entity preceding the period.
+-   In a pointer member access expression, this is the entity pointed to by the
+    pointer preceding the rightward arrow.
 -   For a designator in a struct literal, the name is introduced as a member of
     the struct type.
 
@@ -43,10 +46,12 @@ A member access expression is either a _simple_ member access expression of the
 form:
 
 -   _member-access-expression_ ::= _expression_ `.` _word_
+-   _member-access-expression_ ::= _expression_ `->` _word_
 
 or a _compound_ member access of the form:
 
 -   _member-access-expression_ ::= _expression_ `.` `(` _expression_ `)`
+-   _member-access-expression_ ::= _expression_ `->` `(` _expression_ `)`
 
 Compound member accesses allow specifying a qualified member name.
 
@@ -66,14 +71,26 @@ class Cog {
 fn GrowSomeCogs() {
   var cog1: Cog = Cog.Make(1);
   var cog2: Cog = cog1.Make(2);
+  var cog_pointer: Cog* = &cog2;
   let cog1_size: i32 = cog1.size;
   cog1.Grow(1.5);
   cog2.(Cog.Grow)(cog1_size as f64);
   cog1.(Widget.Grow)(1.1);
   cog2.(Widgets.Cog.(Widgets.Widget.Grow))(1.9);
+  cog_pointer->Grow(0.75);
+  cog_pointer->(Widget.Grow)(1.2);
 }
 ```
 
+Pointer member access expressions are those using a `->` instead of a `.` and
+their semantics are exactly what would result from first dereferencing the
+expression preceding the `->` and then forming a member access expression using
+a `.`. For example, a simple pointer member access expression _expression_ `->`
+_word_ becomes `(` `*` _expression_ `)` `.` _word_. More details on this syntax
+and semantics can be found in the [pointers](/docs/design/values.md#pointers)
+design. The rest of this document describes the semantics using `.` alone for
+simplicity.
+
 A member access expression is processed using the following steps:
 
 -   First, the word or parenthesized expression to the right of the `.` is

docs/design/expressions/pointer_operators.md

@@ -0,0 +1,57 @@
+# Pointer operators
+
+<!--
+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
+
+-   [Overview](#overview)
+-   [Details](#details)
+    -   [Precedence](#precedence)
+-   [Alternatives considered](#alternatives-considered)
+-   [References](#references)
+
+<!-- tocstop -->
+
+## Overview
+
+Carbon provides the following operators related to pointers:
+
+-   `&` as a prefix unary operator takes the address of an object, forming a
+    pointer to it.
+-   `*` as a prefix unary operator dereferences a pointer.
+
+Note that [member access expressions](member_access.md) include an `->` form
+that implicitly performs a dereference in the same way as the `*` operator.
+
+## Details
+
+The semantic details of pointer operators are collected in the main
+[pointers](/docs/design/values.md#pointers) design. The syntax and precedence
+details are covered here.
+
+The syntax tries to remain as similar as possible to C++ pointer types as they
+are commonly written in code and are expected to be extremely common and a key
+anchor of syntactic similarity between the languages.
+
+### Precedence
+
+These operators have high precedence. Only [member access](member_access.md)
+expressions can be used as an unparenthesized operand to them.
+
+The two prefix operators `&` and `*` are generally above the other unary and
+binary operators and can appear inside them as unparenthesized operands. For the
+full details, see the [precedence graph](README.md#precedence).
+
+## Alternatives considered
+
+-   [Alternative pointer syntaxes](/proposals/p2006.md#alternative-pointer-syntaxes)
+
+## References
+
+-   [Proposal #2006: Values, variables, and pointers](/proposals/p2006.md)