org.javimmutable.collections.util.JImmutables Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of javimmutable-collections Show documentation
Library providing immutable/persistent collection classes for Java. While collections are immutable they provide methods for adding and removing values by creating new modified copies of themselves. Each copy shares almost all of its structure with other copies to minimize memory consumption.
The newest version!
///###////////////////////////////////////////////////////////////////////////
//
// Burton Computer Corporation
// http://www.burton-computer.com
//
// Copyright (c) 2021, Burton Computer Corporation
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
//
//     Redistributions of source code must retain the above copyright
//     notice, this list of conditions and the following disclaimer.
//
//     Redistributions in binary form must reproduce the above copyright
//     notice, this list of conditions and the following disclaimer in
//     the documentation and/or other materials provided with the
//     distribution.
//
//     Neither the name of the Burton Computer Corporation nor the names
//     of its contributors may be used to endorse or promote products
//     derived from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package org.javimmutable.collections.util;

import org.javimmutable.collections.Indexed;
import org.javimmutable.collections.InsertableSequence;
import org.javimmutable.collections.JImmutableArray;
import org.javimmutable.collections.JImmutableList;
import org.javimmutable.collections.JImmutableListMap;
import org.javimmutable.collections.JImmutableMap;
import org.javimmutable.collections.JImmutableMultiset;
import org.javimmutable.collections.JImmutableSet;
import org.javimmutable.collections.JImmutableSetMap;
import org.javimmutable.collections.JImmutableStack;
import org.javimmutable.collections.MapEntry;
import org.javimmutable.collections.array.JImmutableTrieArray;
import org.javimmutable.collections.hash.JImmutableHashMap;
import org.javimmutable.collections.hash.JImmutableHashMultiset;
import org.javimmutable.collections.hash.JImmutableHashSet;
import org.javimmutable.collections.indexed.IndexedArray;
import org.javimmutable.collections.indexed.IndexedList;
import org.javimmutable.collections.inorder.JImmutableInsertOrderMap;
import org.javimmutable.collections.inorder.JImmutableInsertOrderMultiset;
import org.javimmutable.collections.inorder.JImmutableInsertOrderSet;
import org.javimmutable.collections.list.JImmutableLinkedStack;
import org.javimmutable.collections.list.JImmutableTreeList;
import org.javimmutable.collections.listmap.JImmutableHashListMap;
import org.javimmutable.collections.listmap.JImmutableInsertOrderListMap;
import org.javimmutable.collections.listmap.JImmutableTreeListMap;
import org.javimmutable.collections.sequence.EmptySequenceNode;
import org.javimmutable.collections.sequence.FilledSequenceNode;
import org.javimmutable.collections.setmap.JImmutableHashSetMap;
import org.javimmutable.collections.setmap.JImmutableInsertOrderSetMap;
import org.javimmutable.collections.setmap.JImmutableSetMapFactory;
import org.javimmutable.collections.setmap.JImmutableTemplateSetMap;
import org.javimmutable.collections.setmap.JImmutableTreeSetMap;
import org.javimmutable.collections.tree.ComparableComparator;
import org.javimmutable.collections.tree.JImmutableTreeMap;
import org.javimmutable.collections.tree.JImmutableTreeMultiset;
import org.javimmutable.collections.tree.JImmutableTreeSet;

import javax.annotation.Nonnull;
import java.util.Arrays;
import java.util.Comparator;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.stream.Collector;

/**
 * This class contains static factory methods to create instances of each of the collection interfaces.
 * Overloaded variants are provided for each to pre-populate the created collection with existing values.
 * Where possible the empty collection methods return a common singleton instance to save memory.  The
 * factory methods always return the fastest implementation of each interface (i.e. hash when sort not
 * required, trie when random access not required, etc).
 */
@SuppressWarnings("ClassWithTooManyMethods")
public final class JImmutables
{
    private JImmutables()
    {
    }

    /**
     * Produces an empty JImmutableStack.
     */
    @Nonnull
    public static  JImmutableStack stack()
    {
        return JImmutableLinkedStack.of();
    }

    /**
     * Produces a JImmutableStack containing all of the specified values.  Note that values
     * are added to the stack in the order they appear in source which means they will be
     * retrieved in the opposite order from the stack (i.e. the last value in source will
     * be the first value retrieved from the stack).
     */
    @Nonnull
    @SafeVarargs
    public static  JImmutableStack stack(T... source)
    {
        return JImmutableLinkedStack.of().insertAll(Arrays.asList(source));
    }

    /**
     * Produces a JImmutableStack containing all of the values in source.  Note that values
     * are added to the stack in the order they appear in source which means they will be
     * retrieved in the opposite order from the stack (i.e. the last value in source will
     * be the first value retrieved from the stack).
     */
    @Nonnull
    public static  JImmutableStack stack(@Nonnull Iterable source)
    {
        return JImmutableLinkedStack.of().insertAll(source);
    }

    /**
     * Produces a JImmutableStack containing all of the values in source.  Note that values
     * are added to the stack in the order they appear in source which means they will be
     * retrieved in the opposite order from the stack (i.e. the last value in source will
     * be the first value retrieved from the stack).
     */
    @Nonnull
    public static  JImmutableStack stack(@Nonnull Iterator source)
    {
        return JImmutableLinkedStack.of().insertAll(source);
    }

