Интерфейс Stream<T>

Последовательность элементов, поддерживающая последовательные и параллельные агрегированные операции. Следующий пример демонстрирует агрегированную операцию с использованием Stream и IntStream:

int sum = widgets.stream()
                      .filter(w -> w.getColor() == RED)
                      .mapToInt(w -> w.getWeight())
                      .sum();

Помимо Stream, являющегося потоком ссылок на объекты, существуют примитивные специализации для IntStream, LongStream и DoubleStream, все из которых называются "потоками" и соответствуют характеристикам и ограничениям, описанным здесь.

Для выполнения вычислений операции потока операции объединяются в потоковую цепочку. Потоковая цепочка состоит из источника (который может быть массивом, коллекцией, функцией-генератором, каналом ввода-вывода и т. д.), нуля или более промежуточных операций (которые преобразуют поток в другой поток, например, filter(Predicate)) и терминальной операции (которая производит результат или побочный эффект, например, count() или forEach(Consumer)). Потоки ленивые; вычисление данных источника выполняется только при инициализации терминальной операции, и элементы источника потребляются только по мере необходимости.

Коллекции и потоки, хотя и имеют некоторые поверхностные сходства, преследуют разные цели. Коллекции в первую очередь ориентированы на эффективное управление элементами и доступ к ним. Напротив, потоки не предоставляют средства для прямого доступа к элементам или их изменения и вместо этого ориентированы на декларативное описание их источника и вычислительных операций, которые будут выполняться агрегированно над этим источником. Однако, если предоставленные операции потока не предлагают желаемой функциональности, операции BaseStream.iterator() и BaseStream.spliterator() могут использоваться для выполнения контролируемого обхода.

Потоковую цепочку, например, пример с "виджетами", можно рассматривать как запрос к источнику потока. Если источник не был явно спроектирован для одновременного изменения (например, ConcurrentHashMap), может возникнуть непредсказуемое или ошибочное поведение при изменении источника потока во время запроса.

Большинство операций потока принимают параметры, описывающие поведение, заданное пользователем, например, лямбда-выражение w -> w.getWeight() , переданное mapToInt в примере выше. Для сохранения правильного поведения эти параметры поведения:

• должны быть не вмешивающимися (они не изменяют источник потока); и
• в большинстве случаев должны быть бессостоятельными (их результат не должен зависеть от состояния, которое может измениться во время выполнения потоковой цепочки).

Такие параметры всегда являются экземплярами функционального интерфейса, такого как Function, и часто представляют собой лямбда-выражения или ссылки на методы. Если не указано иное, эти параметры должны быть не равными null.

Над потоком следует выполнять операции (вызывая промежуточную или терминальную операцию потока) только один раз. Это исключает, например, "разветвлённые" потоки, где один и тот же источник питает две или более цепочки обработки, или несколько обходов одного и того же потока. Реализация потока может выбросить IllegalStateException, если она обнаружит, что поток повторно используется. Однако, поскольку некоторые операции потока могут возвращать свой приемник вместо нового объекта потока, может быть невозможно обнаружить повторное использование во всех случаях.

Поток имеет метод BaseStream.close() и реализует AutoCloseable, но почти все экземпляры потока фактически не нуждаются в закрытии после использования. Как правило, закрытие требуется только для потоков, чей источник является каналом ввода-вывода (таким как возвращаемые Files.lines(Path, Charset)). Большинство потоков поддерживаются коллекциями, массивами или функциями генерации, которые не требуют специального управления ресурсами. (Если поток требует закрытия, он может быть объявлен как ресурс в операторе try-с-ресурсами.)

Потоковые цепочки могут выполняться либо последовательно, либо в параллельном режиме. Этот режим выполнения является свойством потока. Потоки создаются с первоначальным выбором последовательного или параллельного выполнения. (Например, Collection.stream() создает последовательный поток, а Collection.parallelStream() - параллельный.) Этот выбор режима выполнения может быть изменён методами BaseStream.sequential() или BaseStream.parallel(), и может быть запрошен методом BaseStream.isParallel().

Методы

filter

Stream<T> filter(Predicate<? super T> predicate)

Параметры:

predicate - не мешающий, бессостоятельный предикат, применяемый к каждому элементу для определения того, следует ли его включать

Возвращает:

новый поток

map

<R> Stream<R> map(Function<? super T,? extends R> mapper)

Параметры типа:

