Groovy JDK

## java.util
Class List

Method Summary
`boolean` | `addAll(int index, Object[] items)` Modifies this list by inserting all of the elements in the specified array into the list at the specified position.
`List` | `asImmutable()` A convenience method for creating an immutable list
`List` | `asSynchronized()` A convenience method for creating a synchronized List.
`List` | `collate(int size)` Collates this list into sub-lists of length `size`.
`List` | `collate(int size, int step)` Collates this list into sub-lists of length `size` stepping through the code `step` elements for each subList.
`List` | `collate(int size, boolean keepRemainder)` Collates this list into sub-lists of length `size`.
`List` | `collate(int size, int step, boolean keepRemainder)` Collates this list into sub-lists of length `size` stepping through the code `step` elements for each sub-list.
`List` | `drop(int num)` Drops the given number of elements from the head of this list if they are available.
`List` | `dropWhile(Closure condition)` Returns a suffix of this List where elements are dropped from the front while the given Closure evaluates to true.
`boolean` | `equals(Object[] right)` Determines if the contents of this list are equal to the contents of the given array in the same order.
`boolean` | `equals(List right)` Compare the contents of two Lists.
`Process` | `execute()` Executes the command specified by the given list.
`Process` | `execute(String[] envp, File dir)` Executes the command specified by the given list, with the environment defined by `envp` and under the working directory `dir`.
`Process` | `execute(List envp, File dir)` Executes the command specified by the given list, with the environment defined by `envp` and under the working directory `dir`.
`Object` | `first()` Returns the first item from the List.
`List` | `getAt(Range range)` Support the range subscript operator for a List.
`List` | `getAt(EmptyRange range)` Support the range subscript operator for a List.
`List` | `getAt(Collection indices)` Select a List of items from a List using a Collection to identify the indices to be selected.
`Object` | `getAt(int idx)` Support the subscript operator for a List.
`Object` | `head()` Returns the first item from the List.
`Object` | `last()` Returns the last item from the List.
`List` | `minus(Collection removeMe)` Create a List composed of the elements of the first list minus every occurrence of elements of the given Collection.
`List` | `minus(Iterable removeMe)` Create a List composed of the elements of the first list minus every occurrence of elements of the given Iterable.
`List` | `minus(Object removeMe)` Create a new List composed of the elements of the first list minus every occurrence of the given element to remove.
`Set` | `permutations()` Finds all permutations of a collection.
`List` | `plus(int index, Object[] items)` Creates a new List by inserting all of the elements in the specified array to the elements from the original List at the specified index.
`List` | `plus(int index, List additions)` Creates a new List by inserting all of the elements in the given additions List to the elements from the original List at the specified index.
`List` | `plus(int index, Iterable additions)` Creates a new List by inserting all of the elements in the given Iterable to the elements from this List at the specified index.
`Object` | `pop()` Removes the last item from the List.
`boolean` | `push(Object value)` Appends an item to the List.
`void` | `putAt(int idx, Object value)` A helper method to allow lists to work with subscript operators.
`void` | `putAt(EmptyRange range, Object value)` A helper method to allow lists to work with subscript operators.
`void` | `putAt(EmptyRange range, Collection value)` A helper method to allow lists to work with subscript operators.
`void` | `putAt(IntRange range, Collection col)` List subscript assignment operator when given a range as the index and the assignment operand is a collection.
`void` | `putAt(IntRange range, Object value)` List subscript assignment operator when given a range as the index.
`void` | `putAt(List splice, List values)` A helper method to allow lists to work with subscript operators.
`void` | `putAt(List splice, Object value)` A helper method to allow lists to work with subscript operators.
`List` | `reverse()` Creates a new List with the identical contents to this list but in reverse order.
`List` | `reverse(boolean mutate)` Reverses the elements in a list.
`List` | `reverseEach(Closure closure)` Iterate over each element of the list in the reverse order.
`Set` | `subsequences()` Finds all non-null subsequences of a list.
`List` | `tail()` Returns the items from the List excluding the first item.
`List` | `take(int num)` Returns the first `num` elements from the head of this list.
`List` | `takeWhile(Closure condition)` Returns the longest prefix of this list where each element passed to the given closure condition evaluates to true.
`SpreadMap` | `toSpreadMap()` Creates a spreadable map from this list.
`List` | `transpose()` Adds GroovyCollections#transpose(List) as a method on lists.
`List` | `withDefault(Closure init)` An alias for `withLazyDefault` which decorates a list allowing it to grow when called with index values outside the normal list bounds.
`List` | `withEagerDefault(Closure init)` Decorates a list allowing it to grow when called with a non-existent index value.
`List` | `withLazyDefault(Closure init)` Decorates a list allowing it to grow when called with a non-existent index value.

