Iterant

The Concat state of the Iterant represents a state that specifies the concatenation of two streams.

Extension methods for deprecated methods.

The Halt state of the Iterant represents the completion state of a stream, with an optional exception if an error happened.

   `Halt` is received as a final state in the iteration process.
   This state cannot be followed by any other element and
   represents the end of the stream.

The Last state of the Iterant represents a completion state as an alternative to Halt(None), describing one last element.

   It is introduced as an optimization, being equivalent to
   `Next(item, F.pure(Halt(None)), F.unit)`, to avoid extra processing
   in the monadic `F[_]` and to short-circuit operations such as
   concatenation and `flatMap`.

The Next state of the Iterant represents a item / rest cons pair, where the head item is a strict value.

   Note that `item` being a strict value means that it is
   already known, whereas the `rest` is meant to be lazy and
   can have asynchronous behavior as well, depending on the `F`
   type used.

   See [[monix.tail.Iterant.NextCursor NextCursor]]
   for a state where the head is a strict immutable list.

The NextBatch state of the Iterant represents an batch / rest cons pair, where batch is an Iterable type that can generate a whole batch of elements.

The NextCursor state of the Iterant represents an batch / rest cons pair, where batch is an Iterator type that can generate a whole batch of elements.

   Useful for doing buffering, or by giving it an empty iterator,
   useful to postpone the evaluation of the next element.