    /**
     * Produces an empty JImmutableList built atop a balanced binary tree.
     */
    @Nonnull
    public static  JImmutableList list()
    {
        return JImmutableTreeList.of();
    }

    /**
     * Produces a Builder for efficiently constructing a JImmutableList built atop a balanced binary tree.
     */
    @Nonnull
    public static  JImmutableList.Builder listBuilder()
    {
        return JImmutableTreeList.listBuilder();
    }

    /**
     * Efficiently collects values into a JImmutableList built atop a balanced binary tree.
     */
    @Nonnull
    public static  Collector> listCollector()
    {
        return JImmutableTreeList.createListCollector();
    }

    /**
     * Efficiently produces a JImmutableList containing all of the specified values built atop a balanced binary tree.
     */
    @Nonnull
    @SafeVarargs
    public static  JImmutableList list(T... values)
    {
        return JImmutableTreeList.of(IndexedArray.retained(values));
    }

    /**
     * Efficiently produces a JImmutableList containing all of the values in source built atop a balanced binary tree.
     */
    @Nonnull
    public static  JImmutableList list(@Nonnull Indexed source)
    {
        return JImmutableTreeList.of(source);
    }

    /**
     * Efficiently produces a JImmutableList containing all of the values in the specified range from source
     * built atop a balanced binary tree.  The values copied from source are those whose index are in the
     * range offset to (limit - 1).
     */
    @Nonnull
    public static  JImmutableList list(@Nonnull Indexed source,
                                             int offset,
                                             int limit)
    {
        return JImmutableTreeList.of(source, offset, limit);
    }

    /**
     * Efficiently produces a JImmutableList containing all of the values in source built atop a balanced binary tree.
     */
    @Nonnull
    public static  JImmutableList list(@Nonnull JImmutableSet source)
    {
        return JImmutableTreeList.of(source.iterator());
    }

    /**
     * Efficiently produces a JImmutableList containing all of the values in source built atop a balanced binary tree.
     */
    @Nonnull
    public static  JImmutableList list(@Nonnull List source)
    {
        return JImmutableTreeList.of(IndexedList.retained(source));
    }

    /**
     * Efficiently produces a JImmutableList containing all of the values in source built atop a balanced binary tree.
     */
    @Nonnull
    public static  JImmutableList list(@Nonnull Iterator source)
    {
        return JImmutableTreeList.of(source);
    }

    /**
     * Efficiently produces a JImmutableList containing all of the values in source built atop a balanced binary tree.
     */
    @Nonnull
    public static  JImmutableList list(@Nonnull JImmutableList source)
    {
        return JImmutableTreeList.of(source);
    }

    /**
     * Efficiently produces a JImmutableList containing all of the values in source built atop a balanced binary tree.
     */
    @Nonnull
    public static  JImmutableList list(@Nonnull Iterable source)
    {
        return JImmutableTreeList.of(source.iterator());
    }

    /**
     * Constructs an empty unsorted map.
     * 
     * Implementation note: The map will adopt a hash code collision strategy based on
     * the first key assigned to the map.  All keys in the map must either implement Comparable (and
     * be comparable to all other keys in the map) or not implement Comparable.  Attempting to use keys
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous keys in any map.
     */
    @Nonnull
    public static  JImmutableMap map()
    {
        return JImmutableHashMap.of();
    }

    /**
     * Constructs an unsorted map.
     * All key/value pairs from source are copied into the newly created map.
     * 

     * Implementation note: The map will adopt a hash code collision strategy based on
     * the first key in source.  All keys in the map must either implement Comparable (and
     * be comparable to all other keys in the map) or not implement Comparable.  Attempting to use keys
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous keys in any map.
     */
    @Nonnull
    public static  JImmutableMap map(@Nonnull Map source)
    {
        return JImmutableHashMap.builder().add(source).build();
    }

    /**
     * Constructs an unsorted map.
     * If source is already an unsorted map it is returned directly, otherwise a new map
     * is created and all key/value pairs from source are copied into the newly created map.
     * 

     * Implementation note: The map will adopt a hash code collision strategy based on
     * the first key in source.  All keys in the map must either implement Comparable (and
     * be comparable to all other keys in the map) or not implement Comparable.  Attempting to use keys
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous keys in any map.
     */
    @Nonnull
    public static  JImmutableMap map(@Nonnull JImmutableMap source)
    {
        if (source instanceof JImmutableHashMap) {
            return source;
        } else {
            return JImmutableHashMap.builder().add(source).build();
        }
    }

    /**
     * Constructs a Builder to produce unsorted maps.
     * 

     * Implementation note: The map will adopt a hash code collision strategy based on
     * the first key added.  All keys in the map must either implement Comparable (and
     * be comparable to all other keys in the map) or not implement Comparable.  Attempting to use keys
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous keys in any map.
     */
    @Nonnull
    public static  JImmutableMap.Builder mapBuilder()
    {
        return JImmutableHashMap.builder();
    }

