org.eclipse.jgit.util

## Class RefList<T extends Ref>

- java.lang.Object
- - org.eclipse.jgit.util.RefList<T>

Type Parameters:
  `T` - the type of reference being stored in the collection.

All Implemented Interfaces:
  Iterable<Ref>

    public class RefList<T extends Ref>
    extends Object
    implements 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
`static class` `RefList.Builder<T extends Ref>` Builder to facilitate fast construction of an immutable RefList.

### Constructor Summary

Constructors
`protected` `RefList(RefList<T> src)` Initialize this list to use the same backing array as another list.

### Method Summary

Methods
`RefList<T>` `add(int idx, T ref)` Add an item at a specific index.
`List<Ref>` `asList()`
`boolean` `contains(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()`
`int` `find(String name)` Locate an entry by name.
`T` `get(int idx)` Get the reference at a particular index.
`T` `get(String name)` Get a reference object by name.
`boolean` `isEmpty()`
`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()`
`String` `toString()`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Constructor Detail

#### 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 Ref> RefList<T> emptyList()

Type Parameters:
  `T` - the type of reference being stored in the collection.
Returns:
  an empty unmodifiable reference list.

#### iterator

    public Iterator<Ref> iterator()

Specified by:
  `iterator` in interface `Iterable<Ref>`

#### asList

    public final List<Ref> asList()

Returns:
  this cast as an immutable, standard `List`.

#### size

    public final int size()

Returns:
  number of items in this list.

#### isEmpty

    public final boolean isEmpty()

Returns:
  true if the size of this list is 0.

#### find

    public final int find(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(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(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 String toString()

Overrides:
  `toString` in class `Object`