Class BiStream<K,​V>

  • All Implemented Interfaces:
    java.lang.AutoCloseable

    public abstract class BiStream<K,​V>
    extends java.lang.Object
    implements java.lang.AutoCloseable
    A class similar to Stream, but operating over a sequence of pairs of objects.

    Note: For ease of reference, this class uses 'key' and 'value' to refer to each of the two parts of each pair in the sequence. However, both 'key' and 'value' can be any object of the appropriate type, or null. There is no implication that keys or key-value pairs are unique, or that keys can be compared for equality. You may equivalently read them as 'left' and 'right', or 'first' and 'second'.

    If the contents of the stream aren't identifiably 'keys' or 'values', and the methods with 'key' or 'value' in their name are distracting, consider using the pair-wise operations. For instance, instead of:

    
     BiStream.from(cities.stream(), City::population, City::latitude)
         .filterKeys(p -> p > 10000);
     
    you might use:
    
     BiStream.from(cities.stream(), City::population, City::latitude)
         .filter((population, lat) -> population > 10000);
     

    Keys and values are allowed to be null by default unless explicitly documented otherwise.

    Some methods (e.g. mapKeys()) come in two versions, one taking BiFunction (which will receive both key and value) and another taking Function (which in this case will receive only the key) . They operate equivalently otherwise.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  BiStream.Builder<K,​V>
      Builder for BiStream.
      static interface  BiStream.Partitioner<A,​B>
      A predicate used to partition a BiStream into sub-groups of consecutive pairs.
    • Method Summary

      Modifier and Type Method Description
      abstract boolean allMatch​(java.util.function.BiPredicate<? super K,​? super V> predicate)
      Returns true if all pairs in this stream match predicate.
      abstract boolean anyMatch​(java.util.function.BiPredicate<? super K,​? super V> predicate)
      Returns true if any pair in this stream matches predicate.
      BiStream<K,​V> append​(BiStream<? extends K,​? extends V> other)
      Returns a BiStream consisting of the pairs in this stream, followed by the pairs in other.
      BiStream<K,​V> append​(K key, V value)
      Returns a BiStream consisting of the pairs in this stream, followed by the pair of key and value.
      static <T> BiStream<T,​T> biStream​(java.util.Collection<T> elements)
      Short-hand for from(elements, identity(), identity()).
      static <T> BiStream<T,​T> biStream​(java.util.stream.Stream<T> elements)
      Short-hand for from(elements, identity(), identity()).
      static <K,​V>
      BiStream.Builder<K,​V>
      builder()
      Returns a new BiStream.Builder.
      abstract void close()
      Closes any resources associated with this stream, typically used in a try-with-resources statement.
      abstract <A> A collect​(A container, BiAccumulator<? super A,​? super K,​? super V> accumulator)
      Performs mutable reduction, as in collect(ImmutableMap.builder(), ImmutableMap.Builder::put).
      abstract <R> R collect​(BiCollector<? super K,​? super V,​R> collector)
      Returns an object of type R that is the result of collecting the pairs in this stream using collector.
      static <K,​V>
      BiStream<K,​V>
      concat​(BiStream<? extends K,​? extends V> s1, BiStream<? extends K,​? extends V> s2, BiStream<? extends K,​? extends V>... rest)
      Returns a BiStream of the entries from s1, s2 then rest in encounter order.
      static <K,​V>
      BiStream<K,​V>
      concat​(java.util.Map<? extends K,​? extends V> m1, java.util.Map<? extends K,​? extends V> m2, java.util.Map<? extends K,​? extends V>... rest)
      Returns a BiStream of the entries from m1, m2 then rest in encounter order.
      static <K,​V>
      BiStream<K,​V>
      concat​(java.util.stream.Stream<? extends BiStream<? extends K,​? extends V>> biStreams)
      Returns a BiStream of pairs from biStreams concatenated in encounter order.
      static <T,​K,​V>
      java.util.stream.Collector<T,​?,​BiStream<K,​V>>
      concatenating​(java.util.function.Function<? super T,​? extends BiStream<? extends K,​? extends V>> toBiStream)
      Returns a Collector that concatenates BiStream objects derived from the input elements using the given toBiStream function.
      static <T> BiStream<T,​java.lang.Long> consecutiveRunsFrom​(java.util.stream.Stream<T> stream)
      Deprecated.
      Use biStream(stream).groupConsecutiveBy(identity(), counting()) instead.
      static <K,​T,​A,​R>
      BiStream<K,​R>
      consecutiveRunsFrom​(java.util.stream.Stream<T> stream, java.util.function.Function<? super T,​? extends K> by, java.util.stream.Collector<? super T,​A,​R> runSummarizer)
      Deprecated.
      Use biStream(stream).groupConsecutiveBy(by, runSummarizer) instead.
      static <T,​R>
      BiStream<T,​R>
      consecutiveRunsFrom​(java.util.stream.Stream<T> stream, java.util.stream.Collector<? super T,​?,​R> runSummarizer)
      long count()
      Returns the count of pairs in this stream.
      static <L,​R>
      java.util.stream.Collector<L,​?,​BiStream<L,​R>>
      crossJoining​(java.util.stream.Stream<R> right)
      Returns a Collector that will pair each input element with each element from right into a new BiStream.
      BiStream<K,​V> distinct()
      Returns a BiStream consisting of only the distinct pairs (according to Object.equals(Object) for both key and value).
      static <K,​V>
      BiStream<K,​V>
      empty()
      Returns an empty BiStream.
      BiStream<K,​V> filter​(java.util.function.BiPredicate<? super K,​? super V> predicate)
      Filter this stream to only pairs matching predicate.
      BiStream<K,​V> filterKeys​(java.util.function.Predicate<? super K> predicate)
      Filter this stream to only pairs whose key matches predicate.
      BiStream<K,​V> filterValues​(java.util.function.Predicate<? super V> predicate)
      Filter this stream to only pairs whose value matches predicate.
      BiOptional<K,​V> findAny()
      Returns any pair from this stream, or BiOptional.empty() if the stream is empty.
      BiOptional<K,​V> findFirst()
      Returns the first pair from this stream, or BiOptional.empty() if the stream is empty.
      <K2,​V2>
      BiStream<K2,​V2>
      flatMap​(java.util.function.BiFunction<? super K,​? super V,​? extends BiStream<? extends K2,​? extends V2>> mapper)
      Maps each pair in this stream to zero or more pairs in another BiStream.
      <K2> BiStream<K2,​V> flatMapKeys​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.stream.Stream<? extends K2>> keyMapper)
      Maps each key to zero or more keys of type K2.
      <K2> BiStream<K2,​V> flatMapKeys​(java.util.function.Function<? super K,​? extends java.util.stream.Stream<? extends K2>> keyMapper)
      Maps each key to zero or more keys of type K2.
      java.util.stream.DoubleStream flatMapToDouble​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.stream.DoubleStream> mapper)
      Maps a single pair to zero or more doubles.
      java.util.stream.IntStream flatMapToInt​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.stream.IntStream> mapper)
      Maps a single pair to zero or more ints.
      java.util.stream.LongStream flatMapToLong​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.stream.LongStream> mapper)
      Maps a single pair to zero or more longs.
      <T> java.util.stream.Stream<T> flatMapToObj​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.stream.Stream<? extends T>> mapper)
      Maps a single pair to zero or more objects of type T.
      <V2> BiStream<K,​V2> flatMapValues​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.stream.Stream<? extends V2>> valueMapper)
      Maps each value to zero or more values of type V2.
      <V2> BiStream<K,​V2> flatMapValues​(java.util.function.Function<? super V,​? extends java.util.stream.Stream<? extends V2>> valueMapper)
      Maps each value to zero or more values of type V2.
      abstract void forEach​(java.util.function.BiConsumer<? super K,​? super V> action)
      Performs action for each pair in this stream.
      abstract void forEachOrdered​(java.util.function.BiConsumer<? super K,​? super V> consumer)
      Performs action for each pair in this stream, in order.
      static <K,​V>
      BiStream<K,​V>
      from​(java.util.Collection<? extends java.util.Map.Entry<? extends K,​? extends V>> entries)
      Returns a BiStream of the key value pairs from entries.
      static <T,​K,​V>
      BiStream<K,​V>
      from​(java.util.Collection<T> elements, DualValuedFunction<? super T,​? extends K,​? extends V> mapper)
      Deprecated.
      Use from(Stream) instead.
      static <T,​K,​V>
      BiStream<K,​V>
      from​(java.util.Collection<T> elements, java.util.function.Function<? super T,​? extends K> toKey, java.util.function.Function<? super T,​? extends V> toValue)
      Returns a BiStream of elements, each transformed to a pair of values with toKey and toValue.
      static <K,​V>
      BiStream<K,​V>
      from​(java.util.Map<K,​V> map)
      Returns a BiStream of the entries in map.
      static <K,​V>
      BiStream<K,​V>
      from​(java.util.stream.Stream<? extends Both<? extends K,​? extends V>> pairs)
      Returns a BiStream of the pairs from stream.
      static <T,​K,​V>
      BiStream<K,​V>
      from​(java.util.stream.Stream<T> stream, DualValuedFunction<? super T,​? extends K,​? extends V> mapper)
      Deprecated.
      Use from(Stream) instead.
      static <T,​K,​V>
      BiStream<K,​V>
      from​(java.util.stream.Stream<T> stream, java.util.function.Function<? super T,​? extends K> toKey, java.util.function.Function<? super T,​? extends V> toValue)
      Returns a BiStream of the elements from stream, each transformed to a pair of values with toKey and toValue.
      <G,​A,​R>
      BiStream<G,​R>
      groupConsecutiveBy​(java.util.function.BiFunction<? super K,​? super V,​? extends G> classifier, BiCollector<? super K,​? super V,​R> groupCollector)
      Returns a BiStream consisting of consecutive groupings from this stream.
      <G> BiStream<G,​V> groupConsecutiveBy​(java.util.function.Function<? super K,​? extends G> classifier, java.util.function.BinaryOperator<V> groupReducer)
      Returns a lazy BiStream of the consecutive groups of pairs from this stream.
      <G,​A,​R>
      BiStream<G,​R>
      groupConsecutiveBy​(java.util.function.Function<? super K,​? extends G> classifier, java.util.stream.Collector<? super V,​A,​? extends R> groupCollector)
      Returns a BiStream consisting of consecutive groupings from this stream.
      <R> java.util.stream.Stream<R> groupConsecutiveIf​(BiStream.Partitioner<? super K,​? super V> sameGroup, BiCollector<? super K,​? super V,​R> groupCollector)
      Returns a lazy Stream of the consecutive groups of values from this stream.
      java.util.stream.Stream<V> groupConsecutiveIf​(java.util.function.BiPredicate<? super K,​? super K> sameGroup, java.util.function.BinaryOperator<V> groupReducer)
      Returns a lazy Stream of the consecutive groups of values from this stream.
      <A,​R>
      java.util.stream.Stream<R>
      groupConsecutiveIf​(java.util.function.BiPredicate<? super K,​? super K> sameGroup, java.util.stream.Collector<? super V,​A,​R> groupCollector)
      Returns a lazy Stream of the consecutive groups of values from this stream.
      static <T,​K,​V>
      java.util.stream.Collector<T,​?,​BiStream<K,​V>>
      grouping​(java.util.function.Function<? super T,​? extends BiStream<? extends K,​? extends V>> toKeyValues, java.util.function.BinaryOperator<V> reducer)
      Deprecated.
      Use MoreStreams.flatMapping(toKeyValues, BiCollectors.groupingBy(k -> k, reducer)).
      static <T,​K,​V,​R>
      java.util.stream.Collector<T,​?,​BiStream<K,​R>>
      grouping​(java.util.function.Function<? super T,​? extends BiStream<? extends K,​? extends V>> toKeyValues, java.util.stream.Collector<? super V,​?,​R> valueCollector)
      Deprecated.
      Use MoreStreams.flatMapping(toKeyValues, BiCollectors.groupingBy(k -> k, reducer)).
      static <T,​K>
      java.util.stream.Collector<T,​?,​BiStream<K,​java.util.List<T>>>
      groupingBy​(java.util.function.Function<? super T,​? extends K> classifier)
      Returns a Collector that groups the input elements by classifier and collects the values mapping to the same key into a List.
      static <T,​K,​V>
      java.util.stream.Collector<T,​?,​BiStream<K,​V>>
      groupingBy​(java.util.function.Function<? super T,​? extends K> classifier, java.util.function.Function<? super T,​? extends V> mapper, java.util.function.BinaryOperator<V> reducer)
      Returns a Collector that groups the input elements by classifier and reduces the values mapping to the same key using mapper then reducer.
      static <T,​K,​V>
      java.util.stream.Collector<T,​?,​BiStream<K,​V>>
      groupingBy​(java.util.function.Function<? super T,​? extends K> classifier, java.util.stream.Collector<? super T,​?,​V> valueCollector)
      Returns a Collector that groups the input elements by classifier and collects the values mapping to the same key using valueCollector.
      static <K,​V>
      java.util.stream.Collector<V,​?,​BiStream<K,​V>>
      groupingBy​(java.util.function.Function<? super V,​? extends K> classifier, java.util.function.BinaryOperator<V> reducer)
      Returns a Collector that groups the input elements by classifier and reduces the values mapping to the same key using reducer.
      abstract BiStream<V,​K> inverse()
      Returns a BiStream where each pair is a pair from this stream with the key and value swapped.
      java.util.stream.Stream<K> keys()
      Returns a Stream consisting of only the keys from each pair in this stream.
      abstract BiStream<K,​V> limit​(int maxSize)
      Returns a BiStream consisting of the only the first maxSize pairs of this stream.
      <K2,​V2>
      BiStream<K2,​V2>
      map​(java.util.function.BiFunction<? super K,​? super V,​? extends Both<? extends K2,​? extends V2>> mapper)
      Returns a BiStream consisting of the result pairs of applying mapper to the pairs in this BiStream.
      <K2,​V2>
      BiStream<K2,​V2>
      map​(java.util.function.BiFunction<? super K,​? super V,​? extends K2> keyMapper, java.util.function.BiFunction<? super K,​? super V,​? extends V2> valueMapper)
      Returns a BiStream consisting of the results of applying keyMapper and valueMapper to the pairs in this BiStream.
      <K2,​V2>
      BiStream<K2,​V2>
      mapIfPresent​(java.util.function.BiFunction<? super K,​? super V,​? extends BiOptional<? extends K2,​? extends V2>> mapper)
      Returns a BiStream consisting of the results of applying mapper function to the pairs in this BiStream.
      <K2,​V2>
      BiStream<K2,​V2>
      mapIfPresent​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.Optional<? extends K2>> keyMapper, java.util.function.BiFunction<? super K,​? super V,​? extends java.util.Optional<? extends V2>> valueMapper)
      Deprecated.
      <K2> BiStream<K2,​V> mapKeys​(java.util.function.BiFunction<? super K,​? super V,​? extends K2> keyMapper)
      Returns a BiStream of pairs whose keys are the result of applying keyMapper to the key of each pair in this BiStream, and whose values are unchanged.
      abstract <K2> BiStream<K2,​V> mapKeys​(java.util.function.Function<? super K,​? extends K2> keyMapper)
      Maps each key to another key of type K2.
      <K2> BiStream<K2,​V> mapKeysIfPresent​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.Optional<? extends K2>> keyMapper)
      Returns a BiStream of pairs whose keys are the result of applying keyMapper to each pair in this BiStream, and whose values are unchanged.
      <K2> BiStream<K2,​V> mapKeysIfPresent​(java.util.function.Function<? super K,​? extends java.util.Optional<? extends K2>> keyMapper)
      Returns a BiStream of pairs whose keys are the result of applying keyMapper to the key of each pair in this BiStream, and whose values are unchanged.
      <K2> BiStream<K2,​V> mapKeysIfPresent​(java.util.Map<? super K,​? extends K2> keyMapping)
      Given keyMapping that maps the keys of type K to elements of type K2, returns a BiStream of type <K2, V>.
      abstract java.util.stream.DoubleStream mapToDouble​(java.util.function.ToDoubleBiFunction<? super K,​? super V> mapper)
      Returns a DoubleStream consisting of the results of applying mapper to the pairs in this BiStream.
      abstract java.util.stream.IntStream mapToInt​(java.util.function.ToIntBiFunction<? super K,​? super V> mapper)
      Returns an IntStream consisting of the results of applying mapper to the pairs in this BiStream.
      abstract java.util.stream.LongStream mapToLong​(java.util.function.ToLongBiFunction<? super K,​? super V> mapper)
      Returns a LongStream consisting of the results of applying mapper to the pairs in this BiStream.
      abstract <T> java.util.stream.Stream<T> mapToObj​(java.util.function.BiFunction<? super K,​? super V,​? extends T> mapper)
      Returns a Stream consisting of the results of applying mapper to each pair in this BiStream.
      <T> java.util.stream.Stream<T> mapToObjIfPresent​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.Optional<? extends T>> mapper)
      Returns a Stream consisting of the results of applying mapper to each pair in this BiStream.
      <V2> BiStream<K,​V2> mapValues​(java.util.function.BiFunction<? super K,​? super V,​? extends V2> valueMapper)
      Maps each value to another value of type V2.
      abstract <V2> BiStream<K,​V2> mapValues​(java.util.function.Function<? super V,​? extends V2> valueMapper)
      Maps each value to another value of type V2.
      <V2> BiStream<K,​V2> mapValuesIfPresent​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.Optional<? extends V2>> valueMapper)
      Returns a BiStream of pairs whose values are the result of applying valueMapper to each pair in this BiStream, and whose keys are unchanged.
      <V2> BiStream<K,​V2> mapValuesIfPresent​(java.util.function.Function<? super V,​? extends java.util.Optional<? extends V2>> valueMapper)
      Returns a BiStream of pairs whose values are the result of applying valueMapper to the value of each pair in this BiStream, and whose keys are unchanged.
      <V2> BiStream<K,​V2> mapValuesIfPresent​(java.util.Map<? super V,​? extends V2> valueMapping)
      Given valueMapping that maps values of type V to result values of type V2, returns a BiStream of type <K, V2>.
      boolean noneMatch​(java.util.function.BiPredicate<? super K,​? super V> predicate)
      Returns true if no pairs in this stream match predicate.
      static <K,​V>
      BiStream<K,​V>
      of​(K key, V value)
      Returns a BiStream of a single pair containing key and value.
      static <K,​V>
      BiStream<K,​V>
      of​(K key1, V value1, K key2, V value2)
      Returns a BiStream of two pairs, containing the supplied keys and values.
      static <K,​V>
      BiStream<K,​V>
      of​(K key1, V value1, K key2, V value2, K key3, V value3)
      Returns a BiStream of three pairs, containing the supplied keys and values.
      BiStream<K,​V> peek​(java.util.function.BiConsumer<? super K,​? super V> action)
      Returns a BiStream consisting of the pairs of this stream, additionally invoking action on each pair as pairs are consumed from the resulting stream.
      static <I,​O>
      BiStream<I,​O>
      repeat​(java.util.function.Function<? super I,​? extends O> work, I initial, java.util.function.BiFunction<? super I,​? super O,​? extends java.util.Optional<? extends I>> increment)
      Returns a stream of the inputs and outputs from repeated applications of the work function.
      abstract BiStream<K,​V> skip​(int n)
      Returns a BiStream consisting of the remaining pairs from this stream, after discarding the first n pairs.
      BiStream<K,​V> skipIf​(java.util.function.BiPredicate<? super K,​? super V> predicate)
      Filter this stream to exclude pairs matching predicate.
      BiStream<K,​V> skipKeysIf​(java.util.function.Predicate<? super K> predicate)
      Filter this stream to exclude pairs whose key matches predicate.
      BiStream<K,​V> skipValuesIf​(java.util.function.Predicate<? super V> predicate)
      Filter this stream to exclude pairs whose value matches predicate.
      BiStream<K,​V> sorted​(BiComparator<? super K,​? super V> ordering)
      Returns a BiStream consisting of the pairs in this stream, in the order produced by applying ordering BiComparator between each pair.
      BiStream<K,​V> sorted​(java.util.Comparator<? super K> keyComparator, java.util.Comparator<? super V> valueComparator)
      Deprecated.
      BiStream<K,​V> sortedByKeys​(java.util.Comparator<? super K> comparator)
      Returns a BiStream consisting of the pairs in this stream, in the order produced by applying comparator on the keys of each pair.
      BiStream<K,​V> sortedByValues​(java.util.Comparator<? super V> comparator)
      Returns a BiStream consisting of the pairs in this stream, in the order produced by applying comparator on the values of each pair.
      static <T> java.util.stream.Collector<T,​?,​BiStream<T,​T>> toAdjacentPairs()
      Returns a Collector that accumulates every neighboring pair of elements into a new BiStream.
      static <T> java.util.stream.Collector<T,​?,​BiStream<T,​T>> toBiStream()
      Returns a Collector that copies each input element as a pair of itself into an equivalent BiStream.
      static <E,​K,​V>
      java.util.stream.Collector<E,​?,​BiStream<K,​V>>
      toBiStream​(DualValuedFunction<? super E,​? extends K,​? extends V> mapper)
      Deprecated.
      static <E,​K,​V>
      java.util.stream.Collector<E,​?,​BiStream<K,​V>>
      toBiStream​(java.util.function.Function<? super E,​? extends Both<? extends K,​? extends V>> toPair)
      Returns a Collector that splits each input element as a pair and collects them into a BiStream.
      static <E,​K,​V>
      java.util.stream.Collector<E,​?,​BiStream<K,​V>>
      toBiStream​(java.util.function.Function<? super E,​? extends K> toKey, java.util.function.Function<? super E,​? extends V> toValue)
      Returns a Collector that splits each input element as a pair and collects them into a BiStream.
      java.util.Map<K,​V> toMap()
      Returns an immutable Map that is the result of collecting the pairs in this stream.
      java.util.stream.Stream<V> values()
      Returns a Stream consisting of only the values from each pair in this stream.
      static <L,​R>
      BiStream<L,​R>
      zip​(java.util.Collection<L> left, java.util.Collection<R> right)
      Returns a BiStream in which the first element in left is paired with the first element in right; the second paired with the corresponding second and the third with the corresponding third etc.
      static <L,​R>
      BiStream<L,​R>
      zip​(java.util.stream.Stream<L> left, java.util.stream.Stream<R> right)
      Returns a BiStream in which the first element in left is paired with the first element in right; the second paired with the corresponding second and the third with the corresponding third etc.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • groupingBy

        public static <K,​V> java.util.stream.Collector<V,​?,​BiStream<K,​V>> groupingBy​(java.util.function.Function<? super V,​? extends K> classifier,
                                                                                                             java.util.function.BinaryOperator<V> reducer)
        Returns a Collector that groups the input elements by classifier and reduces the values mapping to the same key using reducer.
        
         ImmutableMap<CurrencyCode, Money> expenseByCurrency = expenses.stream()
             .collect(groupingBy(Money::currencyCode, Money::add))
             .collect(ImmutableMap::toImmutableMap);
         

        Entries are collected in encounter order.

        Since:
        3.3
      • groupingBy

        public static <T,​K,​V> java.util.stream.Collector<T,​?,​BiStream<K,​V>> groupingBy​(java.util.function.Function<? super T,​? extends K> classifier,
                                                                                                                     java.util.function.Function<? super T,​? extends V> mapper,
                                                                                                                     java.util.function.BinaryOperator<V> reducer)
        Returns a Collector that groups the input elements by classifier and reduces the values mapping to the same key using mapper then reducer.
        
         ImmutableMap<State, Money> householdIncomeByState = households.stream()
             .collect(groupingBy(Household::state, Household::income, Money::add))
             .collect(ImmutableMap::toImmutableMap);
         

        Entries are collected in encounter order.

        Since:
        3.3
      • groupingBy

        public static <T,​K> java.util.stream.Collector<T,​?,​BiStream<K,​java.util.List<T>>> groupingBy​(java.util.function.Function<? super T,​? extends K> classifier)
        Returns a Collector that groups the input elements by classifier and collects the values mapping to the same key into a List. Similar but different from Collectors.groupingBy(Function), this method collects the groups into BiStream() instead, allowing fluent method chaining. For example:
        
         Map<EmployeeId, List<Task>> employeesWithMultipleTasks = tasks.stream()
             .collect(BiStream.groupingBy(Task::assignedTo))
             .filterValues(tasks -> tasks.size() > 1)
             .toMap();
         
        Even if you don't need to chain more methods, using this collector allows you to fluently collect the results into the desired container type. For example toMap() collects to an immutable Map; or collect(Collectors::toConcurrentMap) if concurrency is needed.

        Entries are collected in encounter order.

        Since:
        3.0
      • groupingBy

        public static <T,​K,​V> java.util.stream.Collector<T,​?,​BiStream<K,​V>> groupingBy​(java.util.function.Function<? super T,​? extends K> classifier,
                                                                                                                     java.util.stream.Collector<? super T,​?,​V> valueCollector)
        Returns a Collector that groups the input elements by classifier and collects the values mapping to the same key using valueCollector. Similar but different from Collectors.groupingBy(Function, Collector), this method collects the groups into BiStream() instead, allowing fluent method chaining. For example:
        
         Map<EmployeeId, Integer> topTenEmployeesByWorkHour = projects.stream()
             .flatMap(project -> project.getMembers().stream())  // Stream<TeamMember>
             .collect(BiStream.groupingBy(TeamMember::employeeId, summingInt(TeamMember::hours)))
             .sortedByValues(Comparator.reverseOrder())
             .limit(10)
             .toMap();
         
        Even if you don't need to chain more methods, using this collector allows you to fluently collect the results into the desired container type. For example toMap() collects to an immutable Map; or you could supply collect(ImmutableBiMap::toImmutableBiMap) if BiMap is needed.

        Entries are collected in encounter order.

        Since:
        3.0
      • grouping

        @Deprecated
        public static <T,​K,​V,​R> java.util.stream.Collector<T,​?,​BiStream<K,​R>> grouping​(java.util.function.Function<? super T,​? extends BiStream<? extends K,​? extends V>> toKeyValues,
                                                                                                                           java.util.stream.Collector<? super V,​?,​R> valueCollector)
        Deprecated.
        Use MoreStreams.flatMapping(toKeyValues, BiCollectors.groupingBy(k -> k, reducer)).
      • grouping

        @Deprecated
        public static <T,​K,​V> java.util.stream.Collector<T,​?,​BiStream<K,​V>> grouping​(java.util.function.Function<? super T,​? extends BiStream<? extends K,​? extends V>> toKeyValues,
                                                                                                                   java.util.function.BinaryOperator<V> reducer)
        Deprecated.
        Use MoreStreams.flatMapping(toKeyValues, BiCollectors.groupingBy(k -> k, reducer)).
      • concatenating

        public static <T,​K,​V> java.util.stream.Collector<T,​?,​BiStream<K,​V>> concatenating​(java.util.function.Function<? super T,​? extends BiStream<? extends K,​? extends V>> toBiStream)
        Returns a Collector that concatenates BiStream objects derived from the input elements using the given toBiStream function.

        For example:

        
         Map<EmployeeId, Task> billableTaskAssignments = projects.stream()
             .collect(concatenating(p -> BiStream.from(p.getTaskAssignments())))
             .filterValues(Task::billable)
             .toMap();
         
        Since:
        3.0
      • crossJoining

        public static <L,​R> java.util.stream.Collector<L,​?,​BiStream<L,​R>> crossJoining​(java.util.stream.Stream<R> right)
        Returns a Collector that will pair each input element with each element from right into a new BiStream. For example:
        
         ImmutableList<QuarterlyReport> allQuarterlyReports = quarters.stream()
             .collect(crossJoining(departments))
             .mapToObj(QuarterlyReport::new)
             .collect(toImmutableList());
         

        The input elements are repeated once per element from right. For example: [1, 2, 3].collect(crossJoining([a, b])) will generate [{1, a}, {2, a}, {3, a}, {1, b}, {2, b}, {3, b}].

        The returned BiStream takes O(n) space where n is the size of the input elements. The "cross-joining" with the right stream is computed on-the-fly with O(1) memory cost.

        Since:
        3.0
      • toAdjacentPairs

        public static <T> java.util.stream.Collector<T,​?,​BiStream<T,​T>> toAdjacentPairs()
        Returns a Collector that accumulates every neighboring pair of elements into a new BiStream. For example Stream.of(1, 2, 3, 4).collect(toAdjacentPairs()) will return [{1, 2}, {2, 3}, {3, 4}].

        If the input has 0 or 1 elements then the output is an empty BiStream. Otherwise the length of the output BiStream is one less than the length of the input.

        Since:
        3.2
      • toBiStream

        public static <E,​K,​V> java.util.stream.Collector<E,​?,​BiStream<K,​V>> toBiStream​(java.util.function.Function<? super E,​? extends K> toKey,
                                                                                                                     java.util.function.Function<? super E,​? extends V> toValue)
        Returns a Collector that splits each input element as a pair and collects them into a BiStream.

        Note that it's more efficient to use BiStream.(stream, toKey, toValue) than stream.collect(toBiStream(toKey, toValue)). The latter is intended to be used in the middle of a long stream pipeline, when performance isn't critical.

        Since:
        3.2
      • toBiStream

        public static <E,​K,​V> java.util.stream.Collector<E,​?,​BiStream<K,​V>> toBiStream​(java.util.function.Function<? super E,​? extends Both<? extends K,​? extends V>> toPair)
        Returns a Collector that splits each input element as a pair and collects them into a BiStream.

        Note that it's more efficient to use BiStream.from(stream, toPair) than stream.collect(toBiStream(toPair)). The latter is intended to be used in the middle of a long stream pipeline, when performance isn't critical.

        Since:
        5.1
      • toBiStream

        @Deprecated
        public static <E,​K,​V> java.util.stream.Collector<E,​?,​BiStream<K,​V>> toBiStream​(DualValuedFunction<? super E,​? extends K,​? extends V> mapper)
        Deprecated.
        Returns a Collector that splits each input element into two values and collects them into a BiStream.

        Note that it's more efficient to use BiStream.from(stream, mapper) than stream.collect(toBiStream(mapper)). The latter is intended to be used in the middle of a long stream pipeline, when performance isn't critical.

        Since:
        4.6
      • toBiStream

        public static <T> java.util.stream.Collector<T,​?,​BiStream<T,​T>> toBiStream()
        Returns a Collector that copies each input element as a pair of itself into an equivalent BiStream.

        Note that it's more efficient to use biStream(stream) than stream.collect(toBiStream()). The latter is intended to be used in the middle of a long stream pipeline, when performance isn't critical.

        Since:
        3.6
      • empty

        public static <K,​V> BiStream<K,​V> empty()
        Returns an empty BiStream.
      • of

        public static <K,​V> BiStream<K,​V> of​(K key,
                                                         V value)
        Returns a BiStream of a single pair containing key and value.
      • of

        public static <K,​V> BiStream<K,​V> of​(K key1,
                                                         V value1,
                                                         K key2,
                                                         V value2)
        Returns a BiStream of two pairs, containing the supplied keys and values.
      • of

        public static <K,​V> BiStream<K,​V> of​(K key1,
                                                         V value1,
                                                         K key2,
                                                         V value2,
                                                         K key3,
                                                         V value3)
        Returns a BiStream of three pairs, containing the supplied keys and values.
      • concat

        @SafeVarargs
        public static <K,​V> BiStream<K,​V> concat​(java.util.Map<? extends K,​? extends V> m1,
                                                             java.util.Map<? extends K,​? extends V> m2,
                                                             java.util.Map<? extends K,​? extends V>... rest)
        Returns a BiStream of the entries from m1, m2 then rest in encounter order. For example:
        
         Map<AccountId, Account> allAccounts = concat(primaryAccounts, secondaryAccounts).toMap();
         
        Since:
        3.0
      • concat

        @SafeVarargs
        public static <K,​V> BiStream<K,​V> concat​(BiStream<? extends K,​? extends V> s1,
                                                             BiStream<? extends K,​? extends V> s2,
                                                             BiStream<? extends K,​? extends V>... rest)
        Returns a BiStream of the entries from s1, s2 then rest in encounter order. For example:
        
         Map<AccountId, Account> allAccounts = concat(primaryAccounts, secondaryAccounts).toMap();
         
        Since:
        4.7
      • concat

        public static <K,​V> BiStream<K,​V> concat​(java.util.stream.Stream<? extends BiStream<? extends K,​? extends V>> biStreams)
        Returns a BiStream of pairs from biStreams concatenated in encounter order.
        Since:
        3.0
      • zip

        public static <L,​R> BiStream<L,​R> zip​(java.util.Collection<L> left,
                                                          java.util.Collection<R> right)
        Returns a BiStream in which the first element in left is paired with the first element in right; the second paired with the corresponding second and the third with the corresponding third etc. For example: BiStream.zip(asList(1, 2, 3), asList("one", "two")) will return BiStream.of(1, "one", 2, "two").

        The resulting stream will only be as long as the shorter of the two iterables; if one is longer, its extra elements will be ignored.

        Since:
        3.0
      • zip

        public static <L,​R> BiStream<L,​R> zip​(java.util.stream.Stream<L> left,
                                                          java.util.stream.Stream<R> right)
        Returns a BiStream in which the first element in left is paired with the first element in right; the second paired with the corresponding second and the third with the corresponding third etc. For example: BiStream.zip(Stream.of(1, 2, 3), Stream.of("one", "two")) will return BiStream.of(1, "one", 2, "two").

        The resulting stream will only be as long as the shorter of the two input streams; if one stream is longer, its extra elements will be ignored.

        The resulting stream by default runs sequentially regardless of the input streams. This is because the implementation is not efficiently splittable. and may not perform well if run in parallel.

      • from

        public static <K,​V> BiStream<K,​V> from​(java.util.Map<K,​V> map)
        Returns a BiStream of the entries in map.
      • from

        public static <K,​V> BiStream<K,​V> from​(java.util.Collection<? extends java.util.Map.Entry<? extends K,​? extends V>> entries)
        Returns a BiStream of the key value pairs from entries. For example BiStream.from(multimap.entries()).
        Since:
        4.7
      • from

        public static <T,​K,​V> BiStream<K,​V> from​(java.util.Collection<T> elements,
                                                                   java.util.function.Function<? super T,​? extends K> toKey,
                                                                   java.util.function.Function<? super T,​? extends V> toValue)
        Returns a BiStream of elements, each transformed to a pair of values with toKey and toValue.
      • from

        public static <T,​K,​V> BiStream<K,​V> from​(java.util.stream.Stream<T> stream,
                                                                   java.util.function.Function<? super T,​? extends K> toKey,
                                                                   java.util.function.Function<? super T,​? extends V> toValue)
        Returns a BiStream of the elements from stream, each transformed to a pair of values with toKey and toValue.
      • from

        public static <K,​V> BiStream<K,​V> from​(java.util.stream.Stream<? extends Both<? extends K,​? extends V>> pairs)
        Returns a BiStream of the pairs from stream.
        Since:
        5.1
      • from

        @Deprecated
        public static <T,​K,​V> BiStream<K,​V> from​(java.util.Collection<T> elements,
                                                                   DualValuedFunction<? super T,​? extends K,​? extends V> mapper)
        Deprecated.
        Use from(Stream) instead.
        Returns a BiStream of the elements from stream, each transformed to a pair of values with mapper function.
        Since:
        4.6
      • from

        @Deprecated
        public static <T,​K,​V> BiStream<K,​V> from​(java.util.stream.Stream<T> stream,
                                                                   DualValuedFunction<? super T,​? extends K,​? extends V> mapper)
        Deprecated.
        Use from(Stream) instead.
        Returns a BiStream of the elements from stream, each transformed to a pair of values with mapper function.
        Since:
        4.6
      • repeat

        public static <I,​O> BiStream<I,​O> repeat​(java.util.function.Function<? super I,​? extends O> work,
                                                             I initial,
                                                             java.util.function.BiFunction<? super I,​? super O,​? extends java.util.Optional<? extends I>> increment)
        Returns a stream of the inputs and outputs from repeated applications of the work function. The initial input is passed to work for the first round, after which the increment function is called to determine the input for the next round. This process repeats until the increment function returns Optional.empty().

        A common use case is pagination. For example, if you have a list API with pagination support, the following code retrieves all pages eagerly:

        
         ImmutableList<Foo> listAllFoos() {
           ImmutableList.Builder<Foo> builder = ImmutableList.builder();
           ListFooRequest.Builder request = ListFooRequest.newBuilder()...;
             do {
               ListFooResponse response = service.listFoos(request.build());
               builder.addAll(response.getFoos());
               request.setPageToken(response.getNextPageToken());
             } while (!request.getPageToken().isEmpty());
           return builder.build();
         }
         
        You can turn the above code to a lazy stream so that callers can short-circuit when they need to without having to exhaust all pages:
        
         Stream<Foo> listAllFoos() {
           return BiStream.repeat(
                   service::listFoos,
                   initialRequest,
                   (request, response) ->
                       optional(
                           response.hasNextPageToken(),
                           request.toBuilder().setPageToken(response.getNextPageToken()).build()))
               .flatMapToObj((request, response) -> response.getAllFoos().stream());
         }
         
        Type Parameters:
        I - the input type
        O - the output type
        Parameters:
        work - the function to repeat. Null outputs are passed through as is.
        initial - the initial input to pass to the work function. Cannot be null.
        increment - the function to get the next input given the current input and output.
        Returns:
        A BiStream of the inputs and outputs of the work function. The stream is lazy in that work won't be called until the stream is being consumed; and it won't be called again until the second pair of input and output are being consumed, etc.
        Since:
        5.5
      • consecutiveRunsFrom

        @Deprecated
        public static <T> BiStream<T,​java.lang.Long> consecutiveRunsFrom​(java.util.stream.Stream<T> stream)
        Deprecated.
        Use biStream(stream).groupConsecutiveBy(identity(), counting()) instead.
        Returns a lazy BiStream of the consecutive runs of equal elements and their run-lengths from the input stream.

        For example, consecutiveRunsFrom([a, a, b, b, b, a]) will result in [{a, 2}, {b, 3}, {a, 1}].

        Null elements are allowed.

        Parameters:
        stream - the stream of input elements
        Since:
        5.3
      • consecutiveRunsFrom

        @Deprecated
        public static <T,​R> BiStream<T,​R> consecutiveRunsFrom​(java.util.stream.Stream<T> stream,
                                                                          java.util.stream.Collector<? super T,​?,​R> runSummarizer)
        Returns a BiStream of the consecutive runs of equal elements from the input stream.

        Consecutive null elements will be grouped in a "run" with null as the key.

        Since:
        5.2
      • consecutiveRunsFrom

        @Deprecated
        public static <K,​T,​A,​R> BiStream<K,​R> consecutiveRunsFrom​(java.util.stream.Stream<T> stream,
                                                                                          java.util.function.Function<? super T,​? extends K> by,
                                                                                          java.util.stream.Collector<? super T,​A,​R> runSummarizer)
        Deprecated.
        Use biStream(stream).groupConsecutiveBy(by, runSummarizer) instead.
        Returns a lazy BiStream of the consecutive runs of elements from the input stream. Elements in the same consecutive run share the same "key" according to the by function.

        The runSummarizer Collector is used to summarize the elements of each "run". For example you could use Collectors.summarizingDouble() to summarize stock price per day:

        
         consecutiveRunsFrom(stockPriceData, PriceDatum::day, summarizingDouble(PriceDatum::price)):
         

        For run-length encoding, use consecutiveRunsFrom(Stream).

        Null elements are allowed as long as the by function allows nulls.

        Parameters:
        stream - the stream of input elements
        by - the function to compute the key of each element
        runSummarizer - collector to summarize elements of the same "run"
        Since:
        5.2
      • mapToObj

        public abstract <T> java.util.stream.Stream<T> mapToObj​(java.util.function.BiFunction<? super K,​? super V,​? extends T> mapper)
        Returns a Stream consisting of the results of applying mapper to each pair in this BiStream.
      • mapToObjIfPresent

        public final <T> java.util.stream.Stream<T> mapToObjIfPresent​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.Optional<? extends T>> mapper)
        Returns a Stream consisting of the results of applying mapper to each pair in this BiStream. If mapper function returns empty, the pair is discarded.
        Since:
        4.7
      • map

        public <K2,​V2> BiStream<K2,​V2> map​(java.util.function.BiFunction<? super K,​? super V,​? extends K2> keyMapper,
                                                       java.util.function.BiFunction<? super K,​? super V,​? extends V2> valueMapper)
        Returns a BiStream consisting of the results of applying keyMapper and valueMapper to the pairs in this BiStream.
      • map

        public final <K2,​V2> BiStream<K2,​V2> map​(java.util.function.BiFunction<? super K,​? super V,​? extends Both<? extends K2,​? extends V2>> mapper)
        Returns a BiStream consisting of the result pairs of applying mapper to the pairs in this BiStream.

        For example, the following code parses each line read from a file in the format of "key: value", and upon expected format, reports the line number:

        
         import static com.google.mu.util.Substring.first;
        
         BiStream.zip(MoreStreams.indexesFrom(1), readLines().stream())
             .map((lineNumber, line) ->
                 first(':')
                     .splitThenTrim(line)
                     .orElseThrow(() -> new IllegalArgumentException("line: " + lineNumber)))
             ...;
         
        Since:
        5.2
      • mapIfPresent

        @Deprecated
        public final <K2,​V2> BiStream<K2,​V2> mapIfPresent​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.Optional<? extends K2>> keyMapper,
                                                                      java.util.function.BiFunction<? super K,​? super V,​? extends java.util.Optional<? extends V2>> valueMapper)
        Deprecated.
        Returns a BiStream consisting of the results of applying keyMapper and valueMapper to the pairs in this BiStream. If either keyMapper function or valueMapper function returns empty, the pair is discarded.
        Since:
        4.7
      • mapIfPresent

        public final <K2,​V2> BiStream<K2,​V2> mapIfPresent​(java.util.function.BiFunction<? super K,​? super V,​? extends BiOptional<? extends K2,​? extends V2>> mapper)
        Returns a BiStream consisting of the results of applying mapper function to the pairs in this BiStream. If mapper returns empty, the pair is discarded.
        Since:
        5.0
      • mapToDouble

        public abstract java.util.stream.DoubleStream mapToDouble​(java.util.function.ToDoubleBiFunction<? super K,​? super V> mapper)
        Returns a DoubleStream consisting of the results of applying mapper to the pairs in this BiStream.
      • mapToInt

        public abstract java.util.stream.IntStream mapToInt​(java.util.function.ToIntBiFunction<? super K,​? super V> mapper)
        Returns an IntStream consisting of the results of applying mapper to the pairs in this BiStream.
      • mapToLong

        public abstract java.util.stream.LongStream mapToLong​(java.util.function.ToLongBiFunction<? super K,​? super V> mapper)
        Returns a LongStream consisting of the results of applying mapper to the pairs in this BiStream.
      • mapKeys

        public <K2> BiStream<K2,​V> mapKeys​(java.util.function.BiFunction<? super K,​? super V,​? extends K2> keyMapper)
        Returns a BiStream of pairs whose keys are the result of applying keyMapper to the key of each pair in this BiStream, and whose values are unchanged.
      • mapKeys

        public abstract <K2> BiStream<K2,​V> mapKeys​(java.util.function.Function<? super K,​? extends K2> keyMapper)
        Maps each key to another key of type K2.
      • mapValues

        public <V2> BiStream<K,​V2> mapValues​(java.util.function.BiFunction<? super K,​? super V,​? extends V2> valueMapper)
        Maps each value to another value of type V2.
      • mapValues

        public abstract <V2> BiStream<K,​V2> mapValues​(java.util.function.Function<? super V,​? extends V2> valueMapper)
        Maps each value to another value of type V2.
      • flatMapToObj

        public final <T> java.util.stream.Stream<T> flatMapToObj​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.stream.Stream<? extends T>> mapper)
        Maps a single pair to zero or more objects of type T.

        If a mapped stream is null, an empty stream is used instead.

      • flatMapToDouble

        public final java.util.stream.DoubleStream flatMapToDouble​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.stream.DoubleStream> mapper)
        Maps a single pair to zero or more doubles.

        If a mapped stream is null, an empty stream is used instead.

      • flatMapToInt

        public final java.util.stream.IntStream flatMapToInt​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.stream.IntStream> mapper)
        Maps a single pair to zero or more ints.

        If a mapped stream is null, an empty stream is used instead.

      • flatMapToLong

        public final java.util.stream.LongStream flatMapToLong​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.stream.LongStream> mapper)
        Maps a single pair to zero or more longs.

        If a mapped stream is null, an empty stream is used instead.

      • flatMap

        public final <K2,​V2> BiStream<K2,​V2> flatMap​(java.util.function.BiFunction<? super K,​? super V,​? extends BiStream<? extends K2,​? extends V2>> mapper)
        Maps each pair in this stream to zero or more pairs in another BiStream. For example the following code snippet repeats each pair in a BiStream for 3 times:
        
         BiStream<K, V> repeated = stream.flatMap((k, v) -> BiStream.of(k, v, k, v, k, v));
         

        If a mapped stream is null, an empty stream is used instead.

      • flatMapKeys

        public final <K2> BiStream<K2,​V> flatMapKeys​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.stream.Stream<? extends K2>> keyMapper)
        Maps each key to zero or more keys of type K2.

        If a mapped stream is null, an empty stream is used instead.

      • flatMapKeys

        public final <K2> BiStream<K2,​V> flatMapKeys​(java.util.function.Function<? super K,​? extends java.util.stream.Stream<? extends K2>> keyMapper)
        Maps each key to zero or more keys of type K2.

        If a mapped stream is null, an empty stream is used instead.

      • mapKeysIfPresent

        public final <K2> BiStream<K2,​V> mapKeysIfPresent​(java.util.Map<? super K,​? extends K2> keyMapping)
        Given keyMapping that maps the keys of type K to elements of type K2, returns a BiStream of type <K2, V>.

        Keys not found in keyMap (or mapped to null) are discarded.

        For example, if you need to turn a BiStream<StudentId, Score> to BiStream<Student, Score> by looking up the student id in a Map<StudentId, Student>, you can do:

        
         Map<StudentId, Score> scores = ...;
         BiStream.from(scores)
             .mapKeysIfPresent(studentsMap)
             ...;
         

        The above code is equivalent to the following variants:

        
         Map<StudentId, Score> scores = ...;
         BiStream.from(scores)
             .mapKeys(studentsMap::get)
             .mapKeys(Optional::ofNullable)
             .flatMapKeys(Streams::stream)
             ...;
         
        or:
        
         Map<StudentId, Score> scores = ...;
         BiStream.from(scores)
             .mapKeys(studentsMap::get)
             .filterKeys(Objects::nonNull)
             ...;
         
        Since:
        4.7
      • mapKeysIfPresent

        public final <K2> BiStream<K2,​V> mapKeysIfPresent​(java.util.function.Function<? super K,​? extends java.util.Optional<? extends K2>> keyMapper)
        Returns a BiStream of pairs whose keys are the result of applying keyMapper to the key of each pair in this BiStream, and whose values are unchanged. If keyMapper function returns empty, the pair is discarded.

        For example the following code counts the total number of unique patients per hospital, from doctors' affiliated hospitals:

        
         Map<Doctor, Patient> doctorAndPatients = ...;
         Map<Hospital, Long> hospitalPatientCounts =
            BiStream.from(doctorAndPatients)
                .mapKeysIfPresent(Doctor::optionalAffliatedHospital)
                .collect(toImmutableMap(counting()));
         
        Since:
        4.7
      • mapKeysIfPresent

        public final <K2> BiStream<K2,​V> mapKeysIfPresent​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.Optional<? extends K2>> keyMapper)
        Returns a BiStream of pairs whose keys are the result of applying keyMapper to each pair in this BiStream, and whose values are unchanged. If keyMapper function returns empty, the pair is discarded.
        Since:
        4.7
      • flatMapValues

        public final <V2> BiStream<K,​V2> flatMapValues​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.stream.Stream<? extends V2>> valueMapper)
        Maps each value to zero or more values of type V2.

        If a mapped stream is null, an empty stream is used instead.

      • flatMapValues

        public final <V2> BiStream<K,​V2> flatMapValues​(java.util.function.Function<? super V,​? extends java.util.stream.Stream<? extends V2>> valueMapper)
        Maps each value to zero or more values of type V2.

        If a mapped stream is null, an empty stream is used instead.

      • mapValuesIfPresent

        public final <V2> BiStream<K,​V2> mapValuesIfPresent​(java.util.Map<? super V,​? extends V2> valueMapping)
        Given valueMapping that maps values of type V to result values of type V2, returns a BiStream of type <K, V2>.

        Values not found in valueMap (or mapped to null) are discarded.

        For example, if you need to turn a Multimap<ClassId, StudentId> to Multimap<ClassId, Student> by looking up the student id in a Map<StudentId, Student>, you can do:

        
         Multimap<ClassId, StudentId> registration = ...;
         ImmutableSetMultimap<ClassId, Student> roster = BiStream.from(registration)
             .mapValuesIfPresent(studentsMap)
             .collect(toImmutableSetMultimap());
         

        The above code is equivalent to the following variants:

        
         Multimap<ClassId, StudentId> registration = ...;
         ImmutableSetMultimap<ClassId, Student> roster = BiStream.from(registration)
             .mapValues(studentsMap::get)
             .mapValues(Optional::ofNullable)
             .flatMapValues(Streams::stream)
             .collect(toImmutableSetMultimap());
         
        or:
        
         Multimap<ClassId, StudentId> registration = ...;
         ImmutableSetMultimap<ClassId, Student> roster = BiStream.from(registration)
             .mapValues(studentsMap::get)
             .filterValues(Objects::nonNull)
             .collect(toImmutableSetMultimap());
         
        Since:
        4.7
      • mapValuesIfPresent

        public final <V2> BiStream<K,​V2> mapValuesIfPresent​(java.util.function.Function<? super V,​? extends java.util.Optional<? extends V2>> valueMapper)
        Returns a BiStream of pairs whose values are the result of applying valueMapper to the value of each pair in this BiStream, and whose keys are unchanged. If valueMapper function returns empty, the pair is discarded.

        For example the following code collects all unique insurance companies per doctor:

        
         Map<Doctor, Patient> doctorAndPatients = ...;
         ImmutableSetMultimap<Doctor, InsuranceCompany> insurancesPerDoctor =
            BiStream.from(doctorAndPatients)
                .mapValuesIfPresent(Partient::optionalInsurarnce)
                .collect(toImmutableSetMultimap());
         
        Since:
        4.7
      • mapValuesIfPresent

        public final <V2> BiStream<K,​V2> mapValuesIfPresent​(java.util.function.BiFunction<? super K,​? super V,​? extends java.util.Optional<? extends V2>> valueMapper)
        Returns a BiStream of pairs whose values are the result of applying valueMapper to each pair in this BiStream, and whose keys are unchanged. If valueMapper function returns empty, the pair is discarded.
        Since:
        4.7
      • peek

        public final BiStream<K,​V> peek​(java.util.function.BiConsumer<? super K,​? super V> action)
        Returns a BiStream consisting of the pairs of this stream, additionally invoking action on each pair as pairs are consumed from the resulting stream.
      • filter

        public final BiStream<K,​V> filter​(java.util.function.BiPredicate<? super K,​? super V> predicate)
        Filter this stream to only pairs matching predicate.

        Note that if you are passing in a lambda with the ! operator, consider using skipIf(java.util.function.BiPredicate<? super K, ? super V>) instead that might even allow you to use method reference.

      • filterKeys

        public final BiStream<K,​V> filterKeys​(java.util.function.Predicate<? super K> predicate)
        Filter this stream to only pairs whose key matches predicate.

        Note that if you are passing in a lambda with the ! operator, consider using skipKeysIf(java.util.function.Predicate<? super K>) instead that might even allow you to use method reference.

      • filterValues

        public final BiStream<K,​V> filterValues​(java.util.function.Predicate<? super V> predicate)
        Filter this stream to only pairs whose value matches predicate.

        Note that if you are passing in a lambda with the ! operator, consider using skipValuesIf(java.util.function.Predicate<? super V>) instead that might even allow you to use method reference.

      • skipIf

        public final BiStream<K,​V> skipIf​(java.util.function.BiPredicate<? super K,​? super V> predicate)
        Filter this stream to exclude pairs matching predicate.

        Useful especially when it allows you to use method reference. For example:

        
         tasks.stream()
              .collect(crossJoining(Arrays.stream(MachineType.values()))
              .skipIf(Worker::blacklistsMachine)
              ...
         
        Since:
        5.1
      • skipKeysIf

        public final BiStream<K,​V> skipKeysIf​(java.util.function.Predicate<? super K> predicate)
        Filter this stream to exclude pairs whose key matches predicate.

        Useful especially when it allows you to use method reference. For example:

        
         BiStream.from(rosters)
              .skipKeysIf(inactiveUserIds::contains)
              ...
         
        Since:
        5.1
      • skipValuesIf

        public final BiStream<K,​V> skipValuesIf​(java.util.function.Predicate<? super V> predicate)
        Filter this stream to exclude pairs whose value matches predicate.

        Useful especially when it allows you to use method reference. For example:

        
         BiStream.zip(userIds, userNames)
              .skipValuesIf(String::isEmpty)
              ...
         
        Since:
        5.1
      • append

        public final BiStream<K,​V> append​(BiStream<? extends K,​? extends V> other)
        Returns a BiStream consisting of the pairs in this stream, followed by the pairs in other.
      • append

        public final BiStream<K,​V> append​(K key,
                                                V value)
        Returns a BiStream consisting of the pairs in this stream, followed by the pair of key and value.
      • keys

        public final java.util.stream.Stream<K> keys()
        Returns a Stream consisting of only the keys from each pair in this stream.
      • values

        public final java.util.stream.Stream<V> values()
        Returns a Stream consisting of only the values from each pair in this stream.
      • inverse

        public abstract BiStream<V,​K> inverse()
        Returns a BiStream where each pair is a pair from this stream with the key and value swapped.
      • forEach

        public abstract void forEach​(java.util.function.BiConsumer<? super K,​? super V> action)
        Performs action for each pair in this stream.
      • forEachOrdered

        public abstract void forEachOrdered​(java.util.function.BiConsumer<? super K,​? super V> consumer)
        Performs action for each pair in this stream, in order.
      • allMatch

        public abstract boolean allMatch​(java.util.function.BiPredicate<? super K,​? super V> predicate)
        Returns true if all pairs in this stream match predicate.
      • anyMatch

        public abstract boolean anyMatch​(java.util.function.BiPredicate<? super K,​? super V> predicate)
        Returns true if any pair in this stream matches predicate.
      • noneMatch

        public final boolean noneMatch​(java.util.function.BiPredicate<? super K,​? super V> predicate)
        Returns true if no pairs in this stream match predicate.
      • findFirst

        public final BiOptional<K,​V> findFirst()
        Returns the first pair from this stream, or BiOptional.empty() if the stream is empty.
        Throws:
        java.lang.NullPointerException - if the chosen pair includes null
        Since:
        5.0
      • findAny

        public final BiOptional<K,​V> findAny()
        Returns any pair from this stream, or BiOptional.empty() if the stream is empty.
        Throws:
        java.lang.NullPointerException - if the chosen pair includes null
        Since:
        5.0
      • limit

        public abstract BiStream<K,​V> limit​(int maxSize)
        Returns a BiStream consisting of the only the first maxSize pairs of this stream.
      • skip

        public abstract BiStream<K,​V> skip​(int n)
        Returns a BiStream consisting of the remaining pairs from this stream, after discarding the first n pairs.
      • distinct

        public final BiStream<K,​V> distinct()
        Returns a BiStream consisting of only the distinct pairs (according to Object.equals(Object) for both key and value).
      • sorted

        @Deprecated
        public final BiStream<K,​V> sorted​(java.util.Comparator<? super K> keyComparator,
                                                java.util.Comparator<? super V> valueComparator)
        Deprecated.
        Returns a BiStream consisting of the pairs in this stream, in the order produced by applying keyComparator on the keys of each pair, and then for equal keys, applying valueComparator on the values of each pair.
      • sortedByKeys

        public final BiStream<K,​V> sortedByKeys​(java.util.Comparator<? super K> comparator)
        Returns a BiStream consisting of the pairs in this stream, in the order produced by applying comparator on the keys of each pair.
      • sortedByValues

        public final BiStream<K,​V> sortedByValues​(java.util.Comparator<? super V> comparator)
        Returns a BiStream consisting of the pairs in this stream, in the order produced by applying comparator on the values of each pair.
      • sorted

        public final BiStream<K,​V> sorted​(BiComparator<? super K,​? super V> ordering)
        Returns a BiStream consisting of the pairs in this stream, in the order produced by applying ordering BiComparator between each pair.

        The following example first sorts by household income and then by address:

        
         import static com.google.mu.function.BiComparator.comparingKey;
         import static com.google.mu.function.BiComparator.comparingValue;
        
         Map<Address, Household> households = ...;
         List<Household> householdsByIncomeThenAddress =
             BiStream.from(households)
                 .sorted(comparingValue(Household::income).then(comparingKey(naturalOrder()))
                 .values()
                 .collect(toList());
         
        Since:
        4.7
      • count

        public final long count()
        Returns the count of pairs in this stream.
      • toMap

        public final java.util.Map<K,​V> toMap()
        Returns an immutable Map that is the result of collecting the pairs in this stream. If a duplicate key is encountered, throws an IllegalStateException.

        While this is a convenient shortcut of collect(Collectors::toMap), if you have a BiStream<SubFoo, SubBar>, the return type of toMap() will be Map<SubFoo, SubBar>. To collect to Map<Foo, Bar>, use the equivalent collect(Collectors::toMap) or collect(BiCollectors.toMap()).

      • collect

        public abstract <R> R collect​(BiCollector<? super K,​? super V,​R> collector)
        Returns an object of type R that is the result of collecting the pairs in this stream using collector.

        Please note that any Collector-returning factory method can be directly "method referenced" as BiCollector if it accepts two Function parameters corresponding to the "key" and the "value" parts respectively. For example: collect(Collectors::toConcurrentMap), collect(ImmutableSetMultimap::toImmutableSetMultimap), collect(Maps::toImmutableEnumMap), collect(ImmutableBiMap::toImmutableBiMap).

        In addition, check out BiCollectors for some other useful BiCollector implementations.

      • collect

        public abstract <A> A collect​(A container,
                                      BiAccumulator<? super A,​? super K,​? super V> accumulator)
        Performs mutable reduction, as in collect(ImmutableMap.builder(), ImmutableMap.Builder::put).

        More realistically (since you'd likely use collect(toImmutableMap()) instead for ImmutableMap), you could collect pairs into two repeated proto fields:

        
           BiStream.zip(shardRequests, shardResponses)
               .filter(...)
               .collect(
                   BatchResponse.newBuilder(),
                   (builder, req, resp) -> builder.addShardRequest(req).addShardResponse(resp))
               .build();
         

        While collect(BiCollector) may perform parallel reduction if the underlying stream is parallel, this reduction is guaranteed to be sequential and single-threaded.

        Returns the populated container instance.

        Since:
        5.0
      • close

        public abstract void close()
        Closes any resources associated with this stream, typically used in a try-with-resources statement.
        Specified by:
        close in interface java.lang.AutoCloseable
      • groupConsecutiveBy

        public final <G,​A,​R> BiStream<G,​R> groupConsecutiveBy​(java.util.function.Function<? super K,​? extends G> classifier,
                                                                                java.util.stream.Collector<? super V,​A,​? extends R> groupCollector)
        Returns a BiStream consisting of consecutive groupings from this stream. Consecutive pairs whose key maps to the same group according to classifier will have their values grouped together using groupCollector.

        For example to lazily summarize a large, pre-sorted stock price data stream per day:

        
         biStream(stockPriceData)
             .groupConsecutiveBy(PriceDatum::day, summarizingDouble(PriceDatum::price))
             .toMap();
         

        Unlike JDK groupingBy() collectors, the returned BiStream consumes the input elements lazily and only requires O(groupCollector) space for the current consecutive elements group. For instance the groupConsecutiveBy(Event::type, counting()) stream takes O(1) space. While this makes it more efficient to process large streams, the input data often need to be pre-sorted for the grouping to be useful.

        To apply grouping beyond consecutive elements, use collect(BiCollectors.groupingBy(classifier, groupCollector)) instead.

        Consecutive keys mapped to null by classifier will be grouped together.

        Parameters:
        classifier - The function to determine the group key. Because it's guaranteed to be invoked once and only once per entry, and that the returned BiStream is sequential and respects encounter order, this function is allowed to have side effects.
        Since:
        5.4
      • groupConsecutiveBy

        public final <G> BiStream<G,​V> groupConsecutiveBy​(java.util.function.Function<? super K,​? extends G> classifier,
                                                                java.util.function.BinaryOperator<V> groupReducer)
        Returns a lazy BiStream of the consecutive groups of pairs from this stream. Consecutive pairs whose key maps to the same group according to classifier will have their values reduced using the groupReducer function.

        For example to lazily find the daily opening stock price from a large, pre-sorted stock data stream:

        
         biStream(stockPriceDataSortedByTime)
             .groupConsecutiveBy(PriceDatum::day, (a, b) -> a)
             ,toMap();
         

        Unlike JDK groupingBy() collectors, the returned BiStream consumes the input elements lazily and only requires O(1) space. While this makes it more efficient to process large streams, the input data often need to be pre-sorted for the grouping to be useful.

        To apply grouping beyond consecutive elements, use collect(BiCollectors.groupingBy(classifier, groupReducer)) instead.

        Consecutive null keys are grouped together.

        Parameters:
        classifier - The function to determine the group key. Because it's guaranteed to be invoked once and only once per entry, and that the returned BiStream is sequential and respects encounter order, this function is allowed to have side effects.
        Since:
        5.4
      • groupConsecutiveBy

        public final <G,​A,​R> BiStream<G,​R> groupConsecutiveBy​(java.util.function.BiFunction<? super K,​? super V,​? extends G> classifier,
                                                                                BiCollector<? super K,​? super V,​R> groupCollector)
        Returns a BiStream consisting of consecutive groupings from this stream. Consecutive pairs mapping to the same group according to classifier will be grouped together using groupCollector.

        This can be useful when you need to apply nested groupings, for example, to first group consecutive events by year, then by continuity (happened within 24 hours):

        
         import static com.google.mu.util.stream.BiiCollectors.collectingAndThen;
        
         ImmutableListMultimap<Integer, List<Event>> continuousEventsByYear =
             biStream(events)
                 .mapKeys(Event::date)
                 .groupConsecutiveBy(
                     (date, event) -> date.year(),
                     collectingAndThen(
                         annual -> annual.groupConsecutiveIf(
                             (d1, d2) -> Duration.between(d1, d2).compareTo(Duration.ofHours(24)) < 0,
                             toList())))
                 .collect(flatteningToImmutableListMultimap(subgroups -> subgroups));
         

        Unlike JDK groupingBy() collectors, the returned BiStream consumes the input elements lazily and only requires O(groupCollector) space for the current consecutive elements group. For instance the groupConsecutiveBy(Event::type, counting()) stream takes O(1) space. While this makes it more efficient to process large streams, the input data often need to be pre-sorted for the grouping to be useful.

        To apply grouping beyond consecutive elements, use collect(BiCollectors.groupingBy(classifier, groupCollector)) instead.

        Consecutive pairs mapped to null by classifier will be grouped together.

        Parameters:
        classifier - The function to determine the group key. Because it's guaranteed to be invoked once and only once per entry, and that the returned BiStream is sequential and respects encounter order, this function is allowed to have side effects.
        Since:
        5.5
      • groupConsecutiveIf

        public final <R> java.util.stream.Stream<R> groupConsecutiveIf​(BiStream.Partitioner<? super K,​? super V> sameGroup,
                                                                       BiCollector<? super K,​? super V,​R> groupCollector)
        Returns a lazy Stream of the consecutive groups of values from this stream. Two consecutive entries belong to the same group if sameGroup.belong(key1, value1, key2, valuue2) is true. Pairs belonging to the same group are grouped together using groupCollector.

        The sameGroup predicate is always evaluated with two consecutive pairs in encounter order.

        The following example identifies price changes above a gap threshold from a stock's historical price:

        
         Map<DateTime, Double> historicalPrices = ...;
         ImmutableList<ImmutableMap<DateTime, Double>> priceClusters =
             biStream(historicalPrices)
                 .groupConsecutiveIf((d1, p1, d2, p2) -> abs(p1 - p2) < gap, toImmutableMap())
                 .collect(toImmutableList());
         

        Unlike JDK groupingBy() collectors, the returned Stream consumes the input elements lazily and only requires O(groupCollector) space for the current consecutive elements group. While this makes it more efficient to process large streams, the input data often need to be pre-sorted for the grouping to be useful.

        Null elements are allowed as long as the sameGroup predicate and groupCollector allow nulls.

        Since:
        5.6
      • groupConsecutiveIf

        public final <A,​R> java.util.stream.Stream<R> groupConsecutiveIf​(java.util.function.BiPredicate<? super K,​? super K> sameGroup,
                                                                               java.util.stream.Collector<? super V,​A,​R> groupCollector)
        Returns a lazy Stream of the consecutive groups of values from this stream. Two consecutive entries belong to the same group if sameGroup.test(key1, key2) is true. Values belonging to the same group are grouped together using groupCollector.

        The sameGroup predicate is always evaluated with two consecutive keys in encounter order.

        The following example identifies price changes above a gap threshold from a stock's historical price:

        
         Stream<DoubleSummaryStatistics> priceClusters =
             biStream(stockPriceData)
                 .groupConsecutiveIf((a, b) -> abs(a - b) < gap, summarizingDouble());
         

        Unlike JDK groupingBy() collectors, the returned Stream consumes the input elements lazily and only requires O(groupCollector) space for the current consecutive elements group. While this makes it more efficient to process large streams, the input data often need to be pre-sorted for the grouping to be useful.

        Null elements are allowed as long as the sameGroup predicate and groupCollector allow nulls.

        Since:
        5.4
      • groupConsecutiveIf

        public final java.util.stream.Stream<V> groupConsecutiveIf​(java.util.function.BiPredicate<? super K,​? super K> sameGroup,
                                                                   java.util.function.BinaryOperator<V> groupReducer)
        Returns a lazy Stream of the consecutive groups of values from this stream. Two consecutive entries belong to the same group if sameGroup.test(key1, key2) is true. Values belonging to the same group are reduced using groupReducer.

        The sameGroup predicate is always evaluated with two consecutive keys in encounter order.

        Unlike JDK groupingBy() collectors, the returned Stream consumes the input elements lazily and only requires O(groupCollector) space for the current consecutive elements group. While this makes it more efficient to process large streams, the input data often need to be pre-sorted for the grouping to be useful.

        Null elements are allowed as long as the sameGroup predicate and groupCollector allow nulls.

        Since:
        5.4