    /**
     * Creates a Collector suitable for use in the stream to produce a map.
     */
    @Nonnull
    public static  Collector, ?, JImmutableMap> mapCollector()
    {
        return JImmutableHashMap.createMapCollector();
    }

    /**
     * Constructs an empty map that sorts keys in their natural sort order (using ComparableComparator).
     */
    @Nonnull
    public static , V> JImmutableMap sortedMap()
    {
        return JImmutableTreeMap.of();
    }

    /**
     * Constructs a map that sorts keys in their natural sort order (using ComparableComparator).
     * All key/value pairs from source are copied into the newly created map.
     *
     * @param source java.util.Map containing starting key/value pairs
     */
    @Nonnull
    public static , V> JImmutableMap sortedMap(@Nonnull Map source)
    {
        return sortedMap(ComparableComparator.of(), source);
    }

    /**
     * Constructs a map that sorts keys in their natural sort order (using ComparableComparator).
     * All key/value pairs from source are copied into the newly created map.
     * If source is already a sorted map using the natural sort order it will be returned directly
     * (effectively performing a simple cast).
     *
     * @param source JImmutableMap containing starting key/value pairs
     */
    @Nonnull
    public static , V> JImmutableMap sortedMap(@Nonnull JImmutableMap source)
    {
        return sortedMap(ComparableComparator.of(), source);
    }

    /**
     * Constructs a map that sorts keys using the specified Comparator.
     * 

     * Note that the Comparator MUST BE IMMUTABLE.
     * The Comparator will be retained and used throughout the life of the map and its offspring and will
     * be aggressively shared so it is imperative that the Comparator be completely immutable.
     * 

     * All key/value pairs from map are copied into the newly created map.
     */
    @Nonnull
    public static  JImmutableMap sortedMap(@Nonnull Comparator comparator)
    {
        return JImmutableTreeMap.of(comparator);
    }

    /**
     * Constructs a map that sorts keys using the specified Comparator.
     * 

     * Note that the Comparator MUST BE IMMUTABLE.
     * The Comparator will be retained and used throughout the life of the map and its offspring and will
     * be aggressively shared so it is imperative that the Comparator be completely immutable.
     * 

     * All key/value pairs from source are copied into the newly created map.
     *
     * @param source java.util.Map containing starting key/value pairs
     */
    @Nonnull
    public static  JImmutableMap sortedMap(@Nonnull Comparator comparator,
                                                       @Nonnull Map source)
    {
        return JImmutableTreeMap.builder(comparator).add(source).build();
    }

    /**
     * Constructs a map that sorts keys using the specified Comparator.
     * 

     * Note that the Comparator MUST BE IMMUTABLE.
     * The Comparator will be retained and used throughout the life of the map and its offspring and will
     * be aggressively shared so it is imperative that the Comparator be completely immutable.
     * 

     * If source is already a sorted map that uses the same comparator (as indicated by comparator.equals())
     * then source will be returned directly.  Otherwise all key/value pairs from source are copied into
     * the newly created map.
     *
     * @param source JImmutableMap containing starting key/value pairs
     */
    @Nonnull
    public static  JImmutableMap sortedMap(@Nonnull Comparator comparator,
                                                       @Nonnull JImmutableMap source)
    {
        if (source instanceof JImmutableTreeMap) {
            final JImmutableTreeMap treemap = (JImmutableTreeMap)source;
            if (treemap.getComparator().equals(comparator)) {
                return source;
            }
        }
        return JImmutableTreeMap.builder(comparator).add(source).build();
    }

    /**
     * Create a Builder to construct sorted maps using the natural order of the keys.
     */
    @Nonnull
    public static , V> JImmutableMap.Builder sortedMapBuilder()
    {
        return JImmutableTreeMap.builder();
    }

    /**
     * Create a Builder to construct sorted maps using the specified Comparator for keys.
     */
    @Nonnull
    public static  JImmutableMap.Builder sortedMapBuilder(@Nonnull Comparator comparator)
    {
        return JImmutableTreeMap.builder(comparator);
    }

    /**
     * Creates a Collector suitable for use in the stream to produce a sorted map.
     */
    @Nonnull
    public static , V> Collector, ?, JImmutableMap> sortedMapCollector()
    {
        return JImmutableTreeMap.createMapCollector();
    }

    /**
     * Creates a Collector suitable for use in the stream to produce a sorted map.
     */
    @Nonnull
    public static , V> Collector, ?, JImmutableMap> sortedMapCollector(@Nonnull Comparator comparator)
    {
        return JImmutableTreeMap.createMapCollector(comparator);
    }

    /**
     * Constructs an empty map whose iterators traverse elements in the same order that they
     * were originally added to the map.  Similar to LinkedHapMap.
     * 

     * The map will adopt a hash code collision strategy based on
     * the first key assigned to the map.  All keys in the map must either implement Comparable (and
     * be comparable to all other keys in the map) or not implement Comparable.  Attempting to use keys
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous keys in any map.
     */
    @Nonnull
    public static  JImmutableMap insertOrderMap()
    {
        return JImmutableInsertOrderMap.of();
    }

