Streams

Edit the material here!

Streams is a new type of data structure introduced to us in lecture 8. Unlike previous data structures, streams are mainly used for functional programming, and we can often manipulate the data to get what we want in a single stream pipeline.

Stream Pipeline

A stream pipeline consists of a data source(e.g. generate/iterate), zero or more intermediate operations(e.g. map, filter) and a terminal operation(e.g. forEach) to end the pipeline. Once a terminal operation is called, the stream is consumed, and can no longer be used. An example of a stream pipeline:

int sum = IntStream.range(1, 10).map(x -> x * 2).filter(x -> x % 2 == 0).sum();
//IntStream.range(1, 10) is the data source
//map and filter are intermediate operations
//sum() is the terminal reduction that ends the stream pipeline

Laziness

What differentiates streams from other data structures is that streams are lazy. Laziness in streams means that in a stream pipeline, intermediate operations are not evaluated until the terminal operation is called. Furthermore, the data from the data source is only generated and consumed when needed. Another example:

int sum = IntStream.iterate(1, x -> x + 1).map(x -> x * 2).filter(x -> x % 2 == 0).forEach(System.out::println);
//(x -> x * 2) is the Function<T,T> mapper
//(x -> x * 2) is the Predicate<T>
//note this program runs forever since iterate creates an infinite stream

In the above example, when we do create the source with iterate, we create a IntStream object in the heap, which captures the value of seed and the UnaryOperator next. The rest of the values in the stream is not yet generated.

When we go to intermediate operations map and filter, we create a new IntStream object in the heap, that captures the the mapper function that we input into the map function and a pointer to the previous IntStream object. At this point, the function mapper is not yet applied. Likewise for the filter operation, a new IntStream object is created in the heap, capturing the Predicate and a pointer to the previous IntStream object created by map. Every intermediate operation in our pipeline will create a new stream object in the heap that captures the operation we want to do and a pointer to the previous stream object.

Only when we call a terminal operation, in this case forEach, we follow the pointers upstream all the way to the source, get the current element, and apply all the intermediate operations downstream up to the terminal operation. We need to go through this upstream-downstream process for each element in the stream.

As in Prof Henry's lecture 9 slides, this example illustrates the laziness in streams.

int sum = IntStream
  .rangeClosed(1, 10)
  .filter(
    x -> {
      System.out.println("filter: " + x);
      return x % 2 == 0;
    })
  .map(
     x -> {
      System.out.println("map: " + x);
      return 2 * x;
     })
  .sum();
System.out.println(sum);

This program prints:

filter: 1
filter: 2
map: 2
filter: 3
filter: 4
map: 4
filter: 5
filter: 6
map: 6
filter: 7
filter: 8
map: 8
filter: 9
filter: 10
map: 10
sum is 60

The output showing the filter and map interleaving with each other shows that the whole pipeline of intermediate operation is applied to one element at a time, as we would expect from the laziness of streams causing our evaluation process to go upstream and downstream for each element and only generating the element and applying the operations as we need. For contrast, if we were to use a List for the same program, the program would first filter the entire list, and then map the entire list, as opposed to applying the whole pipeline to one element at a time.

Advantages of Laziness

We can create incomplete stream pipelines with only intermediate operations and pass it around our program to be to continue adding more intermediate operations or to be consumed at a later time.

In addition, since data elements are only generated and consumed when needed, we can create infinite streams. This is useful when we want to do things where we don't know how many elements we need in our data structure. For example, we can write a program to find the first 100 prime numbers. If we were to use a list, we would not know how big our initial list needs to be. Using streams, we can simply create an infinite stream, filter with a predicate to look for prime numbers and set a limit on the number of elements we want in the stream.

Converting Between Streams, Arrays and ArrayLists

From Array to ArrayList

import java.util.Arrays;
import java.util.ArrayList;
import java.util.stream.IntStream;
import java.util.stream.Collectors;

/*
Integer[] -> ArrayList<Integer>
Works with any Object instead of Integer as well.
Does not work for primitive int[] array as Arrays.asList() method does not deal
with autoboxing and it will just create a List<int[]>
*/
Integer[] integerArray = {0, 1, 2, 3};
ArrayList<Integer> integerArrayList = new ArrayList<>(Arrays.asList(integerArray));

