001// Generated by delombok at Sat Feb 25 17:58:34 UTC 2023
002package io.cui.tools.collect;
003
004import static io.cui.tools.base.Preconditions.checkArgument;
005import java.util.Collection;
006import java.util.Iterator;
007import java.util.Map;
008import java.util.stream.Stream;
009
010/**
011 * <h2>Overview</h2>
012 * Utility Methods for Collections and some types to be used in the context of Collections.
013 *
014 * <h3>isEmpty()</h3>
015 * The overloaded method {@link MoreCollections#isEmpty(Collection)} checks all kinds of
016 * Collections / varargs parameter for not being null and emptiness. In case of {@link Stream}s it
017 * solely checks for being not null in order not to consume it.
018 *
019 * <h3>requireNotEmpty()</h3>
020 * The overloaded method {@link MoreCollections#requireNotEmpty(Collection)} checks all kinds of
021 * Collections / varargs parameter for not being null nor empty. In case of being null / empty they
022 * will throw an {@link IllegalArgumentException}
023 *
024 * <h3>Map Difference</h3>
025 * The method {@link MoreCollections#difference(Map, Map)} creates an {@link MapDifference} view on
026 * the two given maps in order to check, well whether they are equal or not and if not which
027 * elements
028 * are differing.
029 *
030 * <h3>Map contains key</h3>
031 * Check whether the given Map contains at least one of the given keys (varags)
032 *
033 * @author Oliver Wolff
034 */
035public final class MoreCollections {
036    /**
037     * Simple check method for a {@code null} safe check of the emptiness of the given
038     * varags-parameter.
039     *
040     * @param elements to be checked, may be null
041     * @return {@code true} is the given elements are {@code null} or {@code empty}
042     */
043    public static boolean isEmpty(Object... elements) {
044        return null == elements || 0 == elements.length;
045    }
046
047    /**
048     * Simple check method for a {@code null} safe check of the emptiness of the given parameter.
049     *
050     * @param elements to be checked, may be null
051     * @return {@code true} is the given elements are {@code null} or {@code empty}
052     */
053    public static boolean isEmpty(Iterable<?> elements) {
054        return null == elements || isEmpty(elements.iterator());
055    }
056
057    /**
058     * Simple check method for a {@code null} safe check of the emptiness of the given parameter.
059     *
060     * @param elements to be checked, may be null
061     * @return {@code true} is the given elements are {@code null} or {@code empty}
062     */
063    public static boolean isEmpty(Collection<?> elements) {
064        return null == elements || elements.isEmpty();
065    }
066
067    /**
068     * Simple check method for a {@code null} safe check of the emptiness of the given parameter.
069     *
070     * @param map to be checked, may be null
071     * @return {@code true} is the given elements are {@code null} or {@code empty}
072     */
073    public static boolean isEmpty(Map<?, ?> map) {
074        return null == map || map.isEmpty();
075    }
076
077    /**
078     * Simple check method for a {@code null} safe check of the emptiness of the given parameter.
079     *
080     * @param elements to be checked, may be null
081     * @return {@code true} is the given elements are {@code null} or {@code empty}
082     */
083    public static boolean isEmpty(Iterator<?> elements) {
084        return null == elements || !elements.hasNext();
085    }
086
087    /**
088     * Shorthand for checking whether the given elements are empty or not.
089     *
090     * @param <T> identifying the type to be checked
091     * @param elements to be checked
092     * @return the given parameter
093     * @throws IllegalArgumentException in case the given elements are {@code null} or empty
094     */
095    @SafeVarargs
096    public static <T> T[] requireNotEmpty(T... elements) {
097        checkArgument(!isEmpty(elements));
098        return elements;
099    }
100
101    /**
102     * Shorthand for checking whether the given elements are empty or not.
103     *
104     * @param <T> identifying the type to be checked
105     * @param elements to be checked
106     * @return the given parameter
107     * @throws IllegalArgumentException in case the given elements are {@code null} or empty
108     */
109    public static <T> Collection<T> requireNotEmpty(Collection<T> elements) {
110        checkArgument(!isEmpty(elements));
111        return elements;
112    }
113
114    /**
115     * Shorthand for checking whether the given elements are empty or not.
116     *
117     * @param <T> identifying the type to be checked
118     * @param elements to be checked
119     * @param message to be set in error-case
120     * @return the given parameter
121     * @throws IllegalArgumentException in case the given elements are {@code null} or empty
122     */
123    public static <T> Collection<T> requireNotEmpty(Collection<T> elements, String message) {
124        checkArgument(!isEmpty(elements), message);
125        return elements;
126    }
127
128    /**
129     * Shorthand for checking whether the given elements are empty or not.
130     *
131     * @param <K> the type for the key
132     * @param <V> the type for the value
133     * @param elements to be checked
134     * @return the given parameter
135     * @throws IllegalArgumentException in case the given elements are {@code null} or empty
136     */
137    public static <K, V> Map<K, V> requireNotEmpty(Map<K, V> elements) {
138        checkArgument(!isEmpty(elements));
139        return elements;
140    }
141
142    /**
143     * Shorthand for checking whether the given elements are empty or not.
144     *
145     * @param <K> the type for the key
146     * @param <V> the type for the value
147     * @param elements to be checked
148     * @param message to be set in error-case
149     * @return the given parameter
150     * @throws IllegalArgumentException in case the given elements are {@code null} or empty
151     */
152    public static <K, V> Map<K, V> requireNotEmpty(Map<K, V> elements, String message) {
153        checkArgument(!isEmpty(elements), message);
154        return elements;
155    }
156
157    /**
158     * Shorthand for checking whether the given elements are empty or not.
159     *
160     * @param <T> identifying the type to be checked
161     * @param elements to be checked
162     * @return the given parameter
163     * @throws IllegalArgumentException in case the given elements are {@code null} or empty
164     */
165    public static <T> Iterable<T> requireNotEmpty(Iterable<T> elements) {
166        checkArgument(!isEmpty(elements));
167        return elements;
168    }
169
170    /**
171     * Shorthand for checking whether the given elements are empty or not.
172     *
173     * @param <T> identifying the type to be checked
174     * @param elements to be checked
175     * @param message to be set in error-case
176     * @return the given parameter
177     * @throws IllegalArgumentException in case the given elements are {@code null} or empty
178     */
179    public static <T> Iterable<T> requireNotEmpty(Iterable<T> elements, String message) {
180        checkArgument(!isEmpty(elements), message);
181        return elements;
182    }
183
184    /**
185     * Shorthand for checking whether the given elements are empty or not.
186     *
187     * @param elements to be checked
188     * @return the given parameter
189     * @throws IllegalArgumentException in case the given elements are {@code null} or empty
190     */
191    public static <T> Iterator<T> requireNotEmpty(Iterator<T> elements) {
192        checkArgument(!isEmpty(elements));
193        return elements;
194    }
195
196    /**
197     * Shorthand for checking whether the given elements are empty or not.
198     *
199     * @param <T> identifying the type to be checked
200     * @param elements to be checked
201     * @param message to be set in error-case
202     * @return the given parameter
203     * @throws IllegalArgumentException in case the given elements are {@code null} or empty
204     */
205    public static <T> Iterator<T> requireNotEmpty(Iterator<T> elements, String message) {
206        checkArgument(!isEmpty(elements), message);
207        return elements;
208    }
209
210    /**
211     * Shorthand for checking whether the given elements are empty or not.
212     * <em>Caution: </em> In order not to consume the stream only a null check will be performed.
213     *
214     * @param <T> identifying the type to be checked
215     * @param elements to be checked
216     * @return the given parameter
217     * @throws IllegalArgumentException in case the given elements are {@code null}
218     */
219    public static <T> Stream<T> requireNotEmpty(Stream<T> elements) {
220        checkArgument(!isEmpty(elements));
221        return elements;
222    }
223
224    /**
225     * Shorthand for checking whether the given elements are empty or not.
226     * <em>Caution: </em> In order not to consume the stream only a null check will be performed.
227     *
228     * @param <T> identifying the type to be checked
229     * @param elements to be checked
230     * @param message to be set in error-case
231     * @return the given parameter
232     * @throws IllegalArgumentException in case the given elements are {@code null}
233     */
234    public static <T> Stream<T> requireNotEmpty(Stream<T> elements, String message) {
235        checkArgument(!isEmpty(elements), message);
236        return elements;
237    }
238
239    /**
240     * Simple check method for a {@code null} safe check of the emptiness of the given parameter.
241     * <em>Caution: </em> In order not to consume the stream only a null check will be performed.
242     *
243     * @param elements to be checked, may be null
244     * @return {@code true} is the given elements are {@code null}. The Stream content will be
245     *         untouched
246     * @throws IllegalArgumentException in case the given elements are {@code null}
247     */
248    public static boolean isEmpty(Stream<?> elements) {
249        return null == elements;
250    }
251
252    /**
253     * Checks whether the given map contains at least one of the given keys to be checked.
254     *
255     * @param map to be checked. If it is {@code null} or empty the method will always return
256     *            {@code false}
257     * @param keys to be checked. If it is {@code null} or empty the method will always return
258     *            {@code false}
259     * @return {@code true} if the map contains at lest one of the given keys, {@code false}
260     *         otherwise
261     */
262    public static boolean containsKey(Map<?, ?> map, Object... keys) {
263        if (isEmpty(map) || isEmpty(keys)) {
264            return false;
265        }
266        for (Object key : keys) {
267            if (map.containsKey(key)) {
268                return true;
269            }
270        }
271        return false;
272    }
273
274    /**
275     * Computes the difference between two maps. This difference is an immutable snapshot of the
276     * state of the maps at the time this method is called. It will never change, even if the maps
277     * change at a later time.
278     *
279     * <p>
280     * Since this method uses {@code HashMap} instances internally, the keys of the supplied maps
281     * must be well-behaved with respect to {@link Object#equals} and {@link Object#hashCode}.
282     *
283     * <p>
284     * <b>Note:</b>If you only need to know whether two maps have the same mappings, call {@code
285     * left.equals(right)} instead of this method.
286     *
287     * @param <K> the type for the key
288     * @param <V> the type for the value
289     * @param left the map to treat as the "left" map for purposes of comparison, must not be null
290     * @param right the map to treat as the "right" map for purposes of comparison , must not be
291     *            null
292     * @return the difference between the two maps
293     *
294     * @author com.google.common.collect.MapDifference<K, V>
295     */
296    public static <K, V> MapDifference<K, V> difference(Map<? extends K, ? extends V> left, Map<? extends K, ? extends V> right) {
297        return MapDiffenceImpl.from(left, right);
298    }
299
300    @java.lang.SuppressWarnings("all")
301    @lombok.Generated
302    private MoreCollections() {
303        throw new java.lang.UnsupportedOperationException("This is a utility class and cannot be instantiated");
304    }
305}