org.drasyl.util.SetUtil Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of drasyl-core Show documentation
This packages contains the building blocks required to create the drasyl overlay network.
There is a newer version: 0.10.0
/*
 * Copyright (c) 2020-2021 Heiko Bornholdt and Kevin Röbert
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
 * OR OTHER DEALINGS IN THE SOFTWARE.
 */
package org.drasyl.util;

import java.util.Collection;
import java.util.HashSet;
import java.util.Set;

/**
 * Utility class for operations on {@link Set}s.
 */
public final class SetUtil {
    private SetUtil() {
        // util class
    }

    /**
     * Returns a set containing all elements from set a and set b. If
     * there are duplicates in both sets, the elements from the set a are favored.
     *
     * @param a   set a
     * @param b   set b
     * @param  the {@code Set}'s element type
     * @return a {@code Set} containing the specified elements
     */
    public static  Set merge(final Set a, final Set b) {
        final HashSet result = new HashSet<>(a);
        result.addAll(b);
        return result;
    }

    /**
     * Returns a set containing all elements from a and the element b.
     * b is ignored if an equal element is already contained in the set
     * a.
     *
     * @param a   set a
     * @param b   set b
     * @param  the {@code Set}'s element type
     * @return a {@code Set} containing the specified elements
     */
    @SafeVarargs
    public static  Set merge(final Set a, final E... b) {
        return merge(a, Set.of(b));
    }

    /**
     * Returns a set containing all elements from set a that are not in set
     * b.
     *
     * @param a   set a
     * @param b   set b
     * @param  the {@code Set}'s element type
     * @return a {@code Set} containing the specified elements
     */
    public static  Set difference(final Set a, final Collection b) {
        final HashSet result = new HashSet<>(a);
        result.removeAll(b);
        return result;
    }

    /**
     * Returns a set containing all elements from set a that are not b.
     *
     * @param a   set a
     * @param b   set b
     * @param  the {@code Set}'s element type
     * @return a {@code Set} containing the specified elements
     */
    @SafeVarargs
    public static  Set difference(final Set a, final E... b) {
        return difference(a, Set.of(b));
    }

    /**
     * Returns the {@code n}-th element from set {@code set}. Throws a {@link
     * IndexOutOfBoundsException} if {@code n} is negative or greater than the set's cardinality.
     *
     * @param set a set
     * @param n   specifies the element to be taken
     * @param  the {@link Set}'s element type
     * @return {@code n}-th element from set {@code set}
     * @throws IndexOutOfBoundsException if {@code n} is negative or greater than the set's
     *                                   cardinality
     */
    @SuppressWarnings({ "java:S881", "java:S3242" })
    public static  E nthElement(final Set set, final int n) {
        if (n < 0 || n > set.size() - 1) {
            throw new IndexOutOfBoundsException();
        }

        int count = 0;
        for (final E element : set) {
            if (n == count++) {
                return element;
            }
        }

        // unreachable
        return null;
    }

    /**
     * Returns the first element from set {@code set}. Returns {@code null} if set is empty.
     *
     * @param set a set
     * @param  the {@link Set}'s element type
     * @return first element from set {@code set}
     */
    @SuppressWarnings("java:S1166")
    public static  E firstElement(final Set set) {
        try {
            return nthElement(set, 0);
        }
        catch (final IndexOutOfBoundsException e) {
            return null;
        }
    }
}