final case class NextCursor[F[_], A](cursor: BatchCursor[A], rest: F[Iterant[F, A]], stop: F[Unit]) extends Iterant[F, A] with Product with Serializable
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.
- cursor
is an Iterator type that can generate elements by traversing a collection, a standard array or any
Iterator
- rest
is the next state in the sequence that will produce the rest of the stream when evaluated
- stop
is a computation to be executed in case streaming is stopped prematurely, giving it a chance to do resource cleanup (e.g. close file handles)
- Alphabetic
- By Inheritance
- NextCursor
- Iterant
- Serializable
- Serializable
- Product
- Equals
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
Instance Constructors
-
new
NextCursor(cursor: BatchCursor[A], rest: F[Iterant[F, A]], stop: F[Unit])
- cursor
is an Iterator type that can generate elements by traversing a collection, a standard array or any
Iterator
- rest
is the next state in the sequence that will produce the rest of the stream when evaluated
- stop
is a computation to be executed in case streaming is stopped prematurely, giving it a chance to do resource cleanup (e.g. close file handles)
Value Members
-
final
def
!=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
-
final
def
##(): Int
- Definition Classes
- AnyRef → Any
-
final
def
++[B >: A](rhs: Iterant[F, B])(implicit F: Applicative[F]): Iterant[F, B]
Appends the given stream to the end of the source, effectively concatenating them.
Appends the given stream to the end of the source, effectively concatenating them.
Example:
// Yields 1, 2, 3, 4 Iterant[Task].of(1, 2) ++ Iterant[Task].of(3, 4)
- rhs
is the (right hand side) iterant to concatenate at the end of this iterant.
- Definition Classes
- Iterant
-
final
def
++[B >: A](rhs: F[Iterant[F, B]])(implicit F: Applicative[F]): Iterant[F, B]
Appends a stream to the end of the source, effectively concatenating them.
Appends a stream to the end of the source, effectively concatenating them.
The right hand side is suspended in the
F[_]
data type, thus allowing for laziness.Example:
// Yields 1, 2, 3, 4 Iterant[Task].of(1, 2) ++ Task.suspend { Iterant[Task].of(3, 4) }
- rhs
is the iterant to append at the end of our source.
- Definition Classes
- Iterant
-
final
def
+:[B >: A](head: B)(implicit F: Applicative[F]): Iterant[F, B]
Prepends an element to the iterant, returning a new iterant that will start with the given
head
and then continue with the source.Prepends an element to the iterant, returning a new iterant that will start with the given
head
and then continue with the source.Example:
// Yields 1, 2, 3, 4 1 +: Iterant[Task].of(2, 3, 4)
- head
is the element to prepend at the start of this iterant
- Definition Classes
- Iterant
-
final
def
:+[B >: A](elem: B)(implicit F: Applicative[F]): Iterant[F, B]
Appends the right hand side element to the end of this iterant.
Appends the right hand side element to the end of this iterant.
Example:
// Yields 1, 2, 3, 4 Iterant[Task].of(1, 2, 3) :+ 4
- elem
is the element to append at the end
- Definition Classes
- Iterant
-
final
def
==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
-
final
def
asInstanceOf[T0]: T0
- Definition Classes
- Any
-
final
def
attempt(implicit F: Sync[F]): Iterant[F, Either[Throwable, A]]
Converts the source
Iterant
that emitsA
elements into an iterant that emitsEither[Throwable, A]
, thus materializing whatever error that might interrupt the stream.Converts the source
Iterant
that emitsA
elements into an iterant that emitsEither[Throwable, A]
, thus materializing whatever error that might interrupt the stream.Example:
// Yields Right(1), Right(2), Right(3) Iterant[Task].of(1, 2, 3).attempt // Yields Right(1), Right(2), Left(DummyException()) (Iterant[Task].of(1, 2) ++ Iterant[Task].raiseError(DummyException())).attempt
- Definition Classes
- Iterant
-
def
batched(count: Int)(implicit F: Sync[F]): Iterant[F, A]
Optimizes the access to the source by periodically gathering items emitted into batches of the specified size and emitting NextBatch nodes.
Optimizes the access to the source by periodically gathering items emitted into batches of the specified size and emitting NextBatch nodes.
For this operation we have this law:
source.batched(16) <-> source
This means that the result will emit exactly what the source emits, however the underlying representation will be different, the emitted notes being of type
NextBatch
, wrapping arrays with the length equal to the givencount
.Very similar in behavior with bufferTumbling, however the batches are implicit, not explicit. Useful for optimization.
- Definition Classes
- Iterant
-
final
def
bufferSliding(count: Int, skip: Int)(implicit F: Sync[F]): Iterant[F, Seq[A]]
Returns an iterant that emits buffers of items it collects from the source iterant.
Returns an iterant that emits buffers of items it collects from the source iterant. The resulting iterant emits buffers every
skip
items, each containingcount
items.If the source iterant completes, then the current buffer gets signaled downstream. If the source triggers an error then the current buffer is being dropped and the error gets propagated immediately.
For
count
andskip
there are 3 possibilities:- in case
skip == count
, then there are no items dropped and no overlap, the call being equivalent tobuffer(count)
- in case
skip < count
, then overlap between buffers happens, with the number of elements being repeated beingcount - skip
- in case
skip > count
, thenskip - count
elements start getting dropped between windows
Example:
val source = Iterant[Coeval].of(1, 2, 3, 4, 5, 6, 7) // Yields Seq(1, 2, 3), Seq(4, 5, 6), Seq(7) source.bufferSliding(3, 3) // Yields Seq(1, 2, 3), Seq(5, 6, 7) source.bufferSliding(3, 4) // Yields Seq(1, 2, 3), Seq(3, 4, 5), Seq(5, 6, 7) source.bufferSliding(3, 2)
- count
the maximum size of each buffer before it should be emitted
- skip
how many items emitted by the source iterant should be skipped before starting a new buffer. Note that when skip and count are equal, this is the same operation as
bufferTumbling(count)
- Definition Classes
- Iterant
- in case
-
def
bufferTumbling(count: Int)(implicit F: Sync[F]): Iterant[F, Seq[A]]
Periodically gather items emitted by an iterant into bundles and emit these bundles rather than emitting the items one at a time.
Periodically gather items emitted by an iterant into bundles and emit these bundles rather than emitting the items one at a time. This version of
buffer
is emitting items once the internal buffer has reached the given count.If the source iterant completes, then the current buffer gets signaled downstream. If the source triggers an error then the current buffer is being dropped and the error gets propagated immediately.
// Yields Seq(1, 2, 3), Seq(4, 5, 6), Seq(7) Iterant[Coeval].of(1, 2, 3, 4, 5, 6, 7).bufferTumbling(3)
- count
the maximum size of each buffer before it should be emitted
- Definition Classes
- Iterant
- See also
bufferSliding for the more flexible version that allows to specify a
skip
argument.
-
def
clone(): AnyRef
- Attributes
- protected[java.lang]
- Definition Classes
- AnyRef
- Annotations
- @throws( ... )
-
final
def
collect[B](pf: PartialFunction[A, B])(implicit F: Sync[F]): Iterant[F, B]
Builds a new iterant by applying a partial function to all elements of the source on which the function is defined.
Builds a new iterant by applying a partial function to all elements of the source on which the function is defined.
Example:
// Yields 2, 4, 6 Iterant[Task].of(1, 2, 3, 4, 5, 6) .map { x => Option(x).filter(_ % 2 == 0) } .collect { case Some(x) => x }
- B
the element type of the returned iterant.
- pf
the partial function that filters and maps the iterant
- returns
a new iterant resulting from applying the partial function
pf
to each element on which it is defined and collecting the results. The order of the elements is preserved.
- Definition Classes
- Iterant
-
final
def
completeL(implicit F: Sync[F]): F[Unit]
Upon evaluation of the result, consumes this iterant to completion.
Upon evaluation of the result, consumes this iterant to completion.
Example:
val onFinish: Task[Unit] = iterant.completeL >> Task.eval(println("Done!"))
- Definition Classes
- Iterant
-
final
def
concat[B](implicit ev: <:<[A, Iterant[F, B]], F: Sync[F]): Iterant[F, B]
Alias for concat.
-
final
def
concatMap[B](f: (A) ⇒ Iterant[F, B])(implicit F: Sync[F]): Iterant[F, B]
Alias for flatMap.
-
final
def
countL(implicit F: Sync[F]): F[Long]
Counts the total number of elements emitted by the source.
Counts the total number of elements emitted by the source.
Example:
// Yields 100 Iterant[IO].range(0, 100).countL // Yields 1 Iterant[IO].pure(1).countL // Yields 0 Iterant[IO].empty[Int].countL
- Definition Classes
- Iterant
- val cursor: BatchCursor[A]
-
final
def
distinctUntilChanged(implicit F: Sync[F], A: Eq[A]): Iterant[F, A]
Suppress duplicate consecutive items emitted by the source.
Suppress duplicate consecutive items emitted by the source.
Example:
// Yields 1, 2, 1, 3, 2, 4 Iterant[Coeval].of(1, 1, 1, 2, 2, 1, 1, 3, 3, 3, 2, 2, 4, 4, 4) .distinctUntilChanged
Duplication is detected by using the equality relationship provided by the
cats.Eq
type class. This allows one to override the equality operation being used (e.g. maybe the default.equals
is badly defined, or maybe you want reference equality, so depending on use case).In case type
A
is a primitive type and anEq[A]
instance is not in scope, then you probably need this import:import cats.instances.all._
Or in case your type
A
does not have anEq[A]
instance defined for it, then you can quickly define one like this:import cats.Eq implicit val eqA = Eq.fromUniversalEquals[A]
- A
is the
cats.Eq
instance that defines equality forA
- Definition Classes
- Iterant
-
final
def
distinctUntilChangedByKey[K](key: (A) ⇒ K)(implicit F: Sync[F], K: Eq[K]): Iterant[F, A]
Given a function that returns a key for each element emitted by the source, suppress consecutive duplicate items.
Given a function that returns a key for each element emitted by the source, suppress consecutive duplicate items.
Example:
// Yields 1, 2, 3, 4 Iterant[Coeval].of(1, 3, 2, 4, 2, 3, 5, 7, 4) .distinctUntilChangedBy(_ % 2)
Duplication is detected by using the equality relationship provided by the
cats.Eq
type class. This allows one to override the equality operation being used (e.g. maybe the default.equals
is badly defined, or maybe you want reference equality, so depending on use case).In case type
K
is a primitive type and anEq[K]
instance is not in scope, then you probably need this import:import cats.instances.all._
Or in case your type
K
does not have anEq[K]
instance defined for it, then you can quickly define one like this:import cats.Eq implicit val eqK = Eq.fromUniversalEquals[K]
- key
is a function that returns a
K
key for each element, a value that's then used to do the deduplication- K
is the
cats.Eq
instance that defines equality for the key typeK
- Definition Classes
- Iterant
-
final
def
doOnEarlyStop(f: F[Unit])(implicit F: Sync[F]): Iterant[F, A]
Given a routine make sure to execute it whenever the consumer executes the current
stop
action.Given a routine make sure to execute it whenever the consumer executes the current
stop
action.Example:
iterant.doOnEarlyStop(Task.eval { println("Was stopped early!") })
- f
is the function to execute on early stop
- Definition Classes
- Iterant
-
final
def
doOnFinish(f: (Option[Throwable]) ⇒ F[Unit])(implicit F: Sync[F]): Iterant[F, A]
Returns a new enumerator in which
f
is scheduled to be executed on halt or on earlyStop.Returns a new enumerator in which
f
is scheduled to be executed on halt or on earlyStop.This would typically be used to release any resources acquired by this enumerator.
Note that doOnEarlyStop is subsumed under this operation, the given
f
being evaluated on both reaching the end or canceling early.Example:
iterant.doOnEarlyStop(err => Task.eval { err match { case Some(e) => log.error(e) case None => println("Was consumed successfully!") } })
- f
is the function to execute on early stop
- Definition Classes
- Iterant
-
final
def
drop(n: Int)(implicit F: Sync[F]): Iterant[F, A]
Drops the first
n
elements (from the start).Drops the first
n
elements (from the start).Example:
// Yields 4, 5 Iterant[Task].of(1, 2, 3, 4, 5).drop(3)
- n
the number of elements to drop
- returns
a new iterant that drops the first n elements emitted by the source
- Definition Classes
- Iterant
-
final
def
dropWhile(p: (A) ⇒ Boolean)(implicit F: Sync[F]): Iterant[F, A]
Drops the longest prefix of elements that satisfy the given predicate and returns a new iterant that emits the rest.
Drops the longest prefix of elements that satisfy the given predicate and returns a new iterant that emits the rest.
Example:
// Yields 4, 5 Iterant[Task].of(1, 2, 3, 4, 5).dropWhile(_ < 4)
- p
is the predicate used to test whether the current element should be dropped, if
true
, or to interrupt the dropping process, iffalse
- returns
a new iterant that drops the elements of the source until the first time the given predicate returns
false
- Definition Classes
- Iterant
-
final
def
dump(prefix: String, out: PrintStream = System.out)(implicit F: Sync[F]): Iterant[F, A]
Dumps incoming events to standard output with provided prefix.
Dumps incoming events to standard output with provided prefix.
Utility that can be used for debugging purposes.
Example:
Iterant[Task].range(0, 4) .dump("O") .completeL.runAsync // Results in: 0: O --> 0 1: O --> 1 2: O --> 2 3: O --> 3 4: O completed
- Definition Classes
- Iterant
-
def
earlyStop(implicit F: Applicative[F]): F[Unit]
Returns a computation that should be evaluated in case the streaming must stop before reaching the end.
Returns a computation that should be evaluated in case the streaming must stop before reaching the end.
This is useful to release any acquired resources, like opened file handles or network sockets.
- Definition Classes
- NextCursor → Iterant
-
final
def
eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
-
final
def
existsL(p: (A) ⇒ Boolean)(implicit F: Sync[F]): F[Boolean]
Returns
true
in case the given predicate is satisfied by any of the emitted items, orfalse
in case the end of the stream has been reached with no items satisfying the given predicate.Returns
true
in case the given predicate is satisfied by any of the emitted items, orfalse
in case the end of the stream has been reached with no items satisfying the given predicate.Example:
val source = Iterant[Coeval].of(1, 2, 3, 4) // Yields true source.existsL(_ % 2 == 0) // Yields false source.existsL(_ % 7 == 0)
- p
is a predicate function that's going to test each item emitted by the source until we get a positive match for one of them or until the stream ends
- returns
true
if any of the items satisfies the given predicate orfalse
if none of them do
- Definition Classes
- Iterant
-
final
def
filter(p: (A) ⇒ Boolean)(implicit F: Sync[F]): Iterant[F, A]
Filters the iterant by the given predicate function, returning only those elements that match.
Filters the iterant by the given predicate function, returning only those elements that match.
Example:
// Yields 2, 4, 6 Iterant[Task].of(1, 2, 3, 4, 5, 6).filter(_ % 2 == 0)
- p
the predicate used to test elements.
- returns
a new iterant consisting of all elements that satisfy the given predicate. The order of the elements is preserved.
- Definition Classes
- Iterant
-
def
finalize(): Unit
- Attributes
- protected[java.lang]
- Definition Classes
- AnyRef
- Annotations
- @throws( classOf[java.lang.Throwable] )
-
def
findL(p: (A) ⇒ Boolean)(implicit F: Sync[F]): F[Option[A]]
Given a predicate, finds the first item that satisfies it, returning
Some(a)
if available, orNone
otherwise.Given a predicate, finds the first item that satisfies it, returning
Some(a)
if available, orNone
otherwise.// Yields Some(2) Iterant[Coeval].of(1, 2, 3, 4).findL(_ % 2 == 0) // Yields None Iterant[Coeval].of(1, 2, 3, 4).findL(_ > 10)
The stream is traversed from beginning to end, the process being interrupted as soon as it finds one element matching the predicate, or until the stream ends.
- p
is the function to test the elements of the source
- returns
either
Some(value)
in casevalue
is an element emitted by the source, found to satisfy the predicate, orNone
otherwise
- Definition Classes
- Iterant
-
final
def
flatMap[B](f: (A) ⇒ Iterant[F, B])(implicit F: Sync[F]): Iterant[F, B]
Applies the function to the elements of the source and concatenates the results.
Applies the function to the elements of the source and concatenates the results.
This operation is the monadic "bind", with all laws it entails.
Also note that the implementation can use constant memory depending on usage, thus it can be used in tail recursive loops.
Example:
// Effectively equivalent with .filter Iterant[Task].of(1, 2, 3, 4, 5, 6).flatMap { elem => if (elem % 2 == 0) Iterant[Task].pure(elem) else Iterant[Task].empty }
- f
is the function mapping elements from the source to iterants
- Definition Classes
- Iterant
-
final
def
flatten[B](implicit ev: <:<[A, Iterant[F, B]], F: Sync[F]): Iterant[F, B]
Given an
Iterant
that generatesIterant
elements, concatenates all the generated iterants.Given an
Iterant
that generatesIterant
elements, concatenates all the generated iterants.Equivalent with:
source.flatMap(x => x)
- Definition Classes
- Iterant
-
final
def
foldL(implicit F: Sync[F], A: Monoid[A]): F[A]
Given evidence that type
A
has acats.Monoid
implementation, folds the stream with the provided monoid definition.Given evidence that type
A
has acats.Monoid
implementation, folds the stream with the provided monoid definition.For streams emitting numbers, this effectively sums them up. For strings, this concatenates them.
Example:
// Yields 10 Iterant[Task].of(1, 2, 3, 4).foldL // Yields "1234" Iterant[Task].of("1", "2", "3", "4").foldL
Note, in case you don't have a
Monoid
instance in scope, but you feel like you should, try this import:import cats.instances.all._
- A
is the
cats.Monoid
type class instance that's needed in scope for folding the source- returns
the result of combining all elements of the source, or the defined
Monoid.empty
element in case the stream is empty
- Definition Classes
- Iterant
-
final
def
foldLeftL[S](seed: ⇒ S)(op: (S, A) ⇒ S)(implicit F: Sync[F]): F[S]
Left associative fold using the function
op
.Left associative fold using the function
op
.On execution the stream will be traversed from left to right, and the given function will be called with the prior result, accumulating state until the end, when the summary is returned.
Example:
// Yields 15 (1 + 2 + 3 + 4 + 5) Iterant[Task].of(1, 2, 3, 4, 5).foldLeftL(0)(_ + _)
- seed
is the start value
- op
is the binary operator
- returns
the result of inserting
op
between consecutive elements of this iterant, going from left to right with theseed
as the start value, orseed
if the iterant is empty.
- Definition Classes
- Iterant
-
final
def
foldRightL[B](b: F[B])(f: (A, F[B], F[Unit]) ⇒ F[B])(implicit F: Sync[F]): F[B]
Lazily fold the stream to a single value from the right.
Lazily fold the stream to a single value from the right.
This is the common
foldr
operation from Haskell'sFoldable
, orfoldRight
from Scala's collections, however it has a twist: the user is responsible for invoking earlystop
in case the processing is short-circuited, hence the signature of functionf
is different from other implementations, receiving the currentearlyStop: F[Unit]
as a third parameter.Here's for example how existsL, forallL and
++
could be expressed in terms offoldRightL
:def exists[F[_], A](fa: Iterant[F, A], p: A => Boolean) (implicit F: Sync[F]): F[Boolean] = { fa.foldRightL(F.pure(false)) { (a, next, stop) => if (p(a)) stop.map(_ => true) else next } } def forall[F[_], A](fa: Iterant[F, A], p: A => Boolean) (implicit F: Sync[F]): F[Boolean] = { fa.foldRightL(F.pure(true)) { (a, next, stop) => if (!p(a)) stop.map(_ => false) else next } } def concat[F[_], A](lh: Iterant[F, A], rh: Iterant[F, A]) (implicit F: Sync[F]): Iterant[F, A] = { Iterant.suspend[F, A] { lh.foldRightL(F.pure(rh)) { (a, rest, stop) => F.pure(Iterant.nextS(a, rest, stop)) } } }
In this example we are short-circuiting the processing in case we find the one element that we are looking for, otherwise we keep traversing the stream until the end, finally returning the default value in case we haven't found what we were looking for.
WARNING
The implementation cannot ensure resource safety automatically, therefore it falls on the user to chain the
stop
reference in the processing, in case the right parameter isn't factored in.In other words:
- in case the processing fails in any way with exceptions,
it is the user's responsibility to chain
stop
- in case the processing is short-circuited by not using the
F[B]
right param, it is the user responsibility to chainstop
This is in contrast with all operators (unless explicitly mentioned otherwise).
See the examples provided above, as they are correct in their handling of
stop
.- b
is the starting value; in case
f
is a binary operator, this is typically its left-identity (zero)- f
is the function to be called that folds the list, receiving the current element being iterated on (first param), the (lazy) result from recursively combining the rest of the list (second param) and the
earlyStop
routine, to chain in case short-circuiting should happen (third param)
- Definition Classes
- Iterant
- See also
foldWhileLeftL and foldWhileLeftEvalL for safer alternatives in most cases
- in case the processing fails in any way with exceptions,
it is the user's responsibility to chain
-
final
def
foldWhileLeftEvalL[S](seed: F[S])(op: (S, A) ⇒ F[Either[S, S]])(implicit F: Sync[F]): F[S]
Left associative fold using the function
op
that can be short-circuited.Left associative fold using the function
op
that can be short-circuited.On execution the stream will be traversed from left to right, and the given function will be called with the prior result, accumulating state either until the end, or until
op
returns aRight
result, when the summary is returned.The results are returned in the
F[_]
functor context, meaning that we can have lazy or asynchronous processing and we can suspend side effects, depending on theF
data type being used.Example using
cats.effect.IO
:// Sums first 10 items Iterant[IO].range(0, 1000).foldWhileLeftEvalL(IO((0, 0))) { case ((sum, count), e) => IO { val next = (sum + e, count + 1) if (count + 1 < 10) Left(next) else Right(next) } } // Implements exists(predicate) Iterant[IO].of(1, 2, 3, 4, 5).foldWhileLeftEvalL(IO(false)) { (default, e) => IO { if (e == 3) Right(true) else Left(default) } } // Implements forall(predicate) Iterant[IO].of(1, 2, 3, 4, 5).foldWhileLeftEvalL(IO(true)) { (default, e) => IO { if (e != 3) Right(false) else Left(default) } }
- seed
is the start value
- op
is the binary operator returning either
Left
, signaling that the state should be evolved or aRight
, signaling that the process can be short-circuited and the result returned immediately- returns
the result of inserting
op
between consecutive elements of this iterant, going from left to right with theseed
as the start value, orseed
if the iterant is empty
- Definition Classes
- Iterant
- See also
Iterant.foldWhileLeftL for the strict version.
-
final
def
foldWhileLeftL[S](seed: ⇒ S)(op: (S, A) ⇒ Either[S, S])(implicit F: Sync[F]): F[S]
Left associative fold using the function
op
that can be short-circuited.Left associative fold using the function
op
that can be short-circuited.On execution the stream will be traversed from left to right, and the given function will be called with the prior result, accumulating state either until the end, or until
op
returns aRight
result, when the summary is returned.Example:
// Sums first 10 items Iterant[Task].range(0, 1000).foldWhileLeftL((0, 0)) { case ((sum, count), e) => val next = (sum + e, count + 1) if (count + 1 < 10) Left(next) else Right(next) } // Implements exists(predicate) Iterant[Task].of(1, 2, 3, 4, 5).foldWhileLeftL(false) { (default, e) => if (e == 3) Right(true) else Left(default) } // Implements forall(predicate) Iterant[Task].of(1, 2, 3, 4, 5).foldWhileLeftL(true) { (default, e) => if (e != 3) Right(false) else Left(default) }
- seed
is the start value
- op
is the binary operator returning either
Left
, signaling that the state should be evolved or aRight
, signaling that the process can be short-circuited and the result returned immediately- returns
the result of inserting
op
between consecutive elements of this iterant, going from left to right with theseed
as the start value, orseed
if the iterant is empty
- Definition Classes
- Iterant
- See also
Iterant.foldWhileLeftL for the lazy, potentially asynchronous version.
-
final
def
forallL(p: (A) ⇒ Boolean)(implicit F: Sync[F]): F[Boolean]
Returns
true
in case the given predicate is satisfied by all of the emitted items, orfalse
in case the given predicate fails for any of those items.Returns
true
in case the given predicate is satisfied by all of the emitted items, orfalse
in case the given predicate fails for any of those items.Example:
val source = Iterant[Coeval].of(1, 2, 3, 4) // Yields false source.forallL(_ % 2 == 0) // Yields true source.existsL(_ < 10)
- p
is a predicate function that's going to test each item emitted by the source until we get a negative match for one of them or until the stream ends
- returns
true
if all of the items satisfy the given predicate orfalse
if any of them don't
- Definition Classes
- Iterant
-
final
def
foreach(cb: (A) ⇒ Unit)(implicit F: Sync[F]): F[Unit]
Consumes the source iterable, executing the given callback for each element.
Consumes the source iterable, executing the given callback for each element.
Example:
// Prints all elements, each one on a different line Iterant[Task].of(1, 2, 3).foreachL { elem => println("Elem: " + elem.toString) }
- cb
is the callback to call for each element emitted by the source.
- Definition Classes
- Iterant
-
final
def
getClass(): Class[_]
- Definition Classes
- AnyRef → Any
-
final
def
headOptionL(implicit F: Sync[F]): F[Option[A]]
Optionally selects the first element.
Optionally selects the first element.
// Yields Some(1) Iterant[Task].of(1, 2, 3, 4).headOptionL // Yields None Iterant[Task].empty[Int].headOptionL
- returns
the first element of this iterant if it is nonempty, or
None
if it is empty, in theF
context.
- Definition Classes
- Iterant
-
final
def
isInstanceOf[T0]: Boolean
- Definition Classes
- Any
-
final
def
liftMap[G[_]](f1: (F[Iterant[F, A]]) ⇒ G[Iterant[F, A]], f2: (F[Unit]) ⇒ G[Unit])(implicit F: Applicative[F], G: Sync[G]): Iterant[G, A]
Given mapping functions from
F
toG
, lifts the source into an iterant that is going to use the resultingG
for evaluation.Given mapping functions from
F
toG
, lifts the source into an iterant that is going to use the resultingG
for evaluation.This can be used for replacing the underlying
F
type into something else. For example say we have an iterant that uses Coeval, but we want to convert it into one that uses Task for evaluation:// Source is using Coeval for evaluation val source = Iterant[Coeval].of(1, 2, 3, 4) // Transformation to an iterant based on Task source.liftMap(_.toTask, _.toTask)
- G
is the data type that is going to drive the evaluation of the resulting iterant
- f1
is the functor transformation used for transforming
rest
references- f2
is the mapping function for early
stop
references
- Definition Classes
- Iterant
-
final
def
liftMapK[G[_]](f: FunctionK[F, G])(implicit G: Sync[G]): Iterant[G, A]
Given a functor transformation from
F
toG
, lifts the source into an iterant that is going to use the resultingG
for evaluation.Given a functor transformation from
F
toG
, lifts the source into an iterant that is going to use the resultingG
for evaluation.This can be used for replacing the underlying
F
type into something else. For example say we have an iterant that uses Coeval, but we want to convert it into one that uses Task for evaluation:import cats.~> // Source is using Coeval for evaluation val source = Iterant[Coeval].of(1, 2, 3, 4) // Transformation to an iterant based on Task source.liftMapK(new (Coeval ~> Task) { def apply[A](fa: Coeval[A]): Task[A] = fa.task })
This operator can be used for more than transforming the
F
type into something else.- G
is the data type that is going to drive the evaluation of the resulting iterant
- f
is the functor transformation that's used to transform the source into an iterant that uses
G
for evaluation
- Definition Classes
- Iterant
-
final
def
map[B](f: (A) ⇒ B)(implicit F: Sync[F]): Iterant[F, B]
Returns a new stream by mapping the supplied function over the elements of the source.
Returns a new stream by mapping the supplied function over the elements of the source.
// Yields 2, 4, 6 Iterant[Task].of(1, 2, 3).map(_ * 2)
- f
is the mapping function that transforms the source
- returns
a new iterant that's the result of mapping the given function over the source
- Definition Classes
- Iterant
-
final
def
mapEval[B](f: (A) ⇒ F[B])(implicit F: Sync[F]): Iterant[F, B]
Given a mapping function that returns a possibly lazy or asynchronous result, applies it over the elements emitted by the stream.
Given a mapping function that returns a possibly lazy or asynchronous result, applies it over the elements emitted by the stream.
Iterant[Task].of(1, 2, 3, 4).mapEval { elem => Task.eval { println("Received: " + elem.toString) elem * 2 } }
- f
is the mapping function that transforms the source
- returns
a new iterant that's the result of mapping the given function over the source,
- Definition Classes
- Iterant
-
final
def
maxByL[K](key: (A) ⇒ K)(implicit F: Sync[F], K: Order[K]): F[Option[A]]
Takes the elements of the source iterant and emits the element that has the maximum key value, where the key is generated by the given function.
Takes the elements of the source iterant and emits the element that has the maximum key value, where the key is generated by the given function.
Example:
case class Person(name: String, age: Int) // Yields Some(Person("Peter", 23)) Iterant[Coeval].of(Person("Peter", 23), Person("May", 21)) .maxByL(_.age) // Yields None Iterant[Coeval].empty[Int].maxByL(_.age)
- key
is the function that returns the key for which the given ordering is defined
- K
is the
cats.Order
type class instance that's going to be used for comparing elements- returns
the maximum element of the source stream, relative to its key generated by the given function and the given ordering
- Definition Classes
- Iterant
-
final
def
maxL(implicit F: Sync[F], A: Order[A]): F[Option[A]]
Given a
cats.Order
over the stream's elements, returns the maximum element in the stream.Given a
cats.Order
over the stream's elements, returns the maximum element in the stream.Example:
// Yields Some(20) Iterant[Coeval].of(1, 10, 7, 6, 8, 20, 3, 5).maxL // Yields None Iterant[Coeval].empty[Int].maxL
- A
is the
cats.Order
type class instance that's going to be used for comparing elements- returns
the maximum element of the source stream, relative to the defined
Order
- Definition Classes
- Iterant
-
final
def
minByL[K](key: (A) ⇒ K)(implicit F: Sync[F], K: Order[K]): F[Option[A]]
Takes the elements of the source iterant and emits the element that has the minimum key value, where the key is generated by the given function.
Takes the elements of the source iterant and emits the element that has the minimum key value, where the key is generated by the given function.
Example:
case class Person(name: String, age: Int) // Yields Some(Person("May", 21)) Iterant[Coeval].of(Person("Peter", 23), Person("May", 21)) .minByL(_.age) // Yields None Iterant[Coeval].empty[Int].minByL(_.age)
- key
is the function that returns the key for which the given ordering is defined
- K
is the
cats.Order
type class instance that's going to be used for comparing elements- returns
the minimum element of the source stream, relative to its key generated by the given function and the given ordering
- Definition Classes
- Iterant
-
final
def
minL(implicit F: Sync[F], A: Order[A]): F[Option[A]]
Given a
cats.Order
over the stream's elements, returns the minimum element in the stream.Given a
cats.Order
over the stream's elements, returns the minimum element in the stream.Example:
// Yields Some(3) Iterant[Coeval].of(10, 7, 6, 8, 20, 3, 5).minL // Yields None Iterant[Coeval].empty[Int].minL
- A
is the
cats.Order
type class instance that's going to be used for comparing elements- returns
the minimum element of the source stream, relative to the defined
Order
- Definition Classes
- Iterant
-
final
def
ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
-
final
def
notify(): Unit
- Definition Classes
- AnyRef
-
final
def
notifyAll(): Unit
- Definition Classes
- AnyRef
-
final
def
onErrorHandle[B >: A](f: (Throwable) ⇒ B)(implicit F: Sync[F]): Iterant[F, B]
Returns an
Iterant
that mirrors the behavior of the source, unless the source is terminated with an error, in which case the streaming of events fallbacks to an iterant emitting a single element generated by the backup function.Returns an
Iterant
that mirrors the behavior of the source, unless the source is terminated with an error, in which case the streaming of events fallbacks to an iterant emitting a single element generated by the backup function.Example:
val prefix = Iterant[Task].of(1, 2, 3, 4) val suffix = Iterant[Task].raiseError(DummyException("dummy")) val fa = prefix ++ suffix fa.onErrorHandle { _ => 5 }
See onErrorRecover for the version that takes a partial function as a parameter.
- f
is a function that matches errors with a backup element that is emitted when the source throws an error.
- Definition Classes
- Iterant
-
final
def
onErrorHandleWith[B >: A](f: (Throwable) ⇒ Iterant[F, B])(implicit F: Sync[F]): Iterant[F, B]
Returns an
Iterant
that mirrors the behavior of the source, unless the source is terminated with an error, in which case the streaming of events continues with the specified backup sequence generated by the given function.Returns an
Iterant
that mirrors the behavior of the source, unless the source is terminated with an error, in which case the streaming of events continues with the specified backup sequence generated by the given function.Example:
val prefix = Iterant[Task].of(1, 2, 3, 4) val suffix = Iterant[Task].raiseError(DummyException("dummy")) val fa = prefix ++ suffix fa.onErrorHandleWith { case _: DummyException => Iterant[Task].pure(5) case other => Iterant[Task].raiseError(other) }
See onErrorRecoverWith for the version that takes a partial function as a parameter.
- f
is a function that matches errors with a backup throwable that is subscribed when the source throws an error.
- Definition Classes
- Iterant
-
final
def
onErrorIgnore(implicit F: Sync[F]): Iterant[F, A]
Returns a new
Iterant
that mirrors the source, but ignores any errors in case they happen.Returns a new
Iterant
that mirrors the source, but ignores any errors in case they happen.- Definition Classes
- Iterant
-
final
def
onErrorRecover[B >: A](pf: PartialFunction[Throwable, B])(implicit F: Sync[F]): Iterant[F, B]
Returns an
Iterant
that mirrors the behavior of the source, unless the source is terminated with an error, in which case the streaming of events fallbacks to an iterant emitting a single element generated by the backup function.Returns an
Iterant
that mirrors the behavior of the source, unless the source is terminated with an error, in which case the streaming of events fallbacks to an iterant emitting a single element generated by the backup function.The created
Iterant
mirrors the behavior of the source in case the source does not end with an error or if the thrownThrowable
is not matched.Example:
val prefix = Iterant[Task].of(1, 2, 3, 4) val suffix = Iterant[Task].raiseError(DummyException("dummy")) val fa = prefix ++ suffix fa.onErrorRecover { case _: DummyException => 5 }
See onErrorHandle for the version that takes a total function as a parameter.
- pf
- a function that matches errors with a backup element that is emitted when the source throws an error.
- Definition Classes
- Iterant
-
final
def
onErrorRecoverWith[B >: A](pf: PartialFunction[Throwable, Iterant[F, B]])(implicit F: Sync[F]): Iterant[F, B]
Returns an
Iterant
that mirrors the behavior of the source, unless the source is terminated with an error, in which case the streaming of events continues with the specified backup sequence generated by the given partial function.Returns an
Iterant
that mirrors the behavior of the source, unless the source is terminated with an error, in which case the streaming of events continues with the specified backup sequence generated by the given partial function.The created
Iterant
mirrors the behavior of the source in case the source does not end with an error or if the thrownThrowable
is not matched.Example:
val prefix = Iterant[Task].of(1, 2, 3, 4) val suffix = Iterant[Task].raiseError(DummyException("dummy")) val fa = prefix ++ suffix fa.onErrorRecoverWith { case _: DummyException => Iterant[Task].pure(5) }
See onErrorHandleWith for the version that takes a total function as a parameter.
- pf
is a function that matches errors with a backup throwable that is subscribed when the source throws an error.
- Definition Classes
- Iterant
-
final
def
parZip[G[_], B](rhs: Iterant[F, B])(implicit F: Sync[F], P: Parallel[F, G]): Iterant[F, (A, B)]
Lazily zip two iterants together, the elements of the emitted tuples being fetched in parallel.
Lazily zip two iterants together, the elements of the emitted tuples being fetched in parallel.
This is the parallel version of zip, the results are still ordered, but it can yield non-deterministic ordering of effects when fetching the elements of an emitted tuple.
- rhs
is the other iterant to zip the source with (the right hand side)
- Definition Classes
- Iterant
-
final
def
parZipMap[G[_], B, C](rhs: Iterant[F, B])(f: (A, B) ⇒ C)(implicit F: Sync[F], P: Parallel[F, G]): Iterant[F, C]
Lazily zip two iterants together, in parallel, using the given function
f
to produce output values.Lazily zip two iterants together, in parallel, using the given function
f
to produce output values.This is like zipMap, except that the element pairs are processed in parallel (ordered results, but non-deterministic ordering of effects).
- rhs
is the other iterant to zip the source with (the right hand side)
- f
is the mapping function to transform the zipped
(A, B)
elements
- Definition Classes
- Iterant
-
final
def
reduceL(op: (A, A) ⇒ A)(implicit F: Sync[F]): F[Option[A]]
Reduces the elements of the source using the specified associative binary operator, going from left to right, start to finish.
Reduces the elements of the source using the specified associative binary operator, going from left to right, start to finish.
Example:
// Yields Some(10) Iterant[Coeval].of(1, 2, 3, 4).reduceL(_ + _) // Yields None Iterant[Coeval].empty[Int].reduceL(_ + _)
- op
is an associative binary operation that's going to be used to reduce the source to a single value
- returns
either
Some(value)
in case the stream is not empty,value
being the result of insertingop
between consecutive elements of this iterant, going from left to right, orNone
in case the stream is empty
- Definition Classes
- Iterant
- val rest: F[Iterant[F, A]]
-
final
def
scan[S](seed: ⇒ S)(op: (S, A) ⇒ S)(implicit F: Sync[F]): Iterant[F, S]
Applies a binary operator to a start value and all elements of this
Iterant
, going left to right and returns a newIterant
that emits on each step the result of the applied function.Applies a binary operator to a start value and all elements of this
Iterant
, going left to right and returns a newIterant
that emits on each step the result of the applied function.Similar to foldLeftL, but emits the state on each step. Useful for modeling finite state machines.
Example showing how state can be evolved and acted upon:
sealed trait State[+A] { def count: Int } case object Init extends State[Nothing] { def count = 0 } case class Current[A](current: A, count: Int) extends State[A] val scanned = source.scan(Init : State[A]) { (acc, a) => acc match { case Init => Current(a, 1) case Current(_, count) => Current(a, count + 1) } } scanned .takeWhile(_.count < 10) .collect { case Current(a, _) => a }
- seed
is the initial state
- op
is the function that evolves the current state
- returns
a new iterant that emits all intermediate states being resulted from applying function
op
- Definition Classes
- Iterant
-
final
def
scanEval[S](seed: F[S])(op: (S, A) ⇒ F[S])(implicit F: Sync[F]): Iterant[F, S]
Applies a binary operator to a start value and all elements of this
Iterant
, going left to right and returns a newIterant
that emits on each step the result of the applied function.Applies a binary operator to a start value and all elements of this
Iterant
, going left to right and returns a newIterant
that emits on each step the result of the applied function.Similar with scan, but this can suspend and evaluate side effects in the
F[_]
context, thus allowing for asynchronous data processing.Similar to foldLeftL and foldWhileLeftEvalL, but emits the state on each step. Useful for modeling finite state machines.
Example showing how state can be evolved and acted upon:
sealed trait State[+A] { def count: Int } case object Init extends State[Nothing] { def count = 0 } case class Current[A](current: Option[A], count: Int) extends State[A] case class Person(id: Int, name: String) // Initial state val seed = Task.now(Init : State[Person]) val scanned = source.scanEval(seed) { (state, id) => requestPersonDetails(id).map { person => state match { case Init => Current(person, 1) case Current(_, count) => Current(person, count + 1) } } } scanned .takeWhile(_.count < 10) .collect { case Current(a, _) => a }
- seed
is the initial state
- op
is the function that evolves the current state
- returns
a new iterant that emits all intermediate states being resulted from applying the given function
-
final
def
skipSuspendL(implicit F: Sync[F]): F[Iterant[F, A]]
Skips over Iterant.Suspend states, along with Iterant.NextCursor and Iterant.NextBatch states that signal empty collections.
Skips over Iterant.Suspend states, along with Iterant.NextCursor and Iterant.NextBatch states that signal empty collections.
Will mirror the source, except that the emitted internal states might be different. Can be used as an optimization if necessary.
- Definition Classes
- Iterant
- val stop: F[Unit]
-
final
def
synchronized[T0](arg0: ⇒ T0): T0
- Definition Classes
- AnyRef
-
final
def
tail(implicit F: Sync[F]): Iterant[F, A]
Drops the first element of the source iterant, emitting the rest.
Drops the first element of the source iterant, emitting the rest.
Example:
// Yields 2, 3, 4 Iterant[Task].of(1, 2, 3, 4).tail
- returns
a new iterant that upon evaluation will emit all elements of the source, except for the head
- Definition Classes
- Iterant
-
final
def
take(n: Int)(implicit F: Sync[F]): Iterant[F, A]
Creates a new iterant that upon evaluation will select the first
n
elements from the source and then stop, in the order they are emitted by the source.Creates a new iterant that upon evaluation will select the first
n
elements from the source and then stop, in the order they are emitted by the source.Example:
// Yields 1, 2, 3 Iterant[Task].of(1, 2, 3, 4, 5, 6).take(3)
- n
is the number of elements to take from this iterant
- returns
a new iterant instance that on evaluation will emit only the first
n
elements of this iterant
- Definition Classes
- Iterant
-
final
def
takeLast(n: Int)(implicit F: Sync[F]): Iterant[F, A]
Creates a new iterable that only emits the last
n
elements emitted by the source.Creates a new iterable that only emits the last
n
elements emitted by the source.In case the source triggers an error, then the underlying buffer gets dropped and the error gets emitted immediately.
Example:
// Yields 1, 2, 3 Iterant[Task].of(1, 2, 3, 4, 5, 6).take(3)
- n
is the number of elements to take from the end of the stream.
- returns
a new iterant instance that on evaluation will emit the last
n
elements of the source
- Definition Classes
- Iterant
-
final
def
takeWhile(p: (A) ⇒ Boolean)(implicit F: Sync[F]): Iterant[F, A]
Takes longest prefix of elements that satisfy the given predicate and returns a new iterant that emits those elements.
Takes longest prefix of elements that satisfy the given predicate and returns a new iterant that emits those elements.
Example:
// Yields 1, 2, 3 Iterant[Task].of(1, 2, 3, 4, 5, 6).takeWhile(_ < 4)
- p
is the function that tests each element, stopping the streaming on the first
false
result- returns
a new iterant instance that on evaluation will all elements of the source for as long as the given predicate returns
true
, stopping upon the firstfalse
result
- Definition Classes
- Iterant
-
final
def
toListL(implicit F: Sync[F]): F[List[A]]
Aggregates all elements in a
List
and preserves order.Aggregates all elements in a
List
and preserves order.Example:
// Yields List(1, 2, 3, 4) Iterant[Task].of(1, 2, 3, 4).toListL
Note that this operation is dangerous, since if the iterant is infinite then this operation is non-terminating, the process probably blowing up with an out of memory error sooner or later.
- Definition Classes
- Iterant
-
final
def
toReactivePublisher(implicit F: Effect[F], ec: Scheduler): Publisher[A]
Converts this
Iterant
into anorg.reactivestreams.Publisher
.Converts this
Iterant
into anorg.reactivestreams.Publisher
.Meant for interoperability with other Reactive Streams implementations. Also useful because it turns the
Iterant
into another data type with a push-based communication protocol with back-pressure.Usage sample:
import monix.eval.Task import monix.execution.rstreams.SingleAssignmentSubscription import org.reactivestreams.{Publisher, Subscriber, Subscription} def sum(source: Publisher[Int], requestSize: Int): Task[Long] = Task.create { (_, cb) => val sub = SingleAssignmentSubscription() source.subscribe(new Subscriber[Int] { private[this] var requested = 0L private[this] var sum = 0L def onSubscribe(s: Subscription): Unit = { sub := s requested = requestSize s.request(requestSize) } def onNext(t: Int): Unit = { sum += t if (requestSize != Long.MaxValue) requested -= 1 if (requested <= 0) { requested = requestSize sub.request(request) } } def onError(t: Throwable): Unit = cb.onError(t) def onComplete(): Unit = cb.onSuccess(sum) }) // Cancelable that can be used by Task sub } val pub = Iterant[Task].of(1, 2, 3, 4).toReactivePublisher // Yields 10 sum(pub, requestSize = 128)
See the Reactive Streams for details.
- Definition Classes
- Iterant
-
final
def
unsafeFlatMap[B](f: (A) ⇒ Iterant[F, B])(implicit F: Sync[F]): Iterant[F, B]
Applies the function to the elements of the source and concatenates the results.
Applies the function to the elements of the source and concatenates the results.
This variant of flatMap is not referentially transparent, because it tries to apply function
f
immediately, in case theIterant
is in aNextCursor
orNextBatch
state.To be used for optimizations, but keep in mind it's unsafe, as its application isn't referentially transparent.
- f
is the function mapping elements from the source to iterants
- Definition Classes
- Iterant
-
final
def
upcast[B >: A]: Iterant[F, B]
Explicit covariance operator.
Explicit covariance operator.
The Iterant type isn't covariant in type param
A
, because covariance doesn't play well with a higher-kinded type likeF[_]
. So in case you have anIterant[F, A]
, but need anIterant[F, B]
, knowing thatA extends B
, then you can do anupcast
.Example:
val source: Iterant[Task, List[Int]] = ??? // This will trigger an error because of the invariance: val sequences: Iterant[Task, Seq[Int]] = source // But this will work just fine: val sequences: Iterant[Task, Seq[Int]] = source.upcast[Seq[Int]]
- Definition Classes
- Iterant
-
final
def
wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws( ... )
-
final
def
wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws( ... )
-
final
def
wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws( ... )
-
final
def
zip[B](rhs: Iterant[F, B])(implicit F: Sync[F]): Iterant[F, (A, B)]
Lazily zip two iterants together.
Lazily zip two iterants together.
The length of the result will be the shorter of the two arguments.
Example:
val lh = Iterant[Task].of(11, 12, 13, 14) val rh = Iterant[Task].of(21, 22, 23, 24, 25) // Yields (11, 21), (12, 22), (13, 23), (14, 24) lh.zip(rh)
- rhs
is the other iterant to zip the source with (the right hand side)
- Definition Classes
- Iterant
-
final
def
zipMap[B, C](rhs: Iterant[F, B])(f: (A, B) ⇒ C)(implicit F: Sync[F]): Iterant[F, C]
Lazily zip two iterants together, using the given function
f
to produce output values.Lazily zip two iterants together, using the given function
f
to produce output values.The length of the result will be the shorter of the two arguments.
Example:
val lh = Iterant[Task].of(11, 12, 13, 14) val rh = Iterant[Task].of(21, 22, 23, 24, 25) // Yields 32, 34, 36, 38 lh.zipMap(rh) { (a, b) => a + b }
- rhs
is the other iterant to zip the source with (the right hand side)
- f
is the mapping function to transform the zipped
(A, B)
elements
- Definition Classes
- Iterant
-
final
def
zipWithIndex(implicit F: Sync[F]): Iterant[F, (A, Long)]
Zips the emitted elements of the source with their indices.
Zips the emitted elements of the source with their indices.
The length of the result will be the same as the source.
Example:
val source = Iterant[Task].of("Sunday", "Monday", "Tuesday", "Wednesday") // Yields ("Sunday", 0), ("Monday", 1), ("Tuesday", 2), ("Wednesday", 3) source.zipWithIndex
- Definition Classes
- Iterant