// int[] -> ArrayList<Integer>
int[] intArray = {0, 1, 2, 3};
// boxed method converts primitive int to Integer
ArrayList<Integer> intArrayList = IntStream.of(intArray).boxed() 
  .collect(Collectors.toCollection(ArrayList::new));

From Array to Stream

// Integer -> Stream<Integer>
Integer[] integerArray = {0, 1, 2, 3};
Stream<Integer> integerStream = Arrays.stream(integerArray);
// int -> IntStream
int[] intArray = {0, 1, 2, 3};
IntStream intStream = Arrays.stream(intArray);

From ArrayList to Array

// ArrayList<Integer> -> Integer[]
Integer[] integerArray = new Integer[integerArrayList.size()];
integerArray = integerArrayList.toArray(integerArray);
// ArrayList<Integer> -> int[]
int[] intArray = integerArrayList.stream().mapToInt(Integer::intValue).toArray();
// IntStream -> int[]
int[] intArray = intStream.toArray();

From ArrayList to Stream

// ArrayList<Integer> -> Stream<Integer>
Stream<Integer> integerStream = integerArrayList.stream();
// ArrayList<Integer> -> IntStream
IntStream intStream = integerArrayList.stream().mapToInt(Integer::intValue);

From Stream to Array

// Stream<Integer> -> Integer[]
Integer[] integerArray = integerStream.toArray(Integer[]::new);
// intStream -> int[]
int[] intArray = intStream.toArray();

From Stream to ArrayList

// Stream<Integer> -> ArrayList<Integer>
List<Integer> integerList = integerStream.collect(Collectors.toList());
ArrayList<Integer> integerArrayList = new ArrayList<>(integerList);
// intStream -> ArrayList<Integer>
List<Integer> integerList = intStream.boxed().collect(Collectors.toList());
ArrayList<Integer> integerArrayList = new ArrayList<>(integerList);

Summary for Streams

Here is a Summary for Streams that you can use during finals since there are so many methods for streams.

Do note that these are not exhaustive but what I feel is the most common(for this course that is).

Obtaining a Stream	Intermediate Operations	Terminal Operations
`Stream.of(...)`	`filter(Predicate <? super T> pred)`	`forEach(Consumer<? super T> action`
`Stream.of(T t)`	`map(Function<? super T, ? extends R> mapper)`	`toArray()`
`Stream.generate(Supplier<? extends T> s)`	`flatMap(Function<? super T,? extends Stream<? extends R>> mapper)`	`noneMatch(Predicate<? super T> pred)`
`Stream.iterate(T seed, UnaryOperator<T> next)`	`sorted()`	`allMatch(Predicate<? super T> pred)`
`Stream.iterate(T seed, Predicate <? super T> hasNext, UnaryOperator<T> next)`	`limit(long maxSize)`	`anyMatch(Predicate<? super T> predicate)`
`Stream.concat(Stream<? extends T> a, Stream<? extends T> b)`	`skip(long n)`	`count()`
`IntStream.rangeClosed(int startInclusive, int endInclusive)`	`distinct()`	`min(Comparator<? super T> comparator)/ max(Comparator<? super T> comparator)`
`IntStream.ranged(int startInclusive, int endInclusive)`	`mapToObj/mapToInt/mapToLong`	`reduce(BinaryOperator<T> accumulator)`
	`peek(Consumer<? super T> action)`	`reduce(T identity, BinaryOperator<T> accumulator)`
		`collect(Collector<? super T,A,R> collector)`

Also, the Stream API is here and IntStream is here

Stream.of

Making a Stream out of individual values or an array or a list.

//From a bunch of digits
Stream<Integer> stream = Stream.of(1, 2, 3, 5, 7, 11);

//From an array
Stream<String> stream = Stream.of(myArray)

// From a list (need to import java list)
list.stream(); // or from a list

Streams

Stream Pipeline

Laziness

Advantages of Laziness

Converting Between Streams, Arrays and ArrayLists

Summary for Streams

Stream.of

Stream.generate

Stream.iterate

Stream.concat

IntStream.rangeClosed / IntStream.range

filter

map

maptoObj/ maptoLong/ maptoDouble

flatmap

sorted()

limit(long maxSize)

distinct()

skip(long n)

peek(Consumer action)

forEach(Consumer action)

noneMatch/ allMatch/ anyMatch(Predicate predicate)

count()

reduce

.min() and .max()

Collect and toArray()