lyng/docs/List.md

# List built-in class

Mutable list of any objects.

It's class in Lyng is `List`:

    [1,2,3]::class
    >>> List

you can use it's class to ensure type:

    []::class == List
    >>> true

## Indexing

indexing is zero-based, as in C/C++/Java/Kotlin, etc.

    val list = [10, 20, 30]
    list[1]
    >>> 20

There is a shortcut for the last:

    val list = [10, 20, 30]
    [list.last, list.lastIndex]
    >>> [30,2]

__Important__ negative indexes works wherever indexes are used, e.g. in insertion and removal methods too.

## Concatenation

You can concatenate lists or iterable objects:

    assert( [4,5] + [1,2] == [4,5,1,2])
    assert( [4,5] + (1..3) == [4, 5, 1, 2, 3])
    >>> void

## Appending

To append to lists, use `+=` with elements, lists and any [Iterable] instances, but beware it will
concatenate [Iterable] objects instead of appending them. To append [Iterable] instance itself, use `list.add`:

    var list = [1, 2]
    val other = [3, 4]

    // appending lists is clear:
    list += other
    assert( list == [1, 2, 3, 4] )
    
    // but appending other Iterables could be confusing:
    list += (10..12)
    assert( list == [1, 2, 3, 4, 10, 11, 12])

    // now adding list as sublist:
    list.add(other)
    assert( list == [1, 2, 3, 4, 10, 11, 12, [3,4]])

    >>> void

## Removing elements

List is mutable, so it is possible to remove its contents. To remove a single element
by index use:

    assertEquals( [1,2,3].removeAt(1), [1,3] )
    assertEquals( [1,2,3].removeAt(0), [2,3] )
    assertEquals( [1,2,3].removeLast(), [1,2] )
    >>> void

There is a way to remove a range (see [Range] for more on ranges):

    assertEquals( [1, 4], [1,2,3,4].removeRange(1..2))
    assertEquals( [1, 4], [1,2,3,4].removeRange(1..<3))
    >>> void

Open end ranges remove head and tail elements:

    assertEquals( [3, 4, 5], [1,2,3,4,5].removeRange(..1))
    assertEquals( [3, 4, 5], [1,2,3,4,5].removeRange(..<2))
    assertEquals( [1, 2], [1,2,3,4,5].removeRange( (2..) ))
    >>> void

## Comparisons

    assert( [1, 2] != [1, 3])
    assert( [1, 2, 3] > [1, 2])
    assert( [1, 3] > [1, 2, 3])
    assert( [1, 2, 3] == [1, 2, 3])
    assert( [1, 2, 3] != [1, 2, "three"])
    // note that in the case above objects are referentially different:
    assert( [1, 2, 3] !== [1, 2, 3])
    >>> void

## In-place sort

List could be sorted in place, just like [Collection] provide sorted copies, in a very like way:

    val l1 = [6,3,1,9]
    l1.sort()
    assertEquals( [1,3,6,9], l1)
    
    l1.sortBy { -it }
    assertEquals( [1,3,6,9].reversed(), l1)
    
    l1.sort() // 1 3 6 9
    l1.sortBy { it % 4 }
    // 1,3,6,9 gives, mod 4:
    // 1 3 2 1
    // we hope we got it also stable:
    assertEquals( [1,9,6,3], l1)
    >>> void

## Members

| name                          | meaning                                      | type        |
|-------------------------------|----------------------------------------------|-------------|
| `size`                        | current size                                 | Int         |
| `add(elements...)`            | add one or more elements to the end          | Any         |
| `insertAt(index,elements...)` | insert elements at position                  | Int, Any    |
| `removeAt(index)`             | remove element at position                   | Int         |
| `remove(from,toNonInclusive)` | remove range from (incl) to (nonincl)        | Int, Int    |
| `remove(Range)`               | remove range                                 | Range       |
| `removeLast()`                | remove last element                          |             |
| `removeLast(n)`               | remove n last elements                       | Int         |
| `contains(element)`           | check the element is in the list (1)         |             |
| `[index]`                     | get or set element at index                  | Int         |
| `[Range]`                     | get slice of the array (copy)                | Range       |
| `+=`                          | append element(s) (2)                        | List or Obj |
| `sort()`                      | in-place sort, natural order                 | void        |
| `sortBy(predicate)`           | in-place sort bu `predicate` call result (3) | void        |
| `sortWith(comparator)`        | in-place sort using `comarator` function (4) | void        |
| `shiffle()`                   | in-place shiffle contents                    |             |

(1)
: optimized implementation that override `Array` one

(2)
: `+=` append either a single element, or all elements if the List or other Iterable
instance is appended. If you want to append an Iterable object itself, use `add` instead.

(3)
: predicate is called on each element, and the returned values are used to sort in natural
order, e.g. is same as `list.sortWith { a,b -> predicate(a) <=> predicate(b) }`

(4)
: comparator callable takes tho arguments and must return: negative value when first is less,
positive if first is greater, and zero if they are equal. For example, the equvalent comparator
for `sort()` will be `sort { a, b -> a <=> b }

It inherits from [Iterable] too and thus all iterable methods are applicable to any list.

## Member inherited from Array

| name             | meaning                        | type  |
|------------------|--------------------------------|-------|
| `last`           | last element (throws if empty) |       |
| `lastOrNull`     | last element or null           |       |
| `lastIndex`      |                                | Int   |
| `indices`        | range of indexes               | Range |
| `contains(item)` | test that item is in the list  |       |

(1)
: end-inclisiveness allows to use negative indexes to, for exampe, remove several last elements, like
`list.removeRangeInclusive(-2, -1)` will remove two last elements.


[Range]: Range.md

[Iterable]: Iterable.md