Class RefList<T extends Ref>

  • Type Parameters:
    T - the type of reference being stored in the collection.
    All Implemented Interfaces:
    java.lang.Iterable<Ref>
    Direct Known Subclasses:
    RefDirectory.PackedRefList

    public class RefList<T extends Ref>
    extends java.lang.Object
    implements java.lang.Iterable<Ref>
    Specialized variant of an ArrayList to support a RefDatabase.

    This list is a hybrid of a Map<String,Ref> and of a List<Ref>. It tracks reference instances by name by keeping them sorted and performing binary search to locate an entry. Lookup time is O(log N), but addition and removal is O(N + log N) due to the list expansion or contraction costs.

    This list type is copy-on-write. Mutation methods return a new copy of the list, leaving this unmodified. As a result we cannot easily implement the List interface contract.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  RefList.Builder<T extends Ref>
      Builder to facilitate fast construction of an immutable RefList.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) int cnt  
      private static RefList<Ref> EMPTY  
      (package private) Ref[] list  
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      (package private) RefList​(Ref[] list, int cnt)  
      protected RefList​(RefList<T> src)
      Initialize this list to use the same backing array as another list.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      RefList<T> add​(int idx, T ref)
      Add an item at a specific index.
      java.util.List<Ref> asList()
      Cast this as an immutable, standard List.
      boolean contains​(java.lang.String name)
      Determine if a reference is present.
      RefList.Builder<T> copy​(int n)
      Obtain a builder initialized with the first n elements.
      static <T extends Ref>
      RefList<T>
      emptyList()
      Create an empty unmodifiable reference list.
      int find​(java.lang.String name)
      Locate an entry by name.
      T get​(int idx)
      Get the reference at a particular index.
      T get​(java.lang.String name)
      Get a reference object by name.
      boolean isEmpty()
      Get if this list is empty.
      java.util.Iterator<Ref> iterator()
      RefList<T> put​(T ref)
      Store a reference, adding or replacing as necessary.
      RefList<T> remove​(int idx)
      Remove an item at a specific index.
      RefList<T> set​(int idx, T ref)
      Obtain a new copy of the list after changing one element.
      int size()
      Get number of items in this list.
      static <T extends Ref>
      java.util.stream.Collector<T,​?,​RefList<T>>
      toRefList​(java.util.function.BinaryOperator<T> mergeFunction)
      Create a Collector for Ref.
      java.lang.String toString()
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator
    • Field Detail

      • list

        final Ref[] list
      • cnt

        final int cnt
    • Constructor Detail

      • RefList

        RefList​(Ref[] list,
                int cnt)
      • RefList

        protected RefList​(RefList<T> src)
        Initialize this list to use the same backing array as another list.
        Parameters:
        src - the source list.
    • Method Detail

      • emptyList

        public static <T extends RefRefList<T> emptyList()
        Create an empty unmodifiable reference list.
        Returns:
        an empty unmodifiable reference list.
      • iterator

        public java.util.Iterator<Ref> iterator()
        Specified by:
        iterator in interface java.lang.Iterable<T extends Ref>
      • asList

        public final java.util.List<Ref> asList()
        Cast this as an immutable, standard List.
        Returns:
        this as an immutable, standard List.
      • size

        public final int size()
        Get number of items in this list.
        Returns:
        number of items in this list.
      • isEmpty

        public final boolean isEmpty()
        Get if this list is empty.
        Returns:
        true if the size of this list is 0.
      • find

        public final int find​(java.lang.String name)
        Locate an entry by name.
        Parameters:
        name - the name of the reference to find.
        Returns:
        the index the reference is at. If the entry is not present returns a negative value. The insertion position for the given name can be computed from -(index + 1).
      • contains

        public final boolean contains​(java.lang.String name)
        Determine if a reference is present.
        Parameters:
        name - name of the reference to find.
        Returns:
        true if the reference is present; false if it is not.
      • get

        public final T get​(java.lang.String name)
        Get a reference object by name.
        Parameters:
        name - the name of the reference.
        Returns:
        the reference object; null if it does not exist in this list.
      • get

        public final T get​(int idx)
        Get the reference at a particular index.
        Parameters:
        idx - the index to obtain. Must be 0 <= idx < size().
        Returns:
        the reference value, never null.
      • copy

        public final RefList.Builder<T> copy​(int n)
        Obtain a builder initialized with the first n elements.

        Copies the first n elements from this list into a new builder, which can be used by the caller to add additional elements.

        Parameters:
        n - the number of elements to copy.
        Returns:
        a new builder with the first n elements already added.
      • set

        public final RefList<T> set​(int idx,
                                    T ref)
        Obtain a new copy of the list after changing one element.

        This list instance is not affected by the replacement. Because this method copies the entire list, it runs in O(N) time.

        Parameters:
        idx - index of the element to change.
        ref - the new value, must not be null.
        Returns:
        copy of this list, after replacing idx with ref .
      • add

        public final RefList<T> add​(int idx,
                                    T ref)
        Add an item at a specific index.

        This list instance is not affected by the addition. Because this method copies the entire list, it runs in O(N) time.

        Parameters:
        idx - position to add the item at. If negative the method assumes it was a direct return value from find(String) and will adjust it to the correct position.
        ref - the new reference to insert.
        Returns:
        copy of this list, after making space for and adding ref.
      • remove

        public final RefList<T> remove​(int idx)
        Remove an item at a specific index.

        This list instance is not affected by the addition. Because this method copies the entire list, it runs in O(N) time.

        Parameters:
        idx - position to remove the item from.
        Returns:
        copy of this list, after making removing the item at idx.
      • put

        public final RefList<T> put​(T ref)
        Store a reference, adding or replacing as necessary.

        This list instance is not affected by the store. The correct position is determined, and the item is added if missing, or replaced if existing. Because this method copies the entire list, it runs in O(N + log N) time.

        Parameters:
        ref - the reference to store.
        Returns:
        copy of this list, after performing the addition or replacement.
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • toRefList

        public static <T extends Ref> java.util.stream.Collector<T,​?,​RefList<T>> toRefList​(@Nullable
                                                                                                       java.util.function.BinaryOperator<T> mergeFunction)
        Create a Collector for Ref.
        Parameters:
        mergeFunction - if specified the result will be sorted and deduped.
        Returns:
        Collector for Ref
        Since:
        5.4