1 /* 2 * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 package java.util.stream; 26 27 import java.util.LongSummaryStatistics; 28 import java.util.OptionalDouble; 29 import java.util.OptionalLong; 30 import java.util.PrimitiveIterator; 31 import java.util.Spliterator; 32 import java.util.function.BiConsumer; 33 import java.util.function.Function; 34 import java.util.function.LongBinaryOperator; 35 import java.util.function.LongConsumer; 36 import java.util.function.LongFunction; 37 import java.util.function.LongPredicate; 38 import java.util.function.LongToDoubleFunction; 39 import java.util.function.LongToIntFunction; 40 import java.util.function.LongUnaryOperator; 41 import java.util.function.ObjLongConsumer; 42 import java.util.function.Supplier; 43 44 /** 45 * A sequence of primitive long elements supporting sequential and parallel 46 * bulk operations. Streams support lazy intermediate operations (transforming 47 * a stream to another stream) such as {@code filter} and {@code map}, and terminal 48 * operations (consuming the contents of a stream to produce a result or 49 * side-effect), such as {@code forEach}, {@code findFirst}, and {@code 50 * iterator}. Once an operation has been performed on a stream, it 51 * is considered <em>consumed</em> and no longer usable for other operations. 52 * 53 * <p>For sequential stream pipelines, all operations are performed in the 54 * <a href="package-summary.html#Ordering">encounter order</a> of the pipeline 55 * source, if the pipeline source has a defined encounter order. 56 * 57 * <p>For parallel stream pipelines, unless otherwise specified, intermediate 58 * stream operations preserve the <a href="package-summary.html#Ordering"> 59 * encounter order</a> of their source, and terminal operations 60 * respect the encounter order of their source, if the source 61 * has an encounter order. Provided that and parameters to stream operations 62 * satisfy the <a href="package-summary.html#NonInterference">non-interference 63 * requirements</a>, and excepting differences arising from the absence of 64 * a defined encounter order, the result of a stream pipeline should be the 65 * stable across multiple executions of the same operations on the same source. 66 * However, the timing and thread in which side-effects occur (for those 67 * operations which are allowed to produce side-effects, such as 68 * {@link #forEach(LongConsumer)}), are explicitly nondeterministic for parallel 69 * execution of stream pipelines. 70 * 71 * <p>Unless otherwise noted, passing a {@code null} argument to any stream 72 * method may result in a {@link NullPointerException}. 73 * 74 * @apiNote 75 * Streams are not data structures; they do not manage the storage for their 76 * elements, nor do they support access to individual elements. However, 77 * you can use the {@link #iterator()} or {@link #spliterator()} operations to 78 * perform a controlled traversal. 79 * 80 * @since 1.8 81 * @see <a href="package-summary.html">java.util.stream</a> 82 */ 83 public interface LongStream extends BaseStream<Long, LongStream> { 84 85 /** 86 * Returns a stream consisting of the elements of this stream that match 87 * the given predicate. 88 * 89 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 90 * operation</a>. 91 * 92 * @param predicate a <a href="package-summary.html#NonInterference"> 93 * non-interfering, stateless</a> predicate to apply to 94 * each element to determine if it should be included 95 * @return the new stream 96 */ 97 LongStream filter(LongPredicate predicate); 98 99 /** 100 * Returns a stream consisting of the results of applying the given 101 * function to the elements of this stream. 102 * 103 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 104 * operation</a>. 105 * 106 * @param mapper a <a href="package-summary.html#NonInterference"> 107 * non-interfering, stateless</a> function to apply to each 108 * element 109 * @return the new stream 110 */ 111 LongStream map(LongUnaryOperator mapper); 112 113 /** 114 * Returns an object-valued {@code Stream} consisting of the results of 115 * applying the given function to the elements of this stream. 116 * 117 * <p>This is an <a href="package-summary.html#StreamOps"> 118 * intermediate operation</a>. 119 * 120 * @param <U> the element type of the new stream 121 * @param mapper a <a href="package-summary.html#NonInterference"> 122 * non-interfering, stateless</a> function to apply to each 123 * element 124 * @return the new stream 125 */ 126 <U> Stream<U> mapToObj(LongFunction<? extends U> mapper); 127 128 /** 129 * Returns an {@code IntStream} consisting of the results of applying the 130 * given function to the elements of this stream. 131 * 132 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 133 * operation</a>. 134 * 135 * @param mapper a <a href="package-summary.html#NonInterference"> 136 * non-interfering, stateless</a> function to apply to each 137 * element 138 * @return the new stream 139 */ 140 IntStream mapToInt(LongToIntFunction mapper); 141 142 /** 143 * Returns a {@code DoubleStream} consisting of the results of applying the 144 * given function to the elements of this stream. 145 * 146 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 147 * operation</a>. 148 * 149 * @param mapper a <a href="package-summary.html#NonInterference"> 150 * non-interfering, stateless</a> function to apply to each 151 * element 152 * @return the new stream 153 */ 154 DoubleStream mapToDouble(LongToDoubleFunction mapper); 155 156 /** 157 * Returns a stream consisting of the results of replacing each element of 158 * this stream with the contents of the stream produced by applying the 159 * provided mapping function to each element. 160 * 161 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 162 * operation</a>. 163 * 164 * @apiNote 165 * The {@code flatMap()} operation has the effect of applying a one-to-many 166 * tranformation to the elements of the stream, and then flattening the 167 * resulting elements into a new stream. For example, if {@code orders} 168 * is a stream of purchase orders, and each purchase order contains a 169 * collection of line items, then the following produces a stream of line 170 * items: 171 * <pre>{@code 172 * orderStream.flatMap(order -> order.getLineItems().stream())... 173 * }</pre> 174 * 175 * @param mapper a <a href="package-summary.html#NonInterference"> 176 * non-interfering, stateless</a> function to apply to 177 * each element which produces an {@code LongStream} of new 178 * values 179 * @return the new stream 180 * @see Stream#flatMap(Function) 181 */ 182 LongStream flatMap(LongFunction<? extends LongStream> mapper); 183 184 /** 185 * Returns a stream consisting of the distinct elements of this stream. 186 * 187 * <p>This is a <a href="package-summary.html#StreamOps">stateful 188 * intermediate operation</a>. 189 * 190 * @return the new stream 191 */ 192 LongStream distinct(); 193 194 /** 195 * Returns a stream consisting of the elements of this stream in sorted 196 * order. 197 * 198 * <p>This is a <a href="package-summary.html#StreamOps">stateful 199 * intermediate operation</a>. 200 * 201 * @return the new stream 202 */ 203 LongStream sorted(); 204 205 /** 206 * Returns a stream consisting of the elements of this stream, additionally 207 * performing the provided action on each element as elements are consumed 208 * from the resulting stream. 209 * 210 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 211 * operation</a>. 212 * 213 * <p>For parallel stream pipelines, the action may be called at 214 * whatever time and in whatever thread the element is made available by the 215 * upstream operation. If the action modifies shared state, 216 * it is responsible for providing the required synchronization. 217 * 218 * @apiNote This method exists mainly to support debugging, where you want 219 * to see the elements as they flow past a certain point in a pipeline: 220 * <pre>{@code 221 * list.stream() 222 * .filter(filteringFunction) 223 * .peek(e -> {System.out.println("Filtered value: " + e); }); 224 * .map(mappingFunction) 225 * .peek(e -> {System.out.println("Mapped value: " + e); }); 226 * .collect(Collectors.toLongSummaryStastistics()); 227 * }</pre> 228 * 229 * @param consumer a <a href="package-summary.html#NonInterference"> 230 * non-interfering</a> action to perform on the elements as 231 * they are consumed from the stream 232 * @return the new stream 233 */ 234 LongStream peek(LongConsumer consumer); 235 236 /** 237 * Returns a stream consisting of the elements of this stream, truncated 238 * to be no longer than {@code maxSize} in length. 239 * 240 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 241 * stateful intermediate operation</a>. 242 * 243 * @param maxSize the number of elements the stream should be limited to 244 * @return the new stream 245 * @throws IllegalArgumentException if {@code maxSize} is negative 246 */ 247 LongStream limit(long maxSize); 248 249 /** 250 * Returns a stream consisting of the remaining elements of this stream 251 * after indexing {@code startInclusive} elements into the stream. If the 252 * {@code startInclusive} index lies past the end of this stream then an 253 * empty stream will be returned. 254 * 255 * <p>This is a <a href="package-summary.html#StreamOps">stateful 256 * intermediate operation</a>. 257 * 258 * @param startInclusive the number of leading elements to skip 259 * @return the new stream 260 * @throws IllegalArgumentException if {@code startInclusive} is negative 261 */ 262 LongStream substream(long startInclusive); 263 264 /** 265 * Returns a stream consisting of the remaining elements of this stream 266 * after indexing {@code startInclusive} elements into the stream and 267 * truncated to contain no more than {@code endExclusive - startInclusive} 268 * elements. If the {@code startInclusive} index lies past the end 269 * of this stream then an empty stream will be returned. 270 * 271 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 272 * stateful intermediate operation</a>. 273 * 274 * @param startInclusive the starting position of the substream, inclusive 275 * @param endExclusive the ending position of the substream, exclusive 276 * @return the new stream 277 * @throws IllegalArgumentException if {@code startInclusive} or 278 * {@code endExclusive} is negative or {@code startInclusive} is greater 279 * than {@code endExclusive} 280 */ 281 LongStream substream(long startInclusive, long endExclusive); 282 283 /** 284 * Performs an action for each element of this stream. 285 * 286 * <p>This is a <a href="package-summary.html#StreamOps">terminal 287 * operation</a>. 288 * 289 * <p>For parallel stream pipelines, this operation does <em>not</em> 290 * guarantee to respect the encounter order of the stream, as doing so 291 * would sacrifice the benefit of parallelism. For any given element, the 292 * action may be performed at whatever time and in whatever thread the 293 * library chooses. If the action accesses shared state, it is 294 * responsible for providing the required synchronization. 295 * 296 * @param action a <a href="package-summary.html#NonInterference"> 297 * non-interfering</a> action to perform on the elements 298 */ 299 void forEach(LongConsumer action); 300 301 /** 302 * Performs an action for each element of this stream, guaranteeing that 303 * each element is processed in encounter order for streams that have a 304 * defined encounter order. 305 * 306 * <p>This is a <a href="package-summary.html#StreamOps">terminal 307 * operation</a>. 308 * 309 * @param action a <a href="package-summary.html#NonInterference"> 310 * non-interfering</a> action to perform on the elements 311 * @see #forEach(LongConsumer) 312 */ 313 void forEachOrdered(LongConsumer action); 314 315 /** 316 * Returns an array containing the elements of this stream. 317 * 318 * <p>This is a <a href="package-summary.html#StreamOps">terminal 319 * operation</a>. 320 * 321 * @return an array containing the elements of this stream 322 */ 323 long[] toArray(); 324 325 /** 326 * Performs a <a href="package-summary.html#Reduction">reduction</a> on the 327 * elements of this stream, using the provided identity value and an 328 * <a href="package-summary.html#Associativity">associative</a> 329 * accumulation function, and returns the reduced value. This is equivalent 330 * to: 331 * <pre>{@code 332 * long result = identity; 333 * for (long element : this stream) 334 * result = accumulator.apply(result, element) 335 * return result; 336 * }</pre> 337 * 338 * but is not constrained to execute sequentially. 339 * 340 * <p>The {@code identity} value must be an identity for the accumulator 341 * function. This means that for all {@code x}, 342 * {@code accumulator.apply(identity, x)} is equal to {@code x}. 343 * The {@code accumulator} function must be an 344 * <a href="package-summary.html#Associativity">associative</a> function. 345 * 346 * <p>This is a <a href="package-summary.html#StreamOps">terminal 347 * operation</a>. 348 * 349 * @apiNote Sum, min, max, and average are all special cases of reduction. 350 * Summing a stream of numbers can be expressed as: 351 * 352 * <pre>{@code 353 * long sum = integers.reduce(0, (a, b) -> a+b); 354 * }</pre> 355 * 356 * or more compactly: 357 * 358 * <pre>{@code 359 * long sum = integers.reduce(0, Long::sum); 360 * }</pre> 361 * 362 * <p>While this may seem a more roundabout way to perform an aggregation 363 * compared to simply mutating a running total in a loop, reduction 364 * operations parallelize more gracefully, without needing additional 365 * synchronization and with greatly reduced risk of data races. 366 * 367 * @param identity the identity value for the accumulating function 368 * @param op an <a href="package-summary.html#Associativity">associative</a> 369 * <a href="package-summary.html#NonInterference">non-interfering, 370 * stateless</a> function for combining two values 371 * @return the result of the reduction 372 * @see #sum() 373 * @see #min() 374 * @see #max() 375 * @see #average() 376 */ 377 long reduce(long identity, LongBinaryOperator op); 378 379 /** 380 * Performs a <a href="package-summary.html#Reduction">reduction</a> on the 381 * elements of this stream, using an 382 * <a href="package-summary.html#Associativity">associative</a> accumulation 383 * function, and returns an {@code OptionalLong} describing the reduced value, 384 * if any. This is equivalent to: 385 * <pre>{@code 386 * boolean foundAny = false; 387 * long result = null; 388 * for (long element : this stream) { 389 * if (!foundAny) { 390 * foundAny = true; 391 * result = element; 392 * } 393 * else 394 * result = accumulator.apply(result, element); 395 * } 396 * return foundAny ? OptionalLong.of(result) : OptionalLong.empty(); 397 * }</pre> 398 * 399 * but is not constrained to execute sequentially. 400 * 401 * <p>The {@code accumulator} function must be an 402 * <a href="package-summary.html#Associativity">associative</a> function. 403 * 404 * <p>This is a <a href="package-summary.html#StreamOps">terminal 405 * operation</a>. 406 * 407 * @param op an <a href="package-summary.html#Associativity">associative</a> 408 * <a href="package-summary.html#NonInterference">non-interfering, 409 * stateless</a> function for combining two values 410 * @return the result of the reduction 411 * @see #reduce(long, LongBinaryOperator) 412 */ 413 OptionalLong reduce(LongBinaryOperator op); 414 415 /** 416 * Performs a <a href="package-summary.html#MutableReduction">mutable 417 * reduction</a> operation on the elements of this stream. A mutable 418 * reduction is one in which the reduced value is a mutable value holder, 419 * such as an {@code ArrayList}, and elements are incorporated by updating 420 * the state of the result, rather than by replacing the result. This 421 * produces a result equivalent to: 422 * <pre>{@code 423 * R result = resultFactory.get(); 424 * for (long element : this stream) 425 * accumulator.accept(result, element); 426 * return result; 427 * }</pre> 428 * 429 * <p>Like {@link #reduce(long, LongBinaryOperator)}, {@code collect} operations 430 * can be parallelized without requiring additional synchronization. 431 * 432 * <p>This is a <a href="package-summary.html#StreamOps">terminal 433 * operation</a>. 434 * 435 * @param <R> type of the result 436 * @param resultFactory a function that creates a new result container. 437 * For a parallel execution, this function may be 438 * called multiple times and must return a fresh value 439 * each time. 440 * @param accumulator an <a href="package-summary.html#Associativity">associative</a> 441 * <a href="package-summary.html#NonInterference">non-interfering, 442 * stateless</a> function for incorporating an additional 443 * element into a result 444 * @param combiner an <a href="package-summary.html#Associativity">associative</a> 445 * <a href="package-summary.html#NonInterference">non-interfering, 446 * stateless</a> function for combining two values, which 447 * must be compatible with the accumulator function 448 * @return the result of the reduction 449 * @see Stream#collect(Supplier, BiConsumer, BiConsumer) 450 */ 451 <R> R collect(Supplier<R> resultFactory, 452 ObjLongConsumer<R> accumulator, 453 BiConsumer<R, R> combiner); 454 455 /** 456 * Returns the sum of elements in this stream. This is a special case 457 * of a <a href="package-summary.html#MutableReduction">reduction</a> 458 * and is equivalent to: 459 * <pre>{@code 460 * return reduce(0, Long::sum); 461 * }</pre> 462 * 463 * @return the sum of elements in this stream 464 */ 465 long sum(); 466 467 /** 468 * Returns an {@code OptionalLong} describing the minimum element of this 469 * stream, or an empty optional if this stream is empty. This is a special 470 * case of a <a href="package-summary.html#MutableReduction">reduction</a> 471 * and is equivalent to: 472 * <pre>{@code 473 * return reduce(Long::min); 474 * }</pre> 475 * 476 * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. 477 * 478 479 * @return an {@code OptionalLong} containing the minimum element of this 480 * stream, or an empty {@code OptionalLong} if the stream is empty 481 */ 482 OptionalLong min(); 483 484 /** 485 * Returns an {@code OptionalLong} describing the maximum element of this 486 * stream, or an empty optional if this stream is empty. This is a special 487 * case of a <a href="package-summary.html#MutableReduction">reduction</a> 488 * and is equivalent to: 489 * <pre>{@code 490 * return reduce(Long::max); 491 * }</pre> 492 * 493 * <p>This is a <a href="package-summary.html#StreamOps">terminal 494 * operation</a>. 495 * 496 * @return an {@code OptionalLong} containing the maximum element of this 497 * stream, or an empty {@code OptionalLong} if the stream is empty 498 */ 499 OptionalLong max(); 500 501 /** 502 * Returns the count of elements in this stream. This is a special case of 503 * a <a href="package-summary.html#MutableReduction">reduction</a> and is 504 * equivalent to: 505 * <pre>{@code 506 * return map(e -> 1L).sum(); 507 * }</pre> 508 * 509 * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. 510 * 511 * @return the count of elements in this stream 512 */ 513 long count(); 514 515 /** 516 * Returns an {@code OptionalDouble} describing the average of elements of 517 * this stream, or an empty optional if this stream is empty. This is a 518 * special case of a 519 * <a href="package-summary.html#MutableReduction">reduction</a>. 520 * 521 * @return an {@code OptionalDouble} containing the average element of this 522 * stream, or an empty optional if the stream is empty 523 */ 524 OptionalDouble average(); 525 526 /** 527 * Returns a {@code LongSummaryStatistics} describing various summary data 528 * about the elements of this stream. This is a special case of a 529 * <a href="package-summary.html#MutableReduction">reduction</a>. 530 * 531 * @return a {@code LongSummaryStatistics} describing various summary data 532 * about the elements of this stream 533 */ 534 LongSummaryStatistics summaryStatistics(); 535 536 /** 537 * Returns whether any elements of this stream match the provided 538 * predicate. May not evaluate the predicate on all elements if not 539 * necessary for determining the result. 540 * 541 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 542 * terminal operation</a>. 543 * 544 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering, 545 * stateless</a> predicate to apply to elements of this 546 * stream 547 * @return {@code true} if any elements of the stream match the provided 548 * predicate otherwise {@code false} 549 */ 550 boolean anyMatch(LongPredicate predicate); 551 552 /** 553 * Returns whether all elements of this stream match the provided predicate. 554 * May not evaluate the predicate on all elements if not necessary for 555 * determining the result. 556 * 557 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 558 * terminal operation</a>. 559 * 560 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering, 561 * stateless</a> predicate to apply to elements of this 562 * stream 563 * @return {@code true} if all elements of the stream match the provided 564 * predicate otherwise {@code false} 565 */ 566 boolean allMatch(LongPredicate predicate); 567 568 /** 569 * Returns whether no elements of this stream match the provided predicate. 570 * May not evaluate the predicate on all elements if not necessary for 571 * determining the result. 572 * 573 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 574 * terminal operation</a>. 575 * 576 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering, 577 * stateless</a> predicate to apply to elements of this 578 * stream 579 * @return {@code true} if no elements of the stream match the provided 580 * predicate otherwise {@code false} 581 */ 582 boolean noneMatch(LongPredicate predicate); 583 584 /** 585 * Returns an {@link OptionalLong} describing the first element of this 586 * stream (in the encounter order), or an empty {@code OptionalLong} if the 587 * stream is empty. If the stream has no encounter order, than any element 588 * may be returned. 589 * 590 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 591 * terminal operation</a>. 592 * 593 * @return an {@code OptionalLong} describing the first element of this 594 * stream, or an empty {@code OptionalLong} if the stream is empty 595 */ 596 OptionalLong findFirst(); 597 598 /** 599 * Returns an {@link OptionalLong} describing some element of the stream, or 600 * an empty {@code OptionalLong} if the stream is empty. 601 * 602 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 603 * terminal operation</a>. 604 * 605 * <p>The behavior of this operation is explicitly nondeterministic; it is 606 * free to select any element in the stream. This is to allow for maximal 607 * performance in parallel operations; the cost is that multiple invocations 608 * on the same source may not return the same result. (If the first element 609 * in the encounter order is desired, use {@link #findFirst()} instead.) 610 * 611 * @return an {@code OptionalLong} describing some element of this stream, 612 * or an empty {@code OptionalLong} if the stream is empty 613 * @see #findFirst() 614 */ 615 OptionalLong findAny(); 616 617 /** 618 * Returns a {@code DoubleStream} consisting of the elements of this stream, 619 * converted to {@code double}. 620 * 621 * @return a {@code DoubleStream} consisting of the elements of this stream, 622 * converted to {@code double} 623 */ 624 DoubleStream doubles(); 625 626 /** 627 * Returns a {@code Stream} consisting of the elements of this stream, 628 * each boxed to a {@code Long}. 629 * 630 * @return a {@code Stream} consistent of the elements of this stream, 631 * each boxed to {@code Long} 632 */ 633 Stream<Long> boxed(); 634 635 @Override 636 LongStream sequential(); 637 638 @Override 639 LongStream parallel(); 640 641 @Override 642 PrimitiveIterator.OfLong iterator(); 643 644 @Override 645 Spliterator.OfLong spliterator(); 646 }