Method Detail

### addAll

    public boolean addAll(int index, Object[] items)

  Modifies this list by inserting all of the elements in the specified array into the list at the specified position. Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in this list in the order that they occur in the array. The behavior of this operation is undefined if the specified array is modified while the operation is in progress. See also `plus` for similar functionality with copy semantics, i.e. which produces a new list after adding the additional items at the specified position but leaves the original list unchanged.

Parameters:
  `items` - array containing elements to be added to this collection.
  `index` - index at which to insert the first element from the specified array.

Returns:
  `true` if this collection changed as a result of the call

Since:
  1.7.2

See:
  List#addAll(int, Collection).

### asImmutable

    public List asImmutable()

  A convenience method for creating an immutable list

Returns:
  an immutable List

Since:
  1.0

See:
  Collections#unmodifiableList.

### asSynchronized

    public List asSynchronized()

  A convenience method for creating a synchronized List.

Returns:
  a synchronized List

Since:
  1.0

See:
  Collections#synchronizedList.

### collate

    public List collate(int size)

  Collates this list into sub-lists of length `size`. Example:

      def list = [ 1, 2, 3, 4, 5, 6, 7 ]
      def coll = list.collate( 3 )
      assert coll == [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7 ] ]

Parameters:
  `size` - the length of each sub-list in the returned list.

Returns:
  a List containing the data collated into sub-lists

Since:
  1.8.6

### collate

    public List collate(int size, int step)

  Collates this list into sub-lists of length `size` stepping through the code `step` elements for each subList. Example:

      def list = [ 1, 2, 3, 4 ]
      def coll = list.collate( 3, 1 )
      assert coll == [ [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4 ], [ 4 ] ]

Parameters:
  `size` - the length of each sub-list in the returned list.
  `step` - the number of elements to step through for each sub-list.

Returns:
  a List containing the data collated into sub-lists

Since:
  1.8.6

### collate

    public List collate(int size, boolean keepRemainder)

  Collates this list into sub-lists of length `size`. Any remaining elements in the list after the subdivision will be dropped if `keepRemainder` is false. Example:

      def list = [ 1, 2, 3, 4, 5, 6, 7 ]
      def coll = list.collate( 3, false )
      assert coll == [ [ 1, 2, 3 ], [ 4, 5, 6 ] ]

Parameters:
  `size` - the length of each sub-list in the returned list.
  `keepRemainder` - if true, any rmeaining elements are returned as sub-lists. Otherwise they are discarded.

Returns:
  a List containing the data collated into sub-lists

Since:
  1.8.6

### collate

    public List collate(int size, int step, boolean keepRemainder)

  Collates this list into sub-lists of length `size` stepping through the code `step` elements for each sub-list. Any remaining elements in the list after the subdivision will be dropped if `keepRemainder` is false. Example:

      def list = [ 1, 2, 3, 4 ]
      assert list.collate( 3, 1, true  ) == [ [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4 ], [ 4 ] ]
      assert list.collate( 3, 1, false ) == [ [ 1, 2, 3 ], [ 2, 3, 4 ] ]

Parameters:
  `size` - the length of each sub-list in the returned list.
  `step` - the number of elements to step through for each sub-list.
  `keepRemainder` - if true, any rmeaining elements are returned as sub-lists. Otherwise they are discarded.

Returns:
  a List containing the data collated into sub-lists