    /**
     * Constructs a map whose iterators traverse elements in the same order that they
     * were originally added to the map.  Similar to LinkedHapMap.
     * All key/value pairs from source are copied into the newly created map.
     * 

     * The map will adopt a hash code collision strategy based on
     * the first key in source.  All keys in the map must either implement Comparable (and
     * be comparable to all other keys in the map) or not implement Comparable.  Attempting to use keys
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous keys in any map.
     */
    @Nonnull
    public static  JImmutableMap insertOrderMap(@Nonnull Map source)
    {
        return Functions.assignAll(JImmutableInsertOrderMap.of(), source);
    }

    /**
     * Constructs a map whose iterators traverse elements in the same order that they
     * were originally added to the map.  Similar to LinkedHapMap.
     * If source is already an in order map it is returned directly, otherwise a new map
     * is created and all key/value pairs from source are copied into the newly created map.
     * In this case the iteration order for those entries would be based on the order of elements
     * returned by source's iterator.
     * 

     * The map will adopt a hash code collision strategy based on
     * the first key in source.  All keys in the map must either implement Comparable (and
     * be comparable to all other keys in the map) or not implement Comparable.  Attempting to use keys
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous keys in any map.
     */
    @Nonnull
    public static  JImmutableMap insertOrderMap(@Nonnull JImmutableMap source)
    {
        if (source instanceof JImmutableInsertOrderMap) {
            return source;
        } else {
            return Functions.assignAll(JImmutableInsertOrderMap.of(), source);
        }
    }

    /**
     * Create a Builder to construct maps whose iterators visit entries in the same order they were
     * added to the map.
     */
    @Nonnull
    public static  JImmutableMap.Builder insertOrderMapBuilder()
    {
        return JImmutableInsertOrderMap.builder();
    }

    /**
     * Creates a Collector suitable for use in the stream to produce an insert order map.
     */
    @Nonnull
    public static  Collector, ?, JImmutableMap> insertOrderMapCollector()
    {
        return JImmutableInsertOrderMap.of().mapCollector();
    }

    /**
     * Constructs an unsorted set.
     * 

     * Implementation note: The set will adopt a hash code collision strategy based on
     * the first value assigned to the set.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    public static  JImmutableSet set()
    {
        return JImmutableHashSet.of();
    }

    /**
     * Constructs an unsorted set containing the values from source.
     * 

     * Implementation note: The set will adopt a hash code collision strategy based on
     * the first value in source.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    @SafeVarargs
    public static  JImmutableSet set(T... source)
    {
        return JImmutableHashSet.builder().add(source).build();
    }

    /**
     * Constructs an unsorted set containing the values from source.
     * 

     * Implementation note: The set will adopt a hash code collision strategy based on
     * the first value in source.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    public static  JImmutableSet set(@Nonnull Iterable source)
    {
        return JImmutableHashSet.builder().add(source).build();
    }

    /**
     * Constructs an unsorted set containing the values from source.
     * 

     * Implementation note: The set will adopt a hash code collision strategy based on
     * the first value in source.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    public static  JImmutableSet set(@Nonnull Iterator source)
    {
        return JImmutableHashSet.builder().add(source).build();
    }

    /**
     * Constructs Builder object to produce unsorted sets.
     * 

     * Implementation note: The set will adopt a hash code collision strategy based on
     * the first value assigned to the set.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    public static  JImmutableSet.Builder setBuilder()
    {
        return JImmutableHashSet.builder();
    }

    /**
     * Collects into an unsorted set to the set.
     */
    @Nonnull
    public static  Collector> setCollector()
    {
        return JImmutables.set().setCollector();
    }

    /**
     * Constructs an empty set that sorts values in their natural sort order (using ComparableComparator).
     */
    @Nonnull
    public static > JImmutableSet sortedSet()
    {
        return JImmutableTreeSet.of();
    }

    /**
     * Constructs a set containing all of the values in source that sorts values in their
     * natural sort order (using ComparableComparator).
     */
    @Nonnull
    @SafeVarargs
    public static > JImmutableSet sortedSet(T... source)
    {
        return JImmutableTreeSet.builder().add(source).build();
    }

    /**
     * Constructs a set containing all of the values in source that sorts values in their
     * natural sort order (using ComparableComparator).
     */
    @Nonnull
    public static > JImmutableSet sortedSet(@Nonnull Iterable source)
    {
        return JImmutableTreeSet.builder().add(source).build();
    }

    /**
     * Constructs a set containing all of the values in source that sorts values in their
     * natural sort order (using ComparableComparator).
     */
    @Nonnull
    public static > JImmutableSet sortedSet(@Nonnull Iterator source)
    {
        return JImmutableTreeSet.builder().add(source).build();
    }

    /**
     * Constructs an empty set that sorts values using comparator.
     * 

     * Note that the Comparator MUST BE IMMUTABLE.
     * The Comparator will be retained and used throughout the life of the map and its offspring and will
     * be aggressively shared so it is imperative that the Comparator be completely immutable.
     */
    @Nonnull
    public static  JImmutableSet sortedSet(@Nonnull Comparator comparator)
    {
        return JImmutableTreeSet.of(comparator);
    }

