Merge pull request #5955 from jasonmccreary/collection-until

[7.x] Document until collection method

Author: taylorotwell

collections.md

@@ -175,6 +175,7 @@ For the remainder of this documentation, we'll discuss each method available on
 [unless](#method-unless)
 [unlessEmpty](#method-unlessempty)
 [unlessNotEmpty](#method-unlessnotempty)
+[until](#method-until)
 [unwrap](#method-unwrap)
 [values](#method-values)
 [when](#method-when)
@@ -2150,6 +2151,33 @@ Alias for the [`whenNotEmpty`](#method-whennotempty) method.
 
 Alias for the [`whenEmpty`](#method-whenempty) method.
 
+<a name="method-until"></a>
+#### `until()` {#collection-method}
+
+The `until` method returns items in the collection until the given value is found:
+
+    $collection = collect([1, 2, 3, 4]);
+
+    $subset = $collection->until(3);
+
+    $subset->all();
+
+    // [1, 2]
+
+You may also pass a callback to the `until` method to perform your own logic. The callback should return `true` when the `until` method should stop.
+
+    $collection = collect([1, 2, 3, 4]);
+
+    $subset = $collection->until(function ($item) {
+        return $item >= 3;
+    });
+
+    $subset->all();
+
+    // [1, 2]
+
+If the given value is not found or callback does not return `true`, the `until` method will return all items in the collection.
+
 <a name="method-unwrap"></a>
 #### `unwrap()` {#collection-method}
 
@@ -2552,7 +2580,7 @@ The `zip` method merges together the values of the given array with the values o
 <a name="higher-order-messages"></a>
 ## Higher Order Messages
 
-Collections also provide support for "higher order messages", which are short-cuts for performing common actions on collections. The collection methods that provide higher order messages are: [`average`](#method-average), [`avg`](#method-avg), [`contains`](#method-contains), [`each`](#method-each), [`every`](#method-every), [`filter`](#method-filter), [`first`](#method-first), [`flatMap`](#method-flatmap), [`groupBy`](#method-groupby), [`keyBy`](#method-keyby), [`map`](#method-map), [`max`](#method-max), [`min`](#method-min), [`partition`](#method-partition), [`reject`](#method-reject), [`some`](#method-some), [`sortBy`](#method-sortby), [`sortByDesc`](#method-sortbydesc), [`sum`](#method-sum), and [`unique`](#method-unique).
+Collections also provide support for "higher order messages", which are short-cuts for performing common actions on collections. The collection methods that provide higher order messages are: [`average`](#method-average), [`avg`](#method-avg), [`contains`](#method-contains), [`each`](#method-each), [`every`](#method-every), [`filter`](#method-filter), [`first`](#method-first), [`flatMap`](#method-flatmap), [`groupBy`](#method-groupby), [`keyBy`](#method-keyby), [`map`](#method-map), [`max`](#method-max), [`min`](#method-min), [`partition`](#method-partition), [`reject`](#method-reject), [`some`](#method-some), [`sortBy`](#method-sortby), [`sortByDesc`](#method-sortbydesc), [`sum`](#method-sum), [`unique`](#method-unique), and [`until`](#method-until).
 
 Each higher order message can be accessed as a dynamic property on a collection instance. For instance, let's use the `each` higher order message to call a method on each object within a collection: