Package com.google.mu.util

Class BiOptional<A,B>

java.lang.Object
com.google.mu.util.BiOptional<A,B>
public abstract class BiOptional<A,B> extends Object
An optional pair of values; either the pair is present with both values, or is absent with no value.

This is essentially an Optional<Pair> that users can access through fluent methods like map(java.util.function.BiFunction<? super A, ? super B, ? extends T>), filter(java.util.function.BiPredicate<? super A, ? super B>), or(java.util.function.Supplier<? extends com.google.mu.util.BiOptional<? extends A, ? extends B>>) instead of opaque names like first, second.

Since:
5.0

  • Method Summary

    Modifier and Type
    Method
    Description
    static <A, B> BiOptional<A,B>
    empty()
    Returns an empty BiOptional instance.
    abstract BiOptional<A,B>
    filter(BiPredicate<? super A,? super B> predicate)
    If a pair of values is present and matches predicate, return this BiOptional instance.
    abstract <T> Optional<T>
    flatMap(BiFunction<? super A,? super B,? extends Optional<? extends T>> mapper)
    If a pair of values is present, apply the BiOptional-bearing mapper to them, and return that result.
    static <T, A, B> BiOptional<A,B>
    flatMap(Optional<T> optional, Function<? super T,? extends BiOptional<? extends A,? extends B>> mapper)
    Maps the value contained in optional to a BiOptional using mapper, or else returns empty.
    static <T> BiOptional<T,T>
    from(Optional<T> optional)
    If optional is present with value v, adapts it to BiOptional containing values (v, v).
    abstract void
    ifPresent(BiConsumer<? super A,? super B> consumer)
    If a pair of values is present, invoke consumer with them.
    abstract boolean
    isPresent()
    Returns true if the pair of values is present.
    abstract <A2, B2> BiOptional<A2,B2>
    map(BiFunction<? super A,? super B,? extends A2> aMapper, BiFunction<? super A,? super B,? extends B2> bMapper)
    If a pair of values is present, apply aMapper and bMapper to them, and if both results are non-null, return a new BiOptional instance containing the results.
    abstract <T> Optional<T>
    map(BiFunction<? super A,? super B,? extends T> mapper)
    If a pair of values is present, apply mapper to them, and if the result is non-null, return an Optional containing it.
    abstract <A2, B2> BiOptional<A2,B2>
    map(Function<? super A,? extends A2> aMapper, Function<? super B,? extends B2> bMapper)
    If a pair of values is present, apply aMapper and bMapper to each respectively, and if both results are non-null, return a new BiOptional instance containing the results.
    abstract boolean
    matches(BiPredicate<? super A,? super B> condition)
    Returns true if the pair exists and satisfies the condition predicate.
    static <A, B> BiOptional<A,B>
    of(A a, B b)
    Returns a BiOptional containing the pair (a, b).
    abstract BiOptional<A,B>
    or(Supplier<? extends BiOptional<? extends A,? extends B>> alternative)
    If a pair of values are present, return this BiOptional instance.
    abstract Both<A,B>
    orElse(A a, B b)
    Returns the pair if present, or else returns (a, b).
    abstract Both<A,B>
    orElseThrow()
    Ensures that the pair must be present or else throws NoSuchElementException.
    final <E extends Throwable>
    Both<A,B>
    orElseThrow(String message, Object... args)
    Ensures that the pair must be present or else throws NoSuchElementException with message formatted with args.
    final <E extends Throwable>
    Both<A,B>
    orElseThrow(Function<String,E> exceptionFactory, String message, Object... args)
    Ensures that the pair must be present or else throws the exception returned by exceptionFactory with message formatted with args.
    abstract <E extends Throwable>
    Both<A,B>
    orElseThrow(Supplier<E> exceptionSupplier)
    Ensures that the pair must be present or else throws the exception returned by exceptionSupplier.
    abstract BiOptional<A,B>
    peek(BiConsumer<? super A,? super B> consumer)
    Invokes consumer with the pair if present and returns this object as is.
    BiOptional<A,B>
    skipIf(BiPredicate<? super A,? super B> predicate)
    If a pair of values is present and matches predicate, the pair is skipped (returns empty).
    abstract BiStream<A,B>
    stream()
    Returns a BiStream view of this BiOptional.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • empty

      public static <A, B> BiOptional<A,B> empty()
      Returns an empty BiOptional instance.

    • of

      public static <A, B> BiOptional<A,B> of(A a, B b)
      Returns a BiOptional containing the pair (a, b).
      Throws:
      NullPointerException - if either a or b is null

    • from

      public static <T> BiOptional<T,T> from(Optional<T> optional)
      If optional is present with value v, adapts it to BiOptional containing values (v, v).
      Throws:
      NullPointerException - if optional is null.

    • map

      public abstract <T> Optional<T> map(BiFunction<? super A,? super B,? extends T> mapper)
      If a pair of values is present, apply mapper to them, and if the result is non-null, return an Optional containing it. Otherwise return an empty Optional.
      Throws:
      NullPointerException - if mapper is null

    • map

      public abstract <A2, B2> BiOptional<A2,B2> map(BiFunction<? super A,? super B,? extends A2> aMapper, BiFunction<? super A,? super B,? extends B2> bMapper)
      If a pair of values is present, apply aMapper and bMapper to them, and if both results are non-null, return a new BiOptional instance containing the results. Otherwise return an empty BiOptional.
      Throws:
      NullPointerException - if aMapper or bMapper is null

    • map

      public abstract <A2, B2> BiOptional<A2,B2> map(Function<? super A,? extends A2> aMapper, Function<? super B,? extends B2> bMapper)
      If a pair of values is present, apply aMapper and bMapper to each respectively, and if both results are non-null, return a new BiOptional instance containing the results. Otherwise return an empty BiOptional.

      The following example parses and evaluates a numeric comparison: 

      
 if (Substring.first('=')
     .splitThenTrim("10 = 20")
     .map(Ints::tryParse, Ints::tryParse)
     .filter((a, b) -> a.equals(b))
     .isPresent()) {
   // The two numbers are equal.
 }
      Throws:
      NullPointerException - if aMapper or bMapper is null

    • flatMap

      public abstract <T> Optional<T> flatMap(BiFunction<? super A,? super B,? extends Optional<? extends T>> mapper)
      If a pair of values is present, apply the BiOptional-bearing mapper to them, and return that result. Otherwise, return an empty BiOptional.
      Throws:
      NullPointerException - if mapper is null or returns a null result

    • flatMap

      public static <T, A, B> BiOptional<A,B> flatMap(Optional<T> optional, Function<? super T,? extends BiOptional<? extends A,? extends B>> mapper)
      Maps the value contained in optional to a BiOptional using mapper, or else returns empty. For example, the following code uses Substring.Pattern.split(java.lang.CharSequence) to split an optional string: 
      
 Optional<KeyValue> keyValue =
     BiOptional.flatMap(getOptionalInput(), Substring.first(':')::split)
         .map(KeyValue::new);

      Use this method to bridge from an Optional to BiOptional chain.

      Throws:
      NullPointerException - if optional or mapper is null, or if mapper returns null.

    • filter

      public abstract BiOptional<A,B> filter(BiPredicate<? super A,? super B> predicate)
      If a pair of values is present and matches predicate, return this BiOptional instance. Otherwise, return an empty BiOptional.
      Throws:
      NullPointerException - if predicate is null

    • skipIf

      public BiOptional<A,B> skipIf(BiPredicate<? super A,? super B> predicate)
      If a pair of values is present and matches predicate, the pair is skipped (returns empty).
      Throws:
      NullPointerException - if predicate is null
      Since:
      6.6

    • peek

      public abstract BiOptional<A,B> peek(BiConsumer<? super A,? super B> consumer)
      Invokes consumer with the pair if present and returns this object as is.
      Throws:
      NullPointerException - if consumer is null
      Since:
      5.1

    • matches

      public abstract boolean matches(BiPredicate<? super A,? super B> condition)
      Returns true if the pair exists and satisfies the condition predicate.
      Since:
      5.7

    • ifPresent

      public abstract void ifPresent(BiConsumer<? super A,? super B> consumer)
      If a pair of values is present, invoke consumer with them. Otherwise, do nothing.
      Throws:
      NullPointerException - if consumer is null

    • isPresent

      public abstract boolean isPresent()
      Returns true if the pair of values is present.

    • or

      public abstract BiOptional<A,B> or(Supplier<? extends BiOptional<? extends A,? extends B>> alternative)
      If a pair of values are present, return this BiOptional instance. Otherwise, returns a BiOptional produced by alternative.

    • orElse

      public abstract Both<A,B> orElse(A a, B b)
      Returns the pair if present, or else returns (a, b). a and b are allowed to be null.
      Since:
      5.1

    • orElseThrow

      public abstract Both<A,B> orElseThrow()
      Ensures that the pair must be present or else throws NoSuchElementException.
      Since:
      5.1

    • orElseThrow

      public abstract <E extends Throwable> Both<A,B> orElseThrow(Supplier<E> exceptionSupplier) throws E
      Ensures that the pair must be present or else throws the exception returned by exceptionSupplier.
      Throws:
      NullPointerException - if exceptionSupplier is null, or returns null.
      E - if the pair is absent.
      Since:
      5.1

    • orElseThrow

      public final <E extends Throwable> Both<A,B> orElseThrow(String message, Object... args) throws E
      Ensures that the pair must be present or else throws NoSuchElementException with message formatted with args.
      Throws:
      NullPointerException - if message is null, or if exceptionFactory returns null.
      NoSuchElementException - if the pair is absent.
      E
      Since:
      7.2

    • orElseThrow

      public final <E extends Throwable> Both<A,B> orElseThrow(Function<String,E> exceptionFactory, String message, Object... args) throws E
      Ensures that the pair must be present or else throws the exception returned by exceptionFactory with message formatted with args.
      Throws:
      NullPointerException - if exceptionFactory or message is null, or if exceptionFactory returns null.
      E - if the pair is absent.
      Since:
      6.6

    • stream

      public abstract BiStream<A,B> stream()
      Returns a BiStream view of this BiOptional.