    /**
     * Constructs a set containing all of the values in source that sorts values using comparator.
     * 

     * Note that the Comparator MUST BE IMMUTABLE.
     * The Comparator will be retained and used throughout the life of the map and its offspring and will
     * be aggressively shared so it is imperative that the Comparator be completely immutable.
     */
    @Nonnull
    @SafeVarargs
    public static  JImmutableSet sortedSet(@Nonnull Comparator comparator,
                                                 T... source)
    {
        return JImmutableTreeSet.builder(comparator).add(source).build();
    }

    /**
     * Constructs a set containing all of the values in source that sorts values using comparator.
     * 

     * Note that the Comparator MUST BE IMMUTABLE.
     * The Comparator will be retained and used throughout the life of the map and its offspring and will
     * be aggressively shared so it is imperative that the Comparator be completely immutable.
     */
    @Nonnull
    public static  JImmutableSet sortedSet(@Nonnull Comparator comparator,
                                                 @Nonnull Iterable source)
    {
        return JImmutableTreeSet.builder(comparator).add(source).build();
    }

    /**
     * Constructs a set containing all of the values in source that sorts values using comparator.
     * 

     * Note that the Comparator MUST BE IMMUTABLE.
     * The Comparator will be retained and used throughout the life of the map and its offspring and will
     * be aggressively shared so it is imperative that the Comparator be completely immutable.
     */
    @Nonnull
    public static  JImmutableSet sortedSet(@Nonnull Comparator comparator,
                                                 @Nonnull Iterator source)
    {
        return JImmutableTreeSet.builder(comparator).add(source).build();
    }

    /**
     * Constructs a Builder object to produce sets that sort values in their natural
     * sort order (using ComparableComparator).
     */
    @Nonnull
    public static > JImmutableSet.Builder sortedSetBuilder()
    {
        return JImmutableTreeSet.builder();
    }

    /**
     * Constructs a Builder object to produce sets that sort values using specified Comparator.
     */
    @Nonnull
    public static  JImmutableSet.Builder sortedSetBuilder(@Nonnull Comparator comparator)
    {
        return JImmutableTreeSet.builder(comparator);
    }

    /**
     * Collects values into a sorted JImmutableSet using natural sort order of elements.
     */
    @Nonnull
    public static > Collector> sortedSetCollector()
    {
        return JImmutables.sortedSet().setCollector();
    }

    /**
     * Collects values into a sorted JImmutableSet using specified Comparator.
     */
    @Nonnull
    public static  Collector> sortedSetCollector(@Nonnull Comparator comparator)
    {
        return JImmutables.sortedSet(comparator).setCollector();
    }

    /**
     * Constructs an empty set that sorts values based on the order they were originally added to the set.
     * 

     * Implementation note: The set will adopt a hash code collision strategy based on
     * the first value assigned to the set.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    public static  JImmutableSet insertOrderSet()
    {
        return JImmutableInsertOrderSet.of();
    }

    /**
     * Constructs a set containing all of the values in source that sorts values based on
     * the order they were originally added to the set.
     * 

     * Implementation note: The set will adopt a hash code collision strategy based on
     * the first value assigned to the set.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    @SafeVarargs
    public static  JImmutableSet insertOrderSet(T... source)
    {
        return JImmutableInsertOrderSet.builder().add(source).build();
    }

    /**
     * Constructs a set containing all of the values in source that sorts values based on
     * the order they were originally added to the set.
     * 

     * Implementation note: The set will adopt a hash code collision strategy based on
     * the first value assigned to the set.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    public static  JImmutableSet insertOrderSet(@Nonnull Iterable source)
    {
        return JImmutableInsertOrderSet.builder().add(source).build();
    }

    /**
     * Constructs a set containing all of the values in source that sorts values based on
     * the order they were originally added to the set.
     * 

     * Implementation note: The set will adopt a hash code collision strategy based on
     * the first value assigned to the set.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    public static  JImmutableSet insertOrderSet(@Nonnull Iterator source)
    {
        return JImmutableInsertOrderSet.builder().add(source).build();
    }

    /**
     * Constructs Builder object to produce sets that sort values based on
     * the order they were originally added to the set.
     * 

     * Implementation note: The set will adopt a hash code collision strategy based on
     * the first value assigned to the set.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    public static  JImmutableSet.Builder insertOrderSetBuilder()
    {
        return JImmutableInsertOrderSet.builder();
    }

    /**
     * Collects into a set that sorts values based on the order they were originally added to the set.
     * 

     * Implementation note: The set will adopt a hash code collision strategy based on
     * the first value assigned to the set.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    public static  Collector> insertOrderSetCollector()
    {
        return JImmutables.insertOrderSet().setCollector();
    }

    /**
     * Constructs an unsorted multiset.
     * 

     * Implementation note: The multiset will adopt a hash code collision strategy based on
     * the first value assigned to the multiset.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    public static  JImmutableMultiset multiset()
    {
        return JImmutableHashMultiset.of();
    }

    /**
     * Constructs an unsorted multiset containing the values from source.
     * 

     * Implementation note: The multiset will adopt a hash code collision strategy based on
     * the first value in source.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    @SafeVarargs
    public static  JImmutableMultiset multiset(T... source)
    {
        return JImmutableHashMultiset.of().insertAll(Arrays.asList(source));
    }

    /**
     * Constructs an unsorted multiset containing the values from source.
     * 

     * Implementation note: The multiset will adopt a hash code collision strategy based on
     * the first value in source.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    public static  JImmutableMultiset multiset(@Nonnull Iterable source)
    {
        return JImmutableHashMultiset.of().insertAll(source);
    }

    /**
     * Constructs an unsorted multiset containing the values from source.
     * 

     * Implementation note: The multiset will adopt a hash code collision strategy based on
     * the first value in source.  All values in the map must either implement Comparable (and
     * be comparable to all other values in the set) or not implement Comparable.  Attempting to use values
     * some of which implement Comparable and some of which do not will lead to runtime errors.  It is
     * always safest to use homogeneous values in any set.
     */
    @Nonnull
    public static  JImmutableMultiset multiset(@Nonnull Iterator source)
    {
        return JImmutableHashMultiset.of().insertAll(source);
    }