Since:
  1.8.6

### drop

    public List drop(int num)

  Drops the given number of elements from the head of this list if they are available.

      def strings = [ 'a', 'b', 'c' ]
      assert strings.drop( 0 ) == [ 'a', 'b', 'c' ]
      assert strings.drop( 2 ) == [ 'c' ]
      assert strings.drop( 5 ) == []

  Similar to Iterable#drop(int) except that it attempts to preserve the type of the original list.

Parameters:
  `num` - the number of elements to drop from this list.

Returns:
  a list consisting of all elements of this list except the first `num` ones, or else the empty list, if this list has less than `num` elements.

Since:
  1.8.1

### dropWhile

    public List dropWhile(Closure condition)

  Returns a suffix of this List where elements are dropped from the front while the given Closure evaluates to true. Similar to Iterable#dropWhile except that it attempts to preserve the type of the original list.

      def nums = [ 1, 3, 2 ]
      assert nums.dropWhile{ it < 4 } == []
      assert nums.dropWhile{ it < 3 } == [ 3, 2 ]
      assert nums.dropWhile{ it != 2 } == [ 2 ]
      assert nums.dropWhile{ it == 0 } == [ 1, 3, 2 ]

Parameters:
  `condition` - the closure that must evaluate to true to continue dropping elements.

Returns:
  the shortest suffix of the given List such that the given closure condition evaluates to true for each element dropped from the front of the List

Since:
  1.8.7

### equals

    public boolean equals(Object[] right)

  Determines if the contents of this list are equal to the contents of the given array in the same order. This returns `false` if either collection is `null`.

      assert [1, "a"].equals( [ 1, "a" ] as Object[] )

Parameters:
  `right` - the Object[] being compared to.

Returns:
  true if the contents of both collections are equal

Since:
  1.5.0

### equals

    public boolean equals(List right)

  Compare the contents of two Lists. Order matters. If numbers exist in the Lists, then they are compared as numbers, for example 2 == 2L. If both lists are `null`, the result is true; otherwise if either list is `null`, the result is `false`.

      assert ["a", 2].equals(["a", 2])
      assert ![2, "a"].equals("a", 2)
      assert [2.0, "a"].equals(2L, "a") // number comparison at work

Parameters:
  `right` - the List being compared to.

Returns:
  boolean `true` if the contents of both lists are identical, `false` otherwise.

Since:
  1.0

### execute

    public Process execute()

  Executes the command specified by the given list. The toString() method is called for each item in the list to convert into a resulting String. The first item in the list is the command the others are the parameters.

  For more control over Process construction you can use `java.lang.ProcessBuilder` (JDK 1.5+).

Returns:
  the Process which has just started for this command line representation.

Since:
  1.0

### execute

    public Process execute(String[] envp, File dir)

  Executes the command specified by the given list, with the environment defined by `envp` and under the working directory `dir`. The first item in the list is the command; the others are the parameters. The toString() method is called on items in the list to convert them to Strings.

  For more control over Process construction you can use `java.lang.ProcessBuilder` (JDK 1.5+).

Parameters:
  `envp` - an array of Strings, each member of which has environment variable settings in the format name=value, or `null` if the subprocess should inherit the environment of the current process..
  `dir` - the working directory of the subprocess, or `null` if the subprocess should inherit the working directory of the current process..

Returns:
  the Process which has just started for this command line representation.

Since:
  1.7.1

### execute

    public Process execute(List envp, File dir)

  Executes the command specified by the given list, with the environment defined by `envp` and under the working directory `dir`. The first item in the list is the command; the others are the parameters. The toString() method is called on items in the list to convert them to Strings.

  For more control over Process construction you can use `java.lang.ProcessBuilder` (JDK 1.5+).

Parameters:
  `envp` - a List of Objects (converted to Strings using toString), each member of which has environment variable settings in the format name=value, or `null` if the subprocess should inherit the environment of the current process..
  `dir` - the working directory of the subprocess, or `null` if the subprocess should inherit the working directory of the current process..