R - Тип элементов нового потока

Параметры:

mapper - не мешающая, бессостоятельная функция, применяемая к каждому элементу

Возвращает:

новый поток

mapToInt

IntStream mapToInt(ToIntFunction<? super T> mapper)

Параметры:

mapper - не мешающая, бессостоятельная функция, применяемая к каждому элементу

Возвращает:

новый поток

mapToLong

LongStream mapToLong(ToLongFunction<? super T> mapper)

Параметры:

mapper - не мешающая, бессостоятельная функция, применяемая к каждому элементу

Возвращает:

новый поток

mapToDouble

DoubleStream mapToDouble(ToDoubleFunction<? super T> mapper)

Параметры:

mapper - не мешающая, бессостоятельная функция, применяемая к каждому элементу

Возвращает:

новый поток

flatMap

<R> Stream<R> flatMap(Function<? super T,? extends Stream<? extends R>> mapper)

Примечание к API:

Операция flatMap() приводит к применению преобразования один-ко-многим к элементам потока, а затем к выравниванию результирующих элементов в новый поток.

Примеры.

Если orders является потоком заказов на покупку, и каждый заказ на покупку содержит коллекцию позиций, то следующее создает поток, содержащий все позиции во всех заказах:

orders.flatMap(order -> order.getLineItems().stream())...

Если path является путем к файлу, то следующее создает поток words , содержащихся в этом файле:

Stream<String> lines = Files.lines(path, StandardCharsets.UTF_8);
     Stream<String> words = lines.flatMap(line -> Stream.of(line.split(" +")));

Функция mapper , переданная в flatMap , разделяет строку, используя простое регулярное выражение, на массив слов, а затем создает поток слов из этого массива.

Параметры типа:

R - Тип элементов нового потока

Параметры:

mapper - не мешающая, бессостоятельная функция, применяемая к каждому элементу, которая создает поток новых значений

Возвращает:

новый поток

flatMapToInt

IntStream flatMapToInt(Function<? super T,? extends IntStream> mapper)

Параметры:

mapper - не мешающая, бессостоятельная функция, применяемая к каждому элементу, которая создает поток новых значений

Возвращает:

новый поток

См. также:

flatMap(Function)

flatMapToLong

LongStream flatMapToLong(Function<? super T,? extends LongStream> mapper)

Параметры:

mapper - не мешающая, бессостоятельная функция, применяемая к каждому элементу, которая создает поток новых значений

Возвращает:

новый поток

См. также:

flatMap(Function)

flatMapToDouble

DoubleStream flatMapToDouble(Function<? super T,? extends DoubleStream> mapper)

Параметры:

mapper - не мешающая, бессостоятельная функция, применяемая к каждому элементу, которая создает поток новых значений

Возвращает:

новый поток

См. также:

flatMap(Function)

distinct

Stream<T> distinct()

Примечание к API:

Сохранение стабильности для distinct() в параллельных конвейерах относительно дорого (требует, чтобы операция действовала как полный барьер, со значительными накладными расходами на буферизацию), и стабильность часто не требуется. Использование неупорядоченного источника потока (например, generate(Supplier)) или удаление ограничения упорядочивания с помощью BaseStream.unordered() может привести к значительно более эффективному выполнению для distinct() в параллельных конвейерах, если семантика вашей ситуации это позволяет. Если требуется согласованность с порядком встреч, и вы испытываете низкую производительность или использование памяти с distinct() в параллельных конвейерах, переход к последовательному выполнению с помощью BaseStream.sequential() может улучшить производительность.

Возвращает:

новый поток

sorted

Stream<T> sorted()

Возвращает:

новый поток

sorted

Stream<T> sorted(Comparator<? super T> comparator)

Параметры:

comparator - не мешающий, бессостоятельный Comparator , который будет использоваться для сравнения элементов потока

Возвращает:

новый поток

peek

Stream<T> peek(Consumer<? super T> action)

Примечание к API:

Этот метод существует в основном для поддержки отладки, когда вы хотите видеть элементы по мере их прохождения через определенную точку в конвейере:

Stream.of("one", "two", "three", "four")
         .filter(e -> e.length() > 3)
         .peek(e -> System.out.println("Filtered value: " + e))
         .map(String::toUpperCase)
         .peek(e -> System.out.println("Mapped value: " + e))
         .collect(Collectors.toList());

Параметры:

