- Companion
- class
Type members
Classlikes
Projection of a Stream providing various ways to compile a Stream[F,O] to a G[...].
Projection of a Stream providing various ways to compile a Stream[F,O] to a G[...].
Provides syntax for streams that are invariant in F and O.
Provides syntax for streams that are invariant in F and O.
Provides operations on effectful pipes for syntactic convenience.
Provides operations on effectful pipes for syntactic convenience.
Provides operations on pure pipes for syntactic convenience.
Provides operations on pure pipes for syntactic convenience.
Provides operations on pure pipes for syntactic convenience.
Provides operations on pure pipes for syntactic convenience.
When merging multiple streams, this represents step of one leg.
When merging multiple streams, this represents step of one leg.
It is common to uncons, however unlike uncons, it keeps track
of stream scope independently of the main scope of the stream.
This assures, that after each next stepLeg each Stream leg keeps its scope
when interpreting.
Usual scenarios is to first invoke stream.pull.stepLeg and then consume whatever is
available in leg.head. If the next step is required leg.stepLeg will yield next Leg.
Once the stream will stop to be interleaved (merged), then stream allows to return to normal stream
invocation.
Value members
Concrete methods
Creates a pure stream that emits the supplied values. To convert to an effectful stream, use covary.
Creates a pure stream that emits the supplied values. To convert to an effectful stream, use covary.
Creates a single element stream that gets its value by evaluating the supplied effect. If the effect fails, a Left
is emitted. Otherwise, a Right is emitted.
Creates a single element stream that gets its value by evaluating the supplied effect. If the effect fails, a Left
is emitted. Otherwise, a Right is emitted.
Use eval instead if a failure while evaluating the effect should fail the stream.
- Example
scala> import cats.effect.SyncIO scala> Stream.attemptEval(SyncIO(10)).compile.toVector.unsafeRunSync() res0: Vector[Either[Throwable,Int]] = Vector(Right(10)) scala> Stream.attemptEval(SyncIO(throw new RuntimeException)).compile.toVector.unsafeRunSync() res1: Vector[Either[Throwable,Nothing]] = Vector(Left(java.lang.RuntimeException))
Light weight alternative to awakeEvery that sleeps for duration d before each pulled element.
Light weight alternative to awakeEvery that sleeps for duration d before each pulled element.
Discrete stream that every d emits elapsed duration
since the start time of stream consumption.
Discrete stream that every d emits elapsed duration
since the start time of stream consumption.
Missed periods are dampened to a single tick.
For example: awakeEvery[IO](5 seconds) will
return (approximately) 5s, 10s, 15s, and will lie dormant
between emitted values.
- Value Params
- period
duration between emits of the resulting stream
Discrete stream that every d emits elapsed duration
since the start time of stream consumption.
Discrete stream that every d emits elapsed duration
since the start time of stream consumption.
For example: awakeEvery[IO](5 seconds) will
return (approximately) 5s, 10s, 15s, and will lie dormant
between emitted values.
- Value Params
- dampen
whether missed periods result in 1 emitted tick or 1 per missed period, see fixedRate for more info
- period
duration between emits of the resulting stream
Creates a stream that emits a resource allocated by an effect, ensuring the resource is eventually released regardless of how the stream is used.
Creates a stream that emits a resource allocated by an effect, ensuring the resource is eventually released regardless of how the stream is used.
A typical use case for bracket is working with files or network sockets. The resource effect
opens a file and returns a reference to it. One can then flatMap on the returned Stream to access
the file, e.g to read bytes and transform them in to some stream of elements
(e.g., bytes, strings, lines, etc.).
The release action then closes the file once the result Stream terminates, even in case of interruption
or errors.
- Value Params
- acquire
resource to acquire at start of stream
- release
function which returns an effect that releases the resource
Like bracketCase but no scope is introduced, causing resource finalization to occur at the end of the current scope at the time of acquisition.
Like bracketCase but no scope is introduced, causing resource finalization to occur at the end of the current scope at the time of acquisition.
Like bracketCase but the acquire action may be canceled.
Like bracketCase but the acquire action may be canceled.
Like bracketFull but no scope is introduced, causing resource finalization to occur at the end of the current scope at the time of acquisition.
Like bracketFull but no scope is introduced, causing resource finalization to occur at the end of the current scope at the time of acquisition.
Creates a pure stream that emits the elements of the supplied chunk.
Creates a pure stream that emits the elements of the supplied chunk.
- Example
scala> Stream.chunk(Chunk(1,2,3)).toList res0: List[Int] = List(1, 2, 3)
Creates an infinite pure stream that always returns the supplied value.
Creates an infinite pure stream that always returns the supplied value.
Elements are emitted in finite chunks with chunkSize number of elements.
- Example
scala> Stream.constant(0).take(5).toList res0: List[Int] = List(0, 0, 0, 0, 0)
A continuous stream of the elapsed time, computed using System.nanoTime.
Note that the actual granularity of these elapsed times depends on the OS, for instance
the OS may only update the current time every ten milliseconds or so.
A continuous stream of the elapsed time, computed using System.nanoTime.
Note that the actual granularity of these elapsed times depends on the OS, for instance
the OS may only update the current time every ten milliseconds or so.
Creates a singleton pure stream that emits the supplied value.
Creates a singleton pure stream that emits the supplied value.
- Example
scala> Stream.emit(0).toList res0: List[Int] = List(0)
Creates a pure stream that emits the supplied values.
Creates a pure stream that emits the supplied values.
- Example
scala> Stream.emits(List(1, 2, 3)).toList res0: List[Int] = List(1, 2, 3)
Creates a single element stream that gets its value by evaluating the supplied effect. If the effect fails, the returned stream fails.
Creates a single element stream that gets its value by evaluating the supplied effect. If the effect fails, the returned stream fails.
Use attemptEval instead if a failure while evaluating the effect should be emitted as a value.
- Example
scala> import cats.effect.SyncIO scala> Stream.eval(SyncIO(10)).compile.toVector.unsafeRunSync() res0: Vector[Int] = Vector(10) scala> Stream.eval(SyncIO(throw new RuntimeException)).covaryOutput[Int].compile.toVector.attempt.unsafeRunSync() res1: Either[Throwable,Vector[Int]] = Left(java.lang.RuntimeException)
Like eval but resulting chunk is flatten efficiently.
Like eval but resulting chunk is flatten efficiently.
A continuous stream which is true after d, 2d, 3d... elapsed duration,
and false otherwise.
If you'd like a 'discrete' stream that will actually block until d has elapsed,
use awakeEvery instead.
A continuous stream which is true after d, 2d, 3d... elapsed duration,
and false otherwise.
If you'd like a 'discrete' stream that will actually block until d has elapsed,
use awakeEvery instead.
As a result, the returned stream emits no elements and hence has output type INothing.
As a result, the returned stream emits no elements and hence has output type INothing.
- Example
scala> import cats.effect.SyncIO scala> Stream.exec(SyncIO(println("Ran"))).covaryOutput[Int].compile.toVector.unsafeRunSync() res0: Vector[Int] = Vector()
Light weight alternative to fixedRate that sleeps for duration d before each pulled element.
Light weight alternative to fixedRate that sleeps for duration d before each pulled element.
Behavior differs from fixedRate because the sleep between elements occurs after the next element
is pulled whereas fixedRate accounts for the time it takes to process the emitted unit.
This difference can roughly be thought of as the difference between scheduleWithFixedDelay and
scheduleAtFixedRate in java.util.concurrent.Scheduler.
Alias for sleep(period).repeat.
Discrete stream that emits a unit every d, with missed period ticks dampened.
Discrete stream that emits a unit every d, with missed period ticks dampened.
See fixedDelay for an alternative that sleeps d between elements.
- Value Params
- period
duration between emits of the resulting stream
Discrete stream that emits a unit every d.
Discrete stream that emits a unit every d.
See fixedDelay for an alternative that sleeps d between elements.
This operation differs in that the time between ticks should roughly be equal to the specified period, regardless
of how much time it takes to process that tick downstream. For example, with a 1 second period and a task that takes 100ms,
the task would run at timestamps, 1s, 2s, 3s, etc. when using fixedRate >> task whereas it would run at timestamps
1s, 2.1s, 3.2s, etc. when using fixedDelay >> task.
In the case where task processing takes longer than a single period, 1 or more ticks are immediately emitted to "catch-up".
The dampen parameter controls whether a single tick is emitted or whether one per missed period is emitted.
- Value Params
- dampen
true if a single unit should be emitted when multiple periods have passed since last execution, false if a unit for each period should be emitted
- period
period between emits of the resulting stream
Like emits, but works for any G that has a Foldable instance.
Like emits, but works for any G that has a Foldable instance.
Lifts an effect that generates a stream in to a stream. Alias for eval(f).flatMap(_).
Lifts an effect that generates a stream in to a stream. Alias for eval(f).flatMap(_).
- Example
scala> import cats.effect.SyncIO scala> Stream.force(SyncIO(Stream(1,2,3).covary[SyncIO])).compile.toVector.unsafeRunSync() res0: Vector[Int] = Vector(1, 2, 3)
Lifts an iterator into a Stream, shifting any interaction with the iterator to the blocking pool.
Lifts an iterator into a Stream, shifting any interaction with the iterator to the blocking pool.
Lifts an Either[Throwable, A] to an effectful Stream.
Lifts an Either[Throwable, A] to an effectful Stream.
- Example
scala> import cats.effect.SyncIO, scala.util.Try scala> Stream.fromEither[SyncIO](Right(42)).compile.toList.unsafeRunSync() res0: List[Int] = List(42) scala> Try(Stream.fromEither[SyncIO](Left(new RuntimeException)).compile.toList.unsafeRunSync()) res1: Try[List[Nothing]] = Failure(java.lang.RuntimeException)
Lifts an Option[A] to an effectful Stream.
Lifts an Option[A] to an effectful Stream.
- Example
scala> import cats.effect.SyncIO scala> Stream.fromOption[SyncIO](Some(42)).compile.toList.unsafeRunSync() res0: List[Int] = List(42) scala> Stream.fromOption[SyncIO](None).compile.toList.unsafeRunSync() res1: List[Nothing] = List()
Returns a stream of elements from the supplied queue.
Returns a stream of elements from the supplied queue.
The stream terminates upon dequeuing a None.
All elements that are available, up to the specified limit, are dequeued and emitted as a single chunk.
Returns a stream of elements from the supplied queue.
Returns a stream of elements from the supplied queue.
The stream terminates upon dequeuing a None.
All elements that are available, up to the specified limit, are dequeued and emitted as a single chunk.
Returns a stream of elements from the supplied queue.
Returns a stream of elements from the supplied queue.
All elements that are available, up to the specified limit, are dequeued and emitted as a single chunk.
Returns a stream of elements from the supplied queue.
Returns a stream of elements from the supplied queue.
All elements that are available, up to the specified limit, are dequeued and emitted as a single chunk.
Like emits, but works for any class that extends Iterable
Like emits, but works for any class that extends Iterable
An infinite Stream that repeatedly applies a given function
to a start value. start is the first value emitted, followed
by f(start), then f(f(start)), and so on.
An infinite Stream that repeatedly applies a given function
to a start value. start is the first value emitted, followed
by f(start), then f(f(start)), and so on.
- Example
scala> Stream.iterate(0)(_ + 1).take(10).toList res0: List[Int] = List(0, 1, 2, 3, 4, 5, 6, 7, 8, 9)
Like iterate, but takes an effectful function for producing
the next state. start is the first value emitted.
Like iterate, but takes an effectful function for producing
the next state. start is the first value emitted.
- Example
scala> import cats.effect.SyncIO scala> Stream.iterateEval(0)(i => SyncIO(i + 1)).take(10).compile.toVector.unsafeRunSync() res0: Vector[Int] = Vector(0, 1, 2, 3, 4, 5, 6, 7, 8, 9)
Creates a stream that, when run, fails with the supplied exception.
Creates a stream that, when run, fails with the supplied exception.
The F type must be explicitly provided (e.g., via raiseError[IO] or raiseError[Fallible]).
- Example
scala> import cats.effect.SyncIO scala> Stream.raiseError[Fallible](new RuntimeException).toList res0: Either[Throwable,List[INothing]] = Left(java.lang.RuntimeException) scala> Stream.raiseError[SyncIO](new RuntimeException).covaryOutput[Int].compile.drain.attempt.unsafeRunSync() res0: Either[Throwable,Unit] = Left(java.lang.RuntimeException)
Lazily produces the sequence [start, start + 1, start + 2, ..., stopExclusive).
If you want to produce the sequence in one chunk, instead of lazily, use
emits(start until stopExclusive).
Lazily produces the sequence [start, start + 1, start + 2, ..., stopExclusive).
If you want to produce the sequence in one chunk, instead of lazily, use
emits(start until stopExclusive).
- Example
scala> Stream.range(10, 20).toList res0: List[Int] = List(10, 11, 12, 13, 14, 15, 16, 17, 18, 19)
Lazily produce the sequence [start, start + step, start + 2 * step, ..., stopExclusive).
If you want to produce the sequence in one chunk, instead of lazily, use
emits(start until stopExclusive by step).
Lazily produce the sequence [start, start + step, start + 2 * step, ..., stopExclusive).
If you want to produce the sequence in one chunk, instead of lazily, use
emits(start until stopExclusive by step).
- Example
scala> Stream.range(10, 20, 2).toList res0: List[Int] = List(10, 12, 14, 16, 18)
Lazily produce a sequence of nonoverlapping ranges, where each range
contains size integers, assuming the upper bound is exclusive.
Example: ranges(0, 1000, 10) results in the pairs
(0, 10), (10, 20), (20, 30) ... (990, 1000)
Lazily produce a sequence of nonoverlapping ranges, where each range
contains size integers, assuming the upper bound is exclusive.
Example: ranges(0, 1000, 10) results in the pairs
(0, 10), (10, 20), (20, 30) ... (990, 1000)
Note: The last emitted range may be truncated at stopExclusive. For
instance, ranges(0,5,4) results in (0,4), (4,5).
- Throws
- IllegalArgumentException
if
size<= 0
- Example
scala> Stream.ranges(0, 20, 5).toList res0: List[(Int,Int)] = List((0,5), (5,10), (10,15), (15,20))
Converts the supplied resource in to a singleton stream.
Converts the supplied resource in to a singleton stream.
Like resource but does not introduce a scope, allowing finalization to occur after subsequent appends or other scope-preserving transformations.
Like resource but does not introduce a scope, allowing finalization to occur after subsequent appends or other scope-preserving transformations.
Scopes can be manually introduced via scope if desired.
Retries fo on failure, returning a singleton stream with the
result of fo as soon as it succeeds.
Retries fo on failure, returning a singleton stream with the
result of fo as soon as it succeeds.
- Value Params
- delay
Duration of delay before the first retry
- maxAttempts
Number of attempts before failing with the latest error, if
fonever succeeds- nextDelay
Applied to the previous delay to compute the next, e.g. to implement exponential backoff
- retriable
Function to determine whether a failure is retriable or not, defaults to retry every
NonFatal. A failed stream is immediately returned when a non-retriable failure is encountered
A single-element Stream that waits for the duration d before emitting unit.
A single-element Stream that waits for the duration d before emitting unit.
Alias for sleep(d).drain. Often used in conjunction with ++ (i.e., sleep_(..) ++ s) as a more
performant version of sleep(..) >> s.
Alias for sleep(d).drain. Often used in conjunction with ++ (i.e., sleep_(..) ++ s) as a more
performant version of sleep(..) >> s.
Starts the supplied task and cancels it as finalization of the returned stream.
Starts the supplied task and cancels it as finalization of the returned stream.
Returns a stream that evaluates the supplied by-name each time the stream is used, allowing use of a mutable value in stream computations.
Returns a stream that evaluates the supplied by-name each time the stream is used, allowing use of a mutable value in stream computations.
Note: it's generally easier to reason about such computations using effectful
values. That is, allocate the mutable value in an effect and then use
Stream.eval(fa).flatMap { a => ??? }.
- Example
scala> Stream.suspend { | val digest = java.security.MessageDigest.getInstance("SHA-256") | val bytes: Stream[Pure,Byte] = ??? | bytes.chunks.fold(digest) { (d,c) => d.update(c.toBytes.values); d } | }
Creates a stream by successively applying f until a None is returned, emitting
each output O and using each output S as input to the next invocation of f.
Creates a stream by successively applying f until a None is returned, emitting
each output O and using each output S as input to the next invocation of f.
- Example
scala> Stream.unfold(0)(i => if (i < 5) Some(i -> (i+1)) else None).toList res0: List[Int] = List(0, 1, 2, 3, 4)
Like unfoldChunk, but takes an effectful function.
Like unfoldChunk, but takes an effectful function.
Creates a stream by successively applying f to a S, emitting
each output O and using each output S as input to the next invocation of f
if it is Some, or terminating on None
Creates a stream by successively applying f to a S, emitting
each output O and using each output S as input to the next invocation of f
if it is Some, or terminating on None
- Example
scala> Stream.unfoldLoop(0)(i => (i, if (i < 5) Some(i+1) else None)).toList res0: List[Int] = List(0, 1, 2, 3, 4, 5)
Deprecated methods
Creates a stream that evaluates the supplied fa for its effect, discarding the output value.
As a result, the returned stream emits no elements and hence has output type INothing.
Creates a stream that evaluates the supplied fa for its effect, discarding the output value.
As a result, the returned stream emits no elements and hence has output type INothing.
Alias for eval(fa).drain.
- Deprecated
Implicits
Implicits
Align instance for Stream.
Align instance for Stream.
- @example
scala> import cats.syntax.all._
scala> Stream(1,2,3).align(Stream("A","B","C","D","E")).toList
res0: List[cats.data.Ior[Int,String]] = List(Both(1,A), Both(2,B), Both(3,C), Right(D), Right(E))
FunctionK instance for F ~> Stream[F, *]
FunctionK instance for F ~> Stream[F, *]
- Example
scala> import cats.Id scala> Stream.functionKInstance[Id](42).compile.toList res0: cats.Id[List[Int]] = List(42)
FunctorFilter instance for Stream.
FunctorFilter instance for Stream.
- Example
scala> import cats.syntax.all._, scala.util._ scala> Stream("1", "2", "NaN").mapFilter(s => Try(s.toInt).toOption).toList res0: List[Int] = List(1, 2)
MonadError instance for Stream.
MonadError instance for Stream.
- Example
scala> import cats.syntax.all._ scala> Stream(1, -2, 3).fproduct(_.abs).toList res0: List[(Int, Int)] = List((1,1), (-2,2), (3,3))