# Enumerables and Streams ## Enumerables Elixir provides the concept of enumerables and [the `Enum` module](https://hexdocs.pm/elixir/Enum.html) to work with them. We have already learned two enumerables: lists and maps. ```elixir Enum.map([1, 2, 3], fn x -> x * 2 end) ``` ```elixir Enum.map(%{1 => 2, 3 => 4}, fn {k, v} -> k * v end) ``` The `Enum` module provides a huge range of functions to transform, sort, group, filter and retrieve items from enumerables. It is one of the modules developers use frequently in their Elixir code. Elixir also provides ranges: ```elixir Enum.map(1..3, fn x -> x * 2 end) ``` ```elixir Enum.reduce(1..3, 0, &+/2) ``` The functions in the Enum module are limited to, as the name says, enumerating values in data structures. For specific operations, like inserting and updating particular elements, you may need to reach for modules specific to the data type. For example, if you want to insert an element at a given position in a list, you should use the `List.insert_at/3` function from [the `List` module](https://hexdocs.pm/elixir/List.html), as it would make little sense to insert a value into, for example, a range. We say the functions in the `Enum` module are polymorphic because they can work with diverse data types. In particular, the functions in the `Enum` module can work with any data type that implements [the `Enumerable` protocol](https://hexdocs.pm/elixir/Enumerable.html). We are going to discuss Protocols in a later chapter; for now we are going to move on to a specific kind of enumerable called a stream. ## Eager vs Lazy All the functions in the `Enum` module are eager. Many functions expect an enumerable and return a list back: ```elixir odd? = &(rem(&1, 2) != 0) ``` ```elixir Enum.filter(1..3, odd?) ``` This means that when performing multiple operations with `Enum`, each operation is going to generate an intermediate list until we reach the result: ```elixir 1..100_000 |> Enum.map(&(&1 * 3)) |> Enum.filter(odd?) |> Enum.sum() ``` The example above has a pipeline of operations. We start with a range and then multiply each element in the range by 3. This first operation will now create and return a list with `100_000` items. Then we keep all odd elements from the list, generating a new list, now with `50_000` items, and then we sum all entries. ## The pipe operator The `|>` symbol used in the snippet above is the **pipe operator**: it takes the output from the expression on its left side and passes it as the first argument to the function call on its right side. It's similar to the Unix `|` operator. Its purpose is to highlight the data being transformed by a series of functions. To see how it can make the code cleaner, have a look at the example above rewritten without using the `|>` operator: ```elixir Enum.sum(Enum.filter(Enum.map(1..100_000, &(&1 * 3)), odd?)) ``` Find more about the pipe operator [by reading its documentation](https://hexdocs.pm/elixir/Kernel.html#%7C%3E/2). ## Streams As an alternative to `Enum`, Elixir provides [the `Stream` module](https://hexdocs.pm/elixir/Stream.html) which supports lazy operations: ```elixir 1..100_000 |> Stream.map(&(&1 * 3)) |> Stream.filter(odd?) |> Enum.sum() ``` Streams are lazy, composable enumerables. In the example above, `1..100_000 |> Stream.map(&(&1 * 3))` returns a data type, an actual stream, that represents the `map` computation over the range `1..100_000`: ```elixir 1..100_000 |> Stream.map(&(&1 * 3)) ``` Furthermore, they are composable because we can pipe many stream operations: ```elixir 1..100_000 |> Stream.map(&(&1 * 3)) |> Stream.filter(odd?) ``` Instead of generating intermediate lists, streams build a series of computations that are invoked only when we pass the underlying stream to the `Enum` module. Streams are useful when working with large, *possibly infinite*, collections. Many functions in the `Stream` module accept any enumerable as an argument and return a stream as a result. It also provides functions for creating streams. For example, `Stream.cycle/1` can be used to create a stream that cycles a given enumerable infinitely. Be careful to not call a function like `Enum.map/2` on such streams, as they would cycle forever: ```elixir stream = Stream.cycle([1, 2, 3]) ``` ```elixir Enum.take(stream, 10) ``` On the other hand, `Stream.unfold/2` can be used to generate values from a given initial value: ```elixir stream = Stream.unfold("hełło", &String.next_codepoint/1) ``` ```elixir Enum.take(stream, 3) ``` Another interesting function is `Stream.resource/3` which can be used to wrap around resources, guaranteeing they are opened right before enumeration and closed afterwards, even in the case of failures. For example, `File.stream!/1` builds on top of `Stream.resource/3` to stream files: ```elixir stream = File.stream!("path/to/file") ``` ```elixir Enum.take(stream, 10) ``` The example above will fetch the first 10 lines of the file you have selected. This means streams can be very useful for handling large files or even slow resources like network resources. The amount of functionality in the [`Enum`](https://hexdocs.pm/elixir/Enum.html) and [`Stream`](https://hexdocs.pm/elixir/Stream.html) modules can be daunting at first, but you will get familiar with them case by case. In particular, focus on the `Enum` module first and only move to `Stream` for the particular scenarios where laziness is required, to either deal with slow resources or large, possibly infinite, collections. Next, we'll look at a feature central to Elixir, Processes, which allows us to write concurrent, parallel and distributed programs in an easy and understandable way.