action - не мешающее действие, которое нужно выполнить над элементами по мере их потребления из потока

Возвращает:

новый поток

ограничение

Stream<T> limit(long maxSize)

Примечание API:

Хотя limit() обычно является недорогой операцией в последовательных потоковых конвейерах, она может быть довольно дорогостоящей в упорядоченных параллельных конвейерах, особенно для больших значений maxSize, так как limit(n) ограничено возвращением не только любых n элементов, но и первых n элементов в порядке их встреч. Использование неупорядоченного источника потока (такого как generate(Supplier)) или удаление ограничения порядка с помощью BaseStream.unordered() может привести к значительному увеличению скорости limit() в параллельных конвейерах, если это допускают семантика вашей ситуации. Если требуется согласованность с порядком встречи, а вы сталкиваетесь с плохой производительностью или использованием памяти при использовании limit() в параллельных конвейерах, переход к последовательному выполнению с помощью BaseStream.sequential() может повысить производительность.

Параметры:

maxSize - количество элементов, до которого должен быть ограничен поток

Возвращает:

новый поток

Выбрасывает:

IllegalArgumentException - если maxSize отрицательно

пропустить

Stream<T> skip(long n)

Примечание API:

Хотя skip() обычно является недорогой операцией в последовательных потоковых конвейерах, она может быть довольно дорогостоящей в упорядоченных параллельных конвейерах, особенно для больших значений n, так как skip(n) ограничено пропуском не только любых n элементов, но и первых n элементов в порядке их встречи. Использование неупорядоченного источника потока (такого как generate(Supplier)) или удаление ограничения порядка с помощью BaseStream.unordered() может привести к значительному увеличению скорости skip() в параллельных конвейерах, если это допускают семантика вашей ситуации. Если требуется согласованность с порядком встречи, а вы сталкиваетесь с плохой производительностью или использованием памяти при использовании skip() в параллельных конвейерах, переход к последовательному выполнению с помощью BaseStream.sequential() может повысить производительность.

Параметры:

n - количество ведущих элементов для пропуска

Возвращает:

новый поток

Выбрасывает:

IllegalArgumentException - если n отрицательно

forEach

void forEach(Consumer<? super T> action)

Параметры:

action - невоздействующее действие, которое нужно выполнить над элементами

forEachOrdered

void forEachOrdered(Consumer<? super T> action)

Параметры:

action - невоздействующее действие, которое нужно выполнить над элементами

См. также:

forEach(Consumer)

toArray

Object[] toArray()

Возвращает:

массив, содержащий элементы этого потока

toArray

<A> A[] toArray(IntFunction<A[]> generator)

Примечание API:

Функция-генератор принимает целое число, которое является размером желаемого массива, и создаёт массив нужного размера. Это можно лаконично выразить с помощью ссылки на конструктор массива:

Person[] men = people.stream()
                          .filter(p -> p.getGender() == MALE)
                          .toArray(Person[]::new);

Параметры типа:

A - тип элемента возвращаемого массива

Параметры:

generator - функция, которая создаёт новый массив нужного типа и заданной длины

Возвращает:

массив, содержащий элементы в этом потоке

Выбрасывает:

ArrayStoreException - если тип runtime возвращаемого массива из генератора массива не является супертипом типа runtime каждого элемента в этом потоке

reduce

T reduce(T identity,
         BinaryOperator<T> accumulator)

T result = identity;
     for (T element : this stream)
         result = accumulator.apply(result, element)
     return result;

Примечание API:

Суммирование, минимум, максимум, среднее значение и конкатенация строк — все являются частными случаями сведения. Суммирование потока чисел может быть выражено как:

Integer sum = integers.reduce(0, (a, b) -> a+b);

или:

Integer sum = integers.reduce(0, Integer::sum);

Хотя это может показаться более окольным способом выполнения агрегации по сравнению с простым изменением текущей суммы в цикле, операции сведения более эффективно выполняются параллельно, без необходимости дополнительной синхронизации и с значительно меньшим риском гонок данных.

Параметры:

identity - значение тождества для функции накопления

accumulator - ассоциативная, невоздействующая, бессостоятельная функция для объединения двух значений

Возвращает:

результат сведения

reduce

Optional<T> reduce(BinaryOperator<T> accumulator)