Returns:
  the Process which has just started for this command line representation.

Since:
  1.7.1

### first

    public Object first()

  Returns the first item from the List.

      def list = [3, 4, 2]
      assert list.first() == 3
      // check original is unaltered
      assert list == [3, 4, 2]

Returns:
  the first item from the List

Since:
  1.5.5

### getAt

    public List getAt(Range range)

  Support the range subscript operator for a List.

      def list = [1, "a", 4.5, true]
      assert list[1..2] == ["a", 4.5]

Parameters:
  `range` - a Range indicating the items to get.

Returns:
  a sublist based on range borders or a new list if range is reversed

Since:
  1.0

See:
  List#subList.

### getAt

    public List getAt(EmptyRange range)

  Support the range subscript operator for a List.

      def list = [true, 1, 3.4]
      assert list[0..<0] == []

Parameters:
  `range` - a Range indicating the items to get.

Returns:
  a sublist based on range borders or a new list if range is reversed

Since:
  1.0

See:
  List#subList.

### getAt

    public List getAt(Collection indices)

  Select a List of items from a List using a Collection to identify the indices to be selected.

      def list = [true, 1, 3.4, false]
      assert list[1,0,2] == [1, true, 3.4]

Parameters:
  `indices` - a Collection of indices.

Returns:
  a new list of the values at the given indices

Since:
  1.0

### getAt

    public Object getAt(int idx)

  Support the subscript operator for a List.

      def list = [2, "a", 5.3]
      assert list[1] == "a"

Parameters:
  `idx` - an index.

Returns:
  the value at the given index

Since:
  1.0

### head

    public Object head()

  Returns the first item from the List.

      def list = [3, 4, 2]
      assert list.head() == 3
      assert list == [3, 4, 2]

Returns:
  the first item from the List

Since:
  1.5.5

### last

    public Object last()

  Returns the last item from the List.

      def list = [3, 4, 2]
      assert list.last() == 2
      // check original is unaltered
      assert list == [3, 4, 2]

Returns:
  the last item from the List

Since:
  1.5.5

### minus

    public List minus(Collection removeMe)

  Create a List composed of the elements of the first list minus every occurrence of elements of the given Collection.

      assert [1, "a", true, true, false, 5.3] - [true, 5.3] == [1, "a", false]

Parameters:
  `removeMe` - a Collection of elements to remove.

Returns:
  a List with the given elements removed

Since:
  1.0

### minus

    public List minus(Iterable removeMe)

  Create a List composed of the elements of the first list minus every occurrence of elements of the given Iterable.

      class AbcIterable implements Iterable<String> {
          Iterator<String> iterator() { "abc".iterator() }
      }
      assert "backtrack".toList() - new AbcIterable() == ["k", "t", "r", "k"]

Parameters:
  `removeMe` - an Iterable of elements to remove.

Returns:
  a List with the supplied elements removed

Since:
  1.8.7

### minus

    public List minus(Object removeMe)

  Create a new List composed of the elements of the first list minus every occurrence of the given element to remove.

      assert ["a", 5, 5, true] - 5 == ["a", true]

Parameters:
  `removeMe` - an element to remove from the list.

Returns:
  the resulting List with the given element removed

Since:
  1.0

### permutations

    public Set permutations()

  Finds all permutations of a collection.

  Example usage:

      def result = [1, 2, 3].permutations()
      assert result == [[3, 2, 1], [3, 1, 2], [1, 3, 2], [2, 3, 1], [2, 1, 3], [1, 2, 3]] as Set

Returns:
  the permutations from the list

Since:
  1.7.0

### plus

    public List plus(int index, Object[] items)

  Creates a new List by inserting all of the elements in the specified array to the elements from the original List at the specified index. Shifts the element currently at that index (if any) and any subsequent elements to the right (increasing their indices). The new elements will appear in the resulting List in the order that they occur in the original array. The behavior of this operation is undefined if the list or array operands are modified while the operation is in progress. The original list and array operands remain unchanged.

      def items = [1, 2, 3]
      def newItems = items.plus(2, 'a'..'c' as String[])
      assert newItems == [1, 2, 'a', 'b', 'c', 3]
      assert items == [1, 2, 3]

  See also `addAll` for similar functionality with modify semantics, i.e. which performs the changes on the original list itself.

