模块  java.base
软件包  java.util.stream

Interface LongStream

  • All Superinterfaces:
    AutoCloseable ， BaseStream<Long,​LongStream> 
    public interface LongStream
extends BaseStream<Long,​LongStream>
    一系列原始长值元素，支持顺序和并行聚合操作。 这是long原始专业化Stream 。

    以下示例说明了使用Stream和LongStream的聚合操作，计算红色窗口小部件的权重总和： 

       long sum = widgets.stream() .filter(w -> w.getColor() == RED) .mapToLong(w -> w.getWeight()) .sum();
    请参阅类文档Stream和用于包文档java.util.stream为流的附加说明书中，流操作，流管道，和平行度。
    从以下版本开始：
    1.8
    另请参见：
    Stream ， java.util.stream

    • 方法详细信息

      • mapToObj

        <U> Stream<U> mapToObj​(LongFunction<? extends U> mapper)
        返回一个对象值Stream它包含将给定函数应用于此流元素的结果。

        这是一个intermediate operation 。

        参数类型
        U - 新流的元素类型
        参数
        mapper -一个 non-interfering ， stateless函数应用到每个元件
        结果
        新流

      • flatMap

        LongStream flatMap​(LongFunction<? extends LongStream> mapper)
        返回一个流，该流包含将此流的每个元素替换为通过将提供的映射函数应用于每个元素而生成的映射流的内容的结果。 将其内容放入此流后，每个映射的流都为closed 。 （如果映射的流是null ，则使用空流。）

        这是一个intermediate operation 。

        参数
        mapper -一个 non-interfering ， stateless功能应用到其产生的每个元素 LongStream新值的
        结果
        新流
        另请参见：
        Stream.flatMap(Function)

      • peek

        LongStream peek​(LongConsumer action)
        返回由此流的元素组成的流，另外在每个元素上执行提供的操作，因为元素是从结果流中消耗的。

        这是一个intermediate operation 。

        对于并行流管道，可以在任何时间以及上游操作使元素可用的任何线程中调用该动作。 如果操作修改共享状态，则它负责提供所需的同步。

        API Note:
        此方法主要用于支持调试，您希望在元素流经管道中的某个点时查看这些元素： 
           LongStream.of(1, 2, 3, 4) .filter(e -> e > 2) .peek(e -> System.out.println("Filtered value: " + e)) .map(e -> e * e) .peek(e -> System.out.println("Mapped value: " + e)) .sum();

        如果流实现能够优化某些或所有元素的生成（例如使用短路操作，如findFirst ，或者在findFirst中描述的示例 ），则不会为这些元素调用该操作。

        参数
        action - 对从流中使用的元素执行的 non-interfering操作
        结果
        新流

      • limit

        LongStream limit​(long maxSize)
        返回由此流的元素组成的流，截断长度不超过maxSize 。

        这是一个short-circuiting stateful intermediate operation 。

        API Note:
        虽然limit()通常是顺序流管道上的廉价操作，但在有序并行流水线上可能相当昂贵，特别是对于maxSize大值，因为limit(n)被限制为不仅返回任何n个元素，而是在遭遇顺序中的前n个元素。 使用无序流源（例如generate(LongSupplier) ）或去除所述排序约束与BaseStream.unordered()可能导致显著加速比limit()在并行管线，如果情况许可的语义。 如果具有遭遇顺序的一致性是必须的，并且遇到性能或存储器利用率差与limit()在并行管线，在切换到的顺序执行与BaseStream.sequential()可以提高性能。
        参数
        maxSize - 流应限制的元素数
        结果
        新流
        异常
        IllegalArgumentException - 如果 maxSize为负数

      • skip

        LongStream skip​(long n)
        在丢弃流的第一个n元素后，返回由此流的其余元素组成的流。 如果此流包含少于n元素，则将返回空流。

        这是一个stateful intermediate operation 。

        API Note:
        虽然skip()通常是顺序流管道上的廉价操作，但在有序并行管道上可能相当昂贵，特别是对于n大值，因为skip(n)被限制为不仅跳过任何n个元素，而是跳过遭遇顺序中的前n个元素。 使用无序流源（例如generate(LongSupplier) ）或去除所述排序约束与BaseStream.unordered()可能导致显著加速比skip()在并行管线，如果情况许可的语义。 如果具有遭遇顺序的一致性是必须的，并且遇到性能或存储器利用率差与skip()在并行管线，在切换到的顺序执行与BaseStream.sequential()可以提高性能。
        参数
        n - 要跳过的前导元素的数量
        结果
        新流
        异常
        IllegalArgumentException - 如果 n为负数

      • takeWhile

        default LongStream takeWhile​(LongPredicate predicate)
        如果对此流进行排序，则返回一个流，该流包含从此流中获取的与给定谓词匹配的最长元素前缀。 否则，如果此流是无序的，则返回由从此流中获取的与给定谓词匹配的元素子集组成的流。

        如果对此流进行排序，则最长前缀是与该给定谓词匹配的该流的连续元素序列。 序列的第一个元素是此流的第一个元素，紧跟在序列的最后一个元素之后的元素与给定的谓词不匹配。

        如果此流是无序的，并且此流的某些（但不是所有）元素与给定谓词匹配，则此操作的行为是不确定的; 它可以自由地获取匹配元素的任何子集（包括空集）。

        如果此流的所有元素与给定谓词匹配，则此流是有序还是无序，无论此操作是否接受所有元素（结果与输入相同），或者如果流的任何元素都不匹配给定谓词，则没有元素被采取（结果是一个空流）。

        这是一个short-circuiting stateful intermediate operation 。

        API Note:
        虽然takeWhile()通常是对顺序流管道的廉价操作，但在有序并行管道上它可能非常昂贵，因为操作被约束为不仅返回任何有效前缀，而是返回遭遇顺序中元素的最长前缀。 使用无序流源（例如generate(LongSupplier) ）或去除所述排序约束与BaseStream.unordered()可能导致显著加速比takeWhile()在并行管线，如果情况许可的语义。 如果具有遭遇顺序的一致性是必须的，并且遇到性能或存储器利用率差与takeWhile()在并行管线，在切换到的顺序执行与BaseStream.sequential()可以提高性能。
        实现要求：
        默认实现获取此流的spliterator ，包装该spliterator以便在遍历时支持此操作的语义，并返回与包装的spliterator关联的新流。 返回的流保留此流的执行特征（即根据BaseStream.isParallel()进行并行或顺序执行），但是包装的分裂器可以选择不支持分割。 返回的流关闭后，将调用返回的流和此流的关闭处理程序。
        参数
        predicate -一个 non-interfering ， stateless谓词适用于元素，以确定元素的最长前缀。
        结果
        新流
        从以下版本开始：
        9

      • dropWhile

        default LongStream dropWhile​(LongPredicate predicate)
        如果对此流进行排序，则返回在删除与给定谓词匹配的元素的最长前缀之后由该流的其余元素组成的流。 否则，如果此流是无序的，则返回在删除与给定谓词匹配的元素子集之后由该流的其余元素组成的流。

        如果对此流进行排序，则最长前缀是与该给定谓词匹配的该流的连续元素序列。 序列的第一个元素是此流的第一个元素，紧跟在序列的最后一个元素之后的元素与给定的谓词不匹配。

        如果此流是无序的，并且此流的某些（但不是所有）元素与给定谓词匹配，则此操作的行为是不确定的; 它可以自由地删除匹配元素的任何子集（包括空集）。

        如果此流的所有元素与给定谓词匹配，则该流是有序还是无序，无论该操作是否丢弃所有元素（结果是空流），或者如果流的任何元素都不匹配给定谓词，则不会丢弃任何元素（结果与输入相同）。

        这是一个stateful intermediate operation 。

        API Note:
        虽然dropWhile()通常是顺序流管道上的廉价操作，但在有序并行流水线上它可能非常昂贵，因为操作被约束为不仅返回任何有效前缀，而是返回遭遇顺序中元素的最长前缀。 使用无序流源（例如generate(LongSupplier) ）或去除所述排序约束与BaseStream.unordered()可能导致显著加速比dropWhile()在并行管线，如果情况许可的语义。 如果具有遭遇顺序的一致性是必须的，并且遇到性能或存储器利用率差与dropWhile()在并行管线，在切换到的顺序执行与BaseStream.sequential()可以提高性能。
        实现要求：
        默认实现获取此流的spliterator ，包装该spliterator以便在遍历时支持此操作的语义，并返回与包装的spliterator关联的新流。 返回的流保留该流的执行特性（即根据BaseStream.isParallel()进行并行或顺序执行），但是包装的分裂器可以选择不支持分割。 返回的流关闭后，将调用返回的流和此流的关闭处理程序。
        参数
        predicate -一个 non-interfering ， stateless谓词适用于元素，以确定元素的最长前缀。
        结果
        新流
        从以下版本开始：
        9

      • forEach

        void forEach​(LongConsumer action)
        对此流的每个元素执行操作。

        这是一个terminal operation 。

        对于并行流管道，此操作并不保证尊重流的相遇顺序，因为这样做会牺牲并行的利益。 对于任何给定元素，可以在任何时间以及库选择的任何线程中执行该动作。 如果操作访问共享状态，则它负责提供所需的同步。

        参数
        action - 对元素执行的操作 non-interfering

      • toArray

        long[] toArray()
        返回包含此流的元素的数组。

        这是一个terminal operation 。

        结果
        包含此流的元素的数组

      • reduce

        long reduce​(long identity,
            LongBinaryOperator op)
        使用提供的标识值和associative累积函数对此流的元素执行reduction ，并返回减小的值。 这相当于： 
           long result = identity; for (long element : this stream) result = accumulator.applyAsLong(result, element) return result;
        但不限于按顺序执行。

        identity值必须是累加器函数的标识。 这意味着，对于所有x ， accumulator.apply(identity, x)等于x 。 accumulator函数必须是associative函数。

        这是一个terminal operation 。

        API Note:
        总和，最小值，最大值和平均值都是减少的特殊情况。 汇总数字流可以表示为： 
           long sum = integers.reduce(0, (a, b) -> a+b);
        或者更紧凑： 
           long sum = integers.reduce(0, Long::sum);

        虽然与简单地在循环中改变运行总计相比，这似乎是更加迂回的执行聚合的方式，但是还原操作可以更优雅地并行化，而无需额外的同步并且大大降低了数据竞争的风险。

        参数
        identity - 累积函数的标识值
        op -一个 associative ， non-interfering ， stateless功能组合两个值
        结果
        减少的结果
        另请参见：
        sum() ， min() ， max() ， average()

      • collect

        <R> R collect​(Supplier<R> supplier,
              ObjLongConsumer<R> accumulator,
              BiConsumer<R,​R> combiner)
        对此流的元素执行mutable reduction操作。 可变减少是其中减少的值是可变结果容器（例如ArrayList ，并且通过更新结果的状态而不是通过替换结果来合并元素。 这产生的结果相当于： 
           R result = supplier.get(); for (long element : this stream) accumulator.accept(result, element); return result;

        与reduce(long, LongBinaryOperator)一样， collect操作可以并行化，无需额外同步。

        这是一个terminal operation 。

        参数类型
        R - 可变结果容器的类型
        参数
        supplier - 创建新的可变结果容器的函数。 对于并行执行，可以多次调用此函数，并且每次都必须返回一个新值。
        accumulator -一个 associative ， non-interfering ， stateless功能必须的元件折叠成的结果容器。
        combiner -一个associative ， non-interfering ， stateless函数接受两个部分结果的容器和将它们合并，这必须与累加器功能兼容。 组合器函数必须将元素从第二个结果容器折叠到第一个结果容器中。
        结果
        减少的结果
        另请参见：
        Stream.collect(Supplier, BiConsumer, BiConsumer)

      • sum

        long sum()
        返回此流中元素的总和。 这是reduction的特例 ，相当于： 
           return reduce(0, Long::sum);

        这是一个terminal operation 。

        结果
        此流中元素的总和

      • min

        OptionalLong min()
        返回描述此流的最小元素的OptionalLong ，如果此流为空，则返回空的可选项。 这是reduction的特例 ，相当于： 
           return reduce(Long::min);

        这是terminal operation 。

        结果
        一个 OptionalLong含有该料流的一个空的最小元件，或 OptionalLong如果流是空

      • max

        OptionalLong max()
        返回描述此流的最大元素的OptionalLong ，如果此流为空，则返回空可选。 这是reduction的特例 ，相当于： 
           return reduce(Long::max);

        这是一个terminal operation 。

        结果
        一个 OptionalLong含有该料流的最大元素，或空 OptionalLong如果流是空

      • count

        long count()
        返回此流中元素的数量。 这是reduction的特例 ，相当于： 
           return map(e -> 1L).sum();

        这是terminal operation 。

        API Note:
        如果实现可以直接从流源计算计数，则实现可以选择不执行流管道（顺序地或并行地）。 在这种情况下，不会遍历任何源元素，也不会评估中间操作。 除了诸如调试之类的无害情况之外，强烈不鼓励具有副作用的行为参数可能会受到影响。 例如，请考虑以下流： 
           LongStream s = LongStream.of(1, 2, 3, 4); long count = s.peek(System.out::println).count();
        流源所涵盖的元素数量是已知的，并且中间操作peek不会从流中注入或移除元素（ flatMap或filter操作可能是这种情况）。 因此，计数为4，并且不需要执行管道，并且作为副作用，打印出元素。
        结果
        此流中的元素数

      • average

        OptionalDouble average()
        返回描述此流元素的算术平均值的OptionalDouble ，如果此流为空，则返回空可选。 这是reduction的特例 。

        这是一个terminal operation 。

        结果
        包含此流的平均元素的 OptionalDouble ，如果流为空，则为空可选

      • anyMatch

        boolean anyMatch​(LongPredicate predicate)
        返回此流的任何元素是否与提供的谓词匹配。 如果不是确定结果所必需的，则不能评估所有元素的谓词。 如果流为空，则返回false ，并且不评估谓词。

        这是一个short-circuiting terminal operation 。

        API Note:
        此方法评估谓词对流的元素的 存在量化 （对于某些x P（x））。
        参数
        predicate -一个 non-interfering ， stateless谓词适用于该流的元素
        结果
        true如果流的任何元素与提供的谓词匹配，否则为 false

      • allMatch

        boolean allMatch​(LongPredicate predicate)
        返回此流的所有元素是否与提供的谓词匹配。 如果不是确定结果所必需的，则不能评估所有元素的谓词。 如果流为空，则返回true ，并且不评估谓词。

        这是一个short-circuiting terminal operation 。

        API Note:
        此方法评估谓词对流的元素的通用量化 （对于所有x P（x））。 如果流是空的，则称量化是空心满足的并且始终为true （不管P（x））。
        参数
        predicate -一个 non-interfering ， stateless谓词适用于该流的元素
        结果
        true如果流的所有元素都与提供的谓词匹配或流为空，否则为 false

      • noneMatch

        boolean noneMatch​(LongPredicate predicate)
        返回此流的元素是否与提供的谓词匹配。 如果不是确定结果所必需的，则不能评估所有元素的谓词。 如果流为空，则返回true ，并且不评估谓词。

        这是一个short-circuiting terminal operation 。

        API Note:
        该方法评估否定谓词对流的元素的通用量化 （对于所有x~P（x））。 如果流是空的，则称量化是空心满足的，并且总是为true ，与P（x）无关。
        参数
        predicate -一个 non-interfering ， stateless谓词适用于该流的元素
        结果
        true如果流中没有元素与提供的谓词匹配或流为空，否则为 false

      • findFirst

        OptionalLong findFirst()
        返回OptionalLong描述此流的第一个元素，或空OptionalLong如果流是空的。 如果流没有遭遇顺序，则可以返回任何元素。

        这是一个short-circuiting terminal operation 。

        结果
        一个 OptionalLong描述此流的第一个元素，或空 OptionalLong如果流是空

      • findAny

        OptionalLong findAny()
        返回OptionalLong描述流的一些元件，或一个空OptionalLong如果流是空的。

        这是一个short-circuiting terminal operation 。

        此操作的行为明确是不确定的; 可以自由选择流中的任何元素。 这是为了在并行操作中实现最大性能; 成本是同一源上的多次调用可能不会返回相同的结果。 （如果需要稳定的结果，请改用findFirst()。 ）

        结果
        一个 OptionalLong描述该流的一些元件，或一个空 OptionalLong如果流是空
        另请参见：
        findFirst()

      • asDoubleStream

        DoubleStream asDoubleStream()
        返回DoubleStream包含此流的元素，转换为double 。

        这是intermediate operation 。

        结果
        a DoubleStream由此流的元素组成，转换为 double

      • boxed

        Stream<Long> boxed()
        返回Stream包含此流的元素，每个元素都Long 。

        这是intermediate operation 。

        结果
        一个 Stream这个流的元素一致，每个盒装为 Long

      • builder

        static LongStream.Builder builder()
        返回 LongStream的构建器。
        结果
        流构建器

      • empty

        static LongStream empty()
        返回空序列 LongStream 。
        结果
        一个空的顺序流

      • of

        static LongStream of​(long t)
        返回包含单个元素的顺序 LongStream 。
        参数
        t - 单个元素
        结果
        单例顺序流

      • of

        static LongStream of​(long... values)
        返回其元素为指定值的顺序有序流。
        参数
        values - 新流的元素
        结果
        新流

      • iterate

        static LongStream iterate​(long seed,
                          LongUnaryOperator f)
        返回有序无限连续LongStream由函数的迭代应用产生f到初始元素seed ，产生Stream组成的seed ， f(seed) ， f(f(seed))等

        第一元件（位置0在） LongStream将是提供seed 。 对于n > 0 ，位置n处的元素将是将函数f应用于位置n - 1处的元素的n - 1 。

        施加的作用f为一个元件happens-before施加的作用f用于随后的元件。 对于任何给定元素，可以在库选择的任何线程中执行操作。

        参数
        seed - 初始元素
        f - 要应用于前一个元素以生成新元素的函数
        结果
        一个新的顺序 LongStream

      • iterate

        static LongStream iterate​(long seed,
                          LongPredicate hasNext,
                          LongUnaryOperator next)
        返回通过将给定的next函数迭代应用于初始元素LongStream生成的顺序有序LongStream ，条件是满足给定的hasNext谓词。 一旦hasNext谓词返回false，流就会终止。

        LongStream.iterate应该生成与相应的for循环生成的元素序列相同的元素： 

           for (long index=seed; hasNext.test(index); index = next.applyAsLong(index)) { ... }

        如果hasNext谓词不保留种子值，则结果序列可能为空。 否则，第一个元素将是提供的seed值，下一个元素（如果存在）将是将next函数应用于seed值的结果，依此类推，直到hasNext谓词指示流应该终止。

        将hasNext谓词应用于元素happens-before将next函数应用于该元素的操作的操作。 对一个元素应用next函数的操作发生在将hasNext谓词应用于后续元素的操作之前 。 对于任何给定元素，可以在库选择的任何线程中执行动作。

        参数
        seed - 初始元素
        hasNext - 应用于元素以确定流何时必须终止的谓词。
        next - 要应用于前一个元素以生成新元素的函数
        结果
        一个新的顺序 LongStream
        从以下版本开始：
        9

      • generate

        static LongStream generate​(LongSupplier s)
        返回无限顺序无序流，其中每个元素由提供的LongSupplier生成。 这适用于生成恒定流，随机元素流等。
        参数
        s - 生成的元素的 LongSupplier
        结果
        一个新的无限顺序无序 LongStream

      • range

        static LongStream range​(long startInclusive,
                        long endExclusive)
        返回有序的顺序 LongStream从 startInclusive （含）至 endExclusive由增量步骤（独家） 1 。
        API Note:

        可以使用for循环顺序生成等效的递增值序列，如下所示： 

           for (long i = startInclusive; i < endExclusive ; i++) { ... }
        参数
        startInclusive - （包含）初始值
        endExclusive - 独家上限
        结果
        顺序 LongStream ，范围为 long元素

      • rangeClosed

        static LongStream rangeClosed​(long startInclusive,
                              long endInclusive)
        从 startInclusive （含）到 endInclusive （含）返回顺序有序 LongStream ，增量步长为 1 。
        API Note:

        可以使用for循环顺序生成等效的递增值序列，如下所示： 

           for (long i = startInclusive; i <= endInclusive ; i++) { ... }
        参数
        startInclusive - （包含）初始值
        endInclusive - 包含上限
        结果
        顺序 LongStream ，范围为 long元素

      • concat

        static LongStream concat​(LongStream a,
                         LongStream b)
        创建一个延迟连接的流，其元素是第一个流的所有元素，后跟第二个流的所有元素。 如果两个输入流都是有序的，则对所得到的流进行排序，如果任一输入流是并行的，则对其进行并行。 关闭结果流时，将调用两个输入流的关闭处理程序。

        此方法对两个输入流进行操作，并将每个流绑定到其源。 结果，对输入流源的后续修改可能不会反映在级联流结果中。

        API Note:
        为了保留优化机会，此方法将每个流绑定到其源，并仅接受两个流作为参数。 例如，如果已知每个输入流源的确切大小，则可以计算级联流源的确切大小。 要在不绑定的情况下连接更多流，或者不对此方法进行嵌套调用，请尝试使用标识函数创建流和平面映射流，例如： 
           LongStream concat = Stream.of(s1, s2, s3, s4).flatMapToLong(s -> s);
        Implementation Note:
        从重复串联构造流时要小心。 访问深度连接的流的元素可能会导致深度调用链，甚至StackOverflowError 。
        参数
        a - 第一个流
        b - 第二个流
        结果
        两个输入流的串联