001package ball.util.stream;
002/*-
003 * ##########################################################################
004 * Utilities
005 * %%
006 * Copyright (C) 2008 - 2022 Allen D. Ball
007 * %%
008 * Licensed under the Apache License, Version 2.0 (the "License");
009 * you may not use this file except in compliance with the License.
010 * You may obtain a copy of the License at
011 *
012 *      http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing, software
015 * distributed under the License is distributed on an "AS IS" BASIS,
016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017 * See the License for the specific language governing permissions and
018 * limitations under the License.
019 * ##########################################################################
020 */
021import java.util.Collection;
022import java.util.List;
023import java.util.function.Predicate;
024import java.util.stream.Stream;
025
026/**
027 * {@link Stream} implementaion that provides all permutations of a
028 * {@link List}.
029 *
030 * @param       <T>             The {@link List} element type.
031 *
032 * @author {@link.uri mailto:ball@hcf.dev Allen D. Ball}
033 */
034public interface Permutations<T> extends Combinations<T> {
035
036    /**
037     * Method to get the {@link Stream} of permutations.
038     *
039     * @param   collection      The {@link Collection} of elements to
040     *                          permute.
041     * @param   <T>             The {@link Collection} element type.
042     *
043     * @return  The {@link Stream} of permutations.
044     */
045    public static <T> Stream<List<T>> of(Collection<T> collection) {
046        return of(null, collection);
047    }
048
049    /**
050     * Method to get the {@link Stream} of permutations.
051     *
052     * @param   predicate       The optional {@link Predicate} (may be
053     *                          {@code null}) specifying prerequisite
054     *                          requirement(s) for the combinations.  Any
055     *                          path that does not match will be pruned.
056     * @param   collection      The {@link Collection} of elements to
057     *                          permute.
058     * @param   <T>             The {@link Collection} element type.
059     *
060     * @return  The {@link Stream} of permutations.
061     */
062    public static <T> Stream<List<T>> of(Predicate<List<T>> predicate, Collection<T> collection) {
063        int size = collection.size();
064
065        return Combinations.of(size, size, predicate, collection);
066    }
067}