Parameters:
  `items` - array containing elements to be merged with elements from the original list.
  `index` - index at which to insert the first element from the specified array.

Returns:
  the new list

Since:
  1.8.1

See:
  List#plus(int, List).

### plus

    public List plus(int index, List additions)

  Creates a new List by inserting all of the elements in the given additions List to the elements from the original List at the specified index. Shifts the element currently at that index (if any) and any subsequent elements to the right (increasing their indices). The new elements will appear in the resulting List in the order that they occur in the original lists. The behavior of this operation is undefined if the original lists are modified while the operation is in progress. The original lists remain unchanged.

      def items = [1, 2, 3]
      def newItems = items.plus(2, 'a'..'c')
      assert newItems == [1, 2, 'a', 'b', 'c', 3]
      assert items == [1, 2, 3]

  See also `addAll` for similar functionality with modify semantics, i.e. which performs the changes on the original list itself.

Parameters:
  `additions` - a List containing elements to be merged with elements from the original List.
  `index` - index at which to insert the first element from the given additions List.

Returns:
  the new list

Since:
  1.8.1

### plus

    public List plus(int index, Iterable additions)

  Creates a new List by inserting all of the elements in the given Iterable to the elements from this List at the specified index.

Parameters:
  `additions` - an Iterable containing elements to be merged with the elements from the original List.
  `index` - index at which to insert the first element from the given additions Iterable.

Returns:
  the new list

Since:
  1.8.7

See:
  List#plus(int, List).

### pop

    public Object pop()

  Removes the last item from the List. Using add() and pop() is similar to push and pop on a Stack.

      def list = ["a", false, 2]
      assert list.pop() == 2
      assert list == ["a", false]

Returns:
  the item removed from the List

Since:
  1.0

### push

    public boolean push(Object value)

  Appends an item to the List. Synonym for add().

      def list = [3, 4, 2]
      list.push("x")
      assert list == [3, 4, 2, "x"]

Parameters:
  `value` - element to be appended to this list..

Returns:
  `true` (as per the general contract of the `Collection.add` method).

Since:
  1.5.5

### putAt

    public void putAt(int idx, Object value)

  A helper method to allow lists to work with subscript operators.

      def list = [2, 3]
      list[0] = 1
      assert list == [1, 3]

Parameters:
  `idx` - an index.
  `value` - the value to put at the given index.

Since:
  1.0

### putAt

    public void putAt(EmptyRange range, Object value)

  A helper method to allow lists to work with subscript operators.

      def list = ["a", true]
      list[1..<1] = 5
      assert list == ["a", 5, true]

Parameters:
  `range` - the (in this case empty) subset of the list to set.
  `value` - the values to put at the given sublist or a Collection of values.

Since:
  1.0

### putAt

    public void putAt(EmptyRange range, Collection value)

  A helper method to allow lists to work with subscript operators.

      def list = ["a", true]
      list[1..<1] = [4, 3, 2]
      assert list == ["a", 4, 3, 2, true]

Parameters:
  `range` - the (in this case empty) subset of the list to set.
  `value` - the Collection of values.

Since:
  1.0

See:
  List#putAt.

### putAt

    public void putAt(IntRange range, Collection col)

  List subscript assignment operator when given a range as the index and the assignment operand is a collection. Example:

      def myList = [4, 3, 5, 1, 2, 8, 10]
      myList[3..5] = ["a", true]
      assert myList == [4, 3, 5, "a", true, 10]

  Items in the given range are replaced with items from the collection.

Parameters:
  `range` - the subset of the list to set.
  `col` - the collection of values to put at the given sublist.

Since:
  1.5.0

### putAt

    public void putAt(IntRange range, Object value)

  List subscript assignment operator when given a range as the index. Example:

      def myList = [4, 3, 5, 1, 2, 8, 10]
      myList[3..5] = "b"
      assert myList == [4, 3, 5, "b", 10]

  Items in the given range are replaced with the operand. The `value` operand is always treated as a single value.

