001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.lang3.stream; 018 019import java.util.ArrayList; 020import java.util.Collection; 021import java.util.Collections; 022import java.util.Enumeration; 023import java.util.Iterator; 024import java.util.List; 025import java.util.Objects; 026import java.util.Set; 027import java.util.Spliterator; 028import java.util.Spliterators; 029import java.util.Spliterators.AbstractSpliterator; 030import java.util.function.BiConsumer; 031import java.util.function.BinaryOperator; 032import java.util.function.Consumer; 033import java.util.function.Function; 034import java.util.function.Predicate; 035import java.util.function.Supplier; 036import java.util.stream.Collector; 037import java.util.stream.Collectors; 038import java.util.stream.Stream; 039import java.util.stream.StreamSupport; 040 041import org.apache.commons.lang3.ArrayUtils; 042import org.apache.commons.lang3.function.Failable; 043import org.apache.commons.lang3.function.FailableConsumer; 044import org.apache.commons.lang3.function.FailableFunction; 045import org.apache.commons.lang3.function.FailablePredicate; 046 047/** 048 * Provides utility functions, and classes for working with the {@link java.util.stream} package, or more generally, 049 * with Java 8 lambdas. More specifically, it attempts to address the fact that lambdas are supposed not to throw 050 * Exceptions, at least not checked Exceptions, AKA instances of {@link Exception}. This enforces the use of constructs 051 * like: 052 * 053 * <pre> 054 * {@code 055 * Consumer<java.lang.reflect.Method> consumer = m -> { 056 * try { 057 * m.invoke(o, args); 058 * } catch (Throwable t) { 059 * throw Failable.rethrow(t); 060 * } 061 * }; 062 * stream.forEach(consumer); 063 * } 064 * </pre> 065 * <p> 066 * Using a {@link FailableStream}, this can be rewritten as follows: 067 * </p> 068 * 069 * <pre> 070 * {@code 071 * Streams.failable(stream).forEach((m) -> m.invoke(o, args)); 072 * } 073 * </pre> 074 * 075 * Obviously, the second version is much more concise and the spirit of Lambda expressions is met better than in the 076 * first version. 077 * 078 * @see Stream 079 * @see Failable 080 * @since 3.11 081 */ 082public class Streams { 083 084 /** 085 * A Collector type for arrays. 086 * 087 * @param <E> The array type. 088 */ 089 public static class ArrayCollector<E> implements Collector<E, List<E>, E[]> { 090 private static final Set<Characteristics> characteristics = Collections.emptySet(); 091 private final Class<E> elementType; 092 093 /** 094 * Constructs a new instance for the given element type. 095 * 096 * @param elementType The element type. 097 */ 098 public ArrayCollector(final Class<E> elementType) { 099 this.elementType = Objects.requireNonNull(elementType, "elementType"); 100 } 101 102 @Override 103 public BiConsumer<List<E>, E> accumulator() { 104 return List::add; 105 } 106 107 @Override 108 public Set<Characteristics> characteristics() { 109 return characteristics; 110 } 111 112 @Override 113 public BinaryOperator<List<E>> combiner() { 114 return (left, right) -> { 115 left.addAll(right); 116 return left; 117 }; 118 } 119 120 @Override 121 public Function<List<E>, E[]> finisher() { 122 return list -> list.toArray(ArrayUtils.newInstance(elementType, list.size())); 123 } 124 125 @Override 126 public Supplier<List<E>> supplier() { 127 return ArrayList::new; 128 } 129 } 130 131 /** 132 * Helps implement {@link Streams#of(Enumeration)}. 133 * 134 * @param <T> The element type. 135 */ 136 private static final class EnumerationSpliterator<T> extends AbstractSpliterator<T> { 137 138 private final Enumeration<T> enumeration; 139 140 /** 141 * Creates a spliterator reporting the given estimated size and additionalCharacteristics. 142 * 143 * @param estimatedSize the estimated size of this spliterator if known, otherwise {@code Long.MAX_VALUE}. 144 * @param additionalCharacteristics properties of this spliterator's source or elements. If {@code SIZED} is reported then this spliterator will 145 * additionally report {@code SUBSIZED}. 146 * @param enumeration The Enumeration to wrap. 147 */ 148 protected EnumerationSpliterator(final long estimatedSize, final int additionalCharacteristics, final Enumeration<T> enumeration) { 149 super(estimatedSize, additionalCharacteristics); 150 this.enumeration = Objects.requireNonNull(enumeration, "enumeration"); 151 } 152 153 @Override 154 public void forEachRemaining(final Consumer<? super T> action) { 155 while (enumeration.hasMoreElements()) { 156 next(action); 157 } 158 } 159 160 private boolean next(final Consumer<? super T> action) { 161 action.accept(enumeration.nextElement()); 162 return true; 163 164 } 165 166 @Override 167 public boolean tryAdvance(final Consumer<? super T> action) { 168 return enumeration.hasMoreElements() && next(action); 169 } 170 } 171 172 /** 173 * A reduced, and simplified version of a {@link Stream} with failable method signatures. 174 * 175 * @param <T> The streams element type. 176 */ 177 public static class FailableStream<T> { 178 179 private Stream<T> stream; 180 private boolean terminated; 181 182 /** 183 * Constructs a new instance with the given {@code stream}. 184 * 185 * @param stream The stream. 186 */ 187 public FailableStream(final Stream<T> stream) { 188 this.stream = stream; 189 } 190 191 /** 192 * Returns whether all elements of this stream match the provided predicate. May not evaluate the predicate on all 193 * elements if not necessary for determining the result. If the stream is empty then {@code true} is returned and the 194 * predicate is not evaluated. 195 * 196 * <p> 197 * This is a short-circuiting terminal operation. 198 * </p> 199 * 200 * Note This method evaluates the <em>universal quantification</em> of the predicate over the elements of the stream 201 * (for all x P(x)). If the stream is empty, the quantification is said to be <em>vacuously satisfied</em> and is always 202 * {@code true} (regardless of P(x)). 203 * 204 * @param predicate A non-interfering, stateless predicate to apply to elements of this stream 205 * @return {@code true} If either all elements of the stream match the provided predicate or the stream is empty, 206 * otherwise {@code false}. 207 */ 208 public boolean allMatch(final FailablePredicate<T, ?> predicate) { 209 assertNotTerminated(); 210 return stream().allMatch(Failable.asPredicate(predicate)); 211 } 212 213 /** 214 * Returns whether any elements of this stream match the provided predicate. May not evaluate the predicate on all 215 * elements if not necessary for determining the result. If the stream is empty then {@code false} is returned and the 216 * predicate is not evaluated. 217 * 218 * <p> 219 * This is a short-circuiting terminal operation. 220 * </p> 221 * 222 * Note This method evaluates the <em>existential quantification</em> of the predicate over the elements of the stream 223 * (for some x P(x)). 224 * 225 * @param predicate A non-interfering, stateless predicate to apply to elements of this stream 226 * @return {@code true} if any elements of the stream match the provided predicate, otherwise {@code false} 227 */ 228 public boolean anyMatch(final FailablePredicate<T, ?> predicate) { 229 assertNotTerminated(); 230 return stream().anyMatch(Failable.asPredicate(predicate)); 231 } 232 233 /** 234 * Throws IllegalStateException if this stream is already terminated. 235 * 236 * @throws IllegalStateException if this stream is already terminated. 237 */ 238 protected void assertNotTerminated() { 239 if (terminated) { 240 throw new IllegalStateException("This stream is already terminated."); 241 } 242 } 243 244 /** 245 * Performs a mutable reduction operation on the elements of this stream using a {@link Collector}. A {@link Collector} 246 * encapsulates the functions used as arguments to {@link #collect(Supplier, BiConsumer, BiConsumer)}, allowing for 247 * reuse of collection strategies and composition of collect operations such as multiple-level grouping or partitioning. 248 * 249 * <p> 250 * If the underlying stream is parallel, and the {@link Collector} is concurrent, and either the stream is unordered or 251 * the collector is unordered, then a concurrent reduction will be performed (see {@link Collector} for details on 252 * concurrent reduction.) 253 * </p> 254 * 255 * <p> 256 * This is a terminal operation. 257 * </p> 258 * 259 * <p> 260 * When executed in parallel, multiple intermediate results may be instantiated, populated, and merged so as to maintain 261 * isolation of mutable data structures. Therefore, even when executed in parallel with non-thread-safe data structures 262 * (such as {@link ArrayList}), no additional synchronization is needed for a parallel reduction. 263 * </p> 264 * 265 * Note The following will accumulate strings into an ArrayList: 266 * 267 * <pre> 268 * {@code 269 * List<String> asList = stringStream.collect(Collectors.toList()); 270 * } 271 * </pre> 272 * 273 * <p> 274 * The following will classify {@code Person} objects by city: 275 * </p> 276 * 277 * <pre> 278 * {@code 279 * Map<String, List<Person>> peopleByCity = personStream.collect(Collectors.groupingBy(Person::getCity)); 280 * } 281 * </pre> 282 * 283 * <p> 284 * The following will classify {@code Person} objects by state and city, cascading two {@link Collector}s together: 285 * </p> 286 * 287 * <pre> 288 * {@code 289 * Map<String, Map<String, List<Person>>> peopleByStateAndCity = personStream 290 * .collect(Collectors.groupingBy(Person::getState, Collectors.groupingBy(Person::getCity))); 291 * } 292 * </pre> 293 * 294 * @param <R> the type of the result 295 * @param <A> the intermediate accumulation type of the {@link Collector} 296 * @param collector the {@link Collector} describing the reduction 297 * @return the result of the reduction 298 * @see #collect(Supplier, BiConsumer, BiConsumer) 299 * @see Collectors 300 */ 301 public <A, R> R collect(final Collector<? super T, A, R> collector) { 302 makeTerminated(); 303 return stream().collect(collector); 304 } 305 306 /** 307 * Performs a mutable reduction operation on the elements of this FailableStream. A mutable reduction is one in which 308 * the reduced value is a mutable result container, such as an {@link ArrayList}, and elements are incorporated by 309 * updating the state of the result rather than by replacing the result. This produces a result equivalent to: 310 * <pre> 311 * {@code 312 * R result = supplier.get(); 313 * for (T element : this stream) 314 * accumulator.accept(result, element); 315 * return result; 316 * } 317 * </pre> 318 * <p> 319 * Like {@link #reduce(Object, BinaryOperator)}, {@code collect} operations can be parallelized without requiring 320 * additional synchronization. 321 * </p> 322 * <p> 323 * This is a terminal operation. 324 * </p> 325 * <p> 326 * Note There are many existing classes in the JDK whose signatures are well-suited for use with method references as 327 * arguments to {@code collect()}. For example, the following will accumulate strings into an {@link ArrayList}: 328 * </p> 329 * <pre> 330 * {@code 331 * List<String> asList = stringStream.collect(ArrayList::new, ArrayList::add, ArrayList::addAll); 332 * } 333 * </pre> 334 * <p> 335 * The following will take a stream of strings and concatenates them into a single string: 336 * </p> 337 * <pre> 338 * {@code 339 * String concat = stringStream.collect(StringBuilder::new, StringBuilder::append, StringBuilder::append).toString(); 340 * } 341 * </pre> 342 * 343 * @param <R> type of the result 344 * @param <A> Type of the accumulator. 345 * @param supplier a function that creates a new result container. For a parallel execution, this function may be called 346 * multiple times and must return a fresh value each time. 347 * @param accumulator An associative, non-interfering, stateless function for incorporating an additional element into a 348 * result 349 * @param combiner An associative, non-interfering, stateless function for combining two values, which must be 350 * compatible with the accumulator function 351 * @return The result of the reduction 352 */ 353 public <A, R> R collect(final Supplier<R> supplier, final BiConsumer<R, ? super T> accumulator, final BiConsumer<R, R> combiner) { 354 makeTerminated(); 355 return stream().collect(supplier, accumulator, combiner); 356 } 357 358 /** 359 * Returns a FailableStream consisting of the elements of this stream that match the given FailablePredicate. 360 * <p> 361 * This is an intermediate operation. 362 * </p> 363 * 364 * @param predicate a non-interfering, stateless predicate to apply to each element to determine if it should be 365 * included. 366 * @return the new stream 367 */ 368 public FailableStream<T> filter(final FailablePredicate<T, ?> predicate) { 369 assertNotTerminated(); 370 stream = stream.filter(Failable.asPredicate(predicate)); 371 return this; 372 } 373 374 /** 375 * Performs an action for each element of this stream. 376 * <p> 377 * This is a terminal operation. 378 * </p> 379 * <p> 380 * The behavior of this operation is explicitly nondeterministic. For parallel stream pipelines, this operation does 381 * <em>not</em> guarantee to respect the encounter order of the stream, as doing so would sacrifice the benefit of 382 * parallelism. For any given element, the action may be performed at whatever time and in whatever thread the library 383 * chooses. If the action accesses shared state, it is responsible for providing the required synchronization. 384 * </p> 385 * 386 * @param action a non-interfering action to perform on the elements 387 */ 388 public void forEach(final FailableConsumer<T, ?> action) { 389 makeTerminated(); 390 stream().forEach(Failable.asConsumer(action)); 391 } 392 393 /** 394 * Marks this stream as terminated. 395 * 396 * @throws IllegalStateException if this stream is already terminated. 397 */ 398 protected void makeTerminated() { 399 assertNotTerminated(); 400 terminated = true; 401 } 402 403 /** 404 * Returns a stream consisting of the results of applying the given function to the elements of this stream. 405 * 406 * <p> 407 * This is an intermediate operation. 408 * </p> 409 * 410 * @param <R> The element type of the new stream 411 * @param mapper A non-interfering, stateless function to apply to each element 412 * @return the new stream 413 */ 414 public <R> FailableStream<R> map(final FailableFunction<T, R, ?> mapper) { 415 assertNotTerminated(); 416 return new FailableStream<>(stream.map(Failable.asFunction(mapper))); 417 } 418 419 /** 420 * Performs a reduction on the elements of this stream, using the provided identity value and an associative 421 * accumulation function, and returns the reduced value. This is equivalent to: 422 * 423 * <pre> 424 * {@code 425 * T result = identity; 426 * for (T element : this stream) 427 * result = accumulator.apply(result, element) 428 * return result; 429 * } 430 * </pre> 431 * 432 * but is not constrained to execute sequentially. 433 * 434 * <p> 435 * The {@code identity} value must be an identity for the accumulator function. This means that for all {@code t}, 436 * {@code accumulator.apply(identity, t)} is equal to {@code t}. The {@code accumulator} function must be an associative 437 * function. 438 * </p> 439 * 440 * <p> 441 * This is a terminal operation. 442 * </p> 443 * 444 * Note Sum, min, max, average, and string concatenation are all special cases of reduction. Summing a stream of numbers 445 * can be expressed as: 446 * 447 * <pre> 448 * {@code 449 * Integer sum = integers.reduce(0, (a, b) -> a + b); 450 * } 451 * </pre> 452 * 453 * or: 454 * 455 * <pre> 456 * {@code 457 * Integer sum = integers.reduce(0, Integer::sum); 458 * } 459 * </pre> 460 * 461 * <p> 462 * While this may seem a more roundabout way to perform an aggregation compared to simply mutating a running total in a 463 * loop, reduction operations parallelize more gracefully, without needing additional synchronization and with greatly 464 * reduced risk of data races. 465 * </p> 466 * 467 * @param identity the identity value for the accumulating function 468 * @param accumulator an associative, non-interfering, stateless function for combining two values 469 * @return the result of the reduction 470 */ 471 public T reduce(final T identity, final BinaryOperator<T> accumulator) { 472 makeTerminated(); 473 return stream().reduce(identity, accumulator); 474 } 475 476 /** 477 * Converts the FailableStream into an equivalent stream. 478 * 479 * @return A stream, which will return the same elements, which this FailableStream would return. 480 */ 481 public Stream<T> stream() { 482 return stream; 483 } 484 } 485 486 /** 487 * Converts the given {@link Collection} into a {@link FailableStream}. This is basically a simplified, reduced version 488 * of the {@link Stream} class, with the same underlying element stream, except that failable objects, like 489 * {@link FailablePredicate}, {@link FailableFunction}, or {@link FailableConsumer} may be applied, instead of 490 * {@link Predicate}, {@link Function}, or {@link Consumer}. The idea is to rewrite a code snippet like this: 491 * 492 * <pre> 493 * {@code 494 * final List<O> list; 495 * final Method m; 496 * final Function<O, String> mapper = (o) -> { 497 * try { 498 * return (String) m.invoke(o); 499 * } catch (Throwable t) { 500 * throw Failable.rethrow(t); 501 * } 502 * }; 503 * final List<String> strList = list.stream().map(mapper).collect(Collectors.toList()); 504 * } 505 * </pre> 506 * 507 * as follows: 508 * 509 * <pre> 510 * {@code 511 * final List<O> list; 512 * final Method m; 513 * final List<String> strList = Failable.stream(list.stream()).map((o) -> (String) m.invoke(o)).collect(Collectors.toList()); 514 * } 515 * </pre> 516 * 517 * While the second version may not be <em>quite</em> as efficient (because it depends on the creation of additional, 518 * intermediate objects, of type FailableStream), it is much more concise, and readable, and meets the spirit of Lambdas 519 * better than the first version. 520 * 521 * @param <T> The streams element type. 522 * @param stream The stream, which is being converted. 523 * @return The {@link FailableStream}, which has been created by converting the stream. 524 * @since 3.13.0 525 */ 526 public static <T> FailableStream<T> failableStream(final Collection<T> stream) { 527 return failableStream(of(stream)); 528 } 529 530 /** 531 * Converts the given {@link Stream stream} into a {@link FailableStream}. This is basically a simplified, reduced 532 * version of the {@link Stream} class, with the same underlying element stream, except that failable objects, like 533 * {@link FailablePredicate}, {@link FailableFunction}, or {@link FailableConsumer} may be applied, instead of 534 * {@link Predicate}, {@link Function}, or {@link Consumer}. The idea is to rewrite a code snippet like this: 535 * 536 * <pre> 537 * {@code 538 * final List<O> list; 539 * final Method m; 540 * final Function<O, String> mapper = (o) -> { 541 * try { 542 * return (String) m.invoke(o); 543 * } catch (Throwable t) { 544 * throw Failable.rethrow(t); 545 * } 546 * }; 547 * final List<String> strList = list.stream().map(mapper).collect(Collectors.toList()); 548 * } 549 * </pre> 550 * 551 * as follows: 552 * 553 * <pre> 554 * {@code 555 * final List<O> list; 556 * final Method m; 557 * final List<String> strList = Failable.stream(list.stream()).map((o) -> (String) m.invoke(o)).collect(Collectors.toList()); 558 * } 559 * </pre> 560 * 561 * While the second version may not be <em>quite</em> as efficient (because it depends on the creation of additional, 562 * intermediate objects, of type FailableStream), it is much more concise, and readable, and meets the spirit of Lambdas 563 * better than the first version. 564 * 565 * @param <T> The streams element type. 566 * @param stream The stream, which is being converted. 567 * @return The {@link FailableStream}, which has been created by converting the stream. 568 * @since 3.13.0 569 */ 570 public static <T> FailableStream<T> failableStream(final Stream<T> stream) { 571 return new FailableStream<>(stream); 572 } 573 574 /** 575 * Shorthand for {@code Streams.failableStream(value == null ? Stream.empty() : Stream.of(value))}. 576 * 577 * @param <T> the type of stream elements. 578 * @param value the single element of the new stream, may be {@code null}. 579 * @return the new FailableStream on {@code value} or an empty stream. 580 * @since 3.15.0 581 */ 582 public static <T> FailableStream<T> failableStream(final T value) { 583 return failableStream(streamOf(value)); 584 } 585 586 /** 587 * Shorthand for {@code Streams.failableStream(Streams.of(arrayValues))}. 588 * 589 * @param <T> the type of stream elements. 590 * @param values the elements of the new stream, may be {@code null}. 591 * @return the new FailableStream on {@code values} or an empty stream. 592 * @since 3.14.0 593 */ 594 @SafeVarargs // Creating a stream from an array is safe 595 public static <T> FailableStream<T> failableStream(final T... values) { 596 return failableStream(of(values)); 597 } 598 599 /** 600 * Streams only instances of the give Class in a collection. 601 * <p> 602 * This method shorthand for: 603 * </p> 604 * <pre> 605 * {@code (Stream<E>) Streams.toStream(collection).filter(collection, SomeClass.class::isInstance);} 606 * </pre> 607 * 608 * @param <E> the type of elements in the collection we want to stream. 609 * @param clazz the type of elements in the collection we want to stream. 610 * @param collection the collection to stream or null. 611 * @return A non-null stream that only provides instances we want. 612 * @since 3.13.0 613 */ 614 public static <E> Stream<E> instancesOf(final Class<? super E> clazz, final Collection<? super E> collection) { 615 return instancesOf(clazz, of(collection)); 616 } 617 618 @SuppressWarnings("unchecked") // After the isInstance check, we still need to type-cast. 619 private static <E> Stream<E> instancesOf(final Class<? super E> clazz, final Stream<?> stream) { 620 return (Stream<E>) of(stream).filter(clazz::isInstance); 621 } 622 623 /** 624 * Streams the non-null elements of a collection. 625 * 626 * @param <E> the type of elements in the collection. 627 * @param collection the collection to stream or null. 628 * @return A non-null stream that filters out null elements. 629 * @since 3.13.0 630 */ 631 public static <E> Stream<E> nonNull(final Collection<E> collection) { 632 return of(collection).filter(Objects::nonNull); 633 } 634 635 /** 636 * Streams the non-null element. 637 * 638 * @param <E> the type of elements in the collection. 639 * @param array the element to stream or null. 640 * @return A non-null stream that filters out a null element. 641 * @since 3.15.0 642 */ 643 public static <E> Stream<E> nonNull(final E array) { 644 return nonNull(streamOf(array)); 645 } 646 647 /** 648 * Streams the non-null elements of an array. 649 * 650 * @param <E> the type of elements in the collection. 651 * @param array the array to stream or null. 652 * @return A non-null stream that filters out null elements. 653 * @since 3.13.0 654 */ 655 @SafeVarargs 656 public static <E> Stream<E> nonNull(final E... array) { 657 return nonNull(of(array)); 658 } 659 660 /** 661 * Streams the non-null elements of a stream. 662 * 663 * @param <E> the type of elements in the collection. 664 * @param stream the stream to stream or null. 665 * @return A non-null stream that filters out null elements. 666 * @since 3.13.0 667 */ 668 public static <E> Stream<E> nonNull(final Stream<E> stream) { 669 return of(stream).filter(Objects::nonNull); 670 } 671 672 /** 673 * Delegates to {@link Collection#stream()} or returns {@link Stream#empty()} if the collection is null. 674 * 675 * @param <E> the type of elements in the collection. 676 * @param collection the collection to stream or null. 677 * @return {@link Collection#stream()} or {@link Stream#empty()} if the collection is null. 678 * @since 3.13.0 679 */ 680 public static <E> Stream<E> of(final Collection<E> collection) { 681 return collection == null ? Stream.empty() : collection.stream(); 682 } 683 684 /** 685 * Streams the elements of the given enumeration in order. 686 * 687 * @param <E> The enumeration element type. 688 * @param enumeration The enumeration to stream. 689 * @return a new stream. 690 * @since 3.13.0 691 */ 692 public static <E> Stream<E> of(final Enumeration<E> enumeration) { 693 return StreamSupport.stream(new EnumerationSpliterator<>(Long.MAX_VALUE, Spliterator.ORDERED, enumeration), false); 694 } 695 696 /** 697 * Creates a stream on the given Iterable. 698 * 699 * @param <E> the type of elements in the Iterable. 700 * @param iterable the Iterable to stream or null. 701 * @return a new Stream or {@link Stream#empty()} if the Iterable is null. 702 * @since 3.13.0 703 */ 704 public static <E> Stream<E> of(final Iterable<E> iterable) { 705 return iterable == null ? Stream.empty() : StreamSupport.stream(iterable.spliterator(), false); 706 } 707 708 /** 709 * Creates a stream on the given Iterator. 710 * 711 * @param <E> the type of elements in the Iterator. 712 * @param iterator the Iterator to stream or null. 713 * @return a new Stream or {@link Stream#empty()} if the Iterator is null. 714 * @since 3.13.0 715 */ 716 public static <E> Stream<E> of(final Iterator<E> iterator) { 717 return iterator == null ? Stream.empty() : StreamSupport.stream(Spliterators.spliteratorUnknownSize(iterator, Spliterator.ORDERED), false); 718 } 719 720 /** 721 * Returns the stream or {@link Stream#empty()} if the stream is null. 722 * 723 * @param <E> the type of elements in the collection. 724 * @param stream the stream to stream or null. 725 * @return the stream or {@link Stream#empty()} if the stream is null. 726 * @since 3.13.0 727 */ 728 private static <E> Stream<E> of(final Stream<E> stream) { 729 return stream == null ? Stream.empty() : stream; 730 } 731 732 /** 733 * Null-safe version of {@link Stream#of(Object[])}. 734 * 735 * @param <T> the type of stream elements. 736 * @param values the elements of the new stream, may be {@code null}. 737 * @return the new stream on {@code values} or {@link Stream#empty()}. 738 * @since 3.13.0 739 */ 740 @SafeVarargs // Creating a stream from an array is safe 741 public static <T> Stream<T> of(final T... values) { 742 return values == null ? Stream.empty() : Stream.of(values); 743 } 744 745 /** 746 * Converts the given {@link Collection} into a {@link FailableStream}. This is basically a simplified, reduced version 747 * of the {@link Stream} class, with the same underlying element stream, except that failable objects, like 748 * {@link FailablePredicate}, {@link FailableFunction}, or {@link FailableConsumer} may be applied, instead of 749 * {@link Predicate}, {@link Function}, or {@link Consumer}. The idea is to rewrite a code snippet like this: 750 * 751 * <pre> 752 * {@code 753 * final List<O> list; 754 * final Method m; 755 * final Function<O, String> mapper = (o) -> { 756 * try { 757 * return (String) m.invoke(o); 758 * } catch (Throwable t) { 759 * throw Failable.rethrow(t); 760 * } 761 * }; 762 * final List<String> strList = list.stream().map(mapper).collect(Collectors.toList()); 763 * } 764 * </pre> 765 * 766 * as follows: 767 * 768 * <pre> 769 * {@code 770 * final List<O> list; 771 * final Method m; 772 * final List<String> strList = Failable.stream(list.stream()).map((o) -> (String) m.invoke(o)).collect(Collectors.toList()); 773 * } 774 * </pre> 775 * 776 * While the second version may not be <em>quite</em> as efficient (because it depends on the creation of additional, 777 * intermediate objects, of type FailableStream), it is much more concise, and readable, and meets the spirit of Lambdas 778 * better than the first version. 779 * 780 * @param <E> The streams element type. 781 * @param collection The stream, which is being converted. 782 * @return The {@link FailableStream}, which has been created by converting the stream. 783 * @deprecated Use {@link #failableStream(Collection)}. 784 */ 785 @Deprecated 786 public static <E> FailableStream<E> stream(final Collection<E> collection) { 787 return failableStream(collection); 788 } 789 790 /** 791 * Converts the given {@link Stream stream} into a {@link FailableStream}. This is basically a simplified, reduced 792 * version of the {@link Stream} class, with the same underlying element stream, except that failable objects, like 793 * {@link FailablePredicate}, {@link FailableFunction}, or {@link FailableConsumer} may be applied, instead of 794 * {@link Predicate}, {@link Function}, or {@link Consumer}. The idea is to rewrite a code snippet like this: 795 * 796 * <pre> 797 * {@code 798 * final List<O> list; 799 * final Method m; 800 * final Function<O, String> mapper = (o) -> { 801 * try { 802 * return (String) m.invoke(o); 803 * } catch (Throwable t) { 804 * throw Failable.rethrow(t); 805 * } 806 * }; 807 * final List<String> strList = list.stream().map(mapper).collect(Collectors.toList()); 808 * } 809 * </pre> 810 * 811 * as follows: 812 * 813 * <pre> 814 * {@code 815 * final List<O> list; 816 * final Method m; 817 * final List<String> strList = Failable.stream(list.stream()).map((o) -> (String) m.invoke(o)).collect(Collectors.toList()); 818 * } 819 * </pre> 820 * 821 * While the second version may not be <em>quite</em> as efficient (because it depends on the creation of additional, 822 * intermediate objects, of type FailableStream), it is much more concise, and readable, and meets the spirit of Lambdas 823 * better than the first version. 824 * 825 * @param <T> The streams element type. 826 * @param stream The stream, which is being converted. 827 * @return The {@link FailableStream}, which has been created by converting the stream. 828 * @deprecated Use {@link #failableStream(Stream)}. 829 */ 830 @Deprecated 831 public static <T> FailableStream<T> stream(final Stream<T> stream) { 832 return failableStream(stream); 833 } 834 835 private static <T> Stream<T> streamOf(final T value) { 836 return value == null ? Stream.empty() : Stream.of(value); 837 } 838 839 /** 840 * Returns a {@link Collector} that accumulates the input elements into a new array. 841 * 842 * @param pElementType Type of an element in the array. 843 * @param <T> the type of the input elements 844 * @return a {@link Collector} which collects all the input elements into an array, in encounter order 845 */ 846 public static <T> Collector<T, ?, T[]> toArray(final Class<T> pElementType) { 847 return new ArrayCollector<>(pElementType); 848 } 849 850 /** 851 * Make private in 4.0. 852 * 853 * @deprecated TODO Make private in 4.0. 854 */ 855 @Deprecated 856 public Streams() { 857 // empty 858 } 859}