dev.marksman.collectionviews.NonEmptyVectorBuilder 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 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.ConcreteVectorBuilder.concreteVectorBuilder;

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

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

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

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

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

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

    /**
     * Creates a new {@code NonEmptyVectorBuilder}.
     *
     * @param first the first element
     * @param    the element type
     * @return an empty {@link VectorBuilder}
     */
    static  NonEmptyVectorBuilder builder(A first) {
        return concreteVectorBuilder(nothing(), first);
    }

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

}

Related Artifacts