Rename 'byref' attribute to 'inout'.

Swift SVN r8661

Author: jckarter

Diff for: docs/ABI.rst

@@ -255,7 +255,7 @@ types where the metadata itself has unknown layout.)
   type ::= 'M' type                          // metatype
   type ::= 'P' protocol-list '_'             // protocol type
   type ::= archetype
-  type ::= 'R' type                          // byref
+  type ::= 'R' type                          // inout
   type ::= 'T' tuple-element* '_'            // tuple
   type ::= 't' tuple-element* '_'            // variadic tuple
   type ::= 'U' generics '_' type             // generic type

Diff for: docs/LangRef.html

@@ -1451,7 +1451,7 @@ <h3 id="attribute-list">Attribute Lists</h3>
 
     attribute      ::= attribute-infix
     attribute      ::= attribute-resilience
-    attribute      ::= attribute-byref
+    attribute      ::= attribute-inout
     attribute      ::= attribute-auto_closure
     attribute      ::= attribute-noreturn
   </pre>
@@ -1492,19 +1492,19 @@ <h4 id="attribute-resilence">Resilience Attribute</h4>
   <p>See the resilience design.</p>
 
   <!-- _____________________________________________________________________ -->
-  <h4 id="attribute-byref">By-Reference Attribute</h4>
+  <h4 id="attribute-inout">By-Reference Attribute</h4>
 
   <pre class="grammar">
-    attribute-byref ::= 'byref'
+    attribute-inout ::= 'inout'
   </pre>
 
-  <p><tt>byref</tt> is only valid in a <tt>type-annotation</tt> that
+  <p><tt>inout</tt> is only valid in a <tt>type-annotation</tt> that
     appears within either a <a href="#pattern"><tt>pattern</tt></a> of
     a <tt>function-signature</tt> or the input type of a function
     type.
   </p>
 
-  <p><tt>byref</tt> indicates that the argument will be passed "by
+  <p><tt>inout</tt> indicates that the argument will be passed "by
     reference": the bound variable will be an l-value.</p>
 
   <p>The type being annotated must be <a href="#materializable">materializable</a>.
@@ -1649,7 +1649,7 @@ <h3>Materializable Types</h3>
 
   <p id="materializable">A type may be <i>materializable</i>.  A type
     is materializable unless it is 1) annotated with
-    a <a href="#attribute-byref"><tt>byref</tt></a> attribute or 2) a
+    a <a href="#attribute-inout"><tt>inout</tt></a> attribute or 2) a
     tuple with a non-materializable element type.  In general, variables
     must have materializable type.</p>
 
@@ -2221,7 +2221,7 @@ <h3 id="pattern-var">'var' Patterns</h3>
   <p>The type of a bound variable must be
     <a href="#materializable">materializable</a> unless it appears in a
     <a href="#function-signature">function-signature</a> and is directly of
-    a <a href="attribute-byref"><tt>byref</tt></a>-annotated type.</p>
+    a <a href="attribute-inout"><tt>inout</tt></a>-annotated type.</p>
 
   <!-- ********************************************************************* -->
   <h3 id="pattern-tuple">Tuple Patterns</h3>

Diff for: docs/LogicalObjects.rst

@@ -45,9 +45,9 @@ ways.
 For example, methods on value types have a this parameter.  Usually parameters
 are values, but this is actually an object: if I call a method on an object, and
 the method modifies the value of this, I expect it to modify the object I called
-the method on.  This is the high-level perspective of what [byref] really means:
+the method on.  This is the high-level perspective of what [inout] really means:
 that what we're really passing as a parameter is an object, not a value.  With
-one exception, everything that follows applies to any sort of [byref] parameter,
+one exception, everything that follows applies to any sort of [inout] parameter,
 not just this on value types.  More on that exception later.
 
 How do you actually pass an object, though, given that even physical objects
@@ -73,12 +73,12 @@ means materialization: calling the getter, storing the result into temporary
 memory, passing the temporary, and then calling the setter with the new value in
 the temporary when the method call is done.  This last step is called writeback.
 
