Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[5.3] Sync collections documentation #3230

Merged
merged 2 commits into from
Mar 26, 2017
Merged

[5.3] Sync collections documentation #3230

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eefd4f3
Sync collections documentation
paulofreitas Mar 26, 2017
353fb47
Sync Eloquent collections documentation
paulofreitas Mar 26, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 98 additions & 34 deletions collections.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,11 +47,13 @@ For the remainder of this documentation, we'll discuss each method available on
<div id="collection-method-list" markdown="1">

[all](#method-all)
[average](#method-average)
[avg](#method-avg)
[chunk](#method-chunk)
[collapse](#method-collapse)
[combine](#method-combine)
[contains](#method-contains)
[containsStrict](#method-containsstrict)
[count](#method-count)
[diff](#method-diff)
[diffKeys](#method-diffkeys)
Expand All @@ -71,15 +73,19 @@ For the remainder of this documentation, we'll discuss each method available on
[implode](#method-implode)
[intersect](#method-intersect)
[isEmpty](#method-isempty)
[isNotEmpty](#method-isnotempty)
[keyBy](#method-keyby)
[keys](#method-keys)
[last](#method-last)
[map](#method-map)
[mapWithKeys](#method-mapwithkeys)
[max](#method-max)
[median](#method-median)
[merge](#method-merge)
[min](#method-min)
[mode](#method-mode)
[only](#method-only)
[partition](#method-partition)
[pipe](#method-pipe)
[pluck](#method-pluck)
[pop](#method-pop)
Expand Down Expand Up @@ -107,6 +113,7 @@ For the remainder of this documentation, we'll discuss each method available on
[transform](#method-transform)
[union](#method-union)
[unique](#method-unique)
[uniqueStrict](#method-uniquestrict)
[values](#method-values)
[where](#method-where)
[whereStrict](#method-wherestrict)
Expand Down Expand Up @@ -138,25 +145,23 @@ The `all` method returns the underlying array represented by the collection:

// [1, 2, 3]

<a name="method-average"></a>
#### `average()` {#collection-method}

Alias for the [`avg`](#method-avg) method.

<a name="method-avg"></a>
#### `avg()` {#collection-method}

The `avg` method returns the average of all items in the collection:
The `avg` method returns the [average value](https://en.wikipedia.org/wiki/Average) of a given key:

collect([1, 2, 3, 4, 5])->avg();

// 3
$average = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->avg('foo');

If the collection contains nested arrays or objects, you should pass a key to use for determining which values to calculate the average:

$collection = collect([
['name' => 'JavaScript: The Good Parts', 'pages' => 176],
['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],
]);
// 20

$collection->avg('pages');
$average = collect([1, 1, 2, 4])->avg();

// 636
// 2

<a name="method-chunk"></a>
#### `chunk()` {#collection-method}
Expand Down Expand Up @@ -243,6 +248,13 @@ Finally, you may also pass a callback to the `contains` method to perform your o

// false

The `contains` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the [`containsStrict`](#method-containsstrict) method to filter using "strict" comparisons.

<a name="method-containsstrict"></a>
#### `containsStrict()` {#collection-method}

This method has the same signature as the [`contains`](#method-contains) method; however, all values are compared using "strict" comparisons.

<a name="method-count"></a>
#### `count()` {#collection-method}

Expand Down Expand Up @@ -606,6 +618,15 @@ The `isEmpty` method returns `true` if the collection is empty; otherwise, `fals

// true

<a name="method-isnotempty"></a>
#### `isNotEmpty()` {#collection-method}

The `isNotEmpty` method returns `true` if the collection is not empty; otherwise, `false` is returned:

collect([])->isNotEmpty();

// false

<a name="method-keyby"></a>
#### `keyBy()` {#collection-method}

Expand Down Expand Up @@ -642,7 +663,6 @@ You may also pass a callback to the method. The callback should return the value
]
*/


<a name="method-keys"></a>
#### `keys()` {#collection-method}

Expand Down Expand Up @@ -737,10 +757,23 @@ The `max` method returns the maximum value of a given key:

// 5

<a name="method-median"></a>
#### `median()` {#collection-method}

The `median` method returns the [median value](https://en.wikipedia.org/wiki/Median) of a given key:

$median = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->median('foo');

// 15

$median = collect([1, 1, 2, 4])->median();

// 1.5

<a name="method-merge"></a>
#### `merge()` {#collection-method}

The `merge` method merges the given array into the original collection. If a string key in the given array matches a string key in the original collection, the given array's value will overwrite the value in the original collection:
The `merge` method merges the given array or collection with the original collection. If a string key in the given items matches a string key in the original collection, the given items's value will overwrite the value in the original collection:

$collection = collect(['product_id' => 1, 'price' => 100]);

Expand All @@ -750,7 +783,7 @@ The `merge` method merges the given array into the original collection. If a str

// ['product_id' => 1, 'price' => 200, 'discount' => false]

If the given array's keys are numeric, the values will be appended to the end of the collection:
If the given items's keys are numeric, the values will be appended to the end of the collection:

$collection = collect(['Desk', 'Chair']);

Expand All @@ -773,6 +806,19 @@ The `min` method returns the minimum value of a given key:

// 1

<a name="method-mode"></a>
#### `mode()` {#collection-method}

The `mode` method returns the [mode value](https://en.wikipedia.org/wiki/Mode_(statistics)) of a given key:

$mode = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->mode('foo');

// [10]

$mode = collect([1, 1, 2, 4])->mode();

// [1]

<a name="method-only"></a>
#### `only()` {#collection-method}

Expand All @@ -788,6 +834,17 @@ The `only` method returns the items in the collection with the specified keys:

For the inverse of `only`, see the [except](#method-except) method.

<a name="method-partition"></a>
#### `partition()` {#collection-method}

The `partition` method may be combined with the `list` PHP function to separate elements that pass a given truth test from those that do not:

$collection = collect([1, 2, 3, 4, 5, 6]);

list($underThree, $aboveThree) = $collection->partition(function ($i) {
return $i < 3;
});

<a name="method-pipe"></a>
#### `pipe()` {#collection-method}

Expand Down Expand Up @@ -855,13 +912,13 @@ The `prepend` method adds an item to the beginning of the collection:

You may also pass a second argument to set the key of the prepended item:

$collection = collect(['one' => 1, 'two', => 2]);
$collection = collect(['one' => 1, 'two' => 2]);

$collection->prepend(0, 'zero');

$collection->all();

// ['zero' => 0, 'one' => 1, 'two', => 2]
// ['zero' => 0, 'one' => 1, 'two' => 2]

<a name="method-pull"></a>
#### `pull()` {#collection-method}
Expand Down Expand Up @@ -985,7 +1042,7 @@ The `search` method searches the collection for the given value and returns its

// 1

The search is done using a "loose" comparison, meaning a string with an integer value will be considered equal to an integer of the same value. To use strict comparison, pass `true` as the second argument to the method:
The search is done using a "loose" comparison, meaning a string with an integer value will be considered equal to an integer of the same value. To use "strict" comparison, pass `true` as the second argument to the method:

$collection->search('4', true);

Expand Down Expand Up @@ -1025,7 +1082,7 @@ The `shuffle` method randomly shuffles the items in the collection:

$shuffled->all();

// [3, 2, 5, 1, 4] // (generated randomly)
// [3, 2, 5, 1, 4] - (generated randomly)

<a name="method-slice"></a>
#### `slice()` {#collection-method}
Expand All @@ -1048,7 +1105,7 @@ If you would like to limit the size of the returned slice, pass the desired size

// [5, 6]

The returned slice will preserve keys by default. If you do not wish to preserve the original keys, you can use the `values` method to reindex them.
The returned slice will preserve keys by default. If you do not wish to preserve the original keys, you can use the [`values`](#method-values) method to reindex them.

<a name="method-sort"></a>
#### `sort()` {#collection-method}
Expand Down Expand Up @@ -1252,7 +1309,7 @@ The `toArray` method converts the collection into a plain PHP `array`. If the co
<a name="method-tojson"></a>
#### `toJson()` {#collection-method}

The `toJson` method converts the collection into JSON:
The `toJson` method converts the collection into a JSON serialized string:

$collection = collect(['name' => 'Desk', 'price' => 200]);

Expand Down Expand Up @@ -1288,7 +1345,7 @@ The `union` method adds the given array to the collection. If the given array co

$union->all();

// [1 => ['a'], 2 => ['b'], [3 => ['c']]
// [1 => ['a'], 2 => ['b'], 3 => ['c']]

<a name="method-unique"></a>
#### `unique()` {#collection-method}
Expand Down Expand Up @@ -1341,6 +1398,13 @@ You may also pass your own callback to determine item uniqueness:
]
*/

The `unique` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the [`uniqueStrict`](#method-uniquestrict) method to filter using "strict" comparisons.

<a name="method-uniquestrict"></a>
#### `uniqueStrict()` {#collection-method}

This method has the same signature as the [`unique`](#method-unique) method; however, all values are compared using "strict" comparisons.

<a name="method-values"></a>
#### `values()` {#collection-method}

Expand Down Expand Up @@ -1378,13 +1442,13 @@ The `where` method filters the collection by a given key / value pair:
$filtered->all();

/*
[
['product' => 'Chair', 'price' => 100],
['product' => 'Door', 'price' => 100],
]
[
['product' => 'Chair', 'price' => 100],
['product' => 'Door', 'price' => 100],
]
*/

The `where` method uses loose comparisons when checking item values. Use the [`whereStrict`](#method-wherestrict) method to filter using "strict" comparisons.
The `where` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the [`whereStrict`](#method-wherestrict) method to filter using "strict" comparisons.

<a name="method-wherestrict"></a>
#### `whereStrict()` {#collection-method}
Expand All @@ -1394,7 +1458,7 @@ This method has the same signature as the [`where`](#method-where) method; howev
<a name="method-wherein"></a>
#### `whereIn()` {#collection-method}

The `whereIn` method filters the collection by a given key / value contained within the given array.
The `whereIn` method filters the collection by a given key / value contained within the given array:

$collection = collect([
['product' => 'Desk', 'price' => 200],
Expand All @@ -1408,18 +1472,18 @@ The `whereIn` method filters the collection by a given key / value contained wit
$filtered->all();

/*
[
['product' => 'Bookcase', 'price' => 150],
['product' => 'Desk', 'price' => 200],
]
[
['product' => 'Bookcase', 'price' => 150],
['product' => 'Desk', 'price' => 200],
]
*/

The `whereIn` method uses "loose" comparisons when checking item values. Use the [`whereInStrict`](#method-whereinstrict) method to filter using strict comparisons.
The `whereIn` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the [`whereInStrict`](#method-whereinstrict) method to filter using "strict" comparisons.

<a name="method-whereinstrict"></a>
#### `whereInStrict()` {#collection-method}

This method has the same signature as the [`whereIn`](#method-wherein) method; however, all values are compared using strict comparisons.
This method has the same signature as the [`whereIn`](#method-wherein) method; however, all values are compared using "strict" comparisons.

<a name="method-zip"></a>
#### `zip()` {#collection-method}
Expand Down
10 changes: 10 additions & 0 deletions eloquent-collections.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,11 +51,13 @@ All Eloquent collections extend the base [Laravel collection](/docs/{{version}}/
<div id="collection-method-list" markdown="1">

[all](/docs/{{version}}/collections#method-all)
[average](/docs/{{version}}/collections#method-average)
[avg](/docs/{{version}}/collections#method-avg)
[chunk](/docs/{{version}}/collections#method-chunk)
[collapse](/docs/{{version}}/collections#method-collapse)
[combine](/docs/{{version}}/collections#method-combine)
[contains](/docs/{{version}}/collections#method-contains)
[containsStrict](/docs/{{version}}/collections#method-containsstrict)
[count](/docs/{{version}}/collections#method-count)
[diff](/docs/{{version}}/collections#method-diff)
[diffKeys](/docs/{{version}}/collections#method-diffkeys)
Expand All @@ -75,14 +77,20 @@ All Eloquent collections extend the base [Laravel collection](/docs/{{version}}/
[implode](/docs/{{version}}/collections#method-implode)
[intersect](/docs/{{version}}/collections#method-intersect)
[isEmpty](/docs/{{version}}/collections#method-isempty)
[isNotEmpty](/docs/{{version}}/collections#method-isnotempty)
[keyBy](/docs/{{version}}/collections#method-keyby)
[keys](/docs/{{version}}/collections#method-keys)
[last](/docs/{{version}}/collections#method-last)
[map](/docs/{{version}}/collections#method-map)
[mapWithKeys](/docs/{{version}}/collections#method-mapwithkeys)
[max](/docs/{{version}}/collections#method-max)
[median](/docs/{{version}}/collections#method-median)
[merge](/docs/{{version}}/collections#method-merge)
[min](/docs/{{version}}/collections#method-min)
[mode](/docs/{{version}}/collections#method-mode)
[only](/docs/{{version}}/collections#method-only)
[partition](/docs/{{version}}/collections#method-partition)
[pipe](/docs/{{version}}/collections#method-pipe)
[pluck](/docs/{{version}}/collections#method-pluck)
[pop](/docs/{{version}}/collections#method-pop)
[prepend](/docs/{{version}}/collections#method-prepend)
Expand All @@ -101,13 +109,15 @@ All Eloquent collections extend the base [Laravel collection](/docs/{{version}}/
[sortBy](/docs/{{version}}/collections#method-sortby)
[sortByDesc](/docs/{{version}}/collections#method-sortbydesc)
[splice](/docs/{{version}}/collections#method-splice)
[split](/docs/{{version}}/collections#method-split)
[sum](/docs/{{version}}/collections#method-sum)
[take](/docs/{{version}}/collections#method-take)
[toArray](/docs/{{version}}/collections#method-toarray)
[toJson](/docs/{{version}}/collections#method-tojson)
[transform](/docs/{{version}}/collections#method-transform)
[union](/docs/{{version}}/collections#method-union)
[unique](/docs/{{version}}/collections#method-unique)
[uniqueStrict](/docs/{{version}}/collections#method-uniquestrict)
[values](/docs/{{version}}/collections#method-values)
[where](/docs/{{version}}/collections#method-where)
[whereStrict](/docs/{{version}}/collections#method-wherestrict)
Expand Down