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
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 */
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);
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 */
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 */
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 *
|
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
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);
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 *
|