    /**
     * Collects into a multiset that sorts values based on the order they were originally added to the set.
     */
    @Nonnull
    public static  Collector> multisetCollector()
    {
        return JImmutables.multiset().multisetCollector();
    }

    /**
     * Constructs an empty set that sorts values in their natural sort order (using ComparableComparator).
     */
    @Nonnull
    public static > JImmutableMultiset sortedMultiset()
    {
        return JImmutableTreeMultiset.of();
    }

    /**
     * Constructs a multiset containing all of the values in source that sorts values in their
     * natural sort order (using ComparableComparator).
     */
    @Nonnull
    @SafeVarargs
    public static > JImmutableMultiset sortedMultiset(T... source)
    {
        return JImmutableTreeMultiset.of().insertAll(Arrays.asList(source));
    }

    /**
     * Constructs a multiset containing all of the values in source that sorts values in their
     * natural sort order (using ComparableComparator).
     */
    @Nonnull
    public static > JImmutableMultiset sortedMultiset(@Nonnull Iterable source)
    {
        return JImmutableTreeMultiset.of().insertAll(source);
    }

    /**
     * Constructs a multiset containing all of the values in source that sorts values in their
     * natural sort order (using ComparableComparator).
     */
    @Nonnull
    public static > JImmutableMultiset sortedMultiset(@Nonnull Iterator source)
    {
        return JImmutableTreeMultiset.of().insertAll(source);
    }

    /**
     * Constructs an empty multiset that sorts values using comparator.
     * 

     * Note that the Comparator MUST BE IMMUTABLE.
     * The Comparator will be retained and used throughout the life of the map and its offspring and will
     * be aggressively shared so it is imperative that the Comparator be completely immutable.
     */
    @Nonnull
    public static  JImmutableMultiset sortedMultiset(@Nonnull Comparator comparator)
    {
        return JImmutableTreeMultiset.of(comparator);
    }

    /**
     * Constructs a multiset containing all of the values in source that sorts values using comparator.
     * 

     * Note that the Comparator MUST BE IMMUTABLE.
     * The Comparator will be retained and used throughout the life of the map and its offspring and will
     * be aggressively shared so it is imperative that the Comparator be completely immutable.
     */
    @Nonnull
    @SafeVarargs
    public static  JImmutableMultiset sortedMultiset(@Nonnull Comparator comparator,
                                                           T... source)
    {
        return JImmutableTreeMultiset.of(comparator).insertAll(Arrays.asList(source));
    }

    /**
     * Constructs a multiset containing all of the values in source that sorts values using comparator.
     * 

     * Note that the Comparator MUST BE IMMUTABLE.
     * The Comparator will be retained and used throughout the life of the map and its offspring and will
     * be aggressively shared so it is imperative that the Comparator be completely immutable.
     */
    @Nonnull
    public static  JImmutableMultiset sortedMultiset(@Nonnull Comparator comparator,
                                                           @Nonnull Iterable source)
    {
        return JImmutableTreeMultiset.of(comparator).insertAll(source);
    }

    /**
     * Constructs a multiset containing all of the values in source that sorts values using comparator.
     * 
     * Note that the Comparator MUST BE IMMUTABLE.
     * The Comparator will be retained and used throughout the life of the map and its offspring and will
     * be aggressively shared so it is imperative that the Comparator be completely immutable.
     */
    @Nonnull
    public static  JImmutableMultiset sortedMultiset(@Nonnull Comparator comparator,
                                                           @Nonnull Iterator source)
    {
        return JImmutableTreeMultiset.of(comparator).insertAll(source);
    }

    /**
     * Collects values into a sorted JImmutableMultiset using natural sort order of elements.
     */
    @Nonnull
    public static > Collector> sortedMultisetCollector()
    {
        return JImmutables.sortedMultiset().multisetCollector();
    }

    /**
     * Collects values into a sorted JImmutableMultiset using specified Comparator.
     */
    @Nonnull
    public static  Collector> sortedMultisetCollector(@Nonnull Comparator comparator)
    {
        return JImmutables.sortedMultiset(comparator).multisetCollector();
    }

    /**
     * Constructs a multiset containing all of the values in source that sorts values based on
     * the order they were originally added to the multiset.
     */
    @Nonnull
    public static  JImmutableMultiset insertOrderMultiset()
    {
        return JImmutableInsertOrderMultiset.of();
    }

