:orphan:

.. raw:: html

    <style>
    table.docutils td,
    table.docutils th {
      border: 1px solid #aaa;
    }
    </style>


==================================
Immutability and Read-Only Methods
==================================

:Abstract: Swift programmers can already express the concept of
           read-only properties and subscripts, and can express their
           intention to write on a function parameter.  However, the
           model is incomplete, which currently leads to the compiler
           to accept (and silently drop) mutations made by methods of
           these read-only entities.  This proposal completes the
           model, and additionally allows the user to declare truly
           immutable data.

The Problem
===========

Consider::

  class Window {

    var title: String { // title is not writable
      get {
        return somethingComputed()
      }
    }
  }

  var w = Window()
  w.title += " (parenthesized remark)"

What do we do with this?  Since ``+=`` has an ``inout`` first
argument, we detect this situation statically (hopefully one day we'll
have a better error message): 

.. code-block:: swift-console
   
 <REPL Input>:1:9: error: expression does not type-check
 w.title += " (parenthesized remark)"
 ~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~

Great.  Now what about this? [#append]_ ::

  w.title.append(" (fool the compiler)")

Today, we allow it, but since there's no way to implement the
write-back onto ``w.title``, the changes are silently dropped.

Unsatisfying Approaches
=======================

We considered three alternatives to the current proposal, none of
which were considered satisfactory:

1. Ban method calls on read-only properties of value type
2. Ban read-only properties of value type
3. Status quo: silently drop the effects of some method calls

For rationales explaining why these approaches were rejected, please
refer to earlier versions of this document.

Proposed Solution
=================

Terminology
-----------

Classes and generic parameters that conform to a protocol attributed
``@class_protocol`` are called **reference types**.  All other types
are **value types**.

Mutating and Read-Only Methods
------------------------------

A method attributed with ``inout`` is considered **mutating**.
Otherwise, it is considered **read-only**.

.. parsed-literal::

   struct Number {
     init(x: Int) { name = x.toString() }

     func getValue() {              // read-only method
       return Int(name)
     }
     **mutating** func increment() {  // mutating method
       name = (Int(name)+1).toString()
     }
     var name: String
   }

The implicit ``self`` parameter of a struct or enum method is semantically an
``inout`` parameter if and only if the method is attributed with
``mutating``.  Read-only methods do not "write back" onto their target
objects.

A program that applies the ``mutating`` to a method of a
class—or of a protocol attributed with ``@class_protocol``—is
ill-formed.  [Note: it is logically consistent to think of all methods
of classes as read-only, even though they may in fact modify instance
variables, because they never "write back" onto the source reference.]

Mutating Operations
-------------------

The following are considered **mutating operations** on an lvalue

1. Assignment to the lvalue
2. Taking its address

Remember that the following operations all take an lvalue's address
implicitly:

* passing it to a mutating method::

    var x = Number(42)
    x.increment()         // mutating operation
  
* passing it to a function attributed with ``@assignment``::

    var y = 31
    y += 3                // mutating operation

* assigning to a subscript or property (including an instance
  variable) of a value type::

    x._i = 3             // mutating operation
    var z: Array<Int> = [1000]
    z[0] = 2             // mutating operation

Binding for Rvalues
-------------------

Just as ``var`` declares a name for an lvalue, ``let`` now gives a
name to an rvalue:

.. parsed-literal::

   var clay = 42
   **let** stone = clay + 100 // stone can now be used as an rvalue

The grammar rules for ``let`` are identical to those for ``var``.

Properties and Subscripts
-------------------------

A subscript or property access expression is an rvalue if

* the property or subscript has no ``set`` clause
* the target of the property or subscript expression is an rvalue of
  value type

For example, consider this extension to our ``Number`` struct:
  
.. parsed-literal::

  extension Number {
    var readOnlyValue: Int { return getValue()  }

    var writableValue: Int {
      get {
       return getValue()
      }
      **set(x)** {
        name = x.toString()
      }
    }

    subscript(n: Int) -> String { return name }
    subscript(n: String) -> Int {
      get {
        return 42
      }
      **set(x)** {
        name = x.toString()
      }
    }
  }

Also imagine we have a class called ``CNumber`` defined exactly the
same way as ``Number`` (except that it's a class).  Then, the
following table holds:

+----------------------+----------------------------------+------------------------+
|          Declaration:|::                                |                        |
|                      |                                  |::                      |
|Expression            |   var x = Number(42)  // this    |                        |
|                      |   var x = CNumber(42) // or this |  let x = Number(42)    |
|                      |   let x = CNumber(42) // or this |                        |
+======================+==================================+========================+
| ``x.readOnlyValue``  |**rvalue** (no ``set`` clause)    |**rvalue** (target is an|
|                      |                                  |rvalue of value type)   |
|                      |                                  |                        |
+----------------------+                                  |                        |
| ``x[3]``             |                                  |                        |
|                      |                                  |                        |
|                      |                                  |                        |
+----------------------+----------------------------------+                        |
| ``x.writeableValue`` |**lvalue** (has ``set`` clause)   |                        |
|                      |                                  |                        |
+----------------------+                                  |                        |
| ``x["tree"]``        |                                  |                        |
|                      |                                  |                        |
+----------------------+----------------------------------+                        |
| ``x.name``           |**lvalue** (instance variables    |                        |
|                      |implicitly have a ``set``         |                        |
|                      |clause)                           |                        |
+----------------------+----------------------------------+------------------------+

The Big Rule
-------------

.. Error:: A program that applies a mutating operation to an rvalue is ill-formed
   :class: warning
        
For example:
                
.. parsed-literal::

   clay = 43           // OK; a var is always assignable
   **stone =** clay \* 1000 // **Error:** stone is an rvalue

   swap(&clay, **&stone**) // **Error:** 'stone' is an rvalue; can't take its address

   **stone +=** 3          // **Error:** += is declared inout, @assignment and thus
                       // implicitly takes the address of 'stone'

   **let** x = Number(42)  // x is an rvalue
   x.getValue()        // ok, read-only method
   x.increment()       // **Error:** calling mutating method on rvalue
   x.readOnlyValue     // ok, read-only property
   x.writableValue     // ok, there's no assignment to writableValue
   x.writableValue++   // **Error:** assigning into a property of an immutable value

Non-``inout`` Function Parameters are RValues
----------------------------------------------

A function that performs a mutating operation on a parameter is
ill-formed unless that parameter was marked with ``inout``.  A
method that performs a mutating operation on ``self`` is ill-formed
unless the method is attributed with ``mutating``:

.. parsed-literal::

  func f(_ x: Int, y: inout Int) {
    y = x         // ok, y is an inout parameter
    x = y         // **Error:** function parameter 'x' is immutable
  }

Protocols and Constraints
-------------------------

When a protocol declares a property or ``subscript`` requirement, a
``{ get }`` or ``{ get set }`` clause is always required.

.. parsed-literal::

   protocol Bitset {
     var count: Int { **get** }
     var intValue: Int { **get set** }
     subscript(bitIndex: Int) -> Bool { **get set** }
   }

Where a ``{ get set }`` clause appears, the corresponding expression
on a type that conforms to the protocol must be an lvalue or the
program is ill-formed:

.. parsed-literal::

  struct BS {
    var count: Int    // ok; an lvalue or an rvalue is fine

    var intValue : Int {
      get {
        return 3
      }
      set {             // ok, lvalue required and has a set clause
        ignore(value)
      }
    }

    subscript(i: Int) -> Bool {
      return true   // **Error:** needs a 'set' clause to yield an lvalue
    }
  }

-----------------

.. [#append] String will acquire an ``append(other: String)`` method as part of the
             formatting plan, but this scenario applies equally to any
             method of a value type