boolean foundAny = false;
     T result = null;
     for (T element : this stream) {
         if (!foundAny) {
             foundAny = true;
             result = element;
         }
         else
             result = accumulator.apply(result, element);
     }
     return foundAny ? Optional.of(result) : Optional.empty();

Параметры:

accumulator - ассоциативная, невоздействующая, бессостоятельная функция для объединения двух значений

Возвращает:

объект Optional, описывающий результат сведения

Выбрасывает:

NullPointerException - если результатом сведения является null

См. также:

reduce(Object, BinaryOperator), min(Comparator), max(Comparator)

reduce

<U> U reduce(U identity,
             BiFunction<U,? super T,U> accumulator,
             BinaryOperator<U> combiner)

U result = identity;
     for (T element : this stream)
         result = accumulator.apply(result, element)
     return result;

combiner.apply(u, accumulator.apply(identity, t)) == accumulator.apply(u, t)

Примечание API:

Многие сокращения, использующие эту форму, можно представить проще с помощью явного сочетания операций map и reduce. Функция accumulator действует как объединённый преобразователь и аккумулятор, что может быть иногда более эффективным, чем раздельные преобразование и сокращение, например, когда знание ранее уменьшенного значения позволяет избежать некоторых вычислений.

Параметры типа:

U - тип результата

Параметры:

identity - значение тождества для функции комбинирования

accumulator - ассоциативная, не влияющая на состояние, бессостоятельная функция для включения дополнительного элемента в результат

combiner - ассоциативная, не влияющая на состояние, бессостоятельная функция для объединения двух значений, которая должна быть совместима с функцией аккумулятора

Возвращает:

результат сокращения

См. также:

reduce(BinaryOperator), reduce(Object, BinaryOperator)

collect

<R> R collect(Supplier<R> supplier,
              BiConsumer<R,? super T> accumulator,
              BiConsumer<R,R> combiner)

R result = supplier.get();
     for (T element : this stream)
         accumulator.accept(result, element);
     return result;

Примечание API:

Существует много существующих классов в JDK, чьи сигнатуры хорошо подходят для использования с ссылками на методы в качестве аргументов для collect(). Например, следующее накопит строки в ArrayList:

List<String> asList = stringStream.collect(ArrayList::new, ArrayList::add,
                                                ArrayList::addAll);

Следующее возьмёт поток строк и объединит их в одну строку:

String concat = stringStream.collect(StringBuilder::new, StringBuilder::append,
                                          StringBuilder::append)
                                 .toString();

Параметры типа:

R - тип результата

Параметры:

supplier - функция, создающая новый контейнер результата. Для параллельного выполнения эта функция может вызываться несколько раз и должна возвращать новое значение каждый раз.

accumulator - ассоциативная, не влияющая на состояние, бессостоятельная функция для включения дополнительного элемента в результат

combiner - ассоциативная, не влияющая на состояние, бессостоятельная функция для объединения двух значений, которая должна быть совместима с функцией аккумулятора

Возвращает:

результат сокращения

collect

<R,A> R collect(Collector<? super T,A,R> collector)

Примечание API:

Следующее накопит строки в ArrayList:

List<String> asList = stringStream.collect(Collectors.toList());

Следующее классифицирует Person объекты по городам:

Map<String, List<Person>> peopleByCity
         = personStream.collect(Collectors.groupingBy(Person::getCity));

Следующее классифицирует Person объекты по штату и городу, комбинируя два Collector вместе:

Map<String, Map<String, List<Person>>> peopleByStateAndCity
         = personStream.collect(Collectors.groupingBy(Person::getState,
                                                      Collectors.groupingBy(Person::getCity)));

Параметры типа:

R - тип результата

A - промежуточный тип накопления для Collector

Параметры:

collector - Collector описывающий сокращение

Возвращает:

результат сокращения

См. также:

collect(Supplier, BiConsumer, BiConsumer), Collectors

min

Optional<T> min(Comparator<? super T> comparator)

Параметры:

comparator - не влияющая на состояние, бессостоятельная функция сравнения элементов этого потока

Возвращает:

объект Optional описывающий минимальный элемент этого потока, или пустой объект Optional если поток пуст

Исключения:

NullPointerException - если минимальный элемент null

max

Optional<T> max(Comparator<? super T> comparator)

Параметры:

comparator - не влияющая на состояние, бессостоятельная функция сравнения элементов этого потока

Возвращает:

объект Optional описывающий максимальный элемент этого потока, или пустой объект Optional если поток пуст

