dev.marksman.collectionviews.SetBuilder Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of collection-views Show documentation
Low overhead, protected views over Java collections
There is a newer version: 1.2.3
package dev.marksman.collectionviews;

import dev.marksman.enhancediterables.FiniteIterable;
import dev.marksman.enhancediterables.NonEmptyFiniteIterable;

import java.util.Collection;

import static com.jnape.palatable.lambda.adt.Maybe.just;
import static com.jnape.palatable.lambda.adt.Maybe.nothing;
import static dev.marksman.collectionviews.EmptySetBuilder.emptySetBuilder;

/**
 * A builder for {@code ImmutableSet}s.
 * 
 * A {@code SetBuilder} is immutable and all add operations return a new {@code SetBuilder}.
 * To construct the {@link ImmutableSet}, call {@link SetBuilder#build}.
 * 

 * It is safe to continue adding to a {@code SetBuilder} even after {@code build} is called.
 * It is also safe to "fork" a {@code SetBuilder}, but be aware that internal copies may be
 * made when doing so.
 *
 * @param  the element type
 */
public interface SetBuilder {

    /**
     * Adds an element to this {@code SetBuilder}.
     *
     * @param element the element to add
     * @return a new {@code NonEmptySetBuilder} with the element added
     */
    NonEmptySetBuilder add(A element);

    /**
     * Adds all elements in a {@code java.util.Collection} to this {@code SetBuilder}.
     *
     * @param elements the collection to add
     * @return a new {@code SetBuilder} with the elements added
     */
    SetBuilder addAll(Collection elements);

    /**
     * Adds all elements in a {@code FiniteIterable} to this {@code SetBuilder}.
     * 

     * Since {@link Set}s are {@code FiniteIterable}s, this method accepts any {@code Set}.
     *
     * @param elements the {@code FiniteIterable} to add
     * @return a new {@code SetBuilder} with the elements added
     */
    SetBuilder addAll(FiniteIterable elements);

    /**
     * Adds all elements in a {@code NonEmptyFiniteIterable} to this {@code SetBuilder}.
     * 

     * Since {@link NonEmptyVector}s are {@code NonEmptyFiniteIterable}s, this method accepts any {@code NonEmptyVector}.
     *
     * @param elements the {@code NonEmptyFiniteIterable} to add
     * @return a new {@code NonEmptySetBuilder} with the elements added
     */
    NonEmptySetBuilder addAll(NonEmptyFiniteIterable elements);

    /**
     * Builds a new {@code ImmutableSet}.
     * 
     * It is safe to call this at any point, and it safe to continue adding elements after calling this.
     *
     * @return an {@code ImmutableSet}.
     */
    ImmutableSet build();

    /**
     * Creates a new {@code SetBuilder}.
     *
     * @param  the element type
     * @return an empty {@link SetBuilder}
     */
    static  SetBuilder builder() {
        return emptySetBuilder(nothing());
    }

    /**
     * Creates a new {@code SetBuilder} with an initial capacity hint.
     *
     * @param initialCapacity an initial capacity hint.
     *                        Must be >= 0.
     * @param              the element type
     * @return an empty {@link SetBuilder}
     */
    static  SetBuilder builder(int initialCapacity) {
        return emptySetBuilder(just(initialCapacity));
    }

}
Related Artifacts