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/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)
+    }