Change 2nd type parameter of stream

Fixes #453.

lang/lib/stream.bal

@@ -27,6 +27,13 @@ type Type any|error;
 @typeParam
 type ErrorType error;
 
+# A type parameter that is a subtype of `error?`.
+# Has the special semantic that when used in a declaration
+# all uses in the declaration must refer to same type.
+# This represents the result type of an iterator.
+@typeParam
+type ResultType error?;
+
 # A type parameter that is a subtype of `any|error`.
 # Has the special semantic that when used in a declaration
 # all uses in the declaration must refer to same type.
@@ -37,18 +44,18 @@ type Type1 any|error;
 #
 # + stm - the stream
 # + return - a new iterator object that will iterate over the members of `stm`.
-public function iterator(stream<Type,ErrorType> stm) returns abstract object {
+public function iterator(stream<Type,ResultType> stm) returns abstract object {
     public function next() returns record {|
         Type value;
-    |}|ErrorType?;
+    |}|ResultType;
 } = external;
 
 # Closes a stream.
 # This releases any system resources being used by the stream.
 #
 # + stm - the stream to close
 # + return - () if the close completed successfully, otherwise an error
-public function close(stream<Type,ErrorType> stm) returns ErrorType? = external;
+public function close(stream<Type,ResultType> stm) returns ResultType? = external;
 
 // Functional iteration
 
@@ -57,23 +64,23 @@ public function close(stream<Type,ErrorType> stm) returns ErrorType? = external;
 # + stm - the stream
 # + func - a function to apply to each member
 # + return - new stream containing result of applying `func` to each member of `stm` in order
-public function 'map(stream<Type,ErrorType> stm, function(Type val) returns Type1 func)
-   returns stream<Type1,ErrorType> = external;
+public function 'map(stream<Type,ResultType> stm, function(Type val) returns Type1 func)
+   returns stream<Type1,ResultType> = external;
 
 # Applies a function to each member of a stream.
 # The function `func` is applied to each member of stream `stm` in order.
 #
 # + stm - the stream
 # + func - a function to apply to each member
-public function forEach(stream<Type,ErrorType> stm, function(Type val) returns () func) returns ErrorType? = external;
+public function forEach(stream<Type,ResultType> stm, function(Type val) returns () func) returns ResultType = external;
 
 # Selects the members from a stream for which a function returns true.
 #
 # + stm - the stream
 # + func - a predicate to apply to each member to test whether it should be selected
 # + return - new stream only containing members of `stm` for which `func` evaluates to true
-public function filter(stream<Type,ErrorType> stm, function(Type val) returns boolean func)
-   returns stream<Type,ErrorType> = external;
+public function filter(stream<Type,ResultType> stm, function(Type val) returns boolean func)
+   returns stream<Type,ResultType> = external;
 
 # Combines the members of a stream using a combining function.
 # The combining function takes the combined value so far and a member of the stream,
