diff --git a/lang/lib/stream.bal b/lang/lib/stream.bal index c9f5c3d0..e27eefa7 100644 --- a/lang/lib/stream.bal +++ b/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,10 +44,10 @@ type Type1 any|error; # # + stm - the stream # + return - a new iterator object that will iterate over the members of `stm`. -public function iterator(stream stm) returns abstract object { +public function iterator(stream stm) returns abstract object { public function next() returns record {| Type value; - |}|ErrorType?; + |}|ResultType; } = external; # Closes a stream. @@ -48,7 +55,7 @@ public function iterator(stream stm) returns abstract object { # # + stm - the stream to close # + return - () if the close completed successfully, otherwise an error -public function close(stream stm) returns ErrorType? = external; +public function close(stream stm) returns ResultType? = external; // Functional iteration @@ -57,23 +64,23 @@ public function close(stream 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 stm, function(Type val) returns Type1 func) - returns stream = external; +public function 'map(stream stm, function(Type val) returns Type1 func) + returns stream = 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 stm, function(Type val) returns () func) returns ErrorType? = external; +public function forEach(stream 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 stm, function(Type val) returns boolean func) - returns stream = external; +public function filter(stream stm, function(Type val) returns boolean func) + returns stream = 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 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 stm, function(Type1 accum, Type val) returns Type1 func, Type1 initial) +public function reduce(stream stm, function(Type1 accum, Type val) returns Type1 func, Type1 initial) returns Type1|ErrorType = external; diff --git a/lang/spec.html b/lang/spec.html index 6f04e2ab..90061a1f 100644 --- a/lang/spec.html +++ b/lang/spec.html @@ -598,7 +598,7 @@

5. Values, types and variables

Iteration sequence Type descriptor Type of values in iteration sequence -Typeof result +Type of result string @@ -631,9 +631,9 @@

5. Values, types and variables

stream items -stream<T,E> +stream<T,R> T -E|() +R @@ -1958,31 +1958,29 @@

[Preview] Streams

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 stream<T,E> 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 stream<T> if the -values in the generated sequence all belong to T and the generation of the -sequence never fails. Thus stream<T> is equivalent to -stream<T,never>, where never is the type to -which no values belong. A value belongs to a type stream (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 +stream<T,R> if the values in the generated sequence all +belong to T and if the result value belongs to R. The type +stream<T> is equivalent to stream<T,()>. A +value belongs to a type stream (without the type-parameter) if it +has basic type stream. A type stream<T,R> where R does not +include nil represents an unbounded stream.

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 stream<T,E> may -return an error of type E. +used by the stream; the close operation on a stream<T,R> has +a result of type R?, where nil means that the close operation was +successful.

-The normal implementation of a stream<T,E> is a wrapper +The normal implementation of a stream<T,R> is a wrapper around an object belonging to abstract object type -StreamImplementor<T,E?>. 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. +StreamImplementor<T,R>. The next and close operations on +the stream delegate to the next and close methods on the StreamImplementor.

The stream module of the lang library provides @@ -1991,8 +1989,8 @@

[Preview] Streams

A stream is iterable. The type of the values The type of the values in the -iteration sequence of a value belonging stream<T,E> is -T and the type of the iterations result is E?. Calling +iteration sequence of a value belonging stream<T,R> is +T and the type of the iteration's result is R. 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 @@

StreamImplementor

An object belongs to the abstract object type StreamImplementor<T,R> if it belongs to Iterator<T,R> and also optionally has a method -close() with return value R. This is equivalent to belonging to the -following type. +close() with return value R?. This is equivalent to +belonging to the following type. 

StreamImplementor
     }
     | abstract object {
        public next() returns record {| T value; |}|R;
-       public close() returns R;
+       public close() returns R?;
     }