From 2362e68f385d6e2cb41ef723253e90800497d410 Mon Sep 17 00:00:00 2001 From: Joseph Silber Date: Wed, 22 Apr 2020 16:57:04 -0400 Subject: [PATCH 1/2] Document `takeWhile` and `takeUntil` --- collections.md | 76 +++++++++++++++++++++++++++++++------------------- 1 file changed, 47 insertions(+), 29 deletions(-) diff --git a/collections.md b/collections.md index 6f6e185a7e5..b4a29f218c3 100644 --- a/collections.md +++ b/collections.md @@ -164,6 +164,8 @@ For the remainder of this documentation, we'll discuss each method available on [split](#method-split) [sum](#method-sum) [take](#method-take) +[takeUntil](#method-takeuntil) +[takeWhile](#method-takewhile) [tap](#method-tap) [times](#method-times) [toArray](#method-toarray) @@ -175,7 +177,6 @@ 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) @@ -1959,6 +1960,50 @@ You may also pass a negative integer to take the specified amount of items from // [4, 5] + +#### `takeUntil()` {#collection-method} + +The `takeUntil` method returns items in the collection until the given callback returns `true`: + + $collection = collect([1, 2, 3, 4]); + + $subset = $collection->takeUntil(function ($item) { + return $item >= 3; + }); + + $subset->all(); + + // [1, 2] + +You may also pass a simple value to the `takeUntil` method, to get the items until the given value is found: + + $collection = collect([1, 2, 3, 4]); + + $subset = $collection->until(3); + + $subset->all(); + + // [1, 2] + +> {note} If the given value is not found or the callback never returns `true`, the `takeUntil` method will return all items in the collection. + + +#### `takeWhile()` {#collection-method} + +The `takeWhile` method returns items in the collection until the given callback returns `false`: + + $collection = collect([1, 2, 3, 4]); + + $subset = $collection->takeWhile(function ($item) { + return $item < 3; + }); + + $subset->all(); + + // [1, 2] + +> {note} If the callback never returns `false`, the `takeWhile` method will return all items in the collection. + #### `tap()` {#collection-method} @@ -2151,33 +2196,6 @@ Alias for the [`whenNotEmpty`](#method-whennotempty) method. Alias for the [`whenEmpty`](#method-whenempty) method. - -#### `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. - #### `unwrap()` {#collection-method} @@ -2580,7 +2598,7 @@ The `zip` method merges together the values of the given array with the values o ## 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), [`unique`](#method-unique), and [`until`](#method-until). +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) [`takeUntil`](#method-takeuntil), [`takeWhile`](#method-takewhile) and [`unique`](#method-unique). 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: From 7e37a08921500c1b6fc5c073fe396f07cc90944d Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Thu, 23 Apr 2020 09:02:11 -0500 Subject: [PATCH 2/2] Update collections.md --- collections.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/collections.md b/collections.md index b4a29f218c3..ee9a882cd4e 100644 --- a/collections.md +++ b/collections.md @@ -1975,7 +1975,7 @@ The `takeUntil` method returns items in the collection until the given callback // [1, 2] -You may also pass a simple value to the `takeUntil` method, to get the items until the given value is found: +You may also pass a simple value to the `takeUntil` method to get the items until the given value is found: $collection = collect([1, 2, 3, 4]);