fs2

Type Members

1. sealed abstract class Catenable[+A] extends AnyRef

   

   Trivial catenable sequence.

   Trivial catenable sequence. Supports O(1) append, and (amortized) O(1) uncons, such that walking the sequence via N successive uncons steps takes O(N). Like a difference list, conversion to a Seq[A] takes linear time, regardless of how the sequence is built up.

2. abstract class Chunk[+O] extends Serializable

   

   Strict, finite sequence of values that allows index-based random access of elements.

   Strict, finite sequence of values that allows index-based random access of elements.

   Chunks can be created from a variety of collection types using methods on the Chunk companion (e.g., Chunk.vector, Chunk.seq, Chunk.array). Additionally, the Chunk companion defines a subtype of Chunk for each primitive type, using an unboxed primitive array. To work with unboxed arrays, use methods like toBytes to convert a Chunk[Byte] to a Chunk.Bytes and then access the array directly.

   The operations on Chunk are all defined strictly. For example, c.map(f).map(g).map(h) results in intermediate chunks being created (1 per call to map). In contrast, a chunk can be lifted to a segment (via toSegment) to get arbitrary operator fusion.

3. final class CompositeFailure extends Throwable

   

   Represents multiple (>1) exceptions were thrown.

4. type Pipe[F[_], -I, +O] = (Stream[F, I]) ⇒ Stream[F, O]

   

   A stream transformation represented as a function from stream to stream.

   A stream transformation represented as a function from stream to stream.

   Pipes are typically applied with the through operation on Stream.

5. type Pipe2[F[_], -I, -I2, +O] = (Stream[F, I], Stream[F, I2]) ⇒ Stream[F, O]

   

   A stream transformation that combines two streams in to a single stream, represented as a function from two streams to a single stream.

   A stream transformation that combines two streams in to a single stream, represented as a function from two streams to a single stream.

   Pipe2s are typically applied with the through2 operation on Stream.

6. final class Pull[+F[_], +O, +R] extends AnyVal

   

   A p: Pull[F,O,R] reads values from one or more streams, returns a result of type R, and produces a Stream[F,O] when calling p.stream.

   A p: Pull[F,O,R] reads values from one or more streams, returns a result of type R, and produces a Stream[F,O] when calling p.stream.

   Any resources acquired by p are freed following the call to stream.

   Laws:

   Pull forms a monad in R with pure and flatMap:

   • pure >=> f == f
   • f >=> pure == f
   • (f >=> g) >=> h == f >=> (g >=> h) where f >=> g is defined as a => a flatMap f flatMap g

   raiseError is caught by handleErrorWith:

   • handleErrorWith(raiseError(e))(f) == f(e)

7. abstract type Pure[A] <: Nothing

   

   Indicates that a stream evaluates no effects.

   Indicates that a stream evaluates no effects.

   A Stream[Pure,O] can be safely converted to a Stream[F,O] for all F.

8. abstract class Scope[F[_]] extends AnyRef

   

   Represents a period of stream execution in which resources are acquired and released.

   Represents a period of stream execution in which resources are acquired and released.

   Note: this type is generally used to implement low-level actions that manipulate resource lifetimes and hence, isn't generally used by user-level code.

9. type Sink[F[_], -I] = (Stream[F, I]) ⇒ Stream[F, Unit]

   

   A pipe that converts a stream to a Stream[F,Unit].

   A pipe that converts a stream to a Stream[F,Unit].

   Sinks are typically applied with the to operation on Stream.

10. final class Stream[+F[_], +O] extends AnyVal

    

    A stream producing output of type O and which may evaluate F effects.

    A stream producing output of type O and which may evaluate F effects. If F is Pure, the stream evaluates no effects.

    Laws (using infix syntax):

    append forms a monoid in conjunction with empty:

    • empty append s == s and s append empty == s.
    • (s1 append s2) append s3 == s1 append (s2 append s3)

    And cons is consistent with using ++ to prepend a single chunk:

    • s.cons(c) == Stream.chunk(c) ++ s

    Stream.raiseError propagates until being caught by handleErrorWith:

    • Stream.raiseError(e) handleErrorWith h == h(e)
    • Stream.raiseError(e) ++ s == Stream.raiseError(e)
    • Stream.raiseError(e) flatMap f == Stream.raiseError(e)

    Stream forms a monad with emit and flatMap:

    • Stream.emit >=> f == f (left identity)
    • f >=> Stream.emit === f (right identity - note weaker equality notion here)
    • (f >=> g) >=> h == f >=> (g >=> h) (associativity) where Stream.emit(a) is defined as chunk(Chunk.singleton(a)) and f >=> g is defined as a => a flatMap f flatMap g

    The monad is the list-style sequencing monad:

    • (a ++ b) flatMap f == (a flatMap f) ++ (b flatMap f)
    • Stream.empty flatMap f == Stream.empty

    Technical notes

    Note: since the chunk structure of the stream is observable, and s flatMap Stream.emit produces a stream of singleton chunks, the right identity law uses a weaker notion of equality, === which normalizes both sides with respect to chunk structure:

    (s1 === s2) = normalize(s1) == normalize(s2) where == is full equality (a == b iff f(a) is identical to f(b) for all f)

    normalize(s) can be defined as s.flatMap(Stream.emit), which just produces a singly-chunked stream from any input stream s.

    Note: For efficiency Stream.map function operates on an entire chunk at a time and preserves chunk structure, which differs from the map derived from the monad (s map f == s flatMap (f andThen Stream.emit)) which would produce singleton chunk. In particular, if f throws errors, the chunked version will fail on the first chunk with an error, while the unchunked version will fail on the first element with an error. Exceptions in pure code like this are strongly discouraged.