added drop(n) and dropWhile(predicates) for KT-2067 - also tail() now returns the usual idea of tail() - namely everything but the head - rather than just the last element. Finally added more test sample code to the kdoc

libraries/stdlib/ReadMe.md

@@ -0,0 +1,14 @@
+## The Kotlin Standard Library
+
+This module creates the [standard library for kotlin](http://jetbrains.github.com/kotlin/versions/snapshot/apidocs/index.html).
+
+### Notes for contributors
+
+We use some code generation to apply the various collection-like methods to various different types like arrays, strings, kotlin.Iterable and java.lang.Iterable etc.
+
+To run the code generator from a kotlin checkout
+
+    cd libraries/stdlib
+    mvn test-compile exec:java
+
+This then runs the [GenerateStandardLib.kt](https://github.com/JetBrains/kotlin/blob/master/libraries/stdlib/test/GenerateStandardLib.kt) script to create the source from the files for java.lang.Iterable<T> and java.util.Collection etc.

libraries/stdlib/src/kotlin/JLangIterables.kt

@@ -172,6 +172,20 @@ public inline fun <T> java.lang.Iterable<T>.makeString(separator: String = ", ",
     return buffer.toString().sure()
 }
 
+/** Returns a list containing the everything but the first elements that satisfy the given *predicate* */
+public inline fun <T, L: List<in T>> java.lang.Iterable<T>.dropWhileTo(result: L, predicate: (T) -> Boolean) : L {
+    var start = true
+    for (element in this) {
+        if (start && predicate(element)) {
+            // ignore
+        } else {
+            start = false
+            result.add(element)
+        }
+    }
+    return result
+}
+
 /** Returns a list containing the first elements that satisfy the given *predicate* */
 public inline fun <T, L: List<in T>> java.lang.Iterable<T>.takeWhileTo(result: L, predicate: (T) -> Boolean) : L {
     for (element in this) if (predicate(element)) result.add(element) else break

libraries/stdlib/src/kotlin/JLangIterablesLazy.kt

@@ -79,6 +79,26 @@ public inline fun <in T> java.lang.Iterable<T?>?.requireNoNulls() : List<T> {
     return list
 }
 
+/**
+ * Returns a list containing everything but the first *n* elements
+ *
+ * @includeFunctionBody ../../test/CollectionTest.kt drop
+ */
+public inline fun <T> java.lang.Iterable<T>.drop(n: Int): List<T> {
+    fun countTo(n: Int): (T) -> Boolean {
+      var count = 0
+      return { ++count; count <= n }
+    }
+    return dropWhile(countTo(n))
+}
+
+/**
+ * Returns a list containing the everything but the first elements that satisfy the given *predicate*
+ *
+ * @includeFunctionBody ../../test/CollectionTest.kt dropWhile
+ */
+public inline fun <T> java.lang.Iterable<T>.dropWhile(predicate: (T) -> Boolean): List<T> = dropWhileTo(ArrayList<T>(), predicate)
+
 /**
  * Returns a list containing the first *n* elements
  *

libraries/stdlib/src/kotlin/JLangIterablesSpecial.kt

@@ -88,6 +88,8 @@ public fun <T> java.lang.Iterable<T>.contains(item : T) : Boolean {
 
 /**
  * Convert collection of arbitrary elements to collection of tuples of the index and the element
+ *
+ * @includeFunctionBody ../../test/ListTest.kt withIndices
  */
 public fun <T> java.lang.Iterable<T>.withIndices() : java.lang.Iterable<#(Int, T)> {
     return object : java.lang.Iterable<#(Int, T)> {

libraries/stdlib/src/kotlin/JUtil.kt

@@ -152,17 +152,40 @@ public inline fun <in T> List<T>.sort(transform: fun(T) : java.lang.Comparable<*
 }
 */
 
-val <T> List<T>.head : T?
-    get() = this.get(0)
-
+/**
+ * Returns the first item in the list
+ *
+ * @includeFunctionBody ../../test/ListTest.kt first
+ */
 val <T> List<T>.first : T?
     get() = this.head
 
-val <T> List<T>.tail : T?
+
+/**
+ * Returns the last item in the list
+ *
+ * @includeFunctionBody ../../test/ListTest.kt last
+ */
+val <T> List<T>.last : T?
     get() {
       val s = this.size
       return if (s > 0) this.get(s - 1) else null
     }
 
-val <T> List<T>.last : T?
-    get() = this.tail
+/**
+ * Returns the first item in the list
+ *
+ * @includeFunctionBody ../../test/ListTest.kt head
+ */
+val <T> List<T>.head : T?
+    get() = this.get(0)
+
+/**
+ * Returns all elements in this collection apart from the first one
+ *
+ * @includeFunctionBody ../../test/ListTest.kt tail
+ */
+val <T> List<T>.tail : List<T>
+    get() {
+        return drop(1)
+    }

libraries/stdlib/test/CollectionTest.kt

@@ -302,6 +302,29 @@ class CollectionTest {
         }
     }
 
+    test fun drop() {
+        val coll = arrayList("foo", "bar", "abc")
+        assertEquals(arrayList("bar", "abc"), coll.drop(1))
+        assertEquals(arrayList("abc"), coll.drop(2))
+    }
+
+    test fun dropWhile() {
+        val coll = arrayList("foo", "bar", "abc")
+        assertEquals(arrayList("bar", "abc"), coll.dropWhile{ it.startsWith("f") })
+    }
+
+    test fun take() {
+        val coll = arrayList("foo", "bar", "abc")
+        assertEquals(arrayList("foo"), coll.take(1))
+        assertEquals(arrayList("foo", "bar"), coll.take(2))
+    }
+
+    test fun takeWhile() {
+        val coll = arrayList("foo", "bar", "abc")
+        assertEquals(arrayList("foo"), coll.takeWhile{ it.startsWith("f") })
+        assertEquals(arrayList("foo", "bar", "abc"), coll.takeWhile{ it.size == 3 })
+    }
+
     test fun toArray() {
         val data = arrayList("foo", "bar")
         val arr = data.toArray()

libraries/stdlib/test/ListTest.kt

@@ -1,36 +1,39 @@
 package test.collections
 
 import kotlin.test.*
-
-import org.junit.Test
+import org.junit.Test as test
 
 class ListTest {
-  val data = arrayList("foo", "bar")
 
-  Test fun headAndTail() {
-    val h = data.head
-    assertEquals("foo", h)
-
-    val t = data.tail
-    assertEquals("bar", t)
-  }
-
-  Test fun firstAndLast() {
-    val h = data.first
-    assertEquals("foo", h)
-
-    val t = data.last
-    assertEquals("bar", t)
-  }
-
-  Test fun withIndices() {
-    val withIndices = data.withIndices()
-    var index = 0
-    for (withIndex in withIndices) {
-      assertEquals(withIndex._1, index)
-      assertEquals(withIndex._2, data[index])
-      index++
+    test fun head() {
+        val data = arrayList("foo", "bar")
+        assertEquals("foo", data.head)
+    }
+
+    test fun tail() {
+        val data = arrayList("foo", "bar", "whatnot")
+        assertEquals(arrayList("bar", "whatnot"), data.tail)
+    }
+
+    test fun first() {
+        val data = arrayList("foo", "bar")
+        assertEquals("foo", data.first)
+    }
+
+    test fun last() {
+        val data = arrayList("foo", "bar")
+        assertEquals("bar", data.last)
+    }
+
+    test fun withIndices() {
+        val data = arrayList("foo", "bar")
+        val withIndices = data.withIndices()
+        var index = 0
+        for (withIndex in withIndices) {
+            assertEquals(withIndex._1, index)
+            assertEquals(withIndex._2, data[index])
+            index++
+        }
+        assertEquals(data.size(), index)
     }
-    assertEquals(data.size(), index)
-  }
 }