// Path: mug/src/main/java/com/google/mu/util/InternalCollectors.java
// static <T> Collector<T, ?, Set<T>> toImmutableSet() {
//   return checkingNulls(
//       collectingAndThen(toCollection(LinkedHashSet::new), Collections::unmodifiableSet));
// }
// 
// Path: mug/src/main/java/com/google/mu/function/CheckedFunction.java
// @FunctionalInterface
// public interface CheckedFunction<F, T, E extends Throwable> {
//   T apply(F from) throws E;
// 
//   /**
//    * Returns a new {@code CheckedFunction} that maps the return value using {@code mapper}.
//    * For example: {@code (x -> x).andThen(Object::toString).apply(1) => "1"}.
//    */
//   default <R> CheckedFunction<F, R, E> andThen(
//       CheckedFunction<? super T, ? extends R, ? extends E> mapper) {
//     requireNonNull(mapper);
//     return f -> mapper.apply(apply(f));
//   }
// }


import static com.google.mu.util.InternalCollectors.toImmutableSet;
import static java.util.Objects.requireNonNull;
import static java.util.stream.Collectors.collectingAndThen;
import static java.util.stream.Collectors.reducing;
import static java.util.stream.Collectors.toCollection;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Optional;
import java.util.Set;
import java.util.stream.Collector;
import com.google.mu.function.CheckedFunction;
/*****************************************************************************
 * ------------------------------------------------------------------------- *
 * Licensed under the Apache License, Version 2.0 (the "License");           *
 * you may not use this file except in compliance with the License.          *
 * You may obtain a copy of the License at                                   *
 *                                                                           *
 * http://www.apache.org/licenses/LICENSE-2.0                                *
 *                                                                           *
 * Unless required by applicable law or agreed to in writing, software       *
 * distributed under the License is distributed on an "AS IS" BASIS,         *
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  *
 * See the License for the specific language governing permissions and       *
 * limitations under the License.                                            *
 *****************************************************************************/
package com.google.mu.util;




/**
 * An immutable selection of choices supporting both {@link #only limited} and {@link #all
 * unlimited} selections.
 *
 * <p>Useful when you need to disambiguate and enforce correct handling of the
 * <b>implicitly selected all</b> concept, in replacement of the common and error prone
 * <em>empty-means-all</em> hack. That is, instead of adding (or forgetting to add) special
 * handling like:
 *
 * <pre>{@code
 *   Set<String> choices = getChoices();
 *   if (choices.isEmpty() || choices.contains("foo")) {
 *     // foo is selected.
 *   }
 * }</pre>
 *
 * Use {@code Selection} so your code is intuitive and hard to get wrong:
 *
 * <pre>{@code
 *   Selection<String> choices = getChoices();
 *   if (choices.has("foo")) {
 *     // foo is selected.
 *   }
 * }</pre>
 *
 * <p>To gradually migrate from legacy code where empty sets need to be special handled all over,
 * use {@link #nonEmptyOrAll nonEmptyOrAll(set)} to convert to a {@code Selection} object:
 *
 * <pre>{@code
 *   public class FoodDeliveryService {
 *     private final Selection<Driver> eligibleDrivers;
 *
 *     // Too much code churn to change this public constructor signature.
 *     public FoodDeliveryService(Set<Driver> eligibleDrivers) {
 *       // But we can migrate internal implementation to using Selection:
 *       this.eligibleDrivers = Selection.nonEmptyOrAll(eligibleDrivers);
 *     }
 *
 *     ...
 *   }
 * }</pre>
 *
 * <p>While an unlimited selection is conceptually close to a trivially-true predicate, the {@code
 * Selection} type provides access to the explicitly selected choices via the {@link #limited}
 * method. It also implements {@link #equals}, {@link #hashCode} and {@link #toString} sensibly.
 *
 * <p>Nulls are prohibited throughout this class.
 *
 * @since 4.1
 */
public interface Selection<T> {
  /** Returns an unlimited selection of all (unspecified) choices. */
  @SuppressWarnings("unchecked")
  static <T> Selection<T> all() {
    return (Selection<T>) Selections.ALL;
  }

  /** Returns an empty selection. */
  @SuppressWarnings("unchecked")
  static <T> Selection<T> none() {
    return (Selection<T>) Selections.NONE;
  }

  /** Returns a selection of {@code choices}. Null is not allowed. */
  @SafeVarargs
  static <T> Selection<T> only(T... choices) {
    return Arrays.stream(choices).collect(toSelection());
  }

  /**
   * Converts to {@code Selection} from legacy code where an empty collection means <b>all</b>.
   * After converted to {@code Selection}, user code no longer need special handling of the
   * <em>empty</em> case.
   *
   * <p>This method is mainly for migrating legacy code. If you have a set where empty just means
   * "none" with no special handling needed, you should use {@link #toSelection
   * set.stream().collect(toSelection())} instead.
   */
  static <T> Selection<T> nonEmptyOrAll(Collection<? extends T> choices) {
    return choices.isEmpty() ? all() : choices.stream().collect(toSelection());
  }

