CollectionUtils.java
- /*
- * *********************************************************************************************************************
- *
- * TheseFoolishThings: Miscellaneous utilities
- * http://tidalwave.it/projects/thesefoolishthings
- *
- * Copyright (C) 2009 - 2023 by Tidalwave s.a.s. (http://tidalwave.it)
- *
- * *********************************************************************************************************************
- *
- * 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.
- *
- * *********************************************************************************************************************
- *
- * git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
- * git clone https://github.com/tidalwave-it/thesefoolishthings-src
- *
- * *********************************************************************************************************************
- */
- package it.tidalwave.util;
- import javax.annotation.Nonnull;
- import java.util.ArrayList;
- import java.util.Collection;
- import java.util.Collections;
- import java.util.Comparator;
- import java.util.List;
- import java.util.Optional;
- import lombok.AccessLevel;
- import lombok.NoArgsConstructor;
- import static java.util.Collections.emptyList;
- /***********************************************************************************************************************
- *
- * This class contains a bunch of utility methods for manipulating lists.
- *
- * @author Fabrizio Giudici
- * @since 3.2-ALPHA-13
- * @it.tidalwave.javadoc.stable
- *
- **********************************************************************************************************************/
- @NoArgsConstructor(access = AccessLevel.PRIVATE)
- public final class CollectionUtils
- {
- /*******************************************************************************************************************
- *
- * Appends a list to an object. The resulting list is mutable.
- *
- * @param <T> the type of list items
- * @param list the list
- * @param object the list to append
- * @return the list with the appended object
- *
- * @it.tidalwave.javadoc.stable
- *
- ******************************************************************************************************************/
- @Nonnull
- public static <T> List<T> concat (@Nonnull final List<? extends T> list, @Nonnull final T object)
- {
- final List<T> result = new ArrayList<>(list);
- result.add(object);
- return result;
- }
- /*******************************************************************************************************************
- *
- * Returns a concatenation of the given {@link Collection}s.
- *
- * @param <T> the static type
- * @param collections the input collections
- * @return the concatenation
- *
- * @it.tidalwave.javadoc.stable
- *
- ******************************************************************************************************************/
- @Nonnull
- public static <T> List<T> concat (@Nonnull final Collection<? extends T>... collections)
- {
- final List<T> result = new ArrayList<>();
- for (final var collection : collections)
- {
- result.addAll(collection);
- }
- return result;
- }
- /*******************************************************************************************************************
- *
- * Reverses a list. The resulting list is mutable.
- *
- * @param <T> the type of list items
- * @param list the list
- * @return the reversed list
- *
- * @it.tidalwave.javadoc.stable
- *
- ******************************************************************************************************************/
- @Nonnull
- public static <T> List<T> reversed (@Nonnull final List<? extends T> list)
- {
- final List<T> result = new ArrayList<>(list);
- Collections.reverse(result);
- return result;
- }
- /*******************************************************************************************************************
- *
- * Sorts a list. The resulting list is mutable.
- *
- * @param <T> the type of list items
- * @param list the list
- * @return the sorted list
- * @since 3.2-ALPHA-13
- *
- * @it.tidalwave.javadoc.stable
- *
- ******************************************************************************************************************/
- @Nonnull
- public static <T extends Comparable<? super T>> List<T> sorted (@Nonnull final List<? extends T> list)
- {
- final var result = new ArrayList<T>(list);
- Collections.sort(result);
- return result;
- }
- /*******************************************************************************************************************
- *
- * Sorts a list with a given {@link Comparator}. The resulting list is mutable.
- *
- * @param <T> the type of list items
- * @param list the list
- * @param comparator the comparator
- * @return the sorted list
- * @since 3.2-ALPHA-13
- *
- * @it.tidalwave.javadoc.stable
- *
- ******************************************************************************************************************/
- @Nonnull
- public static <T> List<T> sorted (@Nonnull final List<? extends T> list,
- @Nonnull final Comparator<? super T> comparator)
- {
- final var result = new ArrayList<T>(list);
- result.sort(comparator);
- return result;
- }
- /*******************************************************************************************************************
- *
- * Returns the (optional) first element of a list.
- *
- * @param <T> the type of list items
- * @param list the list
- * @return the first element
- *
- * @it.tidalwave.javadoc.stable
- *
- ******************************************************************************************************************/
- @Nonnull
- public static <T> Optional<T> optionalHead (@Nonnull final List<? extends T> list)
- {
- return list.isEmpty() ? Optional.empty() : Optional.of(list.get(0));
- }
- /*******************************************************************************************************************
- *
- * Returns the first element of a list.
- *
- * @param <T> the type of list items
- * @param list the list (cannot be empty)
- * @return the first element
- * @throws IllegalArgumentException if the list is empty
- *
- * @it.tidalwave.javadoc.stable
- *
- ******************************************************************************************************************/
- @Nonnull
- public static <T> T head (@Nonnull final List<? extends T> list)
- {
- if (list.isEmpty())
- {
- throw new IllegalArgumentException("List is empty");
- }
- return list.get(0);
- }
- /*******************************************************************************************************************
- *
- * Returns the tail element of a list, that is a list without the first element. The tail of an empty list is an
- * empty list. The resulting list is mutable.
- *
- * @param <T> the type of list items
- * @param list the list
- * @return the tail of the list
- *
- * @it.tidalwave.javadoc.stable
- *
- ******************************************************************************************************************/
- @Nonnull
- public static <T> List<T> tail (@Nonnull final List<? extends T> list)
- {
- return new ArrayList<>(list.subList(1, list.size()));
- }
- /*******************************************************************************************************************
- *
- * Return a sublist of the original {@link List}, from the given {@code from} and {@code to} index (not included).
- * If the {@code from} index is negative and/or the {@code to} index is lower than the {@code from} index or if an
- * attempt is made to read before the start or past the end of the list, truncation silently occurs.
- *
- * @param <T> the static type
- * @param list the original list
- * @param from the first index (included)
- * @param to the last index (excluded)
- * @return the sublist
- * @since 3.2-ALPHA-17
- *
- ******************************************************************************************************************/
- @Nonnull
- public static <T> List<T> safeSubList (@Nonnull final List<? extends T> list, final int from, final int to)
- {
- final var safeFrom = Math.max(from, 0);
- final var safeTo = Math.min(list.size(), to);
- return (safeFrom >= safeTo) ? emptyList() : new ArrayList<>(list.subList(safeFrom, safeTo));
- }
- /*******************************************************************************************************************
- *
- * Splits a given {@link List} at a set of boundaries. Each boundary is the starting point of a sublist to be
- * returned.
- *
- * @param <T> the static type
- * @param list the original list
- * @param boundaries the boundaries
- * @return a list of sublists
- * @since 3.2-ALPHA-17
- *
- ******************************************************************************************************************/
- @Nonnull
- public static <T> List<List<T>> split (@Nonnull final List<? extends T> list, final int ... boundaries)
- {
- final var result = new ArrayList<List<T>>();
- for (var i = 0; i < boundaries.length - 1; i++)
- {
- result.add(safeSubList(list, boundaries[i], boundaries[i + 1]));
- }
- return result;
- }
- }