fix #26 lists redesigned for ranges, less chaotic and serpentic

docs/List.md

@@ -20,11 +20,11 @@ indexing is zero-based, as in C/C++/Java/Kotlin, etc.
     list[1]
     >>> 20
 
-Using negative indexes has a special meaning: _offset from the end of the list_:
+There is a shortcut for the last:
 
     val list = [10, 20, 30]
-    list[-1]
-    >>> 30
+    [list.last, list.lastIndex]
+    >>> [30, 2]
 
 __Important__ negative indexes works wherever indexes are used, e.g. in insertion and removal methods too.
 
@@ -38,7 +38,8 @@ You can concatenate lists or iterable objects:
 
 ## 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`:
+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]
@@ -57,7 +58,28 @@ To append to lists, use `+=` with elements, lists and any [Iterable] instances,
 
     >>> 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
 
@@ -72,19 +94,44 @@ To append to lists, use `+=` with elements, lists and any [Iterable] instances,
 
 ## Members
 
-| name                              | meaning                             | type     |
-|-----------------------------------|-------------------------------------|----------|
-| `size`                            | current size                        | Int      |
-| `add(elements...)`                | add one or more elements to the end | Any      |
-| `addAt(index,elements...)`        | insert elements at position         | Int, Any |
-| `removeAt(index)`                 | remove element at position          | Int      |
-| `removeRangeInclusive(start,end)` | remove range, inclusive (1)         | Int, Int |
-|                                   |                                     |          |
+| 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)                     | List or Obj |
 
 (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.
+: 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.
+
+## 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.
 
 # Notes
 
 Could be rewritten using array as a class but List as the interface
+
+[Range]: Range.md

docs/tutorial.md

@@ -514,62 +514,73 @@ To add elements to the list:
     assert( x == [1, 2, 3, "the", "end"])
     >>> void
 
-Self-modifying concatenation by `+=` also works:
+Self-modifying concatenation by `+=` also works (also with single elements):
 
     val x = [1, 2]
     x += [3, 4]
-    assert( x == [1, 2, 3, 4])
+    x += 5
+    assert( x == [1, 2, 3, 4, 5])
     >>> void
 
-You can insert elements at any position using `addAt`:
+You can insert elements at any position using `insertAt`:
 
     val x = [1,2,3]
-    x.addAt(1, "foo", "bar")
+    x.insertAt(1, "foo", "bar")
     assert( x == [1, "foo", "bar", 2, 3])
     >>> void
 
 Using splat arguments can simplify inserting list in list:
 
     val x = [1, 2, 3]
-    x.addAt( 1, ...[0,100,0])
+    x.insertAt( 1, ...[0,100,0])
     x
     >>> [1, 0, 100, 0, 2, 3]
 
-Using negative indexes can insert elements as offset from the end, for example:
-
-    val x = [1,2,3]
-    x.addAt(-1, 10)
-    x
-    >>> [1, 2, 10, 3]
 
 Note that to add to the end you still need to use `add` or positive index of the after-last element:
 
     val x = [1,2,3]
-    x.addAt(3, 10)
+    x.insertAt(3, 10)
     x
     >>> [1, 2, 3, 10]
 
+but it is much simpler, and we recommend to use '+='
+
+    val x = [1,2,3]
+    x += 10
+    >>> [1, 2, 3, 10]
+
 ## Removing list items
 
     val x = [1, 2, 3, 4, 5]
     x.removeAt(2)
     assert( x == [1, 2, 4, 5])
     // or remove range (start inclusive, end exclusive):
-    x.removeRangeInclusive(1,2)    
+    x.removeRange(1..2)    
     assert( x == [1, 5])
     >>> void
 
-Again, you can use negative indexes. For example, removing last elements like:
+There is a shortcut to remove the last elements:
 
     val x = [1, 2, 3, 4, 5]
 
     // remove last:
-    x.removeAt(-1)
+    x.removeLast()
     assert( x == [1, 2, 3, 4])
     
     // remove 2 last:
-    x.removeRangeInclusive(-2,-1)
-    assert( x == [1, 2])
+    x.removeLast(2)
+    assertEquals( [1, 2], x)
+    >>> void
+
+You can get ranges to extract a portion from a list:
+
+    val list = [1, 2, 3, 4, 5]
+    assertEquals( [1,2,3], list[..2])
+    assertEquals( [1,2,], list[..<2])
+    assertEquals( [4,5], list[3..])
+    assertEquals( [2,3], list[1..2])
+    assertEquals( [2,3], list[1..<3])
     >>> void
 
 # Flow control operators