# Class: com.pnfsoftware.jeb.util.collect.Lists

Collection of utility functions to create or manipulate concrete or abstract [lists](List).

## Constructor: Lists


## Static Method: add
- parameter: `dst`, type: `java.util.List<T>`
- parameter: `src`, type: `java.util.List<T>`
- return type: `java.util.List<T>`

Description: Add all elements of a source list to a destination list.
parameter: T: element type
parameter: dst: destination list
parameter: src: optional source list
return: the destination list

## Static Method: add
- parameter: `list`, type: `java.util.List<T>`
- parameter: `index`, type: `int`
- parameter: `elt`, type: `T`
- parameter: `def`, type: `T`

Description: Add \(insert\) the element of a collection. If the index is negative, the method throws OOB. If it is greater that the current number of elements in the list, additional elements are inserted using the provided default value.
parameter: T: element type
parameter: list: list to update
parameter: index: insertion index
parameter: elt: element to insert
parameter: def: default value used to grow the list

## Static Method: add
- parameter: `list`, type: `java.util.List<T>`
- parameter: `index`, type: `int`
- parameter: `elt`, type: `T`

Description: Add \(insert\) the element of a collection. If the index is negative, the method throws OOB. If it is greater that the current number of elements in the list, additional elements are inserted using the null default value.
parameter: T: element type
parameter: list: list to update
parameter: index: insertion index
parameter: elt: element to insert

## Static Method: addNonNulls
- parameter: `dst`, type: `java.util.List<T>`
- parameter: `src`, type: `java.util.List<? extends T>`
- return type: `java.util.List<T>`

Description: Add all non\-null source elements to a destination list.
parameter: T: element type
parameter: dst: destination list
parameter: src: optional source list
return: the destination list

## Static Method: addNonNulls
- parameter: `dst`, type: `java.util.List<T>`
- parameter: `elts`, type: `T[]`
- return type: `java.util.List<T>`

Description: Add all non\-null elements to a destination list.
parameter: T: element type
parameter: dst: destination list
parameter: elts: elements to add
return: the destination list

## Static Method: addSorted
- parameter: `sortedList`, type: `java.util.List<T>`
- parameter: `elt`, type: `T`
- return type: `int`

Description: Insert an element into a sorted list at its natural position.
parameter: T: element type
parameter: sortedList: a sorted \(natural sort\) list of comparable elements
parameter: elt: the element to be inserted
return: the insertion index

## Static Method: createArrayList
- return type: `java.util.ArrayList<T>`

Description: Create an empty [ArrayList](ArrayList).
parameter: T: element type
return: a new empty list

## Static Method: createArrayList
- parameter: `elt`, type: `T`
- return type: `java.util.ArrayList<T>`

Description: Create an [ArrayList](ArrayList) containing one element.
parameter: T: element type
parameter: elt: element to add
return: a new list

## Static Method: createArrayList
- parameter: `colls`, type: `java.util.Collection<? extends T>[]`
- return type: `java.util.ArrayList<T>`

Description: Create an [ArrayList](ArrayList) containing the elements of the provided collections.
parameter: T: element type
parameter: colls: source collections
return: a new list

## Static Method: fromIterator
- parameter: `iterable`, type: `java.lang.Iterable<T>`
- return type: `java.util.List<T>`

Description: Generate a list from an iterable.
parameter: T: element type
parameter: iterable: input iterable
return: generated list

## Static Method: get
- parameter: `list`, type: `java.util.List<? extends T>`
- parameter: `index`, type: `int`
- parameter: `safeValue`, type: `T`
- return type: `T`

Description: Get the value of a list, safely returning a provided default value if the list is null or the index out\-of\-range.
parameter: list: optional list
parameter: index: requested index
parameter: safeValue: default value
return: the value at the index, or the default value

## Static Method: get
- parameter: `list`, type: `java.util.List<? extends T>`
- parameter: `index`, type: `int`
- return type: `T`

Description: Get the value of a list, safely returning null if the list is null or the index out\-of\-range.
parameter: list: optional list
parameter: index: requested index
return: the value at the index, or null

## Static Method: getFirst
- parameter: `list`, type: `java.util.List<? extends T>`
- return type: `T`

Description: Get the first value of a list, safely returning null if the list is null or the index out\-of\-range.
parameter: list: optional list
return: the first value, or null

## Static Method: insertIntoSortedList
- parameter: `list`, type: `java.util.List<T>`
- parameter: `elt`, type: `T`

Description: Insert an additional element into a pre\-sorted list and keep the list sorted.
parameter: T: element type
parameter: list: a sorted list
parameter: elt: the element to insert into the sorted list