    /**
     * Constructs a multiset containing all of the values in source that sorts values based on
     * the order they were originally added to the multiset.
     */
    @Nonnull
    @SafeVarargs
    public static  JImmutableMultiset insertOrderMultiset(T... source)
    {
        return JImmutableInsertOrderMultiset.of().insertAll(Arrays.asList(source));
    }

    /**
     * Constructs a multiset containing all of the values in source that sorts values based on
     * the order they were originally added to the multiset.
     */
    @Nonnull
    public static  JImmutableMultiset insertOrderMultiset(@Nonnull Iterable source)
    {
        return JImmutableInsertOrderMultiset.of().insertAll(source);
    }

    /**
     * Constructs a multiset containing all of the values in source that sorts values based on
     * the order they were originally added to the multiset.
     */
    @Nonnull
    public static  JImmutableMultiset insertOrderMultiset(@Nonnull Iterator source)
    {
        return JImmutableInsertOrderMultiset.of().insertAll(source);
    }

    /**
     * Collects into a multiset that sorts values based on the order they were originally added to the set.
     */
    @Nonnull
    public static  Collector> insertOrderMultisetCollector()
    {
        return JImmutables.insertOrderMultiset().multisetCollector();
    }

    /**
     * Creates a list map with higher performance but no specific ordering of keys.
     */
    @Nonnull
    public static  JImmutableListMap listMap()
    {
        return JImmutableHashListMap.of();
    }

    /**
     * Creates a list map with keys sorted by order they are inserted.
     */
    @Nonnull
    public static  JImmutableListMap insertOrderListMap()
    {
        return JImmutableInsertOrderListMap.of();
    }

    /**
     * Creates a list map with keys sorted by their natural ordering.
     */
    @Nonnull
    public static , V> JImmutableListMap sortedListMap()
    {
        return JImmutableTreeListMap.of();
    }

    /**
     * Creates a list map with keys sorted by the specified Comparator.  The Comparator MUST BE IMMUTABLE.
     */
    @Nonnull
    public static  JImmutableListMap sortedListMap(@Nonnull Comparator comparator)
    {
        return JImmutableTreeListMap.of(comparator);
    }

    @Nonnull
    public static  Collector, ?, JImmutableListMap> listMapCollector()
    {
        return JImmutables.listMap().listMapCollector();
    }

    @Nonnull
    public static  Collector, ?, JImmutableListMap> insertOrderListMapCollector()
    {
        return JImmutables.insertOrderListMap().listMapCollector();
    }

    @Nonnull
    public static , V> Collector, ?, JImmutableListMap> sortedListMapCollector()
    {
        return JImmutables.sortedListMap().listMapCollector();
    }

    @Nonnull
    public static , V> Collector, ?, JImmutableListMap> sortedListMapCollector(@Nonnull Comparator comparator)
    {
        return JImmutables.sortedListMap(comparator).listMapCollector();
    }

    /**
     * Creates a set map with higher performance but no specific ordering of keys.
     * Sets for each key are equivalent to one created by JImmutables.set().
     */
    @Nonnull
    public static  JImmutableSetMap setMap()
    {
        return JImmutableHashSetMap.of();
    }

    /**
     * Creates a builder to build a custom JImmutableSetMap configuration from a
     * base map and set type.
     */
    @Nonnull
    public static  JImmutableSetMapFactory setMapFactory()
    {
        return new JImmutableSetMapFactory<>();
    }

    /**
     * Creates a builder to build a custom JImmutableSetMap configuration from a
     * base map and set type.   The provided classes are used to tell the java
     * type system what the target times are.  Sometimes this can be more
     * convenient than angle brackets.
     */
    @Nonnull
    public static  JImmutableSetMapFactory setMapFactory(@Nonnull Class keyClass,
                                                                     @Nonnull Class valueClass)
    {
        return new JImmutableSetMapFactory<>();
    }

    @Nonnull
    public static  Collector, ?, JImmutableSetMap> setMapCollector()
    {
        return JImmutables.setMap().setMapCollector();
    }

    @Nonnull
    public static  Collector, ?, JImmutableSetMap> insertOrderSetMapCollector()
    {
        return JImmutables.insertOrderSetMap().setMapCollector();
    }

    @Nonnull
    public static , V> Collector, ?, JImmutableSetMap> sortedSetMapCollector()
    {
        return JImmutables.sortedSetMap().setMapCollector();
    }

    @Nonnull
    public static , V> Collector, ?, JImmutableSetMap> sortedSetMapCollector(@Nonnull Comparator comparator)
    {
        return JImmutables.sortedSetMap(comparator).setMapCollector();
    }
    
    /**
     * Creates a set map with keys sorted by order they are inserted.
     * Sets for each value are equivalent to one created by JImmutables.set().
     */
    @Nonnull
    public static  JImmutableSetMap insertOrderSetMap()
    {
        return JImmutableInsertOrderSetMap.of();
    }

    /**
     * Creates a set map with keys sorted by their natural ordering.
     * Sets for each key are equivalent to one created by JImmutables.set().
     */
    @Nonnull
    public static , V> JImmutableSetMap sortedSetMap()
    {
        return JImmutableTreeSetMap.of();
    }

