fs2
package fs2
- Source
- fs2.scala
- Alphabetic
- By Inheritance
- fs2
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
Type Members
-
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.
Chunk
s can be created from a variety of collection types using methods on theChunk
companion (e.g.,Chunk.vector
,Chunk.seq
,Chunk.array
). Additionally, theChunk
companion defines a subtype ofChunk
for each primitive type, using an unboxed primitive array. To work with unboxed arrays, use methods liketoBytes
to convert aChunk[Byte]
to aChunk.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 tomap
). In contrast, a chunk can be lifted to a segment (viatoSegment
) to get arbitrary operator fusion. -
final
class
CompositeFailure extends Throwable
Represents multiple (>1) exceptions were thrown.
-
sealed
trait
Fallible[A] extends AnyRef
Indicates that a stream evaluates no effects but unlike Pure, may raise errors.
Indicates that a stream evaluates no effects but unlike Pure, may raise errors.
Uninhabited.
A
Stream[Fallible,O]
can be safely converted to aStream[F,O]
for allF
vias.lift[F]
, provided anApplicativeError[F, Throwable]
is available. -
abstract
type
INothing <: Nothing
Alias for
Nothing
which works better with type inference. -
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 onStream
. -
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.
Pipe2
s are typically applied with thethrough2
operation onStream
. -
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 typeR
, and produces aStream[F,O]
when callingp.stream
.A
p: Pull[F,O,R]
reads values from one or more streams, returns a result of typeR
, and produces aStream[F,O]
when callingp.stream
.Any resources acquired by
p
are freed following the call tostream
.Laws:
Pull
forms a monad inR
withpure
andflatMap
:pure >=> f == f
f >=> pure == f
(f >=> g) >=> h == f >=> (g >=> h)
wheref >=> g
is defined asa => a flatMap f flatMap g
raiseError
is caught byhandleErrorWith
:handleErrorWith(raiseError(e))(f) == f(e)
-
abstract
type
Pure[A] <: Nothing
Indicates that a stream evaluates no effects.
Indicates that a stream evaluates no effects.
A
Stream[Pure,O]
can be safely converted to aStream[F,O]
for allF
. -
trait
RaiseThrowable[F[_]] extends AnyRef
Witnesses that
F
supports raising throwables.Witnesses that
F
supports raising throwables.An instance of
RaiseThrowable
is available for anyF
which has anApplicativeError[F, Throwable]
instance. Alternatively, an instance is available for the uninhabited typeFallible
.- Annotations
- @implicitNotFound( ... )
-
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.
-
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 onStream
. -
final
class
Stream[+F[_], +O] extends AnyVal
A stream producing output of type
O
and which may evaluateF
effects.A stream producing output of type
O
and which may evaluateF
effects. IfF
is Pure, the stream evaluates no effects.Laws (using infix syntax):
append
forms a monoid in conjunction withempty
:empty append s == s
ands append empty == s
.(s1 append s2) append s3 == s1 append (s2 append s3)
And
cons
is consistent with using++
to prepend a single chunk:s.cons(c) == Stream.chunk(c) ++ s
Stream.raiseError
propagates until being caught byhandleErrorWith
: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 withemit
andflatMap
:Stream.emit >=> f == f
(left identity)f >=> Stream.emit === f
(right identity - note weaker equality notion here)(f >=> g) >=> h == f >=> (g >=> h)
(associativity) whereStream.emit(a)
is defined aschunk(Chunk.singleton(a)) and
f >=> gis defined as
a => a flatMap f flatMap g
The monad is the list-style sequencing monad:
(a ++ b) flatMap f == (a flatMap f) ++ (b flatMap f)
Stream.empty flatMap f == Stream.empty
Technical notes
Note: since the chunk structure of the stream is observable, and
s flatMap Stream.emit
produces a stream of singleton chunks, the right identity law uses a weaker notion of equality,===
which normalizes both sides with respect to chunk structure:(s1 === s2) = normalize(s1) == normalize(s2)
where==
is full equality (a == b
ifff(a)
is identical tof(b)
for allf
)normalize(s)
can be defined ass.flatMap(Stream.emit)
, which just produces a singly-chunked stream from any input streams
.Note: For efficiency
Stream.map
function operates on an entire chunk at a time and preserves chunk structure, which differs from themap
derived from the monad (s map f == s flatMap (f andThen Stream.emit)
) which would produce singleton chunk. In particular, iff
throws errors, the chunked version will fail on the first chunk with an error, while the unchunked version will fail on the first element with an error. Exceptions in pure code like this are strongly discouraged.
Value Members
- object Chunk extends Serializable
- object CompositeFailure extends Serializable
- object Fallible
- object Pipe
- object Pull extends PullLowPriority
- object RaiseThrowable
- object Scope
-
object
Sink
Companion for Sink.
- object Stream extends StreamLowPriority
-
object
text
Provides utilities for working with streams of text (e.g., encoding byte streams to strings).