1 /* 2 * Copyright (c) 2012, 2016, 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.Arrays; 28 import java.util.DoubleSummaryStatistics; 29 import java.util.Objects; 30 import java.util.OptionalDouble; 31 import java.util.PrimitiveIterator; 32 import java.util.Spliterator; 33 import java.util.Spliterators; 34 import java.util.function.BiConsumer; 35 import java.util.function.DoubleBinaryOperator; 36 import java.util.function.DoubleConsumer; 37 import java.util.function.DoubleFunction; 38 import java.util.function.DoublePredicate; 39 import java.util.function.DoubleSupplier; 40 import java.util.function.DoubleToIntFunction; 41 import java.util.function.DoubleToLongFunction; 42 import java.util.function.DoubleUnaryOperator; 43 import java.util.function.Function; 44 import java.util.function.ObjDoubleConsumer; 45 import java.util.function.Supplier; 46 47 /** 48 * A sequence of primitive double-valued elements supporting sequential and parallel 49 * aggregate operations. This is the {@code double} primitive specialization of 50 * {@link Stream}. 51 * 52 * <p>The following example illustrates an aggregate operation using 53 * {@link Stream} and {@link DoubleStream}, computing the sum of the weights of the 54 * red widgets: 55 * 56 * <pre>{@code 57 * double sum = widgets.stream() 58 * .filter(w -> w.getColor() == RED) 59 * .mapToDouble(w -> w.getWeight()) 60 * .sum(); 61 * }</pre> 62 * 63 * See the class documentation for {@link Stream} and the package documentation 64 * for <a href="package-summary.html">java.util.stream</a> for additional 65 * specification of streams, stream operations, stream pipelines, and 66 * parallelism. 67 * 68 * @since 1.8 69 * @see Stream 70 * @see <a href="package-summary.html">java.util.stream</a> 71 */ 72 public interface DoubleStream extends BaseStream<Double, DoubleStream> { 73 74 /** 75 * Returns a stream consisting of the elements of this stream that match 76 * the given predicate. 77 * 78 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 79 * operation</a>. 80 * 81 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>, 82 * <a href="package-summary.html#Statelessness">stateless</a> 83 * predicate to apply to each element to determine if it 84 * should be included 85 * @return the new stream 86 */ 87 DoubleStream filter(DoublePredicate predicate); 88 89 /** 90 * Returns a stream consisting of the results of applying the given 91 * function to the elements of this stream. 92 * 93 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 94 * operation</a>. 95 * 96 * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>, 97 * <a href="package-summary.html#Statelessness">stateless</a> 98 * function to apply to each element 99 * @return the new stream 100 */ 101 DoubleStream map(DoubleUnaryOperator mapper); 102 103 /** 104 * Returns an object-valued {@code Stream} consisting of the results of 105 * applying the given function to the elements of this stream. 106 * 107 * <p>This is an <a href="package-summary.html#StreamOps"> 108 * intermediate operation</a>. 109 * 110 * @param <U> the element type of the new stream 111 * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>, 112 * <a href="package-summary.html#Statelessness">stateless</a> 113 * function to apply to each element 114 * @return the new stream 115 */ 116 <U> Stream<U> mapToObj(DoubleFunction<? extends U> mapper); 117 118 /** 119 * Returns an {@code IntStream} consisting of the results of applying the 120 * given function to the elements of this stream. 121 * 122 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 123 * operation</a>. 124 * 125 * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>, 126 * <a href="package-summary.html#Statelessness">stateless</a> 127 * function to apply to each element 128 * @return the new stream 129 */ 130 IntStream mapToInt(DoubleToIntFunction mapper); 131 132 /** 133 * Returns a {@code LongStream} consisting of the results of applying the 134 * given function to the elements of this stream. 135 * 136 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 137 * operation</a>. 138 * 139 * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>, 140 * <a href="package-summary.html#Statelessness">stateless</a> 141 * function to apply to each element 142 * @return the new stream 143 */ 144 LongStream mapToLong(DoubleToLongFunction mapper); 145 146 /** 147 * Returns a stream consisting of the results of replacing each element of 148 * this stream with the contents of a mapped stream produced by applying 149 * the provided mapping function to each element. Each mapped stream is 150 * {@link java.util.stream.BaseStream#close() closed} after its contents 151 * have been placed into this stream. (If a mapped stream is {@code null} 152 * an empty stream is used, instead.) 153 * 154 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 155 * operation</a>. 156 * 157 * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>, 158 * <a href="package-summary.html#Statelessness">stateless</a> 159 * function to apply to each element which produces a 160 * {@code DoubleStream} of new values 161 * @return the new stream 162 * @see Stream#flatMap(Function) 163 */ 164 DoubleStream flatMap(DoubleFunction<? extends DoubleStream> mapper); 165 166 /** 167 * Returns a stream consisting of the distinct elements of this stream. The 168 * elements are compared for equality according to 169 * {@link java.lang.Double#compare(double, double)}. 170 * 171 * <p>This is a <a href="package-summary.html#StreamOps">stateful 172 * intermediate operation</a>. 173 * 174 * @return the result stream 175 */ 176 DoubleStream distinct(); 177 178 /** 179 * Returns a stream consisting of the elements of this stream in sorted 180 * order. The elements are compared for equality according to 181 * {@link java.lang.Double#compare(double, double)}. 182 * 183 * <p>This is a <a href="package-summary.html#StreamOps">stateful 184 * intermediate operation</a>. 185 * 186 * @return the result stream 187 */ 188 DoubleStream sorted(); 189 190 /** 191 * Returns a stream consisting of the elements of this stream, additionally 192 * performing the provided action on each element as elements are consumed 193 * from the resulting stream. 194 * 195 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 196 * operation</a>. 197 * 198 * <p>For parallel stream pipelines, the action may be called at 199 * whatever time and in whatever thread the element is made available by the 200 * upstream operation. If the action modifies shared state, 201 * it is responsible for providing the required synchronization. 202 * 203 * @apiNote This method exists mainly to support debugging, where you want 204 * to see the elements as they flow past a certain point in a pipeline: 205 * <pre>{@code 206 * DoubleStream.of(1, 2, 3, 4) 207 * .filter(e -> e > 2) 208 * .peek(e -> System.out.println("Filtered value: " + e)) 209 * .map(e -> e * e) 210 * .peek(e -> System.out.println("Mapped value: " + e)) 211 * .sum(); 212 * }</pre> 213 * 214 * <p>In cases where the stream implementation is able to optimize away the 215 * production of some or all the elements (such as with short-circuiting 216 * operations like {@code findFirst}, or in the example described in 217 * {@link #count}), the action will not be invoked for those elements. 218 * 219 * @param action a <a href="package-summary.html#NonInterference"> 220 * non-interfering</a> action to perform on the elements as 221 * they are consumed from the stream 222 * @return the new stream 223 */ 224 DoubleStream peek(DoubleConsumer action); 225 226 /** 227 * Returns a stream consisting of the elements of this stream, truncated 228 * to be no longer than {@code maxSize} in length. 229 * 230 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 231 * stateful intermediate operation</a>. 232 * 233 * @apiNote 234 * While {@code limit()} is generally a cheap operation on sequential 235 * stream pipelines, it can be quite expensive on ordered parallel pipelines, 236 * especially for large values of {@code maxSize}, since {@code limit(n)} 237 * is constrained to return not just any <em>n</em> elements, but the 238 * <em>first n</em> elements in the encounter order. Using an unordered 239 * stream source (such as {@link #generate(DoubleSupplier)}) or removing the 240 * ordering constraint with {@link #unordered()} may result in significant 241 * speedups of {@code limit()} in parallel pipelines, if the semantics of 242 * your situation permit. If consistency with encounter order is required, 243 * and you are experiencing poor performance or memory utilization with 244 * {@code limit()} in parallel pipelines, switching to sequential execution 245 * with {@link #sequential()} may improve performance. 246 * 247 * @param maxSize the number of elements the stream should be limited to 248 * @return the new stream 249 * @throws IllegalArgumentException if {@code maxSize} is negative 250 */ 251 DoubleStream limit(long maxSize); 252 253 /** 254 * Returns a stream consisting of the remaining elements of this stream 255 * after discarding the first {@code n} elements of the stream. 256 * If this stream contains fewer than {@code n} elements then an 257 * empty stream will be returned. 258 * 259 * <p>This is a <a href="package-summary.html#StreamOps">stateful 260 * intermediate operation</a>. 261 * 262 * @apiNote 263 * While {@code skip()} is generally a cheap operation on sequential 264 * stream pipelines, it can be quite expensive on ordered parallel pipelines, 265 * especially for large values of {@code n}, since {@code skip(n)} 266 * is constrained to skip not just any <em>n</em> elements, but the 267 * <em>first n</em> elements in the encounter order. Using an unordered 268 * stream source (such as {@link #generate(DoubleSupplier)}) or removing the 269 * ordering constraint with {@link #unordered()} may result in significant 270 * speedups of {@code skip()} in parallel pipelines, if the semantics of 271 * your situation permit. If consistency with encounter order is required, 272 * and you are experiencing poor performance or memory utilization with 273 * {@code skip()} in parallel pipelines, switching to sequential execution 274 * with {@link #sequential()} may improve performance. 275 * 276 * @param n the number of leading elements to skip 277 * @return the new stream 278 * @throws IllegalArgumentException if {@code n} is negative 279 */ 280 DoubleStream skip(long n); 281 282 /** 283 * Returns, if this stream is ordered, a stream consisting of the longest 284 * prefix of elements taken from this stream that match the given predicate. 285 * Otherwise returns, if this stream is unordered, a stream consisting of a 286 * subset of elements taken from this stream that match the given predicate. 287 * 288 * <p>If this stream is ordered then the longest prefix is a contiguous 289 * sequence of elements of this stream that match the given predicate. The 290 * first element of the sequence is the first element of this stream, and 291 * the element immediately following the last element of the sequence does 292 * not match the given predicate. 293 * 294 * <p>If this stream is unordered, and some (but not all) elements of this 295 * stream match the given predicate, then the behavior of this operation is 296 * nondeterministic; it is free to take any subset of matching elements 297 * (which includes the empty set). 298 * 299 * <p>Independent of whether this stream is ordered or unordered if all 300 * elements of this stream match the given predicate then this operation 301 * takes all elements (the result is the same as the input), or if no 302 * elements of the stream match the given predicate then no elements are 303 * taken (the result is an empty stream). 304 * 305 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 306 * stateful intermediate operation</a>. 307 * 308 * @implSpec 309 * The default implementation obtains the {@link #spliterator() spliterator} 310 * of this stream, wraps that spliterator so as to support the semantics 311 * of this operation on traversal, and returns a new stream associated with 312 * the wrapped spliterator. The returned stream preserves the execution 313 * characteristics of this stream (namely parallel or sequential execution 314 * as per {@link #isParallel()}) but the wrapped spliterator may choose to 315 * not support splitting. When the returned stream is closed, the close 316 * handlers for both the returned and this stream are invoked. 317 * 318 * @apiNote 319 * While {@code takeWhile()} is generally a cheap operation on sequential 320 * stream pipelines, it can be quite expensive on ordered parallel 321 * pipelines, since the operation is constrained to return not just any 322 * valid prefix, but the longest prefix of elements in the encounter order. 323 * Using an unordered stream source (such as 324 * {@link #generate(DoubleSupplier)}) or removing the ordering constraint 325 * with {@link #unordered()} may result in significant speedups of 326 * {@code takeWhile()} in parallel pipelines, if the semantics of your 327 * situation permit. If consistency with encounter order is required, and 328 * you are experiencing poor performance or memory utilization with 329 * {@code takeWhile()} in parallel pipelines, switching to sequential 330 * execution with {@link #sequential()} may improve performance. 331 * 332 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>, 333 * <a href="package-summary.html#Statelessness">stateless</a> 334 * predicate to apply to elements to determine the longest 335 * prefix of elements. 336 * @return the new stream 337 * @since 9 338 */ 339 default DoubleStream takeWhile(DoublePredicate predicate) { 340 Objects.requireNonNull(predicate); 341 // Reuses the unordered spliterator, which, when encounter is present, 342 // is safe to use as long as it configured not to split 343 return StreamSupport.doubleStream( 344 new WhileOps.UnorderedWhileSpliterator.OfDouble.Taking(spliterator(), true, predicate), 345 isParallel()).onClose(this::close); 346 } 347 348 /** 349 * Returns, if this stream is ordered, a stream consisting of the remaining 350 * elements of this stream after dropping the longest prefix of elements 351 * that match the given predicate. Otherwise returns, if this stream is 352 * unordered, a stream consisting of the remaining elements of this stream 353 * after dropping a subset of elements that match the given predicate. 354 * 355 * <p>If this stream is ordered then the longest prefix is a contiguous 356 * sequence of elements of this stream that match the given predicate. The 357 * first element of the sequence is the first element of this stream, and 358 * the element immediately following the last element of the sequence does 359 * not match the given predicate. 360 * 361 * <p>If this stream is unordered, and some (but not all) elements of this 362 * stream match the given predicate, then the behavior of this operation is 363 * nondeterministic; it is free to drop any subset of matching elements 364 * (which includes the empty set). 365 * 366 * <p>Independent of whether this stream is ordered or unordered if all 367 * elements of this stream match the given predicate then this operation 368 * drops all elements (the result is an empty stream), or if no elements of 369 * the stream match the given predicate then no elements are dropped (the 370 * result is the same as the input). 371 * 372 * <p>This is a <a href="package-summary.html#StreamOps">stateful 373 * intermediate operation</a>. 374 * 375 * @implSpec 376 * The default implementation obtains the {@link #spliterator() spliterator} 377 * of this stream, wraps that spliterator so as to support the semantics 378 * of this operation on traversal, and returns a new stream associated with 379 * the wrapped spliterator. The returned stream preserves the execution 380 * characteristics of this stream (namely parallel or sequential execution 381 * as per {@link #isParallel()}) but the wrapped spliterator may choose to 382 * not support splitting. When the returned stream is closed, the close 383 * handlers for both the returned and this stream are invoked. 384 * 385 * @apiNote 386 * While {@code dropWhile()} is generally a cheap operation on sequential 387 * stream pipelines, it can be quite expensive on ordered parallel 388 * pipelines, since the operation is constrained to return not just any 389 * valid prefix, but the longest prefix of elements in the encounter order. 390 * Using an unordered stream source (such as 391 * {@link #generate(DoubleSupplier)}) or removing the ordering constraint 392 * with {@link #unordered()} may result in significant speedups of 393 * {@code dropWhile()} in parallel pipelines, if the semantics of your 394 * situation permit. If consistency with encounter order is required, and 395 * you are experiencing poor performance or memory utilization with 396 * {@code dropWhile()} in parallel pipelines, switching to sequential 397 * execution with {@link #sequential()} may improve performance. 398 * 399 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>, 400 * <a href="package-summary.html#Statelessness">stateless</a> 401 * predicate to apply to elements to determine the longest 402 * prefix of elements. 403 * @return the new stream 404 * @since 9 405 */ 406 default DoubleStream dropWhile(DoublePredicate predicate) { 407 Objects.requireNonNull(predicate); 408 // Reuses the unordered spliterator, which, when encounter is present, 409 // is safe to use as long as it configured not to split 410 return StreamSupport.doubleStream( 411 new WhileOps.UnorderedWhileSpliterator.OfDouble.Dropping(spliterator(), true, predicate), 412 isParallel()).onClose(this::close); 413 } 414 415 /** 416 * Performs an action for each element of this stream. 417 * 418 * <p>This is a <a href="package-summary.html#StreamOps">terminal 419 * operation</a>. 420 * 421 * <p>For parallel stream pipelines, this operation does <em>not</em> 422 * guarantee to respect the encounter order of the stream, as doing so 423 * would sacrifice the benefit of parallelism. For any given element, the 424 * action may be performed at whatever time and in whatever thread the 425 * library chooses. If the action accesses shared state, it is 426 * responsible for providing the required synchronization. 427 * 428 * @param action a <a href="package-summary.html#NonInterference"> 429 * non-interfering</a> action to perform on the elements 430 */ 431 void forEach(DoubleConsumer action); 432 433 /** 434 * Performs an action for each element of this stream, guaranteeing that 435 * each element is processed in encounter order for streams that have a 436 * defined encounter order. 437 * 438 * <p>This is a <a href="package-summary.html#StreamOps">terminal 439 * operation</a>. 440 * 441 * @param action a <a href="package-summary.html#NonInterference"> 442 * non-interfering</a> action to perform on the elements 443 * @see #forEach(DoubleConsumer) 444 */ 445 void forEachOrdered(DoubleConsumer action); 446 447 /** 448 * Returns an array containing the elements of this stream. 449 * 450 * <p>This is a <a href="package-summary.html#StreamOps">terminal 451 * operation</a>. 452 * 453 * @return an array containing the elements of this stream 454 */ 455 double[] toArray(); 456 457 /** 458 * Performs a <a href="package-summary.html#Reduction">reduction</a> on the 459 * elements of this stream, using the provided identity value and an 460 * <a href="package-summary.html#Associativity">associative</a> 461 * accumulation function, and returns the reduced value. This is equivalent 462 * to: 463 * <pre>{@code 464 * double result = identity; 465 * for (double element : this stream) 466 * result = accumulator.applyAsDouble(result, element) 467 * return result; 468 * }</pre> 469 * 470 * but is not constrained to execute sequentially. 471 * 472 * <p>The {@code identity} value must be an identity for the accumulator 473 * function. This means that for all {@code x}, 474 * {@code accumulator.apply(identity, x)} is equal to {@code x}. 475 * The {@code accumulator} function must be an 476 * <a href="package-summary.html#Associativity">associative</a> function. 477 * 478 * <p>This is a <a href="package-summary.html#StreamOps">terminal 479 * operation</a>. 480 * 481 * @apiNote Sum, min, max, and average are all special cases of reduction. 482 * Summing a stream of numbers can be expressed as: 483 484 * <pre>{@code 485 * double sum = numbers.reduce(0, (a, b) -> a+b); 486 * }</pre> 487 * 488 * or more compactly: 489 * 490 * <pre>{@code 491 * double sum = numbers.reduce(0, Double::sum); 492 * }</pre> 493 * 494 * <p>While this may seem a more roundabout way to perform an aggregation 495 * compared to simply mutating a running total in a loop, reduction 496 * operations parallelize more gracefully, without needing additional 497 * synchronization and with greatly reduced risk of data races. 498 * 499 * @param identity the identity value for the accumulating function 500 * @param op an <a href="package-summary.html#Associativity">associative</a>, 501 * <a href="package-summary.html#NonInterference">non-interfering</a>, 502 * <a href="package-summary.html#Statelessness">stateless</a> 503 * function for combining two values 504 * @return the result of the reduction 505 * @see #sum() 506 * @see #min() 507 * @see #max() 508 * @see #average() 509 */ 510 double reduce(double identity, DoubleBinaryOperator op); 511 512 /** 513 * Performs a <a href="package-summary.html#Reduction">reduction</a> on the 514 * elements of this stream, using an 515 * <a href="package-summary.html#Associativity">associative</a> accumulation 516 * function, and returns an {@code OptionalDouble} describing the reduced 517 * value, if any. This is equivalent to: 518 * <pre>{@code 519 * boolean foundAny = false; 520 * double result = null; 521 * for (double element : this stream) { 522 * if (!foundAny) { 523 * foundAny = true; 524 * result = element; 525 * } 526 * else 527 * result = accumulator.applyAsDouble(result, element); 528 * } 529 * return foundAny ? OptionalDouble.of(result) : OptionalDouble.empty(); 530 * }</pre> 531 * 532 * but is not constrained to execute sequentially. 533 * 534 * <p>The {@code accumulator} function must be an 535 * <a href="package-summary.html#Associativity">associative</a> function. 536 * 537 * <p>This is a <a href="package-summary.html#StreamOps">terminal 538 * operation</a>. 539 * 540 * @param op an <a href="package-summary.html#Associativity">associative</a>, 541 * <a href="package-summary.html#NonInterference">non-interfering</a>, 542 * <a href="package-summary.html#Statelessness">stateless</a> 543 * function for combining two values 544 * @return the result of the reduction 545 * @see #reduce(double, DoubleBinaryOperator) 546 */ 547 OptionalDouble reduce(DoubleBinaryOperator op); 548 549 /** 550 * Performs a <a href="package-summary.html#MutableReduction">mutable 551 * reduction</a> operation on the elements of this stream. A mutable 552 * reduction is one in which the reduced value is a mutable result container, 553 * such as an {@code ArrayList}, and elements are incorporated by updating 554 * the state of the result rather than by replacing the result. This 555 * produces a result equivalent to: 556 * <pre>{@code 557 * R result = supplier.get(); 558 * for (double element : this stream) 559 * accumulator.accept(result, element); 560 * return result; 561 * }</pre> 562 * 563 * <p>Like {@link #reduce(double, DoubleBinaryOperator)}, {@code collect} 564 * operations can be parallelized without requiring additional 565 * synchronization. 566 * 567 * <p>This is a <a href="package-summary.html#StreamOps">terminal 568 * operation</a>. 569 * 570 * @param <R> the type of the mutable result container 571 * @param supplier a function that creates a new mutable result container. 572 * For a parallel execution, this function may be called 573 * multiple times and must return a fresh value each time. 574 * @param accumulator an <a href="package-summary.html#Associativity">associative</a>, 575 * <a href="package-summary.html#NonInterference">non-interfering</a>, 576 * <a href="package-summary.html#Statelessness">stateless</a> 577 * function that must fold an element into a result 578 * container. 579 * @param combiner an <a href="package-summary.html#Associativity">associative</a>, 580 * <a href="package-summary.html#NonInterference">non-interfering</a>, 581 * <a href="package-summary.html#Statelessness">stateless</a> 582 * function that accepts two partial result containers 583 * and merges them, which must be compatible with the 584 * accumulator function. The combiner function must fold 585 * the elements from the second result container into the 586 * first result container. 587 * @return the result of the reduction 588 * @see Stream#collect(Supplier, BiConsumer, BiConsumer) 589 */ 590 <R> R collect(Supplier<R> supplier, 591 ObjDoubleConsumer<R> accumulator, 592 BiConsumer<R, R> combiner); 593 594 /** 595 * Returns the sum of elements in this stream. 596 * 597 * Summation is a special case of a <a 598 * href="package-summary.html#Reduction">reduction</a>. If 599 * floating-point summation were exact, this method would be 600 * equivalent to: 601 * 602 * <pre>{@code 603 * return reduce(0, Double::sum); 604 * }</pre> 605 * 606 * However, since floating-point summation is not exact, the above 607 * code is not necessarily equivalent to the summation computation 608 * done by this method. 609 * 610 * <p>The value of a floating-point sum is a function both 611 * of the input values as well as the order of addition 612 * operations. The order of addition operations of this method is 613 * intentionally not defined to allow for implementation 614 * flexibility to improve the speed and accuracy of the computed 615 * result. 616 * 617 * In particular, this method may be implemented using compensated 618 * summation or other technique to reduce the error bound in the 619 * numerical sum compared to a simple summation of {@code double} 620 * values. 621 * 622 * Because of the unspecified order of operations and the 623 * possibility of using differing summation schemes, the output of 624 * this method may vary on the same input elements. 625 * 626 * <p>Various conditions can result in a non-finite sum being 627 * computed. This can occur even if the all the elements 628 * being summed are finite. If any element is non-finite, 629 * the sum will be non-finite: 630 * 631 * <ul> 632 * 633 * <li>If any element is a NaN, then the final sum will be 634 * NaN. 635 * 636 * <li>If the elements contain one or more infinities, the 637 * sum will be infinite or NaN. 638 * 639 * <ul> 640 * 641 * <li>If the elements contain infinities of opposite sign, 642 * the sum will be NaN. 643 * 644 * <li>If the elements contain infinities of one sign and 645 * an intermediate sum overflows to an infinity of the opposite 646 * sign, the sum may be NaN. 647 * 648 * </ul> 649 * 650 * </ul> 651 * 652 * It is possible for intermediate sums of finite values to 653 * overflow into opposite-signed infinities; if that occurs, the 654 * final sum will be NaN even if the elements are all 655 * finite. 656 * 657 * If all the elements are zero, the sign of zero is 658 * <em>not</em> guaranteed to be preserved in the final sum. 659 * 660 * <p>This is a <a href="package-summary.html#StreamOps">terminal 661 * operation</a>. 662 * 663 * @apiNote Elements sorted by increasing absolute magnitude tend 664 * to yield more accurate results. 665 * 666 * @return the sum of elements in this stream 667 */ 668 double sum(); 669 670 /** 671 * Returns an {@code OptionalDouble} describing the minimum element of this 672 * stream, or an empty OptionalDouble if this stream is empty. The minimum 673 * element will be {@code Double.NaN} if any stream element was NaN. Unlike 674 * the numerical comparison operators, this method considers negative zero 675 * to be strictly smaller than positive zero. This is a special case of a 676 * <a href="package-summary.html#Reduction">reduction</a> and is 677 * equivalent to: 678 * <pre>{@code 679 * return reduce(Double::min); 680 * }</pre> 681 * 682 * <p>This is a <a href="package-summary.html#StreamOps">terminal 683 * operation</a>. 684 * 685 * @return an {@code OptionalDouble} containing the minimum element of this 686 * stream, or an empty optional if the stream is empty 687 */ 688 OptionalDouble min(); 689 690 /** 691 * Returns an {@code OptionalDouble} describing the maximum element of this 692 * stream, or an empty OptionalDouble if this stream is empty. The maximum 693 * element will be {@code Double.NaN} if any stream element was NaN. Unlike 694 * the numerical comparison operators, this method considers negative zero 695 * to be strictly smaller than positive zero. This is a 696 * special case of a 697 * <a href="package-summary.html#Reduction">reduction</a> and is 698 * equivalent to: 699 * <pre>{@code 700 * return reduce(Double::max); 701 * }</pre> 702 * 703 * <p>This is a <a href="package-summary.html#StreamOps">terminal 704 * operation</a>. 705 * 706 * @return an {@code OptionalDouble} containing the maximum element of this 707 * stream, or an empty optional if the stream is empty 708 */ 709 OptionalDouble max(); 710 711 /** 712 * Returns the count of elements in this stream. This is a special case of 713 * a <a href="package-summary.html#Reduction">reduction</a> and is 714 * equivalent to: 715 * <pre>{@code 716 * return mapToLong(e -> 1L).sum(); 717 * }</pre> 718 * 719 * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. 720 * 721 * @apiNote 722 * An implementation may choose to not execute the stream pipeline (either 723 * sequentially or in parallel) if it is capable of computing the count 724 * directly from the stream source. In such cases no source elements will 725 * be traversed and no intermediate operations will be evaluated. 726 * Behavioral parameters with side-effects, which are strongly discouraged 727 * except for harmless cases such as debugging, may be affected. For 728 * example, consider the following stream: 729 * <pre>{@code 730 * DoubleStream s = DoubleStream.of(1, 2, 3, 4); 731 * long count = s.peek(System.out::println).count(); 732 * }</pre> 733 * The number of elements covered by the stream source is known and the 734 * intermediate operation, {@code peek}, does not inject into or remove 735 * elements from the stream (as may be the case for {@code flatMap} or 736 * {@code filter} operations). Thus the count is 4 and there is no need to 737 * execute the pipeline and, as a side-effect, print out the elements. 738 * 739 * @return the count of elements in this stream 740 */ 741 long count(); 742 743 /** 744 * Returns an {@code OptionalDouble} describing the arithmetic 745 * mean of elements of this stream, or an empty optional if this 746 * stream is empty. 747 * 748 * <p>The computed average can vary numerically and have the 749 * special case behavior as computing the sum; see {@link #sum} 750 * for details. 751 * 752 * <p>The average is a special case of a <a 753 * href="package-summary.html#Reduction">reduction</a>. 754 * 755 * <p>This is a <a href="package-summary.html#StreamOps">terminal 756 * operation</a>. 757 * 758 * @apiNote Elements sorted by increasing absolute magnitude tend 759 * to yield more accurate results. 760 * 761 * @return an {@code OptionalDouble} containing the average element of this 762 * stream, or an empty optional if the stream is empty 763 */ 764 OptionalDouble average(); 765 766 /** 767 * Returns a {@code DoubleSummaryStatistics} describing various summary data 768 * about the elements of this stream. This is a special 769 * case of a <a href="package-summary.html#Reduction">reduction</a>. 770 * 771 * <p>This is a <a href="package-summary.html#StreamOps">terminal 772 * operation</a>. 773 * 774 * @return a {@code DoubleSummaryStatistics} describing various summary data 775 * about the elements of this stream 776 */ 777 DoubleSummaryStatistics summaryStatistics(); 778 779 /** 780 * Returns whether any elements of this stream match the provided 781 * predicate. May not evaluate the predicate on all elements if not 782 * necessary for determining the result. If the stream is empty then 783 * {@code false} is returned and the predicate is not evaluated. 784 * 785 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 786 * terminal operation</a>. 787 * 788 * @apiNote 789 * This method evaluates the <em>existential quantification</em> of the 790 * predicate over the elements of the stream (for some x P(x)). 791 * 792 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>, 793 * <a href="package-summary.html#Statelessness">stateless</a> 794 * predicate to apply to elements of this stream 795 * @return {@code true} if any elements of the stream match the provided 796 * predicate, otherwise {@code false} 797 */ 798 boolean anyMatch(DoublePredicate predicate); 799 800 /** 801 * Returns whether all elements of this stream match the provided predicate. 802 * May not evaluate the predicate on all elements if not necessary for 803 * determining the result. If the stream is empty then {@code true} is 804 * returned and the predicate is not evaluated. 805 * 806 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 807 * terminal operation</a>. 808 * 809 * @apiNote 810 * This method evaluates the <em>universal quantification</em> of the 811 * predicate over the elements of the stream (for all x P(x)). If the 812 * stream is empty, the quantification is said to be <em>vacuously 813 * satisfied</em> and is always {@code true} (regardless of P(x)). 814 * 815 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>, 816 * <a href="package-summary.html#Statelessness">stateless</a> 817 * predicate to apply to elements of this stream 818 * @return {@code true} if either all elements of the stream match the 819 * provided predicate or the stream is empty, otherwise {@code false} 820 */ 821 boolean allMatch(DoublePredicate predicate); 822 823 /** 824 * Returns whether no elements of this stream match the provided predicate. 825 * May not evaluate the predicate on all elements if not necessary for 826 * determining the result. If the stream is empty then {@code true} is 827 * returned and the predicate is not evaluated. 828 * 829 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 830 * terminal operation</a>. 831 * 832 * @apiNote 833 * This method evaluates the <em>universal quantification</em> of the 834 * negated predicate over the elements of the stream (for all x ~P(x)). If 835 * the stream is empty, the quantification is said to be vacuously satisfied 836 * and is always {@code true}, regardless of P(x). 837 * 838 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>, 839 * <a href="package-summary.html#Statelessness">stateless</a> 840 * predicate to apply to elements of this stream 841 * @return {@code true} if either no elements of the stream match the 842 * provided predicate or the stream is empty, otherwise {@code false} 843 */ 844 boolean noneMatch(DoublePredicate predicate); 845 846 /** 847 * Returns an {@link OptionalDouble} describing the first element of this 848 * stream, or an empty {@code OptionalDouble} if the stream is empty. If 849 * the stream has no encounter order, then any element may be returned. 850 * 851 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 852 * terminal operation</a>. 853 * 854 * @return an {@code OptionalDouble} describing the first element of this 855 * stream, or an empty {@code OptionalDouble} if the stream is empty 856 */ 857 OptionalDouble findFirst(); 858 859 /** 860 * Returns an {@link OptionalDouble} describing some element of the stream, 861 * or an empty {@code OptionalDouble} if the stream is empty. 862 * 863 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 864 * terminal operation</a>. 865 * 866 * <p>The behavior of this operation is explicitly nondeterministic; it is 867 * free to select any element in the stream. This is to allow for maximal 868 * performance in parallel operations; the cost is that multiple invocations 869 * on the same source may not return the same result. (If a stable result 870 * is desired, use {@link #findFirst()} instead.) 871 * 872 * @return an {@code OptionalDouble} describing some element of this stream, 873 * or an empty {@code OptionalDouble} if the stream is empty 874 * @see #findFirst() 875 */ 876 OptionalDouble findAny(); 877 878 /** 879 * Returns a {@code Stream} consisting of the elements of this stream, 880 * boxed to {@code Double}. 881 * 882 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 883 * operation</a>. 884 * 885 * @return a {@code Stream} consistent of the elements of this stream, 886 * each boxed to a {@code Double} 887 */ 888 Stream<Double> boxed(); 889 890 @Override 891 DoubleStream sequential(); 892 893 @Override 894 DoubleStream parallel(); 895 896 @Override 897 PrimitiveIterator.OfDouble iterator(); 898 899 @Override 900 Spliterator.OfDouble spliterator(); 901 902 903 // Static factories 904 905 /** 906 * Returns a builder for a {@code DoubleStream}. 907 * 908 * @return a stream builder 909 */ 910 public static Builder builder() { 911 return new Streams.DoubleStreamBuilderImpl(); 912 } 913 914 /** 915 * Returns an empty sequential {@code DoubleStream}. 916 * 917 * @return an empty sequential stream 918 */ 919 public static DoubleStream empty() { 920 return StreamSupport.doubleStream(Spliterators.emptyDoubleSpliterator(), false); 921 } 922 923 /** 924 * Returns a sequential {@code DoubleStream} containing a single element. 925 * 926 * @param t the single element 927 * @return a singleton sequential stream 928 */ 929 public static DoubleStream of(double t) { 930 return StreamSupport.doubleStream(new Streams.DoubleStreamBuilderImpl(t), false); 931 } 932 933 /** 934 * Returns a sequential ordered stream whose elements are the specified values. 935 * 936 * @param values the elements of the new stream 937 * @return the new stream 938 */ 939 public static DoubleStream of(double... values) { 940 return Arrays.stream(values); 941 } 942 943 /** 944 * Returns an infinite sequential ordered {@code DoubleStream} produced by iterative 945 * application of a function {@code f} to an initial element {@code seed}, 946 * producing a {@code Stream} consisting of {@code seed}, {@code f(seed)}, 947 * {@code f(f(seed))}, etc. 948 * 949 * <p>The first element (position {@code 0}) in the {@code DoubleStream} 950 * will be the provided {@code seed}. For {@code n > 0}, the element at 951 * position {@code n}, will be the result of applying the function {@code f} 952 * to the element at position {@code n - 1}. 953 * 954 * <p>The action of applying {@code f} for one element 955 * <a href="../concurrent/package-summary.html#MemoryVisibility"><i>happens-before</i></a> 956 * the action of applying {@code f} for subsequent elements. For any given 957 * element the action may be performed in whatever thread the library 958 * chooses. 959 * 960 * @param seed the initial element 961 * @param f a function to be applied to the previous element to produce 962 * a new element 963 * @return a new sequential {@code DoubleStream} 964 */ 965 public static DoubleStream iterate(final double seed, final DoubleUnaryOperator f) { 966 Objects.requireNonNull(f); 967 Spliterator.OfDouble spliterator = new Spliterators.AbstractDoubleSpliterator(Long.MAX_VALUE, 968 Spliterator.ORDERED | Spliterator.IMMUTABLE | Spliterator.NONNULL) { 969 double prev; 970 boolean started; 971 972 @Override 973 public boolean tryAdvance(DoubleConsumer action) { 974 Objects.requireNonNull(action); 975 double t; 976 if (started) 977 t = f.applyAsDouble(prev); 978 else { 979 t = seed; 980 started = true; 981 } 982 action.accept(prev = t); 983 return true; 984 } 985 }; 986 return StreamSupport.doubleStream(spliterator, false); 987 } 988 989 /** 990 * Returns a sequential ordered {@code DoubleStream} produced by iterative 991 * application of the given {@code next} function to an initial element, 992 * conditioned on satisfying the given {@code hasNext} predicate. The 993 * stream terminates as soon as the {@code hasNext} predicate returns false. 994 * 995 * <p>{@code DoubleStream.iterate} should produce the same sequence of elements as 996 * produced by the corresponding for-loop: 997 * <pre>{@code 998 * for (double index=seed; hasNext.test(index); index = next.applyAsDouble(index)) { 999 * ... 1000 * } 1001 * }</pre> 1002 * 1003 * <p>The resulting sequence may be empty if the {@code hasNext} predicate 1004 * does not hold on the seed value. Otherwise the first element will be the 1005 * supplied {@code seed} value, the next element (if present) will be the 1006 * result of applying the {@code next} function to the {@code seed} value, 1007 * and so on iteratively until the {@code hasNext} predicate indicates that 1008 * the stream should terminate. 1009 * 1010 * <p>The action of applying the {@code hasNext} predicate to an element 1011 * <a href="../concurrent/package-summary.html#MemoryVisibility"><i>happens-before</i></a> 1012 * the action of applying the {@code next} function to that element. The 1013 * action of applying the {@code next} function for one element 1014 * <i>happens-before</i> the action of applying the {@code hasNext} 1015 * predicate for subsequent elements. For any given element an action may 1016 * be performed in whatever thread the library chooses. 1017 * 1018 * @param seed the initial element 1019 * @param hasNext a predicate to apply to elements to determine when the 1020 * stream must terminate. 1021 * @param next a function to be applied to the previous element to produce 1022 * a new element 1023 * @return a new sequential {@code DoubleStream} 1024 * @since 9 1025 */ 1026 public static DoubleStream iterate(double seed, DoublePredicate hasNext, DoubleUnaryOperator next) { 1027 Objects.requireNonNull(next); 1028 Objects.requireNonNull(hasNext); 1029 Spliterator.OfDouble spliterator = new Spliterators.AbstractDoubleSpliterator(Long.MAX_VALUE, 1030 Spliterator.ORDERED | Spliterator.IMMUTABLE | Spliterator.NONNULL) { 1031 double prev; 1032 boolean started, finished; 1033 1034 @Override 1035 public boolean tryAdvance(DoubleConsumer action) { 1036 Objects.requireNonNull(action); 1037 if (finished) 1038 return false; 1039 double t; 1040 if (started) 1041 t = next.applyAsDouble(prev); 1042 else { 1043 t = seed; 1044 started = true; 1045 } 1046 if (!hasNext.test(t)) { 1047 finished = true; 1048 return false; 1049 } 1050 action.accept(prev = t); 1051 return true; 1052 } 1053 1054 @Override 1055 public void forEachRemaining(DoubleConsumer action) { 1056 Objects.requireNonNull(action); 1057 if (finished) 1058 return; 1059 finished = true; 1060 double t = started ? next.applyAsDouble(prev) : seed; 1061 while (hasNext.test(t)) { 1062 action.accept(t); 1063 t = next.applyAsDouble(t); 1064 } 1065 } 1066 }; 1067 return StreamSupport.doubleStream(spliterator, false); 1068 } 1069 1070 /** 1071 * Returns an infinite sequential unordered stream where each element is 1072 * generated by the provided {@code DoubleSupplier}. This is suitable for 1073 * generating constant streams, streams of random elements, etc. 1074 * 1075 * @param s the {@code DoubleSupplier} for generated elements 1076 * @return a new infinite sequential unordered {@code DoubleStream} 1077 */ 1078 public static DoubleStream generate(DoubleSupplier s) { 1079 Objects.requireNonNull(s); 1080 return StreamSupport.doubleStream( 1081 new StreamSpliterators.InfiniteSupplyingSpliterator.OfDouble(Long.MAX_VALUE, s), false); 1082 } 1083 1084 /** 1085 * Creates a lazily concatenated stream whose elements are all the 1086 * elements of the first stream followed by all the elements of the 1087 * second stream. The resulting stream is ordered if both 1088 * of the input streams are ordered, and parallel if either of the input 1089 * streams is parallel. When the resulting stream is closed, the close 1090 * handlers for both input streams are invoked. 1091 * 1092 * <p>This method operates on the two input streams and binds each stream 1093 * to its source. As a result subsequent modifications to an input stream 1094 * source may not be reflected in the concatenated stream result. 1095 * 1096 * @implNote 1097 * Use caution when constructing streams from repeated concatenation. 1098 * Accessing an element of a deeply concatenated stream can result in deep 1099 * call chains, or even {@code StackOverflowError}. 1100 * 1101 * @apiNote 1102 * To preserve optimization opportunities this method binds each stream to 1103 * its source and accepts only two streams as parameters. For example, the 1104 * exact size of the concatenated stream source can be computed if the exact 1105 * size of each input stream source is known. 1106 * To concatenate more streams without binding, or without nested calls to 1107 * this method, try creating a stream of streams and flat-mapping with the 1108 * identity function, for example: 1109 * <pre>{@code 1110 * DoubleStream concat = Stream.of(s1, s2, s3, s4).flatMapToDouble(s -> s); 1111 * }</pre> 1112 * 1113 * @param a the first stream 1114 * @param b the second stream 1115 * @return the concatenation of the two input streams 1116 */ 1117 public static DoubleStream concat(DoubleStream a, DoubleStream b) { 1118 Objects.requireNonNull(a); 1119 Objects.requireNonNull(b); 1120 1121 Spliterator.OfDouble split = new Streams.ConcatSpliterator.OfDouble( 1122 a.spliterator(), b.spliterator()); 1123 DoubleStream stream = StreamSupport.doubleStream(split, a.isParallel() || b.isParallel()); 1124 return stream.onClose(Streams.composedClose(a, b)); 1125 } 1126 1127 /** 1128 * A mutable builder for a {@code DoubleStream}. 1129 * 1130 * <p>A stream builder has a lifecycle, which starts in a building 1131 * phase, during which elements can be added, and then transitions to a built 1132 * phase, after which elements may not be added. The built phase 1133 * begins when the {@link #build()} method is called, which creates an 1134 * ordered stream whose elements are the elements that were added to the 1135 * stream builder, in the order they were added. 1136 * 1137 * @see DoubleStream#builder() 1138 * @since 1.8 1139 */ 1140 public interface Builder extends DoubleConsumer { 1141 1142 /** 1143 * Adds an element to the stream being built. 1144 * 1145 * @throws IllegalStateException if the builder has already transitioned 1146 * to the built state 1147 */ 1148 @Override 1149 void accept(double t); 1150 1151 /** 1152 * Adds an element to the stream being built. 1153 * 1154 * @implSpec 1155 * The default implementation behaves as if: 1156 * <pre>{@code 1157 * accept(t) 1158 * return this; 1159 * }</pre> 1160 * 1161 * @param t the element to add 1162 * @return {@code this} builder 1163 * @throws IllegalStateException if the builder has already transitioned 1164 * to the built state 1165 */ 1166 default Builder add(double t) { 1167 accept(t); 1168 return this; 1169 } 1170 1171 /** 1172 * Builds the stream, transitioning this builder to the built state. 1173 * An {@code IllegalStateException} is thrown if there are further 1174 * attempts to operate on the builder after it has entered the built 1175 * state. 1176 * 1177 * @return the built stream 1178 * @throws IllegalStateException if the builder has already transitioned 1179 * to the built state 1180 */ 1181 DoubleStream build(); 1182 } 1183 }