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.  sealed trait Pure[+A] extends AnyRef

   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 Scheduler extends AnyRef

   Provides operations based on the passage of cpu time.

   Provides operations based on the passage of cpu time.

   Operations on this class generally return streams. Some operations return effectful values instead. These operations are accessed via the .effect method, which returns a projection consisting of operations that return effects.

9.  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.

10.  abstract class Segment[+O, +R] extends AnyRef

    Potentially infinite, pure sequence of values of type O and a result of type R.

    Potentially infinite, pure sequence of values of type O and a result of type R.

    All methods on Segment support fusion with other arbitrary methods that return Segments. This is similar to the staging approach described in Stream Fusion, to Completeness, but without code generation in staging.

    To force evaluation of one or more values of a segment, call .force followed by one of the operations on the returned Segment.Force type. For example, to convert a segment to a vector, call s.force.toVector.

    Stack safety of fused operations is ensured by tracking a fusion depth. If the depth reaches the limit, the computation is trampolined using cats.Eval.

    The equals and hashCode methods are not defined for Segment.

    Implementation notes:

    • Some operators ask for a segment remainder from within a callback (e.g., emits). As such, segments should update state before invoking callbacks so that remainders can be computed accurately.
11.  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.

12.  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.

    Much of the API of Stream is defined in Stream.InvariantOps.

    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 segment:

    • s.cons(seg) == Stream.segment(seg) ++ 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 segment(Segment.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 segment structure of the stream is observable, and s flatMap Stream.emit produces a stream of singleton segments, the right identity law uses a weaker notion of equality, === which normalizes both sides with respect to segment 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 segment at a time and preserves segment structure, which differs from the map derived from the monad (s map f == s flatMap (f andThen Stream.emit)) which would produce singleton segments. In particular, if f throws errors, the segmented version will fail on the first segment with an error, while the unsegmented version will fail on the first element with an error. Exceptions in pure code like this are strongly discouraged.