List; add remove(value)

Having to encode this behaviour at every call site is tedious. It makes a lot of sense to just have the method available on list itself.

doc/site/lists.markdown

@@ -113,21 +113,33 @@ System.print(combined)  //> [a, b, c, d, e, f]
 ## Removing elements
 
 The opposite of `insert` is `removeAt`. It removes a single element from a
-given position in the list. All following items are shifted up to fill in the
-gap:
+given position in the list. 
+
+To remove a specific _value_ instead, use `remove`. The first value that 
+matches using regular equality will be removed.
+
+In both cases, all following items are shifted up to fill in the gap.
 
 <pre class="snippet">
 var letters = ["a", "b", "c", "d"]
 letters.removeAt(1)
 System.print(letters) //> [a, c, d]
+letters.remove("a")
+System.print(letters) //> [c, d]
 </pre>
 
-The `removeAt` method returns the removed item:
+Both the `remove` and `removeAt` method return the removed item:
 
 <pre class="snippet">
 System.print(letters.removeAt(1)) //> c
 </pre>
 
+If `remove` couldn't find the value in the list, it returns null:
+
+<pre class="snippet">
+System.print(letters.remove("not found")) //> null
+</pre>
+
 If you want to remove everything from the list, you can clear it:
 
 <pre class="snippet">

doc/site/modules/core/list.markdown

@@ -96,6 +96,26 @@ list.
 
 [iterator protocol]: ../../control-flow.html#the-iterator-protocol
 
+### **remove**(value)
+
+Removes the first value found in the list that matches the given `value`, 
+using regular equality to compare them. All trailing elements
+are shifted up to fill in where the removed element was.
+
+<pre class="snippet">
+var list = ["a", "b", "c", "d"]
+list.remove("b")
+System.print(list) //> [a, c, d]
+</pre>
+
+Returns the removed value, if found.
+If the value is not found in the list, returns null.
+
+<pre class="snippet">
+System.print(["a", "b", "c"].remove("b")) //> b
+System.print(["a", "b", "c"].remove("not found")) //> null
+</pre>
+
 ### **removeAt**(index)
 
 Removes the element at `index`. If `index` is negative, it counts backwards