@@ -83,5 +90,5 @@ public function filter(stream<Type,ErrorType> stm, function(Type val) returns bo
 # + func - combining function
 # + initial - initial value for the first argument of combining function `func`
 # + return - result of combining the members of `stm` using `func`
-public function reduce(stream<Type,ErrorType> stm, function(Type1 accum, Type val) returns Type1 func, Type1 initial)
+public function reduce(stream<Type,ErrorType?> stm, function(Type1 accum, Type val) returns Type1 func, Type1 initial)
    returns Type1|ErrorType = external;

lang/spec.html

@@ -598,7 +598,7 @@ <h2 id="values_types">5. Values, types and variables</h2>
 <th>Iteration sequence</th>
 <th>Type descriptor</th>
 <th>Type of values in iteration sequence</th>
-<th>Typeof result</th>
+<th>Type of result</th>
 </tr>
 <tr>
 <td>string</td>
@@ -631,9 +631,9 @@ <h2 id="values_types">5. Values, types and variables</h2>
 <tr>
 <td>stream</td>
 <td>items</td>
-<td><code>stream&lt;T,E&gt;</code></td>
+<td><code>stream&lt;T,R&gt;</code></td>
 <td><code>T</code></td>
-<td><code>E|()</code></td>
+<td><code>R</code></td>
 </tr>
 </table>
 
@@ -1958,31 +1958,29 @@ <h4>[Preview] Streams</h4>
 </pre>
 <p>
 A stream is an object-like value that can generate a sequence of values. The
-generation of the sequence may either be successful or may fail at some point
-with an error. A stream belongs to type <code>stream&lt;T,E&gt;</code> if the
-values in the generated sequence all belong to T and if any error on failure
-belongs to E. A stream belongs to type <code>stream&lt;T&gt;</code> if the
-values in the generated sequence all belong to T and the generation of the
-sequence never fails. Thus stream&lt;T&gt; is equivalent to
-<code>stream&lt;T,never&gt;</code>, where <code>never</code> is the type to
-which no values belong. A value belongs to a type <code>stream</code> (without
-the type-parameter) if it has basic type stream.
+generation of the sequence has a result value, which is either nil, indicating
+the sequence was generated successfully, or an error. A stream belongs to type
+<code>stream&lt;T,R&gt;</code> if the values in the generated sequence all
+belong to T and if the result value belongs to R. The type
+<code>stream&lt;T&gt;</code> is equivalent to <code>stream&lt;T,()&gt;</code>. A
+value belongs to a type <code>stream</code> (without the type-parameter) if it
+has basic type stream. A type <code>stream&lt;T,R&gt;</code> where R does not
+include nil represents an unbounded stream.
 </p>
 <p>
 A stream supports two primitive operations: a next operation and a close
 operation. The next operation has the same semantics as the next method on the
 Iterator abstract object type. The close operation informs the stream that there
 will be no more next operations and thus allows the stream to release resources
-used by the stream; the close operation on a <code>stream&lt;T,E&gt;</code> may
-return an error of type <code>E</code>.
+used by the stream; the close operation on a <code>stream&lt;T,R&gt;</code> has
+a result of type <code>R?</code>, where nil means that the close operation was
+successful.
 </p>
 <p>
-The normal implementation of a <code>stream&lt;T,E&gt;</code> is a wrapper
+The normal implementation of a <code>stream&lt;T,R&gt;</code> is a wrapper
 around an object belonging to <a href="#StreamImplementor">abstract object type
-<code>StreamImplementor&lt;T,E?&gt;</code></a>. The next and close operations on
-the stream delegate to the next and close methods on the StreamImplementor. Note
-that nil is implicitly included in the second type parameter of stream, but is
-explicit in the second parameter of StreamImplementor.
+<code>StreamImplementor&lt;T,R&gt;</code></a>. The next and close operations on
+the stream delegate to the next and close methods on the StreamImplementor.
 </p>
 <p>
 The stream module of the <a href="#lang_library">lang library</a> provides
@@ -1991,8 +1989,8 @@ <h4>[Preview] Streams</h4>
 </p>
 <p>
 A stream is iterable. The type of the values The type of the values in the
-iteration sequence of a value belonging <code>stream&lt;T,E&gt;</code> is
-<code>T</code> and the type of the iterations result is <code>E?</code>. Calling
+iteration sequence of a value belonging <code>stream&lt;T,R&gt;</code> is
+<code>T</code> and the type of the iteration's result is <code>R</code>. Calling
 the next method on the iterator created for an iteration has the same effect as
 performing the next operation on the stream. The stream does not keep a copy of
 the sequence of values returned by the next operation. Any subsequent iteration
@@ -2242,8 +2240,8 @@ <h4 id="StreamImplementor">StreamImplementor</h4>
 <p>
 An object belongs to the abstract object type StreamImplementor&lt;T,R&gt; if it
 belongs to Iterator&lt;T,R&gt; and also optionally has a method
-<code>close()</code> with return value R. This is equivalent to belonging to the
-following type.
+<code>close()</code> with return value <code>R?</code>. This is equivalent to
+belonging to the following type.
 </p>
 
 <pre
@@ -2252,7 +2250,7 @@ <h4 id="StreamImplementor">StreamImplementor</h4>
     }
     | abstract object {
        public next() returns record {| T value; |}|R;
-       public close() returns R;
+       public close() returns R?;
     }
 </pre>