Parameters:
  `range` - the subset of the list to set.
  `value` - the value to put at the given sublist.

Since:
  1.0

### putAt

    public void putAt(List splice, List values)

  A helper method to allow lists to work with subscript operators.

      def list = ["a", true, 42, 9.4]
      list[1, 4] = ["x", false]
      assert list == ["a", "x", 42, 9.4, false]

Parameters:
  `splice` - the subset of the list to set.
  `values` - the value to put at the given sublist.

Since:
  1.0

### putAt

    public void putAt(List splice, Object value)

  A helper method to allow lists to work with subscript operators.

      def list = ["a", true, 42, 9.4]
      list[1, 3] = 5
      assert list == ["a", 5, 42, 5]

Parameters:
  `splice` - the subset of the list to set.
  `value` - the value to put at the given sublist.

Since:
  1.0

### reverse

    public List reverse()

  Creates a new List with the identical contents to this list but in reverse order.

      def list = ["a", 4, false]
      assert list.reverse() == [false, 4, "a"]
      assert list == ["a", 4, false]

Returns:
  a reversed List

Since:
  1.0

See:
  List#reverse(boolean).

### reverse

    public List reverse(boolean mutate)

  Reverses the elements in a list. If mutate is true, the original list is modified in place and returned. Otherwise, a new list containing the reversed items is produced.

      def list = ["a", 4, false]
      assert list.reverse(false) == [false, 4, "a"]
      assert list == ["a", 4, false]
      assert list.reverse(true) == [false, 4, "a"]
      assert list == [false, 4, "a"]

Parameters:
  `mutate` - true if the list itself should be reversed in place and returned, false if a new list should be created.

Returns:
  a reversed List

Since:
  1.8.1

### reverseEach

    public List reverseEach(Closure closure)

  Iterate over each element of the list in the reverse order.

      def result = []
      [1,2,3].reverseEach { result << it }
      assert result == [3,2,1]

Parameters:
  `closure` - a closure to which each item is passed..

Returns:
  the original list

Since:
  1.5.0

### subsequences

    public Set subsequences()

  Finds all non-null subsequences of a list.

  Example usage:

      def result = [1, 2, 3].subsequences()
      assert result == [[1, 2, 3], [1, 3], [2, 3], [1, 2], [1], [2], [3]] as Set

Returns:
  the subsequences from the list

Since:
  1.7.0

### tail

    public List tail()

  Returns the items from the List excluding the first item.

      def list = [3, 4, 2]
      assert list.tail() == [4, 2]
      assert list == [3, 4, 2]

Returns:
  a list without its first element

Since:
  1.5.6

### take

    public List take(int num)

  Returns the first `num` elements from the head of this list.

      def strings = [ 'a', 'b', 'c' ]
      assert strings.take( 0 ) == []
      assert strings.take( 2 ) == [ 'a', 'b' ]
      assert strings.take( 5 ) == [ 'a', 'b', 'c' ]

  Similar to Iterable#take(int) except that it attempts to preserve the type of the original list.

Parameters:
  `num` - the number of elements to take from this list.

Returns:
  a list consisting of the first `num` elements of this list, or else the whole list if it has less then `num` elements.

Since:
  1.8.1

### takeWhile

    public List takeWhile(Closure condition)

  Returns the longest prefix of this list where each element passed to the given closure condition evaluates to true. Similar to Iterable#takeWhile except that it attempts to preserve the type of the original list.

      def nums = [ 1, 3, 2 ]
      assert nums.takeWhile{ it < 1 } == []
      assert nums.takeWhile{ it < 3 } == [ 1 ]
      assert nums.takeWhile{ it < 4 } == [ 1, 3, 2 ]

Parameters:
  `condition` - the closure that must evaluate to true to continue taking elements.

Returns:
  a prefix of the given list where each element passed to the given closure evaluates to true

Since:
  1.8.7