-(About that one exception to this all applying equally to [byref]: in addition
+(About that one exception to this all applying equally to [inout]: in addition
 to all this stuff about calling methods on different kinds of object, we also
 want to support calling a method on a value.  This is also implemented with a
 form of materialization, which looks just like the logical-object kind except
 without writeback, because there's nothing to write back to.  This is a special
 rule that only applies to passing this, because we assume that most types will
 have lots of useful methods that don't involve writing to this, whereas we
-assume that a function with an explicit [byref] parameter is almost certain to
+assume that a function with an explicit [inout] parameter is almost certain to
 want to write to it.)

Diff for: docs/Objective-C Interoperability.rst

@@ -435,7 +435,7 @@ Output Parameters
   here: with ARC, the tuple owns the objects in it, and the caller owns the
   tuple.
 
-  Swift currently also has ``[byref]`` arguments. Whether or not these will be
+  Swift currently also has ``[inout]`` arguments. Whether or not these will be
   exposed to users and/or used for Objective-C out parameters is still
   undecided.
 

Diff for: docs/SIL.rst

@@ -731,27 +731,27 @@ The types of the SIL entry points are as follows::
   sil @curried_2 : $((z:C), (y:B), (x:A)) -> (w:D) -> Int { ... }
   sil @curried_3 : $((w:D), (z:C), (y:B), (x:A)) -> Int { ... }
 
-Byref Arguments
-```````````````
+[inout] Arguments
+`````````````````
 
-``[byref]`` arguments are passed into the entry point by address. The callee
+``[inout]`` arguments are passed into the entry point by address. The callee
 does not take ownership of the referenced memory. The referenced memory must
-be initialized upon function entry and exit. If the ``[byref]`` argument
+be initialized upon function entry and exit. If the ``[inout]`` argument
 refers to a fragile physical variable, then the argument is the address of that
-variable. If the ``[byref]`` argument refers to a logical property, then the
+variable. If the ``[inout]`` argument refers to a logical property, then the
 argument is the address of a caller-owner writeback buffer. it is the caller's
 responsibility to initialize the buffer by storing the result of the property
 getter prior to calling the function and to write back to the property
 on return by loading from the buffer and invoking the setter with the final
 value. This Swift function::
 
-  func byref(x:[byref] Int) {
+  func inout(x:[inout] Int) {
     x = 1
   }
 
 gets lowered to SIL as::
 
-  sil @byref : $([byref] Int) -> () {
+  sil @inout : $([inout] Int) -> () {
   entry(%x : $*Int):
     %1 = integer_literal 1 : $Int
     store %1 to %x
@@ -771,7 +771,7 @@ passed last::
     func method(x:Int) -> Int {}
   }
 
-  sil @Foo_method_1 : $((x : Int), [byref] Foo) -> Int { ... }
+  sil @Foo_method_1 : $((x : Int), [inout] Foo) -> Int { ... }
 
 C Calling Convention [cc(cdecl)]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Diff for: docs/StringDesign.rst

@@ -932,7 +932,7 @@ Building
 :Swift:
   .. parsed-literal::
         func **+** (lhs: String, rhs: String) -> String
-        func [infix,assignment] **+=** (lhs: [byref] String, rhs: String)
+        func [infix,assignment] **+=** (lhs: [inout] String, rhs: String)
         func **append**\ (suffix: String)
 
 

Diff for: docs/TextFormatting.rst

@@ -200,7 +200,7 @@ representation before writing an object to a stream, we provide a
 naturally ::
 
   protocol Streamable : Printable {
-    func writeTo<T: OutputStream>(target: [byref] T)
+    func writeTo<T: OutputStream>(target: [inout] T)
 
     // You'll never want to reimplement this
     func format() -> PrintRepresentation {
@@ -223,7 +223,7 @@ adds surrounding quotes and escapes special characters::
   struct EscapedStringRepresentation : Streamable {
     var _value: String
 
-    func writeTo<T: OutputStream>(target: [byref] T) {
+    func writeTo<T: OutputStream>(target: [inout] T) {
       target.append("\"")
       for c in _value {
         target.append(c.escape())
@@ -236,7 +236,7 @@ Besides modeling ``OutputStream``, ``String`` also conforms to
 ``Streamable``::
 
   extension String : Streamable {
-    func writeTo<T: OutputStream>(target: [byref] T) {
+    func writeTo<T: OutputStream>(target: [inout] T) {
       target.append(self) // Append yourself to the stream
     }
 
@@ -274,13 +274,13 @@ complicated ``format(…)`` might be written::
   struct RadixFormat<T: PrintableInteger> : Streamable {
     var value: T, radix = 10, fill = " ", width = 0
 
-    func writeTo<S: OutputStream>(target: [byref] S) {
+    func writeTo<S: OutputStream>(target: [inout] S) {
       _writeSigned(value, &target)
     }
 
     // Write the given positive value to stream
     func _writePositive<T:PrintableInteger, S: OutputStream>( 
-      value: T, stream: [byref] S
+      value: T, stream: [inout] S
     ) -> Int {
       if value == 0 { return 0 }
       var radix: T = T.fromInt(self.radix)
@@ -293,7 +293,7 @@ complicated ``format(…)`` might be written::
     }
 
     func _writeSigned<T:PrintableInteger, S: OutputStream>(
-      value: T, target: [byref] S
+      value: T, target: [inout] S
     ) {
       var width = 0
       var result = ""
@@ -371,7 +371,7 @@ For every conceivable ``OutputStream`` adaptor there's a corresponding
   struct UpperStreamable<UnderlyingStreamable:Streamable> {
     var base: UnderlyingStreamable
 
-    func writeTo<T: OutputStream>(target: [byref] T) {
+    func writeTo<T: OutputStream>(target: [inout] T) {
       var adaptedStream = UpperStream(target)
       self.base.writeTo(&adaptedStream)
       target = adaptedStream.base
@@ -417,7 +417,7 @@ least until we do, we opt not to trade away any CPU, memory, and
 power.
 
 If we were willing to say that only ``class``\ es can conform to
-``OutputStream``, we could eliminate the explicit ``[byref]`` where
+``OutputStream``, we could eliminate the explicit ``[inout]`` where
 ``OutputStream``\ s are passed around. Then, we'd simply need a
 ``class StringStream`` for creating ``String`` representations. It
 would also make ``OutputStream`` adapters a *bit* simpler to use
@@ -430,7 +430,7 @@ the underlying stream, which can then be “written back.”  :
 
   struct AdaptedStreamable<T:Streamable> {
     ...
-    func writeTo<Target: OutputStream>(target: [byref] Target) {
+    func writeTo<Target: OutputStream>(target: [inout] Target) {
       // create the stream that transforms the representation
       var adaptedTarget = adapt(target, adapter);
       // write the Base object to the target stream

Diff for: docs/TypeChecker.rst

@@ -77,7 +77,7 @@ the Swift type system:
     -  Exact equality constraints, or  "binding", written ``T0 := X``
        for some type variable ``T0`` and  type ``X``, which requires
        that ``T0`` be exactly identical to ``X``;
-    - Equality constraints, written ``X == Y`` for types ``X`` and ``Y``, which require ``X`` and ``Y`` to have the same type, ignoring lvalue types in the process. For example, the constraint ``T0 == X`` would be satisfied by assigning ``T0`` the type ``X`` and by assigning ``T0`` the type ``[byref] X``.
+    - Equality constraints, written ``X == Y`` for types ``X`` and ``Y``, which require ``X`` and ``Y`` to have the same type, ignoring lvalue types in the process. For example, the constraint ``T0 == X`` would be satisfied by assigning ``T0`` the type ``X`` and by assigning ``T0`` the type ``[inout] X``.
 
 **Subtyping**
   A subtype constraint requires the first type to be equivalent to or
@@ -150,7 +150,7 @@ and types generated from the primary expression kinds are:
   An expression that refers to a declaration ``x`` is assigned the
   type of a reference to ``x``. For example, if ``x`` is declared as
   ``var x : Int``, the expression ``x`` is assigned the type
-  ``[byref(implicit)] Int``. No constraints are generated.
+  ``[inout(implicit)] Int``. No constraints are generated.
 
   When a name refers to a set of overloaded declarations, the
   selection of the appropriate declaration is handled by the
@@ -256,9 +256,9 @@ and types generated from the primary expression kinds are:
   type.
 
 **Address of**
-  An address-of expression ``&a`` always returns a ``[byref]``
-  type. Therefore, it is assigned the type ``[byref] T0`` for a fresh
-  type variable ``T0``. The subtyping constraint ``[byref] T0 <
+  An address-of expression ``&a`` always returns a ``[inout]``
+  type. Therefore, it is assigned the type ``[inout] T0`` for a fresh
+  type variable ``T0``. The subtyping constraint ``[inout] T0 <
   T(a)`` captures the requirement that input expression be an lvalue
   of some type.
 

Diff for: docs/classes.rst

@@ -261,7 +261,7 @@ type of this declaration is
 ``(NSRect, owner : Id, withUserData : Id, assumeInside : Bool) -> Void``.
 This syntax is just sugar to allow giving arguments sane names for
 the implementation and possibly for documentation.  Being able to rename
-for the implementation is particularly important for byref arguments,
+for the implementation is particularly important for inout arguments,
 because they can't easily be renamed with a var decl in the implementation.
 
 The basic weakness here is that it requires a syntax extension to function

Diff for: docs/proposals/Inplace.rst

@@ -231,7 +231,7 @@ boilerplate::
 
       // ...without typing all this
       operator infix ☃= { assignment }
-      func ☃=(x:[byref] Int, y:Int) {
+      func ☃=(x:[inout] Int, y:Int) {
         x = x ☃ y
       }
 
@@ -291,11 +291,11 @@ When an in-place relationship is created, a definition matching either the
 in-place or value-creating form introduces an implicit definition of the other
 form::
 
-      func += (x:[byref] String, y:String) { ... }
+      func += (x:[inout] String, y:String) { ... }
       // Implicitly defines func + (x:String, y:String) -> String
 
       func + (x:Int, y:Int) -> Int { ... }
-      // Implicitly defines func += (x:[byref] Int, y:Int) -> ()
+      // Implicitly defines func += (x:[inout] Int, y:Int) -> ()
 
       struct String {
         func upper() -> String { ... }
@@ -329,7 +329,7 @@ in-place form, as if written::
 The implicit in-place form applies the value-creating form to its arguments and
 assigns the result to its left argument, as if written::
 
-      func += (x:[byref] Int, y:Int) {
+      func += (x:[inout] Int, y:Int) {
         x = x + y
       }
 

Diff for: docs/proposals/Memory and Concurrency Model.rst

@@ -48,7 +48,7 @@ definition. These kinds are:
    compiler rejects) immutable data that is pointing to mutable data. For
    example::
 
-     struct [immutable,byref] IList { data : int, next : List }
+     struct [immutable,inout] IList { data : int, next : List }
      ...
      var a = IList(1, IList(2, IList(3, nil)))
      ...
@@ -57,7 +57,7 @@ definition. These kinds are:
      a = IList(2, IList(3, nil)) // ok, "a" itself is mutable, it now points to something new.
      a = IList(1, a) // ok
 
-  Strings are a very important example of (byref) immutable data.
+  Strings are a very important example of (inout) immutable data.
 
 
 
@@ -68,7 +68,7 @@ definition. These kinds are:
    synchronization or atomic accesses are ever required for any mutable
    data. For example::
 
-     struct [byref] MEntry { x : int, y : int, list : IList }
+     struct [inout] MEntry { x : int, y : int, list : IList }
      ...
      var b = MEntry(4, 2, IList(1, nil))
      b.x = 4 // ok

Diff for: docs/proposals/ValueSemantics.rst

@@ -177,7 +177,7 @@ Here’s a version of cycle_length that works when state is a mutable
 value type::
 
  func cycle_length<State>(
-   s : State, mutate : ( [byref] State )->() 
+   s : State, mutate : ( [inout] State )->() 
  ) -> Int
    requires State : EqualityComparable
  {
@@ -209,7 +209,7 @@ classes:
  }
 
  func cycle_length<State>(
-   s : State, mutate : ( [byref] State )->() 
+   s : State, mutate : ( [inout] State )->() 
  ) -> Int
    requires State : EqualityComparable, **Clonable**
  {
@@ -221,7 +221,7 @@ classes:
 
  RandomNumberGenerator x = new MersenneTwister()
  println(
-    cycle_length(x, (x : [byref] RandomNumberGenerator) { x.nextValue() })
+    cycle_length(x, (x : [inout] RandomNumberGenerator) { x.nextValue() })
  )
 
 You could also redefine the interface so that it works on both values and
@@ -232,7 +232,7 @@ clonable classes:
  func cycle_length<State>(
    s : State, 
    **next : (x : State)->State,**
-   **equal : ([byref] x : State, [byref] y : State)->Bool**
+   **equal : ([inout] x : State, [inout] y : State)->Bool**
  ) -> Int
    requires State : EqualityComparable
  {
@@ -270,7 +270,7 @@ linked list::
 
 We can measure the length of a cycle in these nodes as follows::
 
- cycle_length( someNode, (x: [byref] Node){ x = x.next } )
+ cycle_length( someNode, (x: [inout] Node){ x = x.next } )
 
 This is why so many generic algorithms seem to work on both 
 ``class``\ es and non-``class``\ es: ``class`` *identities* 
@@ -293,7 +293,7 @@ to observe a difference in behavior:
 Take, for example, `swap`, which uses variable initialization and
 assignment to exchange two values::
 
-  func swap<T>(lhs : [byref] T, rhs : [byref] T)
+  func swap<T>(lhs : [inout] T, rhs : [inout] T)
   {
       var tmp = lhs   // big 3: initialization - ref copy in tmp
       lhs = rhs       // big 3: assignment     - ref copy in lhs
@@ -337,7 +337,7 @@ If we make `X` a `class`, we automatically get reference semantics, so
 its value must be copied before each mutation, which is tedious and
 error-prone.  Its public mutating interface must be in terms of free
 functions (not methods), so that the original reference value can be
-passed `[byref]` and overwritten.  Since there's no user access to the
+passed `[inout]` and overwritten.  Since there's no user access to the
 reference count, we can't determine that we hold the only reference to
 the value, so we can't optimize copy-on-write, even in single-threaded
 programs.  In multi-threaded programs, where each mutation implies