A Java utility class providing methods to create Stream instances from various iterable sources

org.public_domain.java.utils.StreamUtils.java

package org.public_domain.java.utils;

import java.util.Iterator;
import java.util.stream.Stream;
import java.util.stream.StreamSupport;
import org.jetbrains.annotations.NotNull;

/**
 * File: org.public_domain.java.utils.StreamUtils.java
 * <p>
 * Version: v2025.05.14
 * <p>
 * Utility class providing methods to create {@link Stream} instances from various iterable sources.
 */
public class StreamUtils {

  /**
   * Creates a sequential {@link Stream} from a given {@link Iterator}.
   *
   * @param iterator The {@code Iterator} to create the stream from. Must not be {@code null}.
   * @param <T>      The type of elements in the stream.
   * @return A new sequential {@code Stream} containing the elements from the iterator.
   * @throws NullPointerException if the provided {@code iterator} is {@code null}.
   */
  @NotNull
  public static <T> Stream<T> from(
      @NotNull Iterator<T> iterator
  ) {
    return from(iterator, false);
  }

  /**
   * Creates a {@link Stream} from a given {@link Iterator}, allowing for parallel processing.
   *
   * @param iterator   The {@code Iterator} to create the stream from. Must not be {@code null}.
   * @param isParallel If {@code true}, the resulting stream will be parallel; otherwise, it will be sequential.
   * @param <T>        The type of elements in the stream.
   * @return A new {@code Stream} containing the elements from the iterator, with the specified parallelism.
   * @throws NullPointerException if the provided {@code iterator} is {@code null}.
   */
  @NotNull
  public static <T> Stream<T> from(
      @NotNull Iterator<T> iterator,
      boolean isParallel
  ) {
    Iterable<T> iterable = () -> iterator;

    return from(iterable, isParallel);
  }

  /**
   * Creates a sequential {@link Stream} from a given {@link Iterable}.
   *
   * @param iterable The {@code Iterable} to create the stream from. Must not be {@code null}.
   * @param <T>      The type of elements in the stream.
   * @return A new sequential {@code Stream} containing the elements from the iterable.
   * @throws NullPointerException if the provided {@code iterable} is {@code null}.
   */
  @NotNull
  public static <T> Stream<T> from(
      @NotNull Iterable<T> iterable
  ) {
    return from(iterable, false);
  }

  /**
   * Creates a {@link Stream} from a given {@link Iterable}, allowing for parallel processing.
   *
   * @param iterable   The {@code Iterable} to create the stream from. Must not be {@code null}.
   * @param isParallel If {@code true}, the resulting stream will be parallel; otherwise, it will be sequential.
   * @param <T>        The type of elements in the stream.
   * @return A new {@code Stream} containing the elements from the iterable, with the specified parallelism.
   * @throws NullPointerException if the provided {@code iterable} is {@code null}.
   */
  @NotNull
  public static <T> Stream<T> from(
      @NotNull Iterable<T> iterable,
      boolean isParallel
  ) {
    return StreamSupport.stream(iterable.spliterator(), isParallel);
  }
}