Package me.croabeast.common

Class CollectionBuilder<T>

java.lang.Object
me.croabeast.common.CollectionBuilder<T>
Type Parameters:
T - the type of elements in this collection builder
All Implemented Interfaces:
Iterable<T>, Copyable<CollectionBuilder<T>>
public final class CollectionBuilder<T> extends Object implements Iterable<T>, Copyable<CollectionBuilder<T>>
A versatile builder and wrapper for collections, providing a fluent API for filtering, mapping, sorting, and transforming collections.

CollectionBuilder encapsulates a mutable list of elements and allows chaining operations such as filtering, adding, removing, mapping, and more. This utility simplifies working with collections in a functional style, making code more readable and expressive.

Example usage: 


 List<Integer> numbers = Arrays.asList(1, 2, 3, 4, 5);
 List<Integer> evenNumbers = CollectionBuilder.of(numbers)
         .filter(n -> n % 2 == 0)
         .toList();
 // evenNumbers now contains [2, 4]

 String joined = CollectionBuilder.of("a", "b", "c")
         .apply(s -> s.toUpperCase())
         .toList()
         .toString();
 // joined is "[A, B, C]"

  • Method Details

    • iterator

      @NotNull public @NotNull Iterator<T> iterator()
      Returns an iterator over the elements in this builder.
      Specified by:
      iterator in interface Iterable<T>
      Returns:
      an Iterator for the collection

    • filter

      public CollectionBuilder<T> filter(Predicate<T> predicate)
      Filters the elements of the collection based on the provided predicate.

      Elements that do not satisfy the predicate are removed.

      Parameters:
      predicate - the condition to apply for filtering
      Returns:
      this builder instance for method chaining

    • add

      public CollectionBuilder<T> add(T element)
      Adds a single element to the collection.
      Parameters:
      element - the element to add
      Returns:
      this builder instance for method chaining

    • remove

      public CollectionBuilder<T> remove(T element)
      Removes a single element from the collection.
      Parameters:
      element - the element to remove
      Returns:
      this builder instance for method chaining

    • addAll

      public CollectionBuilder<T> addAll(Collection<? extends T> elements)
      Adds all elements from the provided collection to this builder.
      Parameters:
      elements - the collection of elements to add
      Returns:
      this builder instance for method chaining

    • addAll

      @SafeVarargs public final CollectionBuilder<T> addAll(T... elements)
      Adds all provided elements to this builder.
      Parameters:
      elements - an array of elements to add
      Returns:
      this builder instance for method chaining

    • addAll

      public CollectionBuilder<T> addAll(Iterable<? extends T> elements)
      Adds all elements from the provided iterable to this builder.
      Parameters:
      elements - the iterable of elements to add
      Returns:
      this builder instance for method chaining

    • addAll

      public CollectionBuilder<T> addAll(Iterator<? extends T> elements)
      Adds all elements from the provided iterator to this builder.
      Parameters:
      elements - the iterator of elements to add
      Returns:
      this builder instance for method chaining

    • addAll

      public CollectionBuilder<T> addAll(Enumeration<? extends T> elements)
      Adds all elements from the provided enumeration to this builder.
      Parameters:
      elements - the enumeration of elements to add
      Returns:
      this builder instance for method chaining

    • removeAll

      public CollectionBuilder<T> removeAll(Collection<? extends T> elements)
      Removes all elements in the specified collection from this builder.
      Parameters:
      elements - the collection of elements to remove
      Returns:
      this builder instance for method chaining

    • sort

      public CollectionBuilder<T> sort(Comparator<? super T> comparator)
      Sorts the elements in this builder using the provided comparator.
      Parameters:
      comparator - the comparator to determine the order of the elements
      Returns:
      this builder instance for method chaining

    • apply

      public CollectionBuilder<T> apply(UnaryOperator<T> operator)
      Applies a transformation function to each element in this builder.

      Each element is replaced with the result of applying the operator.

      Parameters:
      operator - the transformation function
      Returns:
      this builder instance for method chaining

    • map

      public <U> CollectionBuilder<U> map(Function<T,U> function)
      Maps each element in this builder to a new value using the provided function.
      Type Parameters:
      U - the type of the mapped elements
      Parameters:
      function - the mapping function
      Returns:
      a new CollectionBuilder containing the mapped elements

    • copy

      @NotNull public @NotNull CollectionBuilder<T> copy()
      Creates a copy of this CollectionBuilder.
      Specified by:
      copy in interface Copyable<T>
      Returns:
      a new builder with the same elements

    • findFirst

      public T findFirst(Predicate<T> predicate, T def)
      Finds and returns the first element matching the provided predicate.

      If no element matches, returns the specified default value.

      Parameters:
      predicate - the condition to test
      def - the default value to return if no match is found
      Returns:
      the first matching element, or the default value if none is found

    • findFirst

      @Nullable public T findFirst(Predicate<T> predicate)
      Finds and returns the first element matching the provided predicate.

      If no element matches, returns null.

      Parameters:
      predicate - the condition to test
      Returns:
      the first matching element, or null if none is found

    • collect

      public <C extends Collection<T>> C collect(Supplier<C> supplier)
      Collects the elements of this builder into a new collection provided by the supplier.
      Type Parameters:
      C - the type of the collection to return
      Parameters:
      supplier - a supplier to create a new collection
      Returns:
      a new collection containing all elements in this builder

    • sizeByFilter

      public int sizeByFilter(Predicate<T> predicate)
      Returns the number of elements that satisfy a given predicate.
      Parameters:
      predicate - the condition to test
      Returns:
      the count of elements that match the predicate

    • toList

      public List<T> toList()
      Returns a new list containing all elements in this builder.
      Returns:
      a List of elements

    • toSet

      public Set<T> toSet()
      Returns a new set containing all unique elements in this builder.
      Returns:
      a Set of elements

    • toQueue

      public Queue<T> toQueue()
      Returns a new queue containing all elements in this builder.
      Returns:
      a Queue of elements

    • toEnumeration

      public Enumeration<T> toEnumeration()
      Returns an Enumeration over the elements in this builder.
      Returns:
      an enumeration of elements

    • size

      public int size()
      Returns the number of elements currently held in this builder.
      Returns:
      the size of the collection

    • toString

      public String toString()
      Returns a string representation of the underlying collection.
      Overrides:
      toString in class Object
      Returns:
      a string representing the collection

    • of

      public static <T> CollectionBuilder<T> of(Collection<T> collection)
      Creates a new CollectionBuilder from the provided collection.
      Type Parameters:
      T - the type of elements in the collection
      Parameters:
      collection - the source collection; if null, an empty collection is used
      Returns:
      a new CollectionBuilder instance

    • of

      public static <K, V> CollectionBuilder<Map.Entry<K,V>> of(Map<K,V> map)
      Creates a new CollectionBuilder from the entries of the provided map.
      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      Parameters:
      map - the source map whose entries are to be used
      Returns:
      a new CollectionBuilder containing the map's entries

    • of

      public static <T> CollectionBuilder<T> of(Iterator<T> iterator)
      Creates a new CollectionBuilder from the elements provided by an iterator.
      Type Parameters:
      T - the type of elements
      Parameters:
      iterator - the source iterator of elements
      Returns:
      a new CollectionBuilder containing the elements from the iterator

    • of

      public static <T> CollectionBuilder<T> of(Iterable<T> iterable)
      Creates a new CollectionBuilder from the elements provided by an iterable.
      Type Parameters:
      T - the type of elements
      Parameters:
      iterable - the source iterable of elements
      Returns:
      a new CollectionBuilder containing the elements from the iterable

    • of

      public static <T> CollectionBuilder<T> of(Enumeration<T> enumeration)
      Creates a new CollectionBuilder from the elements provided by an enumeration.
      Type Parameters:
      T - the type of elements
      Parameters:
      enumeration - the source enumeration of elements
      Returns:
      a new CollectionBuilder containing the elements from the enumeration

    • of

      @SafeVarargs public static <T> CollectionBuilder<T> of(T... elements)
      Creates a new CollectionBuilder from an array of elements.
      Type Parameters:
      T - the type of elements
      Parameters:
      elements - the array of elements to include
      Returns:
      a new CollectionBuilder containing the given elements

    • of

      public static <T> CollectionBuilder<T> of(CollectionBuilder<T> builder)
      Creates a copy of the given CollectionBuilder.
      Type Parameters:
      T - the type of elements
      Parameters:
      builder - the builder to copy
      Returns:
      a new CollectionBuilder with the same elements as the provided builder