fs2

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).

This is similar to the standard library collection builders but optimized for
building a collection from a stream.

The companion object provides implicit conversions (methods starting with supports),
which adapts various collections to the Collector trait.

Uninhabited.

A Stream[Fallible,O] can be safely converted to a Stream[F,O] for all F via s.lift[F],
provided an ApplicativeError[F, Throwable] is available.

A Hotswap[F, R] instance is created as a Resource and hence, has
a lifetime that is scoped by the Resource. After creation, a Resource[F, R]
can be swapped in to the Hotswap by calling swap. The acquired resource
is returned and is finalized when the Hotswap is finalized or upon the next
call to swap, whichever occurs first.

For example, the sequence of three resources r1, r2, r3 are shown in the
following diagram:

{{{

        
----- swap(r1) ---- swap(r2) ---- swap(r3) ----X
|        |             |             |          |
Creation |             |             |          |
r1 acquired    |             |          |
r2 acquired    |          |
r1 released   r3 acquired |
r2 released |
r3 released
}}}
      

This class is particularly useful when working with pulls that cycle through
resources -- e.g., writing bytes to files, rotating files every N bytes or M seconds.
Without Hotswap, such pulls leak resources -- on each file rotation, a file handle
or at least an internal resource reference accumulates. With Hotswap, the Hotswap
instance is the only registered resource and each file is swapped in to the Hotswap.

Usage typically looks something like:

{{{
Stream.resource(Hotswap(mkResource)).flatMap { case (hotswap, r) =>
// Use r, call hotswap.swap(mkResource) as necessary
}
}}}

See fs2.io.file.writeRotate for an example of usage.

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)

An instance of RaiseThrowable is available for any F which has an
ApplicativeError[F, Throwable] instance. Alternatively, an instance
is available for the uninhabited type Fallible.

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.

=== Special properties for streams ===

There are some special properties or cases of streams:
- A stream is '''finite''', or if we can reach the end after a limited number of pull steps,
which may yield a finite number of values. It is '''empty''' if it terminates and yields no values.
- A '''singleton''' stream is a stream that ends after yielding one single value.
- A '''pure''' stream is one in which the F is Pure, which indicates that it evaluates no effects.
- A '''never''' stream is a stream that never terminates and never yields any value.

== Pure Streams and operations ==

We can sometimes think of streams, naively, as lists of O elements with F-effects.
This is particularly true for '''pure''' streams, which are instances of Stream which use the Pure effect type.
We can convert every ''pure and finite'' stream into a List[O] using the .toList method.
Also, we can convert pure ''infinite'' streams into instances of the Stream[O] class from the Scala standard library.

A method of the Stream class is '''pure''' if it can be applied to pure streams. Such methods are identified
in that their signature includes no type-class constraint (or implicit parameter) on the F method.
Pure methods in Stream[F, O] can be projected ''naturally'' to methods in the List class, which means
that we can applying the stream's method and converting the result to a list gets the same result as
first converting the stream to a list, and then applying list methods.

Some methods that project directly to list are map, filter, takeWhile, etc.
There are other methods, like exists or find, that in the List class they return a value or an Option,
but their stream counterparts return an (either empty or singleton) stream.
Other methods, like zipWithPrevious, have a more complicated but still pure translation to list methods.

== Type-Class instances and laws of the Stream Operations ==

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 chunk:
- s.cons(c) == Stream.chunk(c) ++ 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 chunk(Chunk.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 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 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.

For instance, for a stream s and a function f: A => B,
- the result of s.map(f) is a Stream with the same chunking as the s; wheras...
- the result of s.flatMap(x => S.emit(f(x))) is a Stream structured as a sequence of singleton chunks.
The latter is using the definition of map that is derived from the Monad instance.

This is not unlike equality for maps or sets, which is defined by which elements they contain,
not by how these are spread between a tree's branches or a hashtable buckets.
However, a Stream structure can be observed through the chunks method,
so two streams "equal" under that notion may give different results through this method.

''Note:'' For efficiency [[Stream.map]] function operates on an entire
chunk at a time and preserves chunk structure, which differs from
the map derived from the monad (s map f == s flatMap (f andThen Stream.emit))
which would produce singleton chunk. In particular, if f 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.

Pipes are typically applied with the through operation on Stream.

Pipe2s are typically applied with the through2 operation on Stream.

A Stream[Pure,O] can be safely converted to a Stream[F,O] for all F.

Sinks are typically applied with the to operation on Stream.