Исключения:

NullPointerException - если максимальный элемент null

count

long count()

return mapToLong(e -> 1L).sum();

Возвращает:

количество элементов в этом потоке

anyMatch

boolean anyMatch(Predicate<? super T> predicate)

Примечание API:

Этот метод вычисляет экзистенциальную квантификацию предиката по элементам потока (для некоторого x P(x)).

Параметры:

predicate - не влияющая на состояние, бессостоятельная функция предиката для применения к элементам этого потока

Возвращает:

true если какие-либо элементы потока соответствуют предоставленному предикату, иначе false

allMatch

boolean allMatch(Predicate<? super T> predicate)

Примечание API:

Этот метод вычисляет универсальную квантификацию предиката по элементам потока (для всех x P(x)). Если поток пуст, то квантификация считается пустым удовлетворением и всегда true (независимо от P(x)).

Параметры:

predicate - не влияющая на состояние, бессостоятельная функция предиката для применения к элементам этого потока

Возвращает:

true если все элементы потока соответствуют предоставленному предикату или поток пуст, иначе false

noneMatch

boolean noneMatch(Predicate<? super T> predicate)

Примечание API:

Этот метод вычисляет универсальную квантификацию отрицания предиката по элементам потока (для всех x ~P(x)). Если поток пуст, квантификация считается пустым удовлетворением и всегда true, вне зависимости от P(x).

Параметры:

predicate - не влияющая на состояние, бессостоятельная функция предиката для применения к элементам этого потока

Возвращает:

true если ни один элемент потока не соответствует предоставленному предикату или поток пуст, иначе false

findFirst

Optional<T> findFirst()

Возвращает:

Optional описывающую первый элемент этого потока, или пустой Optional если поток пуст

Исключение:

NullPointerException - если выбранный элемент равен null

findAny

Optional<T> findAny()

Возвращает:

Optional описывающую некоторый элемент этого потока, или пустой Optional если поток пуст

Исключение:

NullPointerException - если выбранный элемент равен null

См. также:

findFirst()

builder

static <T> Stream.Builder<T> builder()

Возвращает билдер для Stream.

Параметры типа:

T - тип элементов

Возвращает:

билдер потока

empty

static <T> Stream<T> empty()

Возвращает пустой последовательный Stream.

Параметры типа:

T - тип элементов потока

Возвращает:

пустой последовательный поток

of

static <T> Stream<T> of(T t)

Возвращает последовательный Stream, содержащий один элемент.

Параметры типа:

T - тип элементов потока

Параметры:

t - единственный элемент

Возвращает:

последовательный поток из одного элемента

of

@SafeVarargs
static <T> Stream<T> of(T... values)

Возвращает упорядоченный последовательный поток, элементы которого — указанные значения.

Параметры типа:

T - тип элементов потока

Параметры:

values - элементы нового потока

Возвращает:

новый поток

iterate

static <T> Stream<T> iterate(T seed,
                             UnaryOperator<T> f)

Параметры типа:

T - тип элементов потока

Параметры:

seed - начальный элемент

f - функция, применяемая к предыдущему элементу для создания нового элемента

Возвращает:

новый последовательный Stream

generate

static <T> Stream<T> generate(Supplier<T> s)

Возвращает бесконечный неупорядоченный последовательный поток, где каждый элемент генерируется предоставленным Supplier. Это подходит для генерации постоянных потоков, потоков случайных элементов и т. д.

Параметры типа:

T - тип элементов потока

Параметры:

s - Supplier генерируемых элементов

Возвращает:

новый бесконечный неупорядоченный последовательный Stream

concat

static <T> Stream<T> concat(Stream<? extends T> a,
                            Stream<? extends T> b)

Создаёт лениво конкатенированный поток, элементы которого — все элементы первого потока, за которыми следуют все элементы второго потока. Результирующий поток упорядочен, если оба входных потока упорядочены, и параллелен, если любой из входных потоков параллелен. При закрытии результирующего потока вызываются обработчики закрытия для обоих входных потоков.

Примечание реализации:

Будьте осторожны при создании потоков из многократной конкатенации. Доступ к элементу глубоко конкатенированного потока может привести к глубоким цепочкам вызовов или даже к StackOverflowException.

Параметры типа:

T - Тип элементов потока

Параметры:

a - первый поток

b - второй поток

Возвращает:

конкатенацию двух входных потоков