The Scope state of the Iterant represents a stream that is able to specify the acquisition and release of a resource, to be used in generating stream events.

   `Scope` is effectively the encoding of
   [[https://typelevel.org/cats-effect/typeclasses/bracket.html Bracket]],
   necessary for safe handling of resources. The `use`
   parameter is supposed to trigger a side effectful action
   that allocates resources, which are then used via `use`
   and released via `close`.

   Note that this is often used in combination with
   [[Iterant.Suspend Suspend]] and data types like
   [[https://typelevel.org/cats-effect/concurrency/ref.html cats.effect.concurrent.Ref]]
   in order to communicate the acquired resources between
   `open`, `use` and `close`.

Builds a stream state equivalent with Iterant.NextCursor.

The Suspend state of the Iterant represents a suspended stream to be evaluated in the F context. It is useful to delay the evaluation of a stream by deferring to F.

Implements the Visitor Pattern for interpreting the Iterant data structure.

This can be used as an alternative to pattern matching and is used in the implementation of Iterant for performance reasons.

WARN: this being a class instead of a recursive function, it means that it often has to keep "shared state". Keeping shared state is great for performance, but breaks referential transparency, so use with care.

Provides the cats.effect.Sync instance for Iterant.

Alias for monix.catnap.ChannelF, using Option[Throwable] as the completion event, to be compatible with Iterant.

Alias for monix.catnap.ConsumerF, using Option[Throwable] as the completion event, to be compatible with Iterant.

Alias for monix.catnap.ProducerF, using Option[Throwable] as the completion event, to be compatible with Iterant.

The names of the product elements

The name of the type

Returns an IterantBuilders instance for the specified F monadic type that can be used to build Iterant instances.

This is used to achieve the Partially-Applied Type technique.

Example:

 import monix.eval.Task

 Iterant[Task].range(0, 10)

Returns a ProducerF instance, along with an Iterant connected to it.

Internally a ConcurrentChannel is used, the paired Iterant acting as a ConsumerF, connecting via ConcurrentChannel.consume.

Concatenates list of Iterants into a single stream

Builds a stream state equivalent with Iterant.Concat.

The Concat state of the Iterant represents a state that specifies the concatenation of two streams.

Alias for suspend.

Promote a non-strict value representing a stream to a stream of the same type, effectively delaying its initialisation.

Alias for eval.

Returns an empty stream.

Lifts a non-strict value into the stream context, returning a stream of one element that is lazily evaluated.

Converts any standard Array into a stream.

Converts a Batch into a stream.

Converts a BatchCursor into a stream.

Transforms any monix.catnap.ChannelF into an Iterant stream.

This allows for example consuming from a ConcurrentChannel.

Transforms any monix.catnap.ConsumerF into an Iterant stream.

This allows for example consuming from a ConcurrentChannel.

Converts any Scala collection.IndexedSeq into a stream (e.g. Vector).

Converts a scala.collection.Iterable into a stream.

Converts a scala.collection.Iterator into a stream.

Given an initial state and a generator function that produces the next state and the next element in the sequence in F[_] context, creates an Iterant that keeps generating Next items produced by our generator function.

Example:

 import monix.eval.Task

 val f = (x: Int) => Task((x + 1, x * 2))
 val seed = Task.pure(1)
 val stream = Iterant.fromLazyStateAction[Task, Int, Int](f)(seed)

 // Yields 2, 3, 5, 9
 stream.take(5)

Converts any Scala collection.immutable.LinearSeq into a stream.

Given an org.reactivestreams.Publisher, converts it into an Iterant.

Transforms any cats.effect.Resource into an Iterant.

See the documentation for Resource.

 import cats.effect.Resource
 import cats.effect.IO
 import java.io._

 def openFileAsResource(file: File): Resource[IO, FileInputStream] =
   Resource.make(IO(new FileInputStream(file)))(h => IO(h.close()))

 def openFileAsStream(file: File): Iterant[IO, FileInputStream] =
   Iterant[IO].fromResource(openFileAsResource(file))

This example would be equivalent with usage of Iterant.resource:

 def openFileAsResource2(file: File): Iterant[IO, FileInputStream] = {
   Iterant.resource(IO(new FileInputStream(file)))(h => IO(h.close()))
 }

This means that flatMap is safe to use:

 def readLines(file: File): Iterant[IO, String] =
   openFileAsStream(file).flatMap { in =>
     val buf = new BufferedReader(new InputStreamReader(in, "utf-8"))
     Iterant[IO].repeatEval(buf.readLine())
       .takeWhile(_ != null)
   }

Converts any scala.collection.Seq into a stream.

Given an initial state and a generator function that produces the next state and the next element in the sequence, creates an Iterant that keeps generating NextBatch items produced by our generator function with default recommendedBatchSize.

Example:

 import monix.eval.Task

 val f = (x: Int) => (x + 1, x * 2)
 val seed = 1
 val stream = Iterant.fromStateAction[Task, Int, Int](f)(seed)

 // Yields 2, 3, 5, 9
 stream.take(5)

Data constructor for building a Iterant.Halt value.

The Halt state of the Iterant represents the completion state of a stream, with an optional exception if an error happened.

   `Halt` is received as a final state in the iteration process.
   This state cannot be followed by any other element and
   represents the end of the stream.

Creates an iterant that emits auto-incremented natural numbers (longs). at a fixed rate, as given by the specified period. The amount of time it takes to process an incoming value gets subtracted from provided period, thus created iterant tries to emit events spaced by the given time interval, regardless of how long further processing takes

Creates an iterant that emits auto-incremented natural numbers (longs). at a fixed rate, as given by the specified period. The amount of time it takes to process an incoming value gets subtracted from provided period, thus created iterant tries to emit events spaced by the given time interval, regardless of how long further processing takes

This version of the intervalAtFixedRate allows specifying an initialDelay before first value is emitted

Creates an iterant that emits auto-incremented natural numbers (longs) spaced by a given time interval. Starts from 0 with no delay, after which it emits incremented numbers spaced by the period of time. The given period of time acts as a fixed delay between successive events.

Without having an initial delay specified, this overload will immediately emit the first item, without any delays.

Creates an iterant that emits auto-incremented natural numbers (longs) spaced by a given time interval. Starts from 0 with no delay, after which it emits incremented numbers spaced by the period of time. The given period of time acts as a fixed delay between successive events.

Builds a stream state equivalent with Iterant.Last.

The Last state of the Iterant represents a completion state as an alternative to Halt(None), describing one last element.

   It is introduced as an optimization, being equivalent to
   `Next(item, F.pure(Halt(None)), F.unit)`, to avoid extra processing
   in the monadic `F[_]` and to short-circuit operations such as
   concatenation and `flatMap`.

Lifts a value from monadic context into the stream context, returning a stream of one element

Returns a stream that never emits any event and never completes.

Data constructor for building a Iterant.NextBatch value.

The NextBatch state of the Iterant represents an batch / rest cons pair, where batch is an Iterable type that can generate a whole batch of elements.

Data constructor for building a Iterant.NextCursor value.

The NextCursor state of the Iterant represents an batch / rest cons pair, where batch is an Iterator type that can generate a whole batch of elements.

   Useful for doing buffering, or by giving it an empty iterator,
   useful to postpone the evaluation of the next element.

Data constructor for building a Iterant.Next value.

The Next state of the Iterant represents a item / rest cons pair, where the head item is a strict value.

   Note that `item` being a strict value means that it is
   already known, whereas the `rest` is meant to be lazy and
   can have asynchronous behavior as well, depending on the `F`
   type used.

   See [[monix.tail.Iterant.NextCursor NextCursor]]
   for a state where the head is a strict immutable list.

Lifts a strict value into the stream context, returning a stream of one element.

Alias for now.

Returns an empty stream that ends with an error.

Builds a stream that on evaluation will produce equally spaced values in some integer interval.

Builds a stream that repeats the items provided in argument.

It terminates either on error or if the source is empty.

Builds a stream that suspends provided thunk and evaluates it indefinitely on-demand.

The stream will only terminate if evaluation throws an exception

Referentially transparent alternative to Iterator.continually

Example: infinite sequence of random numbers

 import monix.eval.Coeval
 import scala.util.Random

 val randomInts = Iterant[Coeval].repeatEval(Random.nextInt())

Builds a stream that evaluates provided effectful values indefinitely.

The stream will only terminate if an error is raised in F context

Creates a stream that depends on resource allocated by a monadic value, ensuring the resource is released.

Typical use-cases are working with files or network sockets

Example:

 import cats.implicits._
 import cats.effect.IO
 import java.io.PrintWriter

 val printer =
   Iterant.resource {
     IO(new PrintWriter("./lines.txt"))
   } { writer =>
     IO(writer.close())
   }

 // Safely use the resource, because the release is
 // scheduled to happen afterwards
 val writeLines = printer.flatMap { writer =>
   Iterant[IO]
     .fromIterator(Iterator.from(1))
     .mapEval(i => IO { writer.println(s"Line #$$i") })
 }

 // Write 100 numbered lines to the file
 // closing the writer when finished
 writeLines.take(100).completedL

Creates a stream that depends on resource allocated by a monadic value, ensuring the resource is released.

Typical use-cases are working with files or network sockets

Example:

 import cats.effect._
 import java.io.PrintWriter

 val printer =
   Iterant.resource {
     IO(new PrintWriter("./lines.txt"))
   } { writer =>
     IO(writer.close())
   }

 // Safely use the resource, because the release is
 // scheduled to happen afterwards
 val writeLines = printer.flatMap { writer =>
   Iterant[IO]
     .fromIterator(Iterator.from(1))
     .mapEval(i => IO { writer.println(s"Line #$$i") })
 }

 // Write 100 numbered lines to the file
 // closing the writer when finished
 writeLines.take(100).completedL

Builds a stream state equivalent with Iterant.Scope.

The Scope state of the Iterant represents a stream that is able to specify the acquisition and release of a resource, to be used in generating stream events.

   `Scope` is effectively the encoding of
   [[https://typelevel.org/cats-effect/typeclasses/bracket.html Bracket]],
   necessary for safe handling of resources. The `use`
   parameter is supposed to trigger a side effectful action
   that allocates resources, which are then used via `use`
   and released via `close`.

   Note that this is often used in combination with
   [[Iterant.Suspend Suspend]] and data types like
   [[https://typelevel.org/cats-effect/concurrency/ref.html cats.effect.concurrent.Ref]]
   in order to communicate the acquired resources between
   `open`, `use` and `close`.

Promote a non-strict value representing a stream to a stream of the same type, effectively delaying its initialisation.

Defers the stream generation to the underlying evaluation context (e.g. Task, Coeval, IO, etc), building a reference equivalent with Iterant.Suspend.

The Suspend state of the Iterant represents a suspended stream to be evaluated in the F context. It is useful to delay the evaluation of a stream by deferring to F.

Builds a stream state equivalent with Iterant.NextCursor.

The Suspend state of the Iterant represents a suspended stream to be evaluated in the F context. It is useful to delay the evaluation of a stream by deferring to F.

Keeps calling f and concatenating the resulting iterants for each scala.util.Left event emitted by the source, concatenating the resulting iterants and generating events out of scala.util.Right[B] values.

Based on Phil Freeman's Stack Safety for Free.

Provides the cats.effect.Sync instance for Iterant.