## Static Method: insertIntoSortedList
- parameter: `list`, type: `java.util.List<T>`
- parameter: `elt`, type: `T`
- parameter: `cmp`, type: `java.util.Comparator<T>`
- parameter: `reverse`, type: `boolean`

Description: Insert an additional element into a pre\-sorted list and keep the list sorted.
parameter: T: element type
parameter: list: a sorted list
parameter: elt: the element to insert into the sorted list
parameter: cmp: optional comparator to be used; if null, the elements must be [comparable](Comparable)
parameter: reverse: false if the list is sorted in natural \(ascending\) order, true if the list is            sorted in reverse \(descending\) order

## Static Method: last
- parameter: `list`, type: `java.util.List<T>`
- return type: `T`

Description: Retrieve the last item of a [List](List). This method is safe and returns null if the list is null or empty.
parameter: T: element type
parameter: list: a list
return: the last item at index `list.size() - 1` or null if list is null or empty

## Static Method: map
- parameter: `input`, type: `java.util.Collection<T>`
- parameter: `mapper`, type: `java.util.function.Function<? super T,? extends R>`
- return type: `java.util.List<? extends R>`

Description: Apply a 1\-to\-1 map operation to the elements of a collection and return the list of resulting new elements.
parameter: T: type of input element
parameter: R: type of output element
parameter: input: input collection
parameter: mapper: a `map()` function
return: output list

## Static Method: newArrayList
- parameter: `elts`, type: `T[]`
- return type: `java.util.ArrayList<T>`

Description: Create an [ArrayList](ArrayList) containing the provided elements.
parameter: T: element type
parameter: elts: elements to add
return: a new list

## Static Method: reverse
- parameter: `list`, type: `java.util.List<T>`
- return type: `java.util.List<T>`

Description: Reverse the provided input list.
parameter: list: a list
return: the input list \(same object\), reversed

## Static Method: reverseIterator
- parameter: `list`, type: `java.util.List<T>`
- return type: `java.util.ListIterator<T>`

Description: Get a reverse iterator on the list. The pointer is set to the last element of the list \(if any\).
parameter: list: input list
return: a list iterator positioned after the last element

## Static Method: rotate
- parameter: `list`, type: `java.util.List<T>`
- parameter: `rotateForward`, type: `boolean`

Description: Rotate the elements of a list.
parameter: T: element type
parameter: list: a list
parameter: rotateForward: if true, the elements at i are moved to i\+1 \(and the last element will            replace the first one\); else, the elements at i are moved to i\-1 \(and the first            element will replace the last one\)

## Static Method: rotate
- parameter: `list`, type: `java.util.List<T>`
- parameter: `rotateForward`, type: `boolean`
- parameter: `indexFirst`, type: `int`
- parameter: `indexLast`, type: `int`

Description: Rotate the elements of a list or a portion of the elements of a list.
parameter: T: element type
parameter: list: a list
parameter: rotateForward: if true, the elements at i are moved to i\+1 \(and the last element will            replace the first one\); else, the elements at i are moved to i\-1 \(and the first            element will replace the last one\)
parameter: indexFirst: first element to rotate \(included\)
parameter: indexLast: last element to rotate \(included\), must be greater than indexFirst

## Static Method: safe
- parameter: `list`, type: `java.util.List<T>`
- return type: `java.util.List<T>`

Description: Return a non\-null list.
parameter: T: element type
parameter: list: input list, possibly null
return: the input list or an empty list if the input was null

## Static Method: set
- parameter: `list`, type: `java.util.List<T>`
- parameter: `index`, type: `int`
- parameter: `elt`, type: `T`
- parameter: `def`, type: `T`
- return type: `T`

Description: Set the element of a collection. If the index is negative, the method throws OOB. If it is greater or equal than the current number of elements in the list, additional elements are inserted using the provided default value.
parameter: T: element type
parameter: list: list to update
parameter: index: target index
parameter: elt: element to set
parameter: def: default value used to grow the list
return: the element previously at the target index

## Static Method: set
- parameter: `list`, type: `java.util.List<T>`
- parameter: `index`, type: `int`
- parameter: `elt`, type: `T`
- return type: `T`

Description: Set the element of a collection. If the index is negative, the method throws OOB. If it is greater or equal than the current number of elements in the list, additional elements are inserted using the null default value.
parameter: T: element type
parameter: list: list to update
parameter: index: target index
parameter: elt: element to set
return: the element previously at the target index

## Static Method: subList
- parameter: `list`, type: `java.util.List<T>`
- parameter: `fromIndex`, type: `int`
- return type: `java.util.List<T>`

Description: Get a tail sub\-list of a list.
parameter: list: input list
parameter: fromIndex: start index, inclusive
return: a view of the list tail

