1 /* 2 * Copyright (c) 2012, 2014, 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.nio.charset.Charset; 28 import java.nio.file.Files; 29 import java.nio.file.Path; 30 import java.util.Arrays; 31 import java.util.Collection; 32 import java.util.DoubleSummaryStatistics; 33 import java.util.Objects; 34 import java.util.OptionalDouble; 35 import java.util.PrimitiveIterator; 36 import java.util.Spliterator; 37 import java.util.Spliterators; 38 import java.util.concurrent.ConcurrentHashMap; 39 import java.util.function.BiConsumer; 40 import java.util.function.DoubleBinaryOperator; 41 import java.util.function.DoubleConsumer; 42 import java.util.function.DoubleFunction; 43 import java.util.function.DoublePredicate; 44 import java.util.function.DoubleSupplier; 45 import java.util.function.DoubleToIntFunction; 46 import java.util.function.DoubleToLongFunction; 47 import java.util.function.DoubleUnaryOperator; 48 import java.util.function.Function; 49 import java.util.function.ObjDoubleConsumer; 50 import java.util.function.Supplier; 51 52 /** 53 * A sequence of primitive double-valued elements supporting sequential and parallel 54 * aggregate operations. This is the {@code double} primitive specialization of 55 * {@link Stream}. 56 * 57 * <p>The following example illustrates an aggregate operation using 58 * {@link Stream} and {@link DoubleStream}, computing the sum of the weights of the 59 * red widgets: 60 * 61 * <pre>{@code 62 * double sum = widgets.stream() 63 * .filter(w -> w.getColor() == RED) 64 * .mapToDouble(w -> w.getWeight()) 65 * .sum(); 66 * }</pre> 67 * 68 * See the class documentation for {@link Stream} and the package documentation 69 * for <a href="package-summary.html">java.util.stream</a> for additional 70 * specification of streams, stream operations, stream pipelines, and 71 * parallelism. 72 * 73 * @since 1.8 74 * @see Stream 75 * @see <a href="package-summary.html">java.util.stream</a> 76 */ 77 public interface DoubleStream extends BaseStream<Double, DoubleStream> { 78 79 /** 80 * Returns a stream consisting of the elements of this stream that match 81 * the given predicate. 82 * 83 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 84 * operation</a>. 85 * 86 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>, 87 * <a href="package-summary.html#Statelessness">stateless</a> 88 * predicate to apply to each element to determine if it 89 * should be included 90 * @return the new stream 91 */ 92 DoubleStream filter(DoublePredicate predicate); 93 94 /** 95 * Returns a stream consisting of the results of applying the given 96 * function to the elements of this stream. 97 * 98 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 99 * operation</a>. 100 * 101 * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>, 102 * <a href="package-summary.html#Statelessness">stateless</a> 103 * function to apply to each element 104 * @return the new stream 105 */ 106 DoubleStream map(DoubleUnaryOperator mapper); 107 108 /** 109 * Returns an object-valued {@code Stream} consisting of the results of 110 * applying the given function to the elements of this stream. 111 * 112 * <p>This is an <a href="package-summary.html#StreamOps"> 113 * intermediate operation</a>. 114 * 115 * @param <U> the element type of the new stream 116 * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>, 117 * <a href="package-summary.html#Statelessness">stateless</a> 118 * function to apply to each element 119 * @return the new stream 120 */ 121 <U> Stream<U> mapToObj(DoubleFunction<? extends U> mapper); 122 123 /** 124 * Returns an {@code IntStream} consisting of the results of applying the 125 * given function to the elements of this stream. 126 * 127 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 128 * operation</a>. 129 * 130 * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>, 131 * <a href="package-summary.html#Statelessness">stateless</a> 132 * function to apply to each element 133 * @return the new stream 134 */ 135 IntStream mapToInt(DoubleToIntFunction mapper); 136 137 /** 138 * Returns a {@code LongStream} consisting of the results of applying the 139 * given function to the elements of this stream. 140 * 141 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 142 * operation</a>. 143 * 144 * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>, 145 * <a href="package-summary.html#Statelessness">stateless</a> 146 * function to apply to each element 147 * @return the new stream 148 */ 149 LongStream mapToLong(DoubleToLongFunction mapper); 150 151 /** 152 * Returns a stream consisting of the results of replacing each element of 153 * this stream with the contents of a mapped stream produced by applying 154 * the provided mapping function to each element. Each mapped stream is 155 * {@link java.util.stream.BaseStream#close() closed} after its contents 156 * have been placed into this stream. (If a mapped stream is {@code null} 157 * an empty stream is used, instead.) 158 * 159 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 160 * operation</a>. 161 * 162 * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>, 163 * <a href="package-summary.html#Statelessness">stateless</a> 164 * function to apply to each element which produces a 165 * {@code DoubleStream} of new values 166 * @return the new stream 167 * @see Stream#flatMap(Function) 168 */ 169 DoubleStream flatMap(DoubleFunction<? extends DoubleStream> mapper); 170 171 /** 172 * Returns a stream consisting of the distinct elements of this stream. The 173 * elements are compared for equality according to 174 * {@link java.lang.Double#compare(double, double)}. 175 * 176 * <p>This is a <a href="package-summary.html#StreamOps">stateful 177 * intermediate operation</a>. 178 * 179 * @return the result stream 180 */ 181 DoubleStream distinct(); 182 183 /** 184 * Returns a stream consisting of the elements of this stream in sorted 185 * order. The elements are compared for equality according to 186 * {@link java.lang.Double#compare(double, double)}. 187 * 188 * <p>This is a <a href="package-summary.html#StreamOps">stateful 189 * intermediate operation</a>. 190 * 191 * @return the result stream 192 */ 193 DoubleStream sorted(); 194 195 /** 196 * Returns a stream consisting of the elements of this stream, additionally 197 * performing the provided action on each element as elements are consumed 198 * from the resulting stream. 199 * 200 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 201 * operation</a>. 202 * 203 * <p>For parallel stream pipelines, the action may be called at 204 * whatever time and in whatever thread the element is made available by the 205 * upstream operation. If the action modifies shared state, 206 * it is responsible for providing the required synchronization. 207 * 208 * @apiNote This method exists mainly to support debugging, where you want 209 * to see the elements as they flow past a certain point in a pipeline: 210 * <pre>{@code 211 * DoubleStream.of(1, 2, 3, 4) 212 * .filter(e -> e > 2) 213 * .peek(e -> System.out.println("Filtered value: " + e)) 214 * .map(e -> e * e) 215 * .peek(e -> System.out.println("Mapped value: " + e)) 216 * .sum(); 217 * }</pre> 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 * Performs an action for each element of this stream. 284 * 285 * <p>This is a <a href="package-summary.html#StreamOps">terminal 286 * operation</a>. 287 * 288 * <p>For parallel stream pipelines, this operation does <em>not</em> 289 * guarantee to respect the encounter order of the stream, as doing so 290 * would sacrifice the benefit of parallelism. For any given element, the 291 * action may be performed at whatever time and in whatever thread the 292 * library chooses. If the action accesses shared state, it is 293 * responsible for providing the required synchronization. 294 * 295 * @param action a <a href="package-summary.html#NonInterference"> 296 * non-interfering</a> action to perform on the elements 297 */ 298 void forEach(DoubleConsumer action); 299 300 /** 301 * Performs an action for each element of this stream, guaranteeing that 302 * each element is processed in encounter order for streams that have a 303 * defined encounter order. 304 * 305 * <p>This is a <a href="package-summary.html#StreamOps">terminal 306 * operation</a>. 307 * 308 * @param action a <a href="package-summary.html#NonInterference"> 309 * non-interfering</a> action to perform on the elements 310 * @see #forEach(DoubleConsumer) 311 */ 312 void forEachOrdered(DoubleConsumer action); 313 314 /** 315 * Returns an array containing the elements of this stream. 316 * 317 * <p>This is a <a href="package-summary.html#StreamOps">terminal 318 * operation</a>. 319 * 320 * @return an array containing the elements of this stream 321 */ 322 double[] toArray(); 323 324 /** 325 * Performs a <a href="package-summary.html#Reduction">reduction</a> on the 326 * elements of this stream, using the provided identity value and an 327 * <a href="package-summary.html#Associativity">associative</a> 328 * accumulation function, and returns the reduced value. This is equivalent 329 * to: 330 * <pre>{@code 331 * double result = identity; 332 * for (double element : this stream) 333 * result = accumulator.applyAsDouble(result, element) 334 * return result; 335 * }</pre> 336 * 337 * but is not constrained to execute sequentially. 338 * 339 * <p>The {@code identity} value must be an identity for the accumulator 340 * function. This means that for all {@code x}, 341 * {@code accumulator.apply(identity, x)} is equal to {@code x}. 342 * The {@code accumulator} function must be an 343 * <a href="package-summary.html#Associativity">associative</a> function. 344 * 345 * <p>This is a <a href="package-summary.html#StreamOps">terminal 346 * operation</a>. 347 * 348 * @apiNote Sum, min, max, and average are all special cases of reduction. 349 * Summing a stream of numbers can be expressed as: 350 351 * <pre>{@code 352 * double sum = numbers.reduce(0, (a, b) -> a+b); 353 * }</pre> 354 * 355 * or more compactly: 356 * 357 * <pre>{@code 358 * double sum = numbers.reduce(0, Double::sum); 359 * }</pre> 360 * 361 * <p>While this may seem a more roundabout way to perform an aggregation 362 * compared to simply mutating a running total in a loop, reduction 363 * operations parallelize more gracefully, without needing additional 364 * synchronization and with greatly reduced risk of data races. 365 * 366 * @param identity the identity value for the accumulating function 367 * @param op an <a href="package-summary.html#Associativity">associative</a>, 368 * <a href="package-summary.html#NonInterference">non-interfering</a>, 369 * <a href="package-summary.html#Statelessness">stateless</a> 370 * 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 double reduce(double identity, DoubleBinaryOperator 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 OptionalDouble} describing the reduced 384 * value, if any. This is equivalent to: 385 * <pre>{@code 386 * boolean foundAny = false; 387 * double result = null; 388 * for (double element : this stream) { 389 * if (!foundAny) { 390 * foundAny = true; 391 * result = element; 392 * } 393 * else 394 * result = accumulator.applyAsDouble(result, element); 395 * } 396 * return foundAny ? OptionalDouble.of(result) : OptionalDouble.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</a>, 409 * <a href="package-summary.html#Statelessness">stateless</a> 410 * function for combining two values 411 * @return the result of the reduction 412 * @see #reduce(double, DoubleBinaryOperator) 413 */ 414 OptionalDouble reduce(DoubleBinaryOperator op); 415 416 /** 417 * Performs a <a href="package-summary.html#MutableReduction">mutable 418 * reduction</a> operation on the elements of this stream. A mutable 419 * reduction is one in which the reduced value is a mutable result container, 420 * such as an {@code ArrayList}, and elements are incorporated by updating 421 * the state of the result rather than by replacing the result. This 422 * produces a result equivalent to: 423 * <pre>{@code 424 * R result = supplier.get(); 425 * for (double element : this stream) 426 * accumulator.accept(result, element); 427 * return result; 428 * }</pre> 429 * 430 * <p>Like {@link #reduce(double, DoubleBinaryOperator)}, {@code collect} 431 * operations can be parallelized without requiring additional 432 * synchronization. 433 * 434 * <p>This is a <a href="package-summary.html#StreamOps">terminal 435 * operation</a>. 436 * 437 * @param <R> type of the result 438 * @param supplier a function that creates a new result container. For a 439 * parallel execution, this function may be called 440 * multiple times and must return a fresh value each time. 441 * @param accumulator an <a href="package-summary.html#Associativity">associative</a>, 442 * <a href="package-summary.html#NonInterference">non-interfering</a>, 443 * <a href="package-summary.html#Statelessness">stateless</a> 444 * function for incorporating an additional element into a result 445 * @param combiner an <a href="package-summary.html#Associativity">associative</a>, 446 * <a href="package-summary.html#NonInterference">non-interfering</a>, 447 * <a href="package-summary.html#Statelessness">stateless</a> 448 * function for combining two values, which must be 449 * compatible with the accumulator function 450 * @return the result of the reduction 451 * @see Stream#collect(Supplier, BiConsumer, BiConsumer) 452 */ 453 <R> R collect(Supplier<R> supplier, 454 ObjDoubleConsumer<R> accumulator, 455 BiConsumer<R, R> combiner); 456 457 /** 458 * Returns the sum of elements in this stream. 459 * 460 * Summation is a special case of a <a 461 * href="package-summary.html#Reduction">reduction</a>. If 462 * floating-point summation were exact, this method would be 463 * equivalent to: 464 * 465 * <pre>{@code 466 * return reduce(0, Double::sum); 467 * }</pre> 468 * 469 * However, since floating-point summation is not exact, the above 470 * code is not necessarily equivalent to the summation computation 471 * done by this method. 472 * 473 * <p>The value of a floating-point sum is a function both 474 * of the input values as well as the order of addition 475 * operations. The order of addition operations of this method is 476 * intentionally not defined to allow for implementation 477 * flexibility to improve the speed and accuracy of the computed 478 * result. 479 * 480 * In particular, this method may be implemented using compensated 481 * summation or other technique to reduce the error bound in the 482 * numerical sum compared to a simple summation of {@code double} 483 * values. 484 * 485 * <p>If any stream element is a NaN or the intermediate sum is at 486 * any point a NaN, then the final sum will be NaN. 487 * 488 * If the stream elements contain infinities of opposite sign, the 489 * final sum will be NaN. 490 * 491 * It is possible for intermediate sums of finite values to 492 * overflow into opposite-signed infinities; if that occurs, the 493 * final sum will be NaN even if the stream elements are all 494 * finite. 495 * 496 * If the exact sum is infinite, a properly-signed infinity is 497 * returned. 498 * 499 * If all the stream elements are zero, the sign of zero is 500 * <em>not</em> guaranteed to be preserved in the final sum. 501 * 502 * <p>This is a <a href="package-summary.html#StreamOps">terminal 503 * operation</a>. 504 * 505 * @apiNote Elements sorted by increasing absolute magnitude tend 506 * to yield more accurate results. 507 * 508 * @return the sum of elements in this stream 509 */ 510 double sum(); 511 512 /** 513 * Returns an {@code OptionalDouble} describing the minimum element of this 514 * stream, or an empty OptionalDouble if this stream is empty. The minimum 515 * element will be {@code Double.NaN} if any stream element was NaN. Unlike 516 * the numerical comparison operators, this method considers negative zero 517 * to be strictly smaller than positive zero. This is a special case of a 518 * <a href="package-summary.html#Reduction">reduction</a> and is 519 * equivalent to: 520 * <pre>{@code 521 * return reduce(Double::min); 522 * }</pre> 523 * 524 * <p>This is a <a href="package-summary.html#StreamOps">terminal 525 * operation</a>. 526 * 527 * @return an {@code OptionalDouble} containing the minimum element of this 528 * stream, or an empty optional if the stream is empty 529 */ 530 OptionalDouble min(); 531 532 /** 533 * Returns an {@code OptionalDouble} describing the maximum element of this 534 * stream, or an empty OptionalDouble if this stream is empty. The maximum 535 * element will be {@code Double.NaN} if any stream element was NaN. Unlike 536 * the numerical comparison operators, this method considers negative zero 537 * to be strictly smaller than positive zero. This is a 538 * special case of a 539 * <a href="package-summary.html#Reduction">reduction</a> and is 540 * equivalent to: 541 * <pre>{@code 542 * return reduce(Double::max); 543 * }</pre> 544 * 545 * <p>This is a <a href="package-summary.html#StreamOps">terminal 546 * operation</a>. 547 * 548 * @return an {@code OptionalDouble} containing the maximum element of this 549 * stream, or an empty optional if the stream is empty 550 */ 551 OptionalDouble max(); 552 553 /** 554 * Returns the count of elements in this stream. This is a special case of 555 * a <a href="package-summary.html#Reduction">reduction</a> and is 556 * equivalent to: 557 * <pre>{@code 558 * return mapToLong(e -> 1L).sum(); 559 * }</pre> 560 * 561 * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. 562 * 563 * @return the count of elements in this stream 564 */ 565 long count(); 566 567 /** 568 * Returns an {@code OptionalDouble} describing the arithmetic 569 * mean of elements of this stream, or an empty optional if this 570 * stream is empty. 571 * 572 * <p>The average returned can vary depending upon the order in 573 * which values are recorded. 574 * 575 * This method may be implemented using compensated summation or 576 * other technique to reduce the error bound in the {@link #sum 577 * numerical sum} used to compute the average. 578 * 579 * <p>This method can return a NaN or infinite result in the same 580 * kind of numerical situations as {@linkplain #sum() the sum} can 581 * be NaN or infinite, respectively. 582 * 583 * <p>The average is a special case of a <a 584 * href="package-summary.html#Reduction">reduction</a>. 585 * 586 * <p>This is a <a href="package-summary.html#StreamOps">terminal 587 * operation</a>. 588 * 589 * @apiNote Elements sorted by increasing absolute magnitude tend 590 * to yield more accurate results. 591 * 592 * @return an {@code OptionalDouble} containing the average element of this 593 * stream, or an empty optional if the stream is empty 594 */ 595 OptionalDouble average(); 596 597 /** 598 * Returns a {@code DoubleSummaryStatistics} describing various summary data 599 * about the elements of this stream. This is a special 600 * case of a <a href="package-summary.html#Reduction">reduction</a>. 601 * 602 * <p>This is a <a href="package-summary.html#StreamOps">terminal 603 * operation</a>. 604 * 605 * @return a {@code DoubleSummaryStatistics} describing various summary data 606 * about the elements of this stream 607 */ 608 DoubleSummaryStatistics summaryStatistics(); 609 610 /** 611 * Returns whether any elements of this stream match the provided 612 * predicate. May not evaluate the predicate on all elements if not 613 * necessary for determining the result. If the stream is empty then 614 * {@code false} is returned and the predicate is not evaluated. 615 * 616 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 617 * terminal operation</a>. 618 * 619 * @apiNote 620 * This method evaluates the <em>existential quantification</em> of the 621 * predicate over the elements of the stream (for some x P(x)). 622 * 623 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>, 624 * <a href="package-summary.html#Statelessness">stateless</a> 625 * predicate to apply to elements of this stream 626 * @return {@code true} if any elements of the stream match the provided 627 * predicate, otherwise {@code false} 628 */ 629 boolean anyMatch(DoublePredicate predicate); 630 631 /** 632 * Returns whether all elements of this stream match the provided predicate. 633 * May not evaluate the predicate on all elements if not necessary for 634 * determining the result. If the stream is empty then {@code true} is 635 * returned and the predicate is not evaluated. 636 * 637 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 638 * terminal operation</a>. 639 * 640 * @apiNote 641 * This method evaluates the <em>universal quantification</em> of the 642 * predicate over the elements of the stream (for all x P(x)). If the 643 * stream is empty, the quantification is said to be <em>vacuously 644 * satisfied</em> and is always {@code true} (regardless of P(x)). 645 * 646 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>, 647 * <a href="package-summary.html#Statelessness">stateless</a> 648 * predicate to apply to elements of this stream 649 * @return {@code true} if either all elements of the stream match the 650 * provided predicate or the stream is empty, otherwise {@code false} 651 */ 652 boolean allMatch(DoublePredicate predicate); 653 654 /** 655 * Returns whether no elements of this stream match the provided predicate. 656 * May not evaluate the predicate on all elements if not necessary for 657 * determining the result. If the stream is empty then {@code true} is 658 * returned and the predicate is not evaluated. 659 * 660 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 661 * terminal operation</a>. 662 * 663 * @apiNote 664 * This method evaluates the <em>universal quantification</em> of the 665 * negated predicate over the elements of the stream (for all x ~P(x)). If 666 * the stream is empty, the quantification is said to be vacuously satisfied 667 * and is always {@code true}, regardless of P(x). 668 * 669 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>, 670 * <a href="package-summary.html#Statelessness">stateless</a> 671 * predicate to apply to elements of this stream 672 * @return {@code true} if either no elements of the stream match the 673 * provided predicate or the stream is empty, otherwise {@code false} 674 */ 675 boolean noneMatch(DoublePredicate predicate); 676 677 /** 678 * Returns an {@link OptionalDouble} describing the first element of this 679 * stream, or an empty {@code OptionalDouble} if the stream is empty. If 680 * the stream has no encounter order, then any element may be returned. 681 * 682 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 683 * terminal operation</a>. 684 * 685 * @return an {@code OptionalDouble} describing the first element of this 686 * stream, or an empty {@code OptionalDouble} if the stream is empty 687 */ 688 OptionalDouble findFirst(); 689 690 /** 691 * Returns an {@link OptionalDouble} describing some element of the stream, 692 * or an empty {@code OptionalDouble} if the stream is empty. 693 * 694 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 695 * terminal operation</a>. 696 * 697 * <p>The behavior of this operation is explicitly nondeterministic; it is 698 * free to select any element in the stream. This is to allow for maximal 699 * performance in parallel operations; the cost is that multiple invocations 700 * on the same source may not return the same result. (If a stable result 701 * is desired, use {@link #findFirst()} instead.) 702 * 703 * @return an {@code OptionalDouble} describing some element of this stream, 704 * or an empty {@code OptionalDouble} if the stream is empty 705 * @see #findFirst() 706 */ 707 OptionalDouble findAny(); 708 709 /** 710 * Returns a {@code Stream} consisting of the elements of this stream, 711 * boxed to {@code Double}. 712 * 713 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 714 * operation</a>. 715 * 716 * @return a {@code Stream} consistent of the elements of this stream, 717 * each boxed to a {@code Double} 718 */ 719 Stream<Double> boxed(); 720 721 @Override 722 DoubleStream sequential(); 723 724 @Override 725 DoubleStream parallel(); 726 727 @Override 728 PrimitiveIterator.OfDouble iterator(); 729 730 @Override 731 Spliterator.OfDouble spliterator(); 732 733 734 // Static factories 735 736 /** 737 * Returns a builder for a {@code DoubleStream}. 738 * 739 * @return a stream builder 740 */ 741 public static Builder builder() { 742 return new Streams.DoubleStreamBuilderImpl(); 743 } 744 745 /** 746 * Returns an empty sequential {@code DoubleStream}. 747 * 748 * @return an empty sequential stream 749 */ 750 public static DoubleStream empty() { 751 return StreamSupport.doubleStream(Spliterators.emptyDoubleSpliterator(), false); 752 } 753 754 /** 755 * Returns a sequential {@code DoubleStream} containing a single element. 756 * 757 * @param t the single element 758 * @return a singleton sequential stream 759 */ 760 public static DoubleStream of(double t) { 761 return StreamSupport.doubleStream(new Streams.DoubleStreamBuilderImpl(t), false); 762 } 763 764 /** 765 * Returns a sequential ordered stream whose elements are the specified values. 766 * 767 * @param values the elements of the new stream 768 * @return the new stream 769 */ 770 public static DoubleStream of(double... values) { 771 return Arrays.stream(values); 772 } 773 774 /** 775 * Returns an infinite sequential ordered {@code DoubleStream} produced by iterative 776 * application of a function {@code f} to an initial element {@code seed}, 777 * producing a {@code Stream} consisting of {@code seed}, {@code f(seed)}, 778 * {@code f(f(seed))}, etc. 779 * 780 * <p>The first element (position {@code 0}) in the {@code DoubleStream} 781 * will be the provided {@code seed}. For {@code n > 0}, the element at 782 * position {@code n}, will be the result of applying the function {@code f} 783 * to the element at position {@code n - 1}. 784 * 785 * @param seed the initial element 786 * @param f a function to be applied to to the previous element to produce 787 * a new element 788 * @return a new sequential {@code DoubleStream} 789 */ 790 public static DoubleStream iterate(final double seed, final DoubleUnaryOperator f) { 791 Objects.requireNonNull(f); 792 final PrimitiveIterator.OfDouble iterator = new PrimitiveIterator.OfDouble() { 793 double t = seed; 794 795 @Override 796 public boolean hasNext() { 797 return true; 798 } 799 800 @Override 801 public double nextDouble() { 802 double v = t; 803 t = f.applyAsDouble(t); 804 return v; 805 } 806 }; 807 return StreamSupport.doubleStream(Spliterators.spliteratorUnknownSize( 808 iterator, 809 Spliterator.ORDERED | Spliterator.IMMUTABLE | Spliterator.NONNULL), false); 810 } 811 812 /** 813 * Returns an infinite sequential unordered stream where each element is 814 * generated by the provided {@code DoubleSupplier}. This is suitable for 815 * generating constant streams, streams of random elements, etc. 816 * 817 * @param s the {@code DoubleSupplier} for generated elements 818 * @return a new infinite sequential unordered {@code DoubleStream} 819 */ 820 public static DoubleStream generate(DoubleSupplier s) { 821 Objects.requireNonNull(s); 822 return StreamSupport.doubleStream( 823 new StreamSpliterators.InfiniteSupplyingSpliterator.OfDouble(Long.MAX_VALUE, s), false); 824 } 825 826 /** 827 * Creates a lazily concatenated stream whose elements are all the 828 * elements of the first stream followed by all the elements of the 829 * second stream. The resulting stream is ordered if both 830 * of the input streams are ordered, and parallel if either of the input 831 * streams is parallel. When the resulting stream is closed, the close 832 * handlers for both input streams are invoked. 833 * 834 * @implNote 835 * Use caution when constructing streams from repeated concatenation. 836 * Accessing an element of a deeply concatenated stream can result in deep 837 * call chains, or even {@code StackOverflowException}. 838 * 839 * @param a the first stream 840 * @param b the second stream 841 * @return the concatenation of the two input streams 842 */ 843 public static DoubleStream concat(DoubleStream a, DoubleStream b) { 844 Objects.requireNonNull(a); 845 Objects.requireNonNull(b); 846 847 Spliterator.OfDouble split = new Streams.ConcatSpliterator.OfDouble( 848 a.spliterator(), b.spliterator()); 849 DoubleStream stream = StreamSupport.doubleStream(split, a.isParallel() || b.isParallel()); 850 return stream.onClose(Streams.composedClose(a, b)); 851 } 852 853 /** 854 * A mutable builder for a {@code DoubleStream}. 855 * 856 * <p>A stream builder has a lifecycle, which starts in a building 857 * phase, during which elements can be added, and then transitions to a built 858 * phase, after which elements may not be added. The built phase 859 * begins when the {@link #build()} method is called, which creates an 860 * ordered stream whose elements are the elements that were added to the 861 * stream builder, in the order they were added. 862 * 863 * @see DoubleStream#builder() 864 * @since 1.8 865 */ 866 public interface Builder extends DoubleConsumer { 867 868 /** 869 * Adds an element to the stream being built. 870 * 871 * @throws IllegalStateException if the builder has already transitioned 872 * to the built state 873 */ 874 @Override 875 void accept(double t); 876 877 /** 878 * Adds an element to the stream being built. 879 * 880 * @implSpec 881 * The default implementation behaves as if: 882 * <pre>{@code 883 * accept(t) 884 * return this; 885 * }</pre> 886 * 887 * @param t the element to add 888 * @return {@code this} builder 889 * @throws IllegalStateException if the builder has already transitioned 890 * to the built state 891 */ 892 default Builder add(double t) { 893 accept(t); 894 return this; 895 } 896 897 /** 898 * Builds the stream, transitioning this builder to the built state. 899 * An {@code IllegalStateException} is thrown if there are further 900 * attempts to operate on the builder after it has entered the built 901 * state. 902 * 903 * @return the built stream 904 * @throws IllegalStateException if the builder has already transitioned 905 * to the built state 906 */ 907 DoubleStream build(); 908 } 909 }