  /** Returns a collector that collects input elements into a limited selection. */
  static <T> Collector<T, ?, Selection<T>> toSelection() {
// Path: mug/src/main/java/com/google/mu/util/InternalCollectors.java
// static <T> Collector<T, ?, Set<T>> toImmutableSet() {
//   return checkingNulls(
//       collectingAndThen(toCollection(LinkedHashSet::new), Collections::unmodifiableSet));
// }
// 
// Path: mug/src/main/java/com/google/mu/function/CheckedFunction.java
// @FunctionalInterface
// public interface CheckedFunction<F, T, E extends Throwable> {
//   T apply(F from) throws E;
// 
//   /**
//    * Returns a new {@code CheckedFunction} that maps the return value using {@code mapper}.
//    * For example: {@code (x -> x).andThen(Object::toString).apply(1) => "1"}.
//    */
//   default <R> CheckedFunction<F, R, E> andThen(
//       CheckedFunction<? super T, ? extends R, ? extends E> mapper) {
//     requireNonNull(mapper);
//     return f -> mapper.apply(apply(f));
//   }
// }


// Path: mug/src/main/java/com/google/mu/util/Selection.java
import static com.google.mu.util.InternalCollectors.toImmutableSet;
import static java.util.Objects.requireNonNull;
import static java.util.stream.Collectors.collectingAndThen;
import static java.util.stream.Collectors.reducing;
import static java.util.stream.Collectors.toCollection;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Optional;
import java.util.Set;
import java.util.stream.Collector;
import com.google.mu.function.CheckedFunction;

/*****************************************************************************
 * ------------------------------------------------------------------------- *
 * Licensed under the Apache License, Version 2.0 (the "License");           *
 * you may not use this file except in compliance with the License.          *
 * You may obtain a copy of the License at                                   *
 *                                                                           *
 * http://www.apache.org/licenses/LICENSE-2.0                                *
 *                                                                           *
 * Unless required by applicable law or agreed to in writing, software       *
 * distributed under the License is distributed on an "AS IS" BASIS,         *
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  *
 * See the License for the specific language governing permissions and       *
 * limitations under the License.                                            *
 *****************************************************************************/
package com.google.mu.util;




/**
 * An immutable selection of choices supporting both {@link #only limited} and {@link #all
 * unlimited} selections.
 *
 * <p>Useful when you need to disambiguate and enforce correct handling of the
 * <b>implicitly selected all</b> concept, in replacement of the common and error prone
 * <em>empty-means-all</em> hack. That is, instead of adding (or forgetting to add) special
 * handling like:
 *
 * <pre>{@code
 *   Set<String> choices = getChoices();
 *   if (choices.isEmpty() || choices.contains("foo")) {
 *     // foo is selected.
 *   }
 * }</pre>
 *
 * Use {@code Selection} so your code is intuitive and hard to get wrong:
 *
 * <pre>{@code
 *   Selection<String> choices = getChoices();
 *   if (choices.has("foo")) {
 *     // foo is selected.
 *   }
 * }</pre>
 *
 * <p>To gradually migrate from legacy code where empty sets need to be special handled all over,
 * use {@link #nonEmptyOrAll nonEmptyOrAll(set)} to convert to a {@code Selection} object:
 *
 * <pre>{@code
 *   public class FoodDeliveryService {
 *     private final Selection<Driver> eligibleDrivers;
 *
 *     // Too much code churn to change this public constructor signature.
 *     public FoodDeliveryService(Set<Driver> eligibleDrivers) {
 *       // But we can migrate internal implementation to using Selection:
 *       this.eligibleDrivers = Selection.nonEmptyOrAll(eligibleDrivers);
 *     }
 *
 *     ...
 *   }
 * }</pre>
 *
 * <p>While an unlimited selection is conceptually close to a trivially-true predicate, the {@code
 * Selection} type provides access to the explicitly selected choices via the {@link #limited}
 * method. It also implements {@link #equals}, {@link #hashCode} and {@link #toString} sensibly.
 *
 * <p>Nulls are prohibited throughout this class.
 *
 * @since 4.1
 */
public interface Selection<T> {
  /** Returns an unlimited selection of all (unspecified) choices. */
  @SuppressWarnings("unchecked")
  static <T> Selection<T> all() {
    return (Selection<T>) Selections.ALL;
  }

  /** Returns an empty selection. */
  @SuppressWarnings("unchecked")
  static <T> Selection<T> none() {
    return (Selection<T>) Selections.NONE;
  }

  /** Returns a selection of {@code choices}. Null is not allowed. */
  @SafeVarargs
  static <T> Selection<T> only(T... choices) {
    return Arrays.stream(choices).collect(toSelection());
  }

  /**
   * Converts to {@code Selection} from legacy code where an empty collection means <b>all</b>.
   * After converted to {@code Selection}, user code no longer need special handling of the
   * <em>empty</em> case.
   *
   * <p>This method is mainly for migrating legacy code. If you have a set where empty just means
   * "none" with no special handling needed, you should use {@link #toSelection
   * set.stream().collect(toSelection())} instead.
   */
  static <T> Selection<T> nonEmptyOrAll(Collection<? extends T> choices) {
    return choices.isEmpty() ? all() : choices.stream().collect(toSelection());
  }

  /** Returns a collector that collects input elements into a limited selection. */
  static <T> Collector<T, ?, Selection<T>> toSelection() {
    return collectingAndThen(toImmutableSet(), Selections::explicit);