1 /* 2 * Copyright (c) 2012, 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.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 */ filter(DoublePredicate predicate)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 */ map(DoubleUnaryOperator mapper)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 */ mapToObj(DoubleFunction<? extends U> mapper)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 */ mapToInt(DoubleToIntFunction mapper)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 */ mapToLong(DoubleToLongFunction mapper)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 */ flatMap(DoubleFunction<? extends DoubleStream> mapper)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 */ distinct()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 */ sorted()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 */ peek(DoubleConsumer action)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 */ limit(long maxSize)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 */ skip(long n)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 */ forEach(DoubleConsumer action)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 */ forEachOrdered(DoubleConsumer action)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 */ toArray()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 */ reduce(double identity, DoubleBinaryOperator op)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 */ reduce(DoubleBinaryOperator op)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 */ collect(Supplier<R> supplier, ObjDoubleConsumer<R> accumulator, BiConsumer<R, R> combiner)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>If any stream element is a NaN or the sum is at any point a NaN 474 * then the sum will be NaN. 475 * 476 * The value of a floating-point sum is a function both 477 * of the input values as well as the order of addition 478 * operations. The order of addition operations of this method is 479 * intentionally not defined to allow for implementation 480 * flexibility to improve the speed and accuracy of the computed 481 * result. 482 * 483 * In particular, this method may be implemented using compensated 484 * summation or other technique to reduce the error bound in the 485 * numerical sum compared to a simple summation of {@code double} 486 * values. 487 * 488 * <p>This is a <a href="package-summary.html#StreamOps">terminal 489 * operation</a>. 490 * 491 * @apiNote Elements sorted by increasing absolute magnitude tend 492 * to yield more accurate results. 493 * 494 * @return the sum of elements in this stream 495 */ sum()496 double sum(); 497 498 /** 499 * Returns an {@code OptionalDouble} describing the minimum element of this 500 * stream, or an empty OptionalDouble if this stream is empty. The minimum 501 * element will be {@code Double.NaN} if any stream element was NaN. Unlike 502 * the numerical comparison operators, this method considers negative zero 503 * to be strictly smaller than positive zero. This is a special case of a 504 * <a href="package-summary.html#Reduction">reduction</a> and is 505 * equivalent to: 506 * <pre>{@code 507 * return reduce(Double::min); 508 * }</pre> 509 * 510 * <p>This is a <a href="package-summary.html#StreamOps">terminal 511 * operation</a>. 512 * 513 * @return an {@code OptionalDouble} containing the minimum element of this 514 * stream, or an empty optional if the stream is empty 515 */ min()516 OptionalDouble min(); 517 518 /** 519 * Returns an {@code OptionalDouble} describing the maximum element of this 520 * stream, or an empty OptionalDouble if this stream is empty. The maximum 521 * element will be {@code Double.NaN} if any stream element was NaN. Unlike 522 * the numerical comparison operators, this method considers negative zero 523 * to be strictly smaller than positive zero. This is a 524 * special case of a 525 * <a href="package-summary.html#Reduction">reduction</a> and is 526 * equivalent to: 527 * <pre>{@code 528 * return reduce(Double::max); 529 * }</pre> 530 * 531 * <p>This is a <a href="package-summary.html#StreamOps">terminal 532 * operation</a>. 533 * 534 * @return an {@code OptionalDouble} containing the maximum element of this 535 * stream, or an empty optional if the stream is empty 536 */ max()537 OptionalDouble max(); 538 539 /** 540 * Returns the count of elements in this stream. This is a special case of 541 * a <a href="package-summary.html#Reduction">reduction</a> and is 542 * equivalent to: 543 * <pre>{@code 544 * return mapToLong(e -> 1L).sum(); 545 * }</pre> 546 * 547 * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>. 548 * 549 * @return the count of elements in this stream 550 */ count()551 long count(); 552 553 /** 554 * Returns an {@code OptionalDouble} describing the arithmetic 555 * mean of elements of this stream, or an empty optional if this 556 * stream is empty. 557 * 558 * If any recorded value is a NaN or the sum is at any point a NaN 559 * then the average will be NaN. 560 * 561 * <p>The average returned can vary depending upon the order in 562 * which values are recorded. 563 * 564 * This method may be implemented using compensated summation or 565 * other technique to reduce the error bound in the {@link #sum 566 * numerical sum} used to compute the average. 567 * 568 * <p>The average is a special case of a <a 569 * href="package-summary.html#Reduction">reduction</a>. 570 * 571 * <p>This is a <a href="package-summary.html#StreamOps">terminal 572 * operation</a>. 573 * 574 * @apiNote Elements sorted by increasing absolute magnitude tend 575 * to yield more accurate results. 576 * 577 * @return an {@code OptionalDouble} containing the average element of this 578 * stream, or an empty optional if the stream is empty 579 */ average()580 OptionalDouble average(); 581 582 /** 583 * Returns a {@code DoubleSummaryStatistics} describing various summary data 584 * about the elements of this stream. This is a special 585 * case of a <a href="package-summary.html#Reduction">reduction</a>. 586 * 587 * <p>This is a <a href="package-summary.html#StreamOps">terminal 588 * operation</a>. 589 * 590 * @return a {@code DoubleSummaryStatistics} describing various summary data 591 * about the elements of this stream 592 */ summaryStatistics()593 DoubleSummaryStatistics summaryStatistics(); 594 595 /** 596 * Returns whether any elements of this stream match the provided 597 * predicate. May not evaluate the predicate on all elements if not 598 * necessary for determining the result. If the stream is empty then 599 * {@code false} is returned and the predicate is not evaluated. 600 * 601 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 602 * terminal operation</a>. 603 * 604 * @apiNote 605 * This method evaluates the <em>existential quantification</em> of the 606 * predicate over the elements of the stream (for some x P(x)). 607 * 608 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>, 609 * <a href="package-summary.html#Statelessness">stateless</a> 610 * predicate to apply to elements of this stream 611 * @return {@code true} if any elements of the stream match the provided 612 * predicate, otherwise {@code false} 613 */ anyMatch(DoublePredicate predicate)614 boolean anyMatch(DoublePredicate predicate); 615 616 /** 617 * Returns whether all elements of this stream match the provided predicate. 618 * May not evaluate the predicate on all elements if not necessary for 619 * determining the result. If the stream is empty then {@code true} is 620 * returned and the predicate is not evaluated. 621 * 622 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 623 * terminal operation</a>. 624 * 625 * @apiNote 626 * This method evaluates the <em>universal quantification</em> of the 627 * predicate over the elements of the stream (for all x P(x)). If the 628 * stream is empty, the quantification is said to be <em>vacuously 629 * satisfied</em> and is always {@code true} (regardless of P(x)). 630 * 631 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>, 632 * <a href="package-summary.html#Statelessness">stateless</a> 633 * predicate to apply to elements of this stream 634 * @return {@code true} if either all elements of the stream match the 635 * provided predicate or the stream is empty, otherwise {@code false} 636 */ allMatch(DoublePredicate predicate)637 boolean allMatch(DoublePredicate predicate); 638 639 /** 640 * Returns whether no elements of this stream match the provided predicate. 641 * May not evaluate the predicate on all elements if not necessary for 642 * determining the result. If the stream is empty then {@code true} is 643 * returned and the predicate is not evaluated. 644 * 645 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 646 * terminal operation</a>. 647 * 648 * @apiNote 649 * This method evaluates the <em>universal quantification</em> of the 650 * negated predicate over the elements of the stream (for all x ~P(x)). If 651 * the stream is empty, the quantification is said to be vacuously satisfied 652 * and is always {@code true}, regardless of P(x). 653 * 654 * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>, 655 * <a href="package-summary.html#Statelessness">stateless</a> 656 * predicate to apply to elements of this stream 657 * @return {@code true} if either no elements of the stream match the 658 * provided predicate or the stream is empty, otherwise {@code false} 659 */ noneMatch(DoublePredicate predicate)660 boolean noneMatch(DoublePredicate predicate); 661 662 /** 663 * Returns an {@link OptionalDouble} describing the first element of this 664 * stream, or an empty {@code OptionalDouble} if the stream is empty. If 665 * the stream has no encounter order, then any element may be returned. 666 * 667 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 668 * terminal operation</a>. 669 * 670 * @return an {@code OptionalDouble} describing the first element of this 671 * stream, or an empty {@code OptionalDouble} if the stream is empty 672 */ findFirst()673 OptionalDouble findFirst(); 674 675 /** 676 * Returns an {@link OptionalDouble} describing some element of the stream, 677 * or an empty {@code OptionalDouble} if the stream is empty. 678 * 679 * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting 680 * terminal operation</a>. 681 * 682 * <p>The behavior of this operation is explicitly nondeterministic; it is 683 * free to select any element in the stream. This is to allow for maximal 684 * performance in parallel operations; the cost is that multiple invocations 685 * on the same source may not return the same result. (If a stable result 686 * is desired, use {@link #findFirst()} instead.) 687 * 688 * @return an {@code OptionalDouble} describing some element of this stream, 689 * or an empty {@code OptionalDouble} if the stream is empty 690 * @see #findFirst() 691 */ findAny()692 OptionalDouble findAny(); 693 694 /** 695 * Returns a {@code Stream} consisting of the elements of this stream, 696 * boxed to {@code Double}. 697 * 698 * <p>This is an <a href="package-summary.html#StreamOps">intermediate 699 * operation</a>. 700 * 701 * @return a {@code Stream} consistent of the elements of this stream, 702 * each boxed to a {@code Double} 703 */ boxed()704 Stream<Double> boxed(); 705 706 @Override sequential()707 DoubleStream sequential(); 708 709 @Override parallel()710 DoubleStream parallel(); 711 712 @Override iterator()713 PrimitiveIterator.OfDouble iterator(); 714 715 @Override spliterator()716 Spliterator.OfDouble spliterator(); 717 718 719 // Static factories 720 721 /** 722 * Returns a builder for a {@code DoubleStream}. 723 * 724 * @return a stream builder 725 */ builder()726 public static Builder builder() { 727 return new Streams.DoubleStreamBuilderImpl(); 728 } 729 730 /** 731 * Returns an empty sequential {@code DoubleStream}. 732 * 733 * @return an empty sequential stream 734 */ empty()735 public static DoubleStream empty() { 736 return StreamSupport.doubleStream(Spliterators.emptyDoubleSpliterator(), false); 737 } 738 739 /** 740 * Returns a sequential {@code DoubleStream} containing a single element. 741 * 742 * @param t the single element 743 * @return a singleton sequential stream 744 */ of(double t)745 public static DoubleStream of(double t) { 746 return StreamSupport.doubleStream(new Streams.DoubleStreamBuilderImpl(t), false); 747 } 748 749 /** 750 * Returns a sequential ordered stream whose elements are the specified values. 751 * 752 * @param values the elements of the new stream 753 * @return the new stream 754 */ of(double... values)755 public static DoubleStream of(double... values) { 756 return Arrays.stream(values); 757 } 758 759 /** 760 * Returns an infinite sequential ordered {@code DoubleStream} produced by iterative 761 * application of a function {@code f} to an initial element {@code seed}, 762 * producing a {@code Stream} consisting of {@code seed}, {@code f(seed)}, 763 * {@code f(f(seed))}, etc. 764 * 765 * <p>The first element (position {@code 0}) in the {@code DoubleStream} 766 * will be the provided {@code seed}. For {@code n > 0}, the element at 767 * position {@code n}, will be the result of applying the function {@code f} 768 * to the element at position {@code n - 1}. 769 * 770 * @param seed the initial element 771 * @param f a function to be applied to to the previous element to produce 772 * a new element 773 * @return a new sequential {@code DoubleStream} 774 */ iterate(final double seed, final DoubleUnaryOperator f)775 public static DoubleStream iterate(final double seed, final DoubleUnaryOperator f) { 776 Objects.requireNonNull(f); 777 final PrimitiveIterator.OfDouble iterator = new PrimitiveIterator.OfDouble() { 778 double t = seed; 779 780 @Override 781 public boolean hasNext() { 782 return true; 783 } 784 785 @Override 786 public double nextDouble() { 787 double v = t; 788 t = f.applyAsDouble(t); 789 return v; 790 } 791 }; 792 return StreamSupport.doubleStream(Spliterators.spliteratorUnknownSize( 793 iterator, 794 Spliterator.ORDERED | Spliterator.IMMUTABLE | Spliterator.NONNULL), false); 795 } 796 797 /** 798 * Returns an infinite sequential unordered stream where each element is 799 * generated by the provided {@code DoubleSupplier}. This is suitable for 800 * generating constant streams, streams of random elements, etc. 801 * 802 * @param s the {@code DoubleSupplier} for generated elements 803 * @return a new infinite sequential unordered {@code DoubleStream} 804 */ generate(DoubleSupplier s)805 public static DoubleStream generate(DoubleSupplier s) { 806 Objects.requireNonNull(s); 807 return StreamSupport.doubleStream( 808 new StreamSpliterators.InfiniteSupplyingSpliterator.OfDouble(Long.MAX_VALUE, s), false); 809 } 810 811 /** 812 * Creates a lazily concatenated stream whose elements are all the 813 * elements of the first stream followed by all the elements of the 814 * second stream. The resulting stream is ordered if both 815 * of the input streams are ordered, and parallel if either of the input 816 * streams is parallel. When the resulting stream is closed, the close 817 * handlers for both input streams are invoked. 818 * 819 * @implNote 820 * Use caution when constructing streams from repeated concatenation. 821 * Accessing an element of a deeply concatenated stream can result in deep 822 * call chains, or even {@code StackOverflowException}. 823 * 824 * @param a the first stream 825 * @param b the second stream 826 * @return the concatenation of the two input streams 827 */ concat(DoubleStream a, DoubleStream b)828 public static DoubleStream concat(DoubleStream a, DoubleStream b) { 829 Objects.requireNonNull(a); 830 Objects.requireNonNull(b); 831 832 Spliterator.OfDouble split = new Streams.ConcatSpliterator.OfDouble( 833 a.spliterator(), b.spliterator()); 834 DoubleStream stream = StreamSupport.doubleStream(split, a.isParallel() || b.isParallel()); 835 return stream.onClose(Streams.composedClose(a, b)); 836 } 837 838 /** 839 * A mutable builder for a {@code DoubleStream}. 840 * 841 * <p>A stream builder has a lifecycle, which starts in a building 842 * phase, during which elements can be added, and then transitions to a built 843 * phase, after which elements may not be added. The built phase 844 * begins when the {@link #build()} method is called, which creates an 845 * ordered stream whose elements are the elements that were added to the 846 * stream builder, in the order they were added. 847 * 848 * @see DoubleStream#builder() 849 * @since 1.8 850 */ 851 public interface Builder extends DoubleConsumer { 852 853 /** 854 * Adds an element to the stream being built. 855 * 856 * @throws IllegalStateException if the builder has already transitioned 857 * to the built state 858 */ 859 @Override accept(double t)860 void accept(double t); 861 862 /** 863 * Adds an element to the stream being built. 864 * 865 * @implSpec 866 * The default implementation behaves as if: 867 * <pre>{@code 868 * accept(t) 869 * return this; 870 * }</pre> 871 * 872 * @param t the element to add 873 * @return {@code this} builder 874 * @throws IllegalStateException if the builder has already transitioned 875 * to the built state 876 */ add(double t)877 default Builder add(double t) { 878 accept(t); 879 return this; 880 } 881 882 /** 883 * Builds the stream, transitioning this builder to the built state. 884 * An {@code IllegalStateException} is thrown if there are further 885 * attempts to operate on the builder after it has entered the built 886 * state. 887 * 888 * @return the built stream 889 * @throws IllegalStateException if the builder has already transitioned 890 * to the built state 891 */ build()892 DoubleStream build(); 893 } 894 } 895