### toSpreadMap

    public SpreadMap toSpreadMap()

  Creates a spreadable map from this list.

Returns:
  a newly created SpreadMap

Since:
  1.8.0

See:
  SpreadMap#SpreadMap.
  Map#toSpreadMap.

### transpose

    public List transpose()

  Adds GroovyCollections#transpose(List) as a method on lists.
  A TransposeFunction takes a collection of columns and returns a collection of rows. The first row consists of the first element from each column. Successive rows are constructed similarly.

  Example usage:

      def result = [['a', 'b'], [1, 2]].transpose()
      assert result == [['a', 1], ['b', 2]]

      def result = [['a', 'b'], [1, 2], [3, 4]].transpose()
      assert result == [['a', 1, 3], ['b', 2, 4]]

Returns:
  a List of the transposed lists

Since:
  1.5.0

See:
  GroovyCollections#transpose.

### withDefault

    public List withDefault(Closure init)

  An alias for `withLazyDefault` which decorates a list allowing it to grow when called with index values outside the normal list bounds.

Parameters:
  `init` - a Closure with the target index as parameter which generates the default value.

Returns:
  the decorated List

Since:
  1.8.7

See:
  List#withLazyDefault.
  List#withEagerDefault.

### withEagerDefault

    public List withEagerDefault(Closure init)

  Decorates a list allowing it to grow when called with a non-existent index value. When called with such values, the list is grown in size and a default value is placed in the list by calling a supplied `init` Closure. Null values can be stored in the list.

  How it works: The decorated list intercepts all calls to `getAt(index)` and `get(index)`. If an index greater than or equal to the current `size()` is used, the list will grow automatically up to the specified index. Gaps will be filled by calling the `init` Closure. If generating a default value is a costly operation consider using `withLazyDefault`.

  Example usage:

      def list = [0, 1].withEagerDefault{ 42 }
      assert list[0] == 0
      assert list[1] == 1
      assert list[3] == 42   // default value
      assert list == [0, 1, 42, 42]   // gap filled with default value

      // illustrate using the index when generating default values
      def list2 = [5].withEagerDefault{ index -> index * index }
      assert list2[3] == 9
      assert list2 == [5, 1, 4, 9]

      // illustrate what happens with null values
      list2[2] = null
      assert list2[2] == null
      assert list2 == [5, 1, null, 9]

Parameters:
  `init` - a Closure with the target index as parameter which generates the default value.

Returns:
  the wrapped List

Since:
  1.8.7

### withLazyDefault

    public List withLazyDefault(Closure init)

  Decorates a list allowing it to grow when called with a non-existent index value. When called with such values, the list is grown in size and a default value is placed in the list by calling a supplied `init` Closure. Subsequent retrieval operations if finding a null value in the list assume it was set as null from an earlier growing operation and again call the `init` Closure to populate the retrieved value; consequently the list can't be used to store null values.

  How it works: The decorated list intercepts all calls to `getAt(index)` and `get(index)`. If an index greater than or equal to the current `size()` is used, the list will grow automatically up to the specified index. Gaps will be filled by {@code null}. If a default value should also be used to fill gaps instead of {@code null}, use `withEagerDefault`. If `getAt(index)` or `get(index)` are called and a null value is found, it is assumed that the null value was a consequence of an earlier grow list operation and the `init` Closure is called to populate the value.

  Example usage:

      def list = [0, 1].withLazyDefault{ 42 }
      assert list[0] == 0
      assert list[1] == 1
      assert list[3] == 42   // default value
      assert list == [0, 1, null, 42] // gap filled with null

      // illustrate using the index when generating default values
      def list2 = [5].withLazyDefault{ index -> index * index }
      assert list2[3] == 9
      assert list2 == [5, null, null, 9]
      assert list2[2] == 4
      assert list2 == [5, null, 4, 9]

      // illustrate what happens with null values
      list2[2] = null
      assert list2[2] == 4

Parameters:
  `init` - a Closure with the target index as parameter which generates the default value.

Returns:
  the decorated List

Since:
  1.8.7

Groovy JDK