    /**
     * Creates a set map with keys sorted by the specified Comparator.  The Comparator MUST BE IMMUTABLE.
     * Sets for each value are equivalent to one created by JImmutables.set().
     */
    @Nonnull
    public static  JImmutableSetMap sortedSetMap(@Nonnull Comparator comparator)
    {
        return JImmutableTreeSetMap.of(comparator);
    }

    /**
     * Creates a set map using the provided templates for map and set.  The templates do not have to be
     * empty but the set map will always use empty versions of them internally.  This factory method
     * provided complete flexibility in the choice of map and set types by caller.
     *
     * @param templateMap instance of the type of map to use
     * @param templateSet instance of the type of set to use
     */
    @Nonnull
    public static  JImmutableSetMap setMap(@Nonnull JImmutableMap> templateMap,
                                                       @Nonnull JImmutableSet templateSet)
    {
        return JImmutableTemplateSetMap.of(templateMap, templateSet);
    }

    /**
     * Creates an empty sparse array that supports any integer (positive or negative) as an index.
     * Indexes do not need to be consecutive there can be gaps of any size between indexes.
     */
    @Nonnull
    public static  JImmutableArray array()
    {
        return JImmutableTrieArray.of();
    }

    /**
     * Creates an empty sparse array that supports any integer (positive or negative) as an index.
     * Indexes do not need to be consecutive there can be gaps of any size between indexes.
     * Copies all values into the array starting at index zero.
     */
    @Nonnull
    @SafeVarargs
    public static  JImmutableArray array(T... source)
    {
        return JImmutableTrieArray.builder().add(source).build();
    }

    /**
     * Creates a sparse array containing all of the values from source that supports any integer
     * (positive or negative) as an index.  Indexes do not need to be consecutive there can be gaps
     * of any size between indexes. Copies all entries into the array using each key as an index
     * for storing the corresponding value.
     */
    @Nonnull
    public static  JImmutableArray array(@Nonnull Iterator> source)
    {
        return JImmutableTrieArray.of().insertAll(source);
    }

    /**
     * Creates a sparse array containing all of the values from source that supports any integer
     * (positive or negative) as an index.  Indexes do not need to be consecutive there can be gaps
     * of any size between indexes. Copies all entries into the array using each key as an index
     * for storing the corresponding value.
     */
    @Nonnull
    public static  JImmutableArray array(@Nonnull Indexed source)
    {
        return JImmutableTrieArray.builder().add(source).build();
    }

    /**
     * Creates a sparse array containing all of the values in the specified range from source that
     * supports any integer (positive or negative) as an index.  Indexes do not need to be
     * consecutive there can be gaps of any size between indexes. Copies all entries into the
     * array using each key as an index for storing the corresponding value.  The values copied
     * from source are those whose index are in the range offset to (limit - 1).
     */
    @Nonnull
    public static  JImmutableArray array(@Nonnull Indexed source,
                                               int offset,
                                               int limit)
    {
        return JImmutableTrieArray.builder().add(source, offset, limit).build();
    }

    /**
     * Creates a sparse array containing all of the values from source that supports any integer
     * (positive or negative) as an index.  Indexes do not need to be consecutive there can be gaps
     * of any size between indexes. Copies all entries into the array using each key as an index
     * for storing the corresponding value.
     */
    @Nonnull
    public static  JImmutableArray array(@Nonnull Iterable source)
    {
        return JImmutableTrieArray.builder().add(source).build();
    }

    /**
     * Produces a Builder for efficiently constructing a JImmutableArray
     * built atop a 32-way integer trie.  All values added by the builder are
     * assigned consecutive indices starting with zero.
     */
    @Nonnull
    public static  JImmutableArray.Builder arrayBuilder()
    {
        return JImmutableTrieArray.builder();
    }

    /**
     * Collects values into a JImmutableArray.
     */
    @Nonnull
    public static  Collector> arrayCollector()
    {
        return JImmutableTrieArray.collector();
    }

    /**
     * Creates an empty InsertableSequence.
     */
    @Nonnull
    public static  InsertableSequence sequence()
    {
        return EmptySequenceNode.of();
    }

    /**
     * Creates an InsertableSequence with a single value.
     */
    @Nonnull
    public static  InsertableSequence sequence(T value)
    {
        return FilledSequenceNode.of(value);
    }

    /**
     * Convenience function to create a JImmutableMap.Entry.
     */
    @Nonnull
    public static  JImmutableMap.Entry entry(K1 key,
                                                                                     V1 value)
    {
        return MapEntry.of(key, value);
    }

    /**
     * Convenience function to create a JImmutableMap.Entry.
     */
    @Nonnull
    public static  JImmutableMap.Entry entry(@Nonnull JImmutableMap.Entry e)
    {
        return MapEntry.of(e.getKey(), e.getValue());
    }

    /**
     * Convenience function to create a Map.Entry.
     */
    @Nonnull
    public static  JImmutableMap.Entry entry(@Nonnull Map.Entry e)
    {
        return MapEntry.of(e.getKey(), e.getValue());
    }
}