org.javafunk.funk.Literals Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of funk-core Show documentation
Show all versions of funk-core Show documentation
Functional utilities for Java: core APIs
The newest version!
/*
* Copyright (C) 2011-Present Funk committers.
* All rights reserved.
*
* The software in this package is published under the terms of the BSD
* style license a copy of which has been included with this distribution in
* the LICENSE.txt file.
*/
package org.javafunk.funk;
import com.google.common.collect.Multiset;
import org.javafunk.funk.builders.ArrayBuilder;
import org.javafunk.funk.builders.CollectionBuilder;
import org.javafunk.funk.builders.IterableBuilder;
import org.javafunk.funk.builders.IteratorBuilder;
import org.javafunk.funk.builders.ListBuilder;
import org.javafunk.funk.builders.MapBuilder;
import org.javafunk.funk.builders.MultisetBuilder;
import org.javafunk.funk.builders.SetBuilder;
import org.javafunk.funk.datastructures.tuples.Nonuple;
import org.javafunk.funk.datastructures.tuples.Octuple;
import org.javafunk.funk.datastructures.tuples.Pair;
import org.javafunk.funk.datastructures.tuples.Quadruple;
import org.javafunk.funk.datastructures.tuples.Quintuple;
import org.javafunk.funk.datastructures.tuples.Septuple;
import org.javafunk.funk.datastructures.tuples.Sextuple;
import org.javafunk.funk.datastructures.tuples.Single;
import org.javafunk.funk.datastructures.tuples.Triple;
import java.util.AbstractMap;
import java.util.Collection;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Set;
import static java.util.Arrays.asList;
import static org.javafunk.funk.Classes.uncheckedInstantiate;
import static org.javafunk.funk.datastructures.tuples.Nonuple.nonuple;
import static org.javafunk.funk.datastructures.tuples.Octuple.octuple;
import static org.javafunk.funk.datastructures.tuples.Pair.pair;
import static org.javafunk.funk.datastructures.tuples.Quadruple.quadruple;
import static org.javafunk.funk.datastructures.tuples.Quintuple.quintuple;
import static org.javafunk.funk.datastructures.tuples.Septuple.septuple;
import static org.javafunk.funk.datastructures.tuples.Sextuple.sextuple;
import static org.javafunk.funk.datastructures.tuples.Single.single;
import static org.javafunk.funk.datastructures.tuples.Triple.triple;
public class Literals {
private Literals() {}
/**
* Returns an empty immutable {@code Iterable} instance.
*
* This form of literal is most suited to direct assignment to a variable
* since in this case, the type {@code E} is inferred from the variable
* declaration. For example:
*
*
* Iterable<String> strings = iterable();
*
*
*
* @param The type of the elements contained in the {@code Iterable}.
* @return An {@code Iterable} instance over the type {@code E} containing no elements.
*/
public static Iterable iterable() {
return new IterableBuilder().build();
}
/**
* Returns an empty immutable {@code Iterable} instance of the supplied concrete class.
*
* The supplied class must have a public no-argument constructor, otherwise
* an {@code IllegalArgumentException} will be thrown.
*
* @param iterableClass The class of the {@code Iterable} implementation to be
* instantiated.
* @param The type of the elements contained in the {@code Iterable}.
* @return An {@code Iterable} instance over the type {@code E} of the concrete
* type specified by the supplied {@code Class}.
* @throws IllegalArgumentException if the supplied class does not have
* a public no-argument constructor.
*/
@SuppressWarnings("unchecked")
public static Iterable iterable(Class iterableClass) {
return uncheckedInstantiate(iterableClass);
}
/**
* Returns an empty immutable {@code Iterable} instance over the type
* of the supplied {@code Class}.
*
* This form of literal is most suited to inline usage such as when passing an
* empty iterable as a parameter in a method call since it reads more clearly than
* {@link #iterable()}. For example, compare the following:
*
*
* public class Account {
* public Account(Money balance, List<Money> transactions) {
* ...
* }
*
* ...
* }
*
* Account account1 = new Account(new Money(0), Literals.<Money>iterable());
* Account account2 = new Account(new Money(0), iterableOf(Money.class));
*
*
*
* @param elementClass A {@code Class} representing the type of elements
* contained in this {@code Iterable}
* @param The type of the elements contained in the {@code Iterable}.
* @return An {@code Iterable} instance over the type {@code E} containing no elements.
*/
public static Iterable iterableOf(Class elementClass) {
return new IterableBuilder().build();
}
/**
* Returns an immutable {@code Iterable} instance over the type {@code E}
* containing all elements from the supplied {@code Iterable}. The order of
* the elements in the resulting {@code Iterable} is determined by the order in
* which they are yielded from the supplied {@code Iterable}.
*
* This form of literal is useful when an immutable copy of an {@code Iterable}
* is required. For example:
*
*
* public class Product {
* public Iterable<Integer> getSizes() {
* return iterableFrom(sizes);
* }
*
* ...
* }
*
*
*
* @param elements An {@code Iterable} of elements from which an {@code Iterable} should
* be constructed.
* @param The type of the elements to be contained in the returned
* {@code Iterable}.
* @return An {@code Iterable} over the type {@code E} containing all elements from the
* supplied {@code Iterable} in the order they are yielded.
*/
public static Iterable iterableFrom(Iterable elements) {
return new IterableBuilder().with(elements).build();
}
/**
* Returns an immutable {@code Iterable} instance over the type {@code E}
* containing all elements from the supplied array. The order of the elements
* in the resulting {@code Iterable} is the same as the order of the elements
* in the array.
*
* For example, the following:
*
*
* String[] strings = new String[]{"one", "two", "three"};
* Iterable<String> iterableOfStrings = Literals.iterableFrom(strings);
*
*
* is equivalent to:
*
*
* Iterable<String> iterableOfStrings = Literals.iterableWith("one", "two", "three");
*
*
*
* @param elementArray An array of elements from which an {@code Iterable} should be
* constructed.
* @param The type of the elements to be contained in the returned
* {@code Iterable}.
* @return An {@code Iterable} over the type {@code E} containing all elements from the
* supplied array in the same order as the supplied array.
*/
public static Iterable iterableFrom(E[] elementArray) {
return new IterableBuilder().with(elementArray).build();
}
/**
* Returns an immutable {@code Iterable} instance over the type {@code E} containing the
* supplied element.
*
* @param e An element from which to construct an {@code Iterable}.
* @param The type of the element contained in the returned {@code Iterable}.
* @return An {@code Iterable} instance over type {@code E} containing the supplied element.
*/
@SuppressWarnings("unchecked") public static Iterable iterableWith(E e) {
return iterableFrom(asList(e));
}
/**
* Returns an immutable {@code Iterable} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterable} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterable}.
* @param e2 The second element from which to construct an {@code Iterable}.
* @param The type of the elements contained in the returned {@code Iterable}.
* @return An {@code Iterable} instance over type {@code E} containing the supplied elements.
*/
@SuppressWarnings("unchecked") public static Iterable iterableWith(E e1, E e2) {
return iterableFrom(asList(e1, e2));
}
/**
* Returns an immutable {@code Iterable} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterable} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterable}.
* @param e2 The second element from which to construct an {@code Iterable}.
* @param e3 The third element from which to construct an {@code Iterable}.
* @param The type of the elements contained in the returned {@code Iterable}.
* @return An {@code Iterable} instance over type {@code E} containing the supplied elements.
*/
@SuppressWarnings("unchecked") public static Iterable iterableWith(E e1, E e2, E e3) {
return iterableFrom(asList(e1, e2, e3));
}
/**
* Returns an immutable {@code Iterable} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterable} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterable}.
* @param e2 The second element from which to construct an {@code Iterable}.
* @param e3 The third element from which to construct an {@code Iterable}.
* @param e4 The fourth element from which to construct an {@code Iterable}.
* @param The type of the elements contained in the returned {@code Iterable}.
* @return An {@code Iterable} instance over type {@code E} containing the supplied elements.
*/
@SuppressWarnings("unchecked") public static Iterable iterableWith(E e1, E e2, E e3, E e4) {
return iterableFrom(asList(e1, e2, e3, e4));
}
/**
* Returns an immutable {@code Iterable} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterable} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterable}.
* @param e2 The second element from which to construct an {@code Iterable}.
* @param e3 The third element from which to construct an {@code Iterable}.
* @param e4 The fourth element from which to construct an {@code Iterable}.
* @param e5 The fifth element from which to construct an {@code Iterable}.
* @param The type of the elements contained in the returned {@code Iterable}.
* @return An {@code Iterable} instance over type {@code E} containing the supplied elements.
*/
@SuppressWarnings("unchecked") public static Iterable iterableWith(E e1, E e2, E e3, E e4, E e5) {
return iterableFrom(asList(e1, e2, e3, e4, e5));
}
/**
* Returns an immutable {@code Iterable} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterable} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterable}.
* @param e2 The second element from which to construct an {@code Iterable}.
* @param e3 The third element from which to construct an {@code Iterable}.
* @param e4 The fourth element from which to construct an {@code Iterable}.
* @param e5 The fifth element from which to construct an {@code Iterable}.
* @param e6 The sixth element from which to construct an {@code Iterable}.
* @param The type of the elements contained in the returned {@code Iterable}.
* @return An {@code Iterable} instance over type {@code E} containing the supplied elements.
*/
@SuppressWarnings("unchecked") public static Iterable iterableWith(E e1, E e2, E e3, E e4, E e5, E e6) {
return iterableFrom(asList(e1, e2, e3, e4, e5, e6));
}
/**
* Returns an immutable {@code Iterable} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterable} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterable}.
* @param e2 The second element from which to construct an {@code Iterable}.
* @param e3 The third element from which to construct an {@code Iterable}.
* @param e4 The fourth element from which to construct an {@code Iterable}.
* @param e5 The fifth element from which to construct an {@code Iterable}.
* @param e6 The sixth element from which to construct an {@code Iterable}.
* @param e7 The seventh element from which to construct an {@code Iterable}.
* @param The type of the elements contained in the returned {@code Iterable}.
* @return An {@code Iterable} instance over type {@code E} containing the supplied elements.
*/
@SuppressWarnings("unchecked") public static Iterable iterableWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
return iterableFrom(asList(e1, e2, e3, e4, e5, e6, e7));
}
/**
* Returns an immutable {@code Iterable} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterable} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterable}.
* @param e2 The second element from which to construct an {@code Iterable}.
* @param e3 The third element from which to construct an {@code Iterable}.
* @param e4 The fourth element from which to construct an {@code Iterable}.
* @param e5 The fifth element from which to construct an {@code Iterable}.
* @param e6 The sixth element from which to construct an {@code Iterable}.
* @param e7 The seventh element from which to construct an {@code Iterable}.
* @param e8 The eighth element from which to construct an {@code Iterable}.
* @param The type of the elements contained in the returned {@code Iterable}.
* @return An {@code Iterable} instance over type {@code E} containing the supplied elements.
*/
@SuppressWarnings("unchecked") public static Iterable iterableWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
return iterableFrom(asList(e1, e2, e3, e4, e5, e6, e7, e8));
}
/**
* Returns an immutable {@code Iterable} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterable} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterable}.
* @param e2 The second element from which to construct an {@code Iterable}.
* @param e3 The third element from which to construct an {@code Iterable}.
* @param e4 The fourth element from which to construct an {@code Iterable}.
* @param e5 The fifth element from which to construct an {@code Iterable}.
* @param e6 The sixth element from which to construct an {@code Iterable}.
* @param e7 The seventh element from which to construct an {@code Iterable}.
* @param e8 The eighth element from which to construct an {@code Iterable}.
* @param e9 The ninth element from which to construct an {@code Iterable}.
* @param The type of the elements contained in the returned {@code Iterable}.
* @return An {@code Iterable} instance over type {@code E} containing the supplied elements.
*/
@SuppressWarnings("unchecked") public static Iterable iterableWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
return iterableFrom(asList(e1, e2, e3, e4, e5, e6, e7, e8, e9));
}
/**
* Returns an immutable {@code Iterable} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterable} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterable}.
* @param e2 The second element from which to construct an {@code Iterable}.
* @param e3 The third element from which to construct an {@code Iterable}.
* @param e4 The fourth element from which to construct an {@code Iterable}.
* @param e5 The fifth element from which to construct an {@code Iterable}.
* @param e6 The sixth element from which to construct an {@code Iterable}.
* @param e7 The seventh element from which to construct an {@code Iterable}.
* @param e8 The eighth element from which to construct an {@code Iterable}.
* @param e9 The ninth element from which to construct an {@code Iterable}.
* @param e10 The tenth element from which to construct an {@code Iterable}.
* @param The type of the elements contained in the returned {@code Iterable}.
* @return An {@code Iterable} instance over type {@code E} containing the supplied elements.
*/
@SuppressWarnings("unchecked") public static Iterable iterableWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) {
return iterableFrom(asList(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10));
}
/**
* Returns an immutable {@code Iterable} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterable} is the same as the order
* of the elements in the argument list.
*
* Note that this literal uses a generic varargs parameter as the last argument in the
* argument list and as such will cause unchecked cast warnings. Explicit argument
* lists for up to ten arguments have been provided for convenience. In order to avoid
* the unchecked cast warnings, an {@link IterableBuilder} can be used instead.
*
* @param e1 The first element from which to construct an {@code Iterable}.
* @param e2 The second element from which to construct an {@code Iterable}.
* @param e3 The third element from which to construct an {@code Iterable}.
* @param e4 The fourth element from which to construct an {@code Iterable}.
* @param e5 The fifth element from which to construct an {@code Iterable}.
* @param e6 The sixth element from which to construct an {@code Iterable}.
* @param e7 The seventh element from which to construct an {@code Iterable}.
* @param e8 The eighth element from which to construct an {@code Iterable}.
* @param e9 The ninth element from which to construct an {@code Iterable}.
* @param e10 The tenth element from which to construct an {@code Iterable}.
* @param e11on The remaining elements from which to construct an {@code Iterable}.
* @param The type of the elements contained in the returned {@code Iterable}.
* @return an {@code Iterable} instance over type {@code E} containing the supplied elements.
*/
@SuppressWarnings("unchecked") public static Iterable iterableWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10, E... e11on) {
return iterableBuilderFrom(asList(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10)).with(asList(e11on)).build();
}
/**
* Returns an {@code IterableBuilder} containing no elements.
*
* Example Usage:
* An {@code IterableBuilder} can be used to assemble an {@code Iterable} as follows:
*
*
* Iterable<Integer> iterable = Literals.<Integer>iterableBuilder()
* .with(1, 2, 3)
* .and(4, 5, 6)
* .build()
*
*
* This is equivalent to the following:
*
*
* Iterable<Integer> iterable = Literals.iterableWith(1, 2, 3, 4, 5, 6);
*
*
* The advantage of the {@code IterableBuilder} is that the iterable can be built up from
* individual objects, arrays or existing iterables. See {@link IterableBuilder} for
* further details.
*
* @param The type of the elements contained in the {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over the type {@code E} containing no elements.
*/
public static IterableBuilder iterableBuilder() {
return new IterableBuilder();
}
/**
* Returns an {@code IterableBuilder} over the type of the supplied {@code Class}
* containing no elements.
*
* Example Usage:
* An {@code IterableBuilder} can be used to assemble an {@code Iterable} as follows:
*
*
* Iterable<String> iterable = iterableBuilderOf(String.class)
* .with("first", "second", "third")
* .and(new String[]{"fourth", "fifth"})
* .build()
*
*
* This is equivalent to the following:
*
*
* Iterable<String> iterable = Literals.iterableWith("first", "second", "third", "fourth", "fifth");
*
*
* The advantage of the {@code IterableBuilder} is that the iterable can be built
* up from individual objects, arrays or existing iterables. See {@link IterableBuilder}
* for further details.
*
* @param elementClass A {@code Class} representing the type of elements
* contained in this {@code IterableBuilder}
* @param The type of the elements contained in the {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over the type {@code E} containing no
* elements.
*/
public static IterableBuilder iterableBuilderOf(Class elementClass) {
return new IterableBuilder();
}
/**
* Returns an {@code IterableBuilder} over type {@code E} initialised with the elements
* contained in the supplied {@code Iterable}.
*
* Example Usage:
* An {@code IterableBuilder} can be used to assemble an {@code Iterable} from two existing
* {@code Collection} instances as follows:
*
*
* Collection<Character> firstCollection = Literals.collectionWith('a', 'b', 'c');
* Collection<Character> secondCollection = Literals.collectionWith('d', 'e', 'f');
* Iterable<Character> iterable = iterableBuilderFrom(firstCollection)
* .with(secondCollection)
* .build()
*
*
* This is equivalent to the following:
*
*
* Iterable<Character> iterable = Literals.iterableWith('a', 'b', 'c', 'd', 'e', 'f');
*
*
* The advantage of the {@code IterableBuilder} is that the iterable can be built up from
* individual objects, arrays or existing iterables. See {@link IterableBuilder} for
* further details.
*
* @param elements An {@code Iterable} containing elements with which the
* {@code IterableBuilder} should be initialised.
* @param The type of the elements contained in the {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over the type {@code E} containing
* the elements from the supplied {@code Iterable}.
*/
public static IterableBuilder iterableBuilderFrom(Iterable elements) {
return new IterableBuilder().with(elements);
}
/**
* Returns an {@code IterableBuilder} over type {@code E} initialised with the elements
* contained in the supplied array.
*
* Example Usage:
* An {@code IterableBuilder} can be used to assemble an {@code Iterable} from two existing
* arrays as follows:
*
*
* Long[] firstArray = new Long[]{1L, 2L, 3L};
* Long[] secondArray = new Long[]{3L, 4L, 5L};
* Iterable<Long> iterable = iterableBuilderFrom(firstArray)
* .with(secondArray)
* .build()
*
*
* This is equivalent to the following:
*
*
* Iterable<Long> iterable = Literals.iterableWith(1L, 2L, 3L, 3L, 4L, 5L);
*
*
* The advantage of the {@code IterableBuilder} is that the iterable can be built up from
* individual objects, arrays or existing iterables. See {@link IterableBuilder} for
* further details.
*
* @param elementArray An array containing elements with which the
* {@code IterableBuilder} should be initialised.
* @param The type of the elements contained in the {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over the type {@code E} containing
* the elements from the supplied array.
*/
public static IterableBuilder iterableBuilderFrom(E[] elementArray) {
return new IterableBuilder().with(elementArray);
}
/**
* Returns an {@code IterableBuilder} instance over the type {@code E} containing
* the supplied element.
*
* @param e The element to be added to the {@code IterableBuilder}.
* @param The type of the elements contained in the returned {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over type {@code E} containing the supplied
* element.
*/
public static IterableBuilder iterableBuilderWith(E e) {
return iterableBuilderFrom(iterableWith(e));
}
/**
* Returns an {@code IterableBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IterableBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IterableBuilder}.
* @param e2 The second element to be added to the {@code IterableBuilder}.
* @param The type of the elements contained in the returned {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IterableBuilder iterableBuilderWith(E e1, E e2) {
return iterableBuilderFrom(iterableWith(e1, e2));
}
/**
* Returns an {@code IterableBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IterableBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IterableBuilder}.
* @param e2 The second element to be added to the {@code IterableBuilder}.
* @param e3 The third element to be added to the {@code IterableBuilder}.
* @param The type of the elements contained in the returned {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IterableBuilder iterableBuilderWith(E e1, E e2, E e3) {
return iterableBuilderFrom(iterableWith(e1, e2, e3));
}
/**
* Returns an {@code IterableBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IterableBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IterableBuilder}.
* @param e2 The second element to be added to the {@code IterableBuilder}.
* @param e3 The third element to be added to the {@code IterableBuilder}.
* @param e4 The fourth element to be added to the {@code IterableBuilder}.
* @param The type of the elements contained in the returned {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IterableBuilder iterableBuilderWith(E e1, E e2, E e3, E e4) {
return iterableBuilderFrom(iterableWith(e1, e2, e3, e4));
}
/**
* Returns an {@code IterableBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IterableBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IterableBuilder}.
* @param e2 The second element to be added to the {@code IterableBuilder}.
* @param e3 The third element to be added to the {@code IterableBuilder}.
* @param e4 The fourth element to be added to the {@code IterableBuilder}.
* @param e5 The fifth element to be added to the {@code IterableBuilder}.
* @param The type of the elements contained in the returned {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IterableBuilder iterableBuilderWith(E e1, E e2, E e3, E e4, E e5) {
return iterableBuilderFrom(iterableWith(e1, e2, e3, e4, e5));
}
/**
* Returns an {@code IterableBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IterableBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IterableBuilder}.
* @param e2 The second element to be added to the {@code IterableBuilder}.
* @param e3 The third element to be added to the {@code IterableBuilder}.
* @param e4 The fourth element to be added to the {@code IterableBuilder}.
* @param e5 The fifth element to be added to the {@code IterableBuilder}.
* @param e6 The sixth element to be added to the {@code IterableBuilder}.
* @param The type of the elements contained in the returned {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IterableBuilder iterableBuilderWith(E e1, E e2, E e3, E e4, E e5, E e6) {
return iterableBuilderFrom(iterableWith(e1, e2, e3, e4, e5, e6));
}
/**
* Returns an {@code IterableBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IterableBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IterableBuilder}.
* @param e2 The second element to be added to the {@code IterableBuilder}.
* @param e3 The third element to be added to the {@code IterableBuilder}.
* @param e4 The fourth element to be added to the {@code IterableBuilder}.
* @param e5 The fifth element to be added to the {@code IterableBuilder}.
* @param e6 The sixth element to be added to the {@code IterableBuilder}.
* @param e7 The seventh element to be added to the {@code IterableBuilder}.
* @param The type of the elements contained in the returned {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IterableBuilder iterableBuilderWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
return iterableBuilderFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7));
}
/**
* Returns an {@code IterableBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IterableBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IterableBuilder}.
* @param e2 The second element to be added to the {@code IterableBuilder}.
* @param e3 The third element to be added to the {@code IterableBuilder}.
* @param e4 The fourth element to be added to the {@code IterableBuilder}.
* @param e5 The fifth element to be added to the {@code IterableBuilder}.
* @param e6 The sixth element to be added to the {@code IterableBuilder}.
* @param e7 The seventh element to be added to the {@code IterableBuilder}.
* @param e8 The eighth element to be added to the {@code IterableBuilder}.
* @param The type of the elements contained in the returned {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IterableBuilder iterableBuilderWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
return iterableBuilderFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7, e8));
}
/**
* Returns an {@code IterableBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IterableBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IterableBuilder}.
* @param e2 The second element to be added to the {@code IterableBuilder}.
* @param e3 The third element to be added to the {@code IterableBuilder}.
* @param e4 The fourth element to be added to the {@code IterableBuilder}.
* @param e5 The fifth element to be added to the {@code IterableBuilder}.
* @param e6 The sixth element to be added to the {@code IterableBuilder}.
* @param e7 The seventh element to be added to the {@code IterableBuilder}.
* @param e8 The eighth element to be added to the {@code IterableBuilder}.
* @param e9 The ninth element to be added to the {@code IterableBuilder}.
* @param The type of the elements contained in the returned {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IterableBuilder iterableBuilderWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
return iterableBuilderFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7, e8, e9));
}
/**
* Returns an {@code IterableBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IterableBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IterableBuilder}.
* @param e2 The second element to be added to the {@code IterableBuilder}.
* @param e3 The third element to be added to the {@code IterableBuilder}.
* @param e4 The fourth element to be added to the {@code IterableBuilder}.
* @param e5 The fifth element to be added to the {@code IterableBuilder}.
* @param e6 The sixth element to be added to the {@code IterableBuilder}.
* @param e7 The seventh element to be added to the {@code IterableBuilder}.
* @param e8 The eighth element to be added to the {@code IterableBuilder}.
* @param e9 The ninth element to be added to the {@code IterableBuilder}.
* @param e10 The tenth element to be added to the {@code IterableBuilder}.
* @param The type of the elements contained in the returned {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IterableBuilder iterableBuilderWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) {
return iterableBuilderFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10));
}
/**
* Returns an {@code IterableBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IterableBuilder}
* instance in the same order as they are defined in the argument list.
*
* Note that this literal uses a generic varargs parameter as the last argument in the
* argument list and as such will cause unchecked cast warnings. Explicit argument
* lists for up to ten arguments have been provided for convenience. In order to avoid
* the unchecked cast warnings, an {@link IterableBuilder} instance can be used directly with
* multiple method calls accumulating the builder contents.
*
* @param e1 The first element to be added to the {@code IterableBuilder}.
* @param e2 The second element to be added to the {@code IterableBuilder}.
* @param e3 The third element to be added to the {@code IterableBuilder}.
* @param e4 The fourth element to be added to the {@code IterableBuilder}.
* @param e5 The fifth element to be added to the {@code IterableBuilder}.
* @param e6 The sixth element to be added to the {@code IterableBuilder}.
* @param e7 The seventh element to be added to the {@code IterableBuilder}.
* @param e8 The eighth element to be added to the {@code IterableBuilder}.
* @param e9 The ninth element to be added to the {@code IterableBuilder}.
* @param e10 The tenth element to be added to the {@code IterableBuilder}.
* @param e11on The remaining elements to be added to the {@code IterableBuilder}. The elements
* will be added to the {@code IterableBuilder} in the order they are defined in the
* variadic argument..
* @param The type of the elements contained in the returned {@code IterableBuilder}.
* @return An {@code IterableBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IterableBuilder iterableBuilderWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10, E... e11on) {
return iterableBuilderFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10)).with(e11on);
}
/**
* Returns an empty immutable {@code Iterator} instance.
*
* This form of literal is most suited to direct assignment to a variable
* since in this case, the type {@code E} is inferred from the variable
* declaration. For example:
*
*
* Iterator<String> strings = iterator();
*
*
*
* @param The type of the elements contained in the {@code Iterator}.
* @return An {@code Iterator} instance over the type {@code E} containing no elements.
*/
public static Iterator iterator() {
return new IteratorBuilder().build();
}
/**
* Returns an empty immutable {@code Iterator} instance of the supplied concrete class.
*
* The supplied class must have a public no-argument constructor, otherwise
* an {@code IllegalArgumentException} will be thrown.
*
* @param iteratorClass The class of the {@code Iterator} implementation to be
* instantiated.
* @param The type of the elements contained in the {@code Iterator}.
* @return An {@code Iterator} instance over the type {@code E} of the concrete
* type specified by the supplied {@code Class}.
* @throws IllegalArgumentException if the supplied class does not have
* a public no-argument constructor.
*/
@SuppressWarnings("unchecked") public static Iterator iterator(Class iteratorClass) {
return uncheckedInstantiate(iteratorClass);
}
/**
* Returns an empty immutable {@code Iterator} instance over the type
* of the supplied {@code Class}.
*
* This form of literal is most suited to inline usage such as when passing an
* empty iterator as a parameter in a method call since it reads more clearly than
* {@link #iterator()}. For example, compare the following:
*
*
* public class Iterators {
* public static <T> Iterator<T> buffer(Iterator<T> stream) {
* ...
* }
*
* ...
* }
*
* Iterator<Character> bufferedIterator1 = Iterators.buffer(Literals.<Character>iterator());
* Iterator<Character> bufferedIterator2 = Iterators.buffer(iterableOf(Character.class));
*
*
*
* @param elementClass A {@code Class} representing the type of elements
* contained in this {@code Iterator}
* @param The type of the elements contained in the {@code Iterator}.
* @return An {@code Iterator} instance over the type {@code E} containing no elements.
*/
public static Iterator iteratorOf(Class elementClass) {
return new IteratorBuilder().build();
}
/**
* Returns an immutable {@code Iterator} instance over the type {@code E}
* containing all elements from the supplied {@code Iterable}. The order of
* the elements in the resulting {@code Iterator} is determined by the order in
* which they are yielded from the supplied {@code Iterable}.
*
* This form of literal is useful when an immutable {@code Iterator} from an
* {@code Iterable} is required. For example:
*
*
* public class DataStructure<T> implements Iterable<T> {
* private final Iterable<T> backingStore;
*
* public Iterator<T> iterator() {
* return iteratorFrom(backingStore);
* }
*
* ...
* }
*
*
*
* @param elements An {@code Iterable} of elements from which an {@code Iterator} should
* be constructed.
* @param The type of the elements to be contained in the returned
* {@code Iterator}.
* @return An {@code Iterator} over the type {@code E} containing all elements from the
* supplied {@code Iterable} in the order they are yielded.
*/
public static Iterator iteratorFrom(Iterable elements) {
return new IteratorBuilder().with(elements).build();
}
/**
* Returns an immutable {@code Iterator} instance over the type {@code E}
* containing all elements from the supplied array. The order of the elements
* in the resulting {@code Iterator} is the same as the order of the elements
* in the array.
*
* For example, the following:
*
*
* String[] strings = new String[]{"one", "two", "three"};
* Iterator<String> iteratorOfStrings = Literals.iteratorFrom(strings);
*
*
* is equivalent to:
*
*
* Iterator<String> iteratorOfStrings = Literals.iteratorWith("one", "two", "three");
*
*
*
* @param elementArray An array of elements from which an {@code Iterator} should be
* constructed.
* @param The type of the elements to be contained in the returned
* {@code Iterator}.
* @return An {@code Iterator} over the type {@code E} containing all elements from the
* supplied array in the same order as the supplied array.
*/
public static Iterator iteratorFrom(E[] elementArray) {
return new IteratorBuilder().with(elementArray).build();
}
/**
* Returns an immutable {@code Iterator} instance over the type {@code E} containing the
* supplied element.
*
* @param e An element from which to construct an {@code Iterator}.
* @param The type of the element contained in the returned {@code Iterator}.
* @return An {@code Iterator} instance over type {@code E} containing the supplied element.
*/
public static Iterator iteratorWith(E e) {
return iteratorFrom(iterableWith(e));
}
/**
* Returns an immutable {@code Iterator} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterator} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterator}.
* @param e2 The second element from which to construct an {@code Iterator}.
* @param The type of the elements contained in the returned {@code Iterator}.
* @return An {@code Iterator} instance over type {@code E} containing the supplied elements.
*/
public static Iterator iteratorWith(E e1, E e2) {
return iteratorFrom(iterableWith(e1, e2));
}
/**
* Returns an immutable {@code Iterator} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterator} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterator}.
* @param e2 The second element from which to construct an {@code Iterator}.
* @param e3 The third element from which to construct an {@code Iterator}.
* @param The type of the elements contained in the returned {@code Iterator}.
* @return An {@code Iterator} instance over type {@code E} containing the supplied elements.
*/
public static Iterator iteratorWith(E e1, E e2, E e3) {
return iteratorFrom(iterableWith(e1, e2, e3));
}
/**
* Returns an immutable {@code Iterator} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterator} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterator}.
* @param e2 The second element from which to construct an {@code Iterator}.
* @param e3 The third element from which to construct an {@code Iterator}.
* @param e4 The fourth element from which to construct an {@code Iterator}.
* @param The type of the elements contained in the returned {@code Iterator}.
* @return An {@code Iterator} instance over type {@code E} containing the supplied elements.
*/
public static Iterator iteratorWith(E e1, E e2, E e3, E e4) {
return iteratorFrom(iterableWith(e1, e2, e3, e4));
}
/**
* Returns an immutable {@code Iterator} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterator} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterator}.
* @param e2 The second element from which to construct an {@code Iterator}.
* @param e3 The third element from which to construct an {@code Iterator}.
* @param e4 The fourth element from which to construct an {@code Iterator}.
* @param e5 The fifth element from which to construct an {@code Iterator}.
* @param The type of the elements contained in the returned {@code Iterator}.
* @return An {@code Iterator} instance over type {@code E} containing the supplied elements.
*/
public static Iterator iteratorWith(E e1, E e2, E e3, E e4, E e5) {
return iteratorFrom(iterableWith(e1, e2, e3, e4, e5));
}
/**
* Returns an immutable {@code Iterator} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterator} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterator}.
* @param e2 The second element from which to construct an {@code Iterator}.
* @param e3 The third element from which to construct an {@code Iterator}.
* @param e4 The fourth element from which to construct an {@code Iterator}.
* @param e5 The fifth element from which to construct an {@code Iterator}.
* @param e6 The sixth element from which to construct an {@code Iterator}.
* @param The type of the elements contained in the returned {@code Iterator}.
* @return An {@code Iterator} instance over type {@code E} containing the supplied elements.
*/
public static Iterator iteratorWith(E e1, E e2, E e3, E e4, E e5, E e6) {
return iteratorFrom(iterableWith(e1, e2, e3, e4, e5, e6));
}
/**
* Returns an immutable {@code Iterator} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterator} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterator}.
* @param e2 The second element from which to construct an {@code Iterator}.
* @param e3 The third element from which to construct an {@code Iterator}.
* @param e4 The fourth element from which to construct an {@code Iterator}.
* @param e5 The fifth element from which to construct an {@code Iterator}.
* @param e6 The sixth element from which to construct an {@code Iterator}.
* @param e7 The seventh element from which to construct an {@code Iterator}.
* @param The type of the elements contained in the returned {@code Iterator}.
* @return An {@code Iterator} instance over type {@code E} containing the supplied elements.
*/
public static Iterator iteratorWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
return iteratorFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7));
}
/**
* Returns an immutable {@code Iterator} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterator} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterator}.
* @param e2 The second element from which to construct an {@code Iterator}.
* @param e3 The third element from which to construct an {@code Iterator}.
* @param e4 The fourth element from which to construct an {@code Iterator}.
* @param e5 The fifth element from which to construct an {@code Iterator}.
* @param e6 The sixth element from which to construct an {@code Iterator}.
* @param e7 The seventh element from which to construct an {@code Iterator}.
* @param e8 The eighth element from which to construct an {@code Iterator}.
* @param The type of the elements contained in the returned {@code Iterator}.
* @return An {@code Iterator} instance over type {@code E} containing the supplied elements.
*/
public static Iterator iteratorWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
return iteratorFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7, e8));
}
/**
* Returns an immutable {@code Iterator} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterator} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterator}.
* @param e2 The second element from which to construct an {@code Iterator}.
* @param e3 The third element from which to construct an {@code Iterator}.
* @param e4 The fourth element from which to construct an {@code Iterator}.
* @param e5 The fifth element from which to construct an {@code Iterator}.
* @param e6 The sixth element from which to construct an {@code Iterator}.
* @param e7 The seventh element from which to construct an {@code Iterator}.
* @param e8 The eighth element from which to construct an {@code Iterator}.
* @param e9 The ninth element from which to construct an {@code Iterator}.
* @param The type of the elements contained in the returned {@code Iterator}.
* @return An {@code Iterator} instance over type {@code E} containing the supplied elements.
*/
public static Iterator iteratorWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
return iteratorFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7, e8, e9));
}
/**
* Returns an immutable {@code Iterator} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterator} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct an {@code Iterator}.
* @param e2 The second element from which to construct an {@code Iterator}.
* @param e3 The third element from which to construct an {@code Iterator}.
* @param e4 The fourth element from which to construct an {@code Iterator}.
* @param e5 The fifth element from which to construct an {@code Iterator}.
* @param e6 The sixth element from which to construct an {@code Iterator}.
* @param e7 The seventh element from which to construct an {@code Iterator}.
* @param e8 The eighth element from which to construct an {@code Iterator}.
* @param e9 The ninth element from which to construct an {@code Iterator}.
* @param e10 The tenth element from which to construct an {@code Iterator}.
* @param The type of the elements contained in the returned {@code Iterator}.
* @return An {@code Iterator} instance over type {@code E} containing the supplied elements.
*/
public static Iterator iteratorWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) {
return iteratorFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10));
}
/**
* Returns an immutable {@code Iterator} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Iterator} is the same as the order
* of the elements in the argument list.
*
* Note that this literal uses a generic varargs parameter as the last argument in the
* argument list and as such will cause unchecked cast warnings. Explicit argument
* lists for up to ten arguments have been provided for convenience. In order to avoid
* the unchecked cast warnings, an {@link IteratorBuilder} can be used instead.
*
* @param e1 The first element from which to construct an {@code Iterator}.
* @param e2 The second element from which to construct an {@code Iterator}.
* @param e3 The third element from which to construct an {@code Iterator}.
* @param e4 The fourth element from which to construct an {@code Iterator}.
* @param e5 The fifth element from which to construct an {@code Iterator}.
* @param e6 The sixth element from which to construct an {@code Iterator}.
* @param e7 The seventh element from which to construct an {@code Iterator}.
* @param e8 The eighth element from which to construct an {@code Iterator}.
* @param e9 The ninth element from which to construct an {@code Iterator}.
* @param e10 The tenth element from which to construct an {@code Iterator}.
* @param e11on The remaining elements from which to construct an {@code Iterator}.
* @param The type of the elements contained in the returned {@code Iterator}.
* @return an {@code Iterator} instance over type {@code E} containing the supplied elements.
*/
public static Iterator iteratorWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10, E... e11on) {
return iteratorBuilderFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10)).with(e11on).build();
}
/**
* Returns an {@code IteratorBuilder} containing no elements.
*
* Example Usage:
* An {@code IteratorBuilder} can be used to assemble an {@code Iterator} as follows:
*
*
* Iterator<Double> iterator = Literals.<Double>iteratorBuilder()
* .with(1.34, 2.2, 3.5)
* .and(4, 5.78, 6.21)
* .build()
*
*
* This is equivalent to the following:
*
*
* Iterator<Double> iterator = Literals.iteratorWith(1.34, 2.2, 3.5, 4, 5.78, 6.21);
*
*
* The advantage of the {@code IteratorBuilder} is that the iterator can be built up from
* individual objects, arrays or existing iterables. See {@link IteratorBuilder} for
* further details.
*
* @param The type of the elements contained in the {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over the type {@code E} containing no elements.
*/
public static IteratorBuilder iteratorBuilder() {
return new IteratorBuilder();
}
/**
* Returns an {@code IteratorBuilder} over the type of the supplied {@code Class}
* containing no elements.
*
* Example Usage:
* An {@code IteratorBuilder} can be used to assemble an {@code Iterator} as follows:
*
*
* Iterator<Integer> iterator = iteratorBuilderOf(Integer.class)
* .with(new Integer[]{65, 72})
* .and(95, 43, 20)
* .build()
*
*
* This is equivalent to the following:
*
*
* Iterator<Integer> iterator = Literals.iteratorWith(65, 72, 95, 43, 20);
*
*
* The advantage of the {@code IteratorBuilder} is that the iterator can be built
* up from individual objects, arrays or existing iterables. See {@link IteratorBuilder}
* for further details.
*
* @param elementClass A {@code Class} representing the type of elements
* contained in this {@code IteratorBuilder}
* @param The type of the elements contained in the {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over the type {@code E} containing no
* elements.
*/
public static IteratorBuilder iteratorBuilderOf(Class elementClass) {
return new IteratorBuilder();
}
/**
* Returns an {@code IteratorBuilder} over type {@code E} initialised with the elements
* contained in the supplied {@code Iterator}.
*
* Example Usage:
* An {@code IteratorBuilder} can be used to assemble an {@code Iterator} from two existing
* {@code Collection} instances as follows:
*
*
* Collection<String> firstCollection = Literals.collectionWith("a", "b", "c");
* Collection<String> secondCollection = Literals.collectionWith("d", "e", "f");
* Iterator<String> iterator = iteratorBuilderFrom(firstCollection)
* .with(secondCollection)
* .build()
*
*
* This is equivalent to the following:
*
*
* Iterator<String> iterator = Literals.iteratorWith("a", "b", "c", "d", "e", "f");
*
*
* The advantage of the {@code IteratorBuilder} is that the iterator can be built up from
* individual objects, arrays or existing iterables. See {@link IteratorBuilder} for
* further details.
*
* @param elements An {@code Iterable} containing elements with which the
* {@code IteratorBuilder} should be initialised.
* @param The type of the elements contained in the {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over the type {@code E} containing
* the elements from the supplied {@code Iterable}.
*/
public static IteratorBuilder iteratorBuilderFrom(Iterable elements) {
return new IteratorBuilder().with(elements);
}
/**
* Returns an {@code IteratorBuilder} over type {@code E} initialised with the elements
* contained in the supplied array.
*
* Example Usage:
* An {@code IteratorBuilder} can be used to assemble an {@code Iterator} from two existing
* arrays as follows:
*
*
* Integer[] firstArray = new Integer[]{1, 2, 3};
* Integer[] secondArray = new Long[]{3, 4, 5};
* Iterator<Integer> iterator = iteratorBuilderFrom(firstArray)
* .with(secondArray)
* .build()
*
*
* This is equivalent to the following:
*
*
* Iterator<Integer> iterator = Literals.iteratorWith(1, 2, 3, 3, 4, 5);
*
*
* The advantage of the {@code IteratorBuilder} is that the iterator can be built up from
* individual objects, arrays or existing iterables. See {@link IteratorBuilder} for
* further details.
*
* @param elementArray An array containing elements with which the
* {@code IteratorBuilder} should be initialised.
* @param The type of the elements contained in the {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over the type {@code E} containing
* the elements from the supplied array.
*/
public static IteratorBuilder iteratorBuilderFrom(E[] elementArray) {
return new IteratorBuilder().with(elementArray);
}
/**
* Returns an {@code IteratorBuilder} instance over the type {@code E} containing
* the supplied element.
*
* @param e The element to be added to the {@code IteratorBuilder}.
* @param The type of the elements contained in the returned {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over type {@code E} containing the supplied
* element.
*/
public static IteratorBuilder iteratorBuilderWith(E e) {
return iteratorBuilderFrom(iterableWith(e));
}
/**
* Returns an {@code IteratorBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IteratorBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IteratorBuilder}.
* @param e2 The second element to be added to the {@code IteratorBuilder}.
* @param The type of the elements contained in the returned {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IteratorBuilder iteratorBuilderWith(E e1, E e2) {
return iteratorBuilderFrom(iterableWith(e1, e2));
}
/**
* Returns an {@code IteratorBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IteratorBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IteratorBuilder}.
* @param e2 The second element to be added to the {@code IteratorBuilder}.
* @param e3 The third element to be added to the {@code IteratorBuilder}.
* @param The type of the elements contained in the returned {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IteratorBuilder iteratorBuilderWith(E e1, E e2, E e3) {
return iteratorBuilderFrom(iterableWith(e1, e2, e3));
}
/**
* Returns an {@code IteratorBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IteratorBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IteratorBuilder}.
* @param e2 The second element to be added to the {@code IteratorBuilder}.
* @param e3 The third element to be added to the {@code IteratorBuilder}.
* @param e4 The fourth element to be added to the {@code IteratorBuilder}.
* @param The type of the elements contained in the returned {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IteratorBuilder iteratorBuilderWith(E e1, E e2, E e3, E e4) {
return iteratorBuilderFrom(iterableWith(e1, e2, e3, e4));
}
/**
* Returns an {@code IteratorBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IteratorBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IteratorBuilder}.
* @param e2 The second element to be added to the {@code IteratorBuilder}.
* @param e3 The third element to be added to the {@code IteratorBuilder}.
* @param e4 The fourth element to be added to the {@code IteratorBuilder}.
* @param e5 The fifth element to be added to the {@code IteratorBuilder}.
* @param The type of the elements contained in the returned {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IteratorBuilder iteratorBuilderWith(E e1, E e2, E e3, E e4, E e5) {
return iteratorBuilderFrom(iterableWith(e1, e2, e3, e4, e5));
}
/**
* Returns an {@code IteratorBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IteratorBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IteratorBuilder}.
* @param e2 The second element to be added to the {@code IteratorBuilder}.
* @param e3 The third element to be added to the {@code IteratorBuilder}.
* @param e4 The fourth element to be added to the {@code IteratorBuilder}.
* @param e5 The fifth element to be added to the {@code IteratorBuilder}.
* @param e6 The sixth element to be added to the {@code IteratorBuilder}.
* @param The type of the elements contained in the returned {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IteratorBuilder iteratorBuilderWith(E e1, E e2, E e3, E e4, E e5, E e6) {
return iteratorBuilderFrom(iterableWith(e1, e2, e3, e4, e5, e6));
}
/**
* Returns an {@code IteratorBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IteratorBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IteratorBuilder}.
* @param e2 The second element to be added to the {@code IteratorBuilder}.
* @param e3 The third element to be added to the {@code IteratorBuilder}.
* @param e4 The fourth element to be added to the {@code IteratorBuilder}.
* @param e5 The fifth element to be added to the {@code IteratorBuilder}.
* @param e6 The sixth element to be added to the {@code IteratorBuilder}.
* @param e7 The seventh element to be added to the {@code IteratorBuilder}.
* @param The type of the elements contained in the returned {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IteratorBuilder iteratorBuilderWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
return iteratorBuilderFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7));
}
/**
* Returns an {@code IteratorBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IteratorBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IteratorBuilder}.
* @param e2 The second element to be added to the {@code IteratorBuilder}.
* @param e3 The third element to be added to the {@code IteratorBuilder}.
* @param e4 The fourth element to be added to the {@code IteratorBuilder}.
* @param e5 The fifth element to be added to the {@code IteratorBuilder}.
* @param e6 The sixth element to be added to the {@code IteratorBuilder}.
* @param e7 The seventh element to be added to the {@code IteratorBuilder}.
* @param e8 The eighth element to be added to the {@code IteratorBuilder}.
* @param The type of the elements contained in the returned {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IteratorBuilder iteratorBuilderWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
return iteratorBuilderFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7, e8));
}
/**
* Returns an {@code IteratorBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IteratorBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IteratorBuilder}.
* @param e2 The second element to be added to the {@code IteratorBuilder}.
* @param e3 The third element to be added to the {@code IteratorBuilder}.
* @param e4 The fourth element to be added to the {@code IteratorBuilder}.
* @param e5 The fifth element to be added to the {@code IteratorBuilder}.
* @param e6 The sixth element to be added to the {@code IteratorBuilder}.
* @param e7 The seventh element to be added to the {@code IteratorBuilder}.
* @param e8 The eighth element to be added to the {@code IteratorBuilder}.
* @param e9 The ninth element to be added to the {@code IteratorBuilder}.
* @param The type of the elements contained in the returned {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IteratorBuilder iteratorBuilderWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
return iteratorBuilderFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7, e8, e9));
}
/**
* Returns an {@code IteratorBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IteratorBuilder}
* instance in the same order as they are defined in the argument list.
*
* @param e1 The first element to be added to the {@code IteratorBuilder}.
* @param e2 The second element to be added to the {@code IteratorBuilder}.
* @param e3 The third element to be added to the {@code IteratorBuilder}.
* @param e4 The fourth element to be added to the {@code IteratorBuilder}.
* @param e5 The fifth element to be added to the {@code IteratorBuilder}.
* @param e6 The sixth element to be added to the {@code IteratorBuilder}.
* @param e7 The seventh element to be added to the {@code IteratorBuilder}.
* @param e8 The eighth element to be added to the {@code IteratorBuilder}.
* @param e9 The ninth element to be added to the {@code IteratorBuilder}.
* @param e10 The tenth element to be added to the {@code IteratorBuilder}.
* @param The type of the elements contained in the returned {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IteratorBuilder iteratorBuilderWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) {
return iteratorBuilderFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10));
}
/**
* Returns an {@code IteratorBuilder} instance over the type {@code E} containing the
* supplied elements. The supplied elements are added to the {@code IteratorBuilder}
* instance in the same order as they are defined in the argument list.
*
* Note that this literal uses a generic varargs parameter as the last argument in the
* argument list and as such will cause unchecked cast warnings. Explicit argument
* lists for up to ten arguments have been provided for convenience. In order to avoid
* the unchecked cast warnings, an {@link IteratorBuilder} instance can be used directly with
* multiple method calls accumulating the builder contents.
*
* @param e1 The first element to be added to the {@code IteratorBuilder}.
* @param e2 The second element to be added to the {@code IteratorBuilder}.
* @param e3 The third element to be added to the {@code IteratorBuilder}.
* @param e4 The fourth element to be added to the {@code IteratorBuilder}.
* @param e5 The fifth element to be added to the {@code IteratorBuilder}.
* @param e6 The sixth element to be added to the {@code IteratorBuilder}.
* @param e7 The seventh element to be added to the {@code IteratorBuilder}.
* @param e8 The eighth element to be added to the {@code IteratorBuilder}.
* @param e9 The ninth element to be added to the {@code IteratorBuilder}.
* @param e10 The tenth element to be added to the {@code IteratorBuilder}.
* @param e11on The remaining elements to be added to the {@code IteratorBuilder}. The elements
* will be added to the {@code IteratorBuilder} in the order they are defined in the
* variadic argument.
* @param The type of the elements contained in the returned {@code IteratorBuilder}.
* @return An {@code IteratorBuilder} instance over type {@code E} containing the supplied
* elements.
*/
public static IteratorBuilder iteratorBuilderWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10, E... e11on) {
return iteratorBuilderFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10)).with(e11on);
}
/**
* Returns an empty immutable {@code Collection} instance.
*
* This form of literal is most suited to direct assignment to a variable
* since in this case, the type {@code E} is inferred from the variable
* declaration. For example:
*
*
* Collection<Long> numbers = collection();
*
*
*
* @param The type of the elements contained in the {@code Collection}.
* @return A {@code Collection} instance over the type {@code E} containing no elements.
*/
public static Collection collection() {
return new CollectionBuilder().build();
}
/**
* Returns an empty immutable {@code Collection} instance of the supplied concrete class.
*
* The supplied class must have a public no-argument constructor, otherwise
* an {@code IllegalArgumentException} will be thrown.
*
* @param collectionClass The class of the {@code Collection} implementation to be
* instantiated.
* @param The type of the elements contained in the {@code Collection}.
* @return A {@code Collection} instance over the type {@code E} of the concrete
* type specified by the supplied {@code Class}.
* @throws IllegalArgumentException if the supplied class does not have
* a public no-argument constructor.
*/
public static Collection collection(Class collectionClass) {
return new CollectionBuilder().build(collectionClass);
}
/**
* Returns an empty immutable {@code Collection} instance over the type
* of the supplied {@code Class}.
*
* This form of literal is most suited to inline usage such as when passing an
* empty collection as a parameter in a method call since it reads more clearly than
* {@link #collection()}. For example, compare the following:
*
*
* public class Tree {
* ...
*
* public void addNode(Node node, Collection<Attribute> attributes) {
* ...
* }
* }
*
* tree.addNode(new LeafNode(), Literals.<Attribute>collection());
* tree.addNode(new LeafNode(), collectionOf(Attribute.class));
*
*
*
* @param elementClass A {@code Class} representing the type of elements
* contained in this {@code Collection}
* @param The type of the elements contained in the {@code Collection}.
* @return A {@code Collection} instance over the type {@code E} containing no elements.
*/
public static Collection collectionOf(Class elementClass) {
return new CollectionBuilder().build();
}
/**
* Returns an immutable {@code Collection} instance over the type {@code E}
* containing all elements from the supplied {@code Iterable}. The order of
* the elements in the resulting {@code Collection} is determined by the order in
* which they are yielded from the supplied {@code Iterable}.
*
* This form of literal is useful when an object conforming to the {@code Collection}
* interface is required and only an {@code Iterable} is available. For example:
*
*
* Iterable<Word> words = book.getWords();
* statusBar.displayWordCount(collectionFrom(words).size());
*
*
*
* @param elements An {@code Iterable} of elements from which a {@code Collection} should
* be constructed.
* @param The type of the elements to be contained in the returned
* {@code Collection}.
* @return A {@code Collection} over the type {@code E} containing all elements from the
* supplied {@code Iterable} in the order they are yielded.
*/
public static Collection collectionFrom(Iterable elements) {
return new CollectionBuilder().with(elements).build();
}
/**
* Returns an immutable {@code Collection} instance over the type {@code E}
* containing all elements from the supplied array. The order of the elements
* in the resulting {@code Collection} is the same as the order of the elements
* in the array.
*
* For example, the following:
*
*
* String[] strings = new String[]{"one", "one", "two", "three"};
* Collection<String> collectionOfStrings = Literals.collectionFrom(strings);
*
*
* is equivalent to:
*
*
* Collection<String> collectionOfStrings = Literals.collectionWith("one", "one", "two", "three");
*
*
*
* @param elementArray An array of elements from which a {@code Collection} should be
* constructed.
* @param The type of the elements to be contained in the returned
* {@code Collection}.
* @return A {@code Collection} over the type {@code E} containing all elements from the
* supplied array in the same order as the supplied array.
*/
public static Collection collectionFrom(E[] elementArray) {
return new CollectionBuilder().with(elementArray).build();
}
/**
* Returns an immutable {@code Collection} instance over the type {@code E} containing the
* supplied element.
*
* @param e An element from which to construct a {@code Collection}.
* @param The type of the element contained in the returned {@code Collection}.
* @return A {@code Collection} instance over type {@code E} containing the supplied element.
*/
public static Collection collectionWith(E e) {
return collectionFrom(iterableWith(e));
}
/**
* Returns an immutable {@code Collection} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Collection} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct a {@code Collection}.
* @param e2 The second element from which to construct a {@code Collection}.
* @param The type of the elements contained in the returned {@code Collection}.
* @return A {@code Collection} instance over type {@code E} containing the supplied elements.
*/
public static Collection collectionWith(E e1, E e2) {
return collectionFrom(iterableWith(e1, e2));
}
/**
* Returns an immutable {@code Collection} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Collection} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct a {@code Collection}.
* @param e2 The second element from which to construct a {@code Collection}.
* @param e3 The third element from which to construct a {@code Collection}.
* @param The type of the elements contained in the returned {@code Collection}.
* @return A {@code Collection} instance over type {@code E} containing the supplied elements.
*/
public static Collection collectionWith(E e1, E e2, E e3) {
return collectionFrom(iterableWith(e1, e2, e3));
}
/**
* Returns an immutable {@code Collection} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Collection} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct a {@code Collection}.
* @param e2 The second element from which to construct a {@code Collection}.
* @param e3 The third element from which to construct a {@code Collection}.
* @param e4 The fourth element from which to construct a {@code Collection}.
* @param The type of the elements contained in the returned {@code Collection}.
* @return A {@code Collection} instance over type {@code E} containing the supplied elements.
*/
public static Collection collectionWith(E e1, E e2, E e3, E e4) {
return collectionFrom(iterableWith(e1, e2, e3, e4));
}
/**
* Returns an immutable {@code Collection} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Collection} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct a {@code Collection}.
* @param e2 The second element from which to construct a {@code Collection}.
* @param e3 The third element from which to construct a {@code Collection}.
* @param e4 The fourth element from which to construct a {@code Collection}.
* @param e5 The fifth element from which to construct a {@code Collection}.
* @param The type of the elements contained in the returned {@code Collection}.
* @return A {@code Collection} instance over type {@code E} containing the supplied elements.
*/
public static Collection collectionWith(E e1, E e2, E e3, E e4, E e5) {
return collectionFrom(iterableWith(e1, e2, e3, e4, e5));
}
/**
* Returns an immutable {@code Collection} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Collection} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct a {@code Collection}.
* @param e2 The second element from which to construct a {@code Collection}.
* @param e3 The third element from which to construct a {@code Collection}.
* @param e4 The fourth element from which to construct a {@code Collection}.
* @param e5 The fifth element from which to construct a {@code Collection}.
* @param e6 The sixth element from which to construct a {@code Collection}.
* @param The type of the elements contained in the returned {@code Collection}.
* @return A {@code Collection} instance over type {@code E} containing the supplied elements.
*/
public static Collection collectionWith(E e1, E e2, E e3, E e4, E e5, E e6) {
return collectionFrom(iterableWith(e1, e2, e3, e4, e5, e6));
}
/**
* Returns an immutable {@code Collection} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Collection} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct a {@code Collection}.
* @param e2 The second element from which to construct a {@code Collection}.
* @param e3 The third element from which to construct a {@code Collection}.
* @param e4 The fourth element from which to construct a {@code Collection}.
* @param e5 The fifth element from which to construct a {@code Collection}.
* @param e6 The sixth element from which to construct a {@code Collection}.
* @param e7 The seventh element from which to construct a {@code Collection}.
* @param The type of the elements contained in the returned {@code Collection}.
* @return A {@code Collection} instance over type {@code E} containing the supplied elements.
*/
public static Collection collectionWith(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
return collectionFrom(iterableWith(e1, e2, e3, e4, e5, e6, e7));
}
/**
* Returns an immutable {@code Collection} instance over the type {@code E} containing the
* supplied elements. The order of the resultant {@code Collection} is the same as the order
* of the elements in the argument list.
*
* @param e1 The first element from which to construct a {@code Collection}.
* @param e2 The second element from which to construct a {@code Collection}.
* @param e3 The third element from which to construct a {@code Collection}.
* @param e4 The fourth element from which to construct a {@code Collection}.
* @param e5 The fifth element from which to construct a {@code Collection}.
* @param e6 The sixth element from which to construct a {@code Collection}.
* @param e7 The seventh element from which to construct a {@code Collection}.
* @param e8 The eighth element from which to construct a {@code Collection}.
* @param The type of the elements contained in the returned {@code Collection}.
* @return A {@code Collection} instance over type {@code E} containing the supplied elements.
*/
public static