Skip to content

Commit eefd4f3

Browse files
paulofreitaspaulofreitas
authored
Sync collections documentation
1 parent f1bca17 commit eefd4f3

File tree

1 file changed

+98
-34
lines changed

1 file changed

+98
-34
lines changed

‎collections.md

Lines changed: 98 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -47,11 +47,13 @@ For the remainder of this documentation, we'll discuss each method available on
4747
<div id="collection-method-list" markdown="1">
4848

4949
[all](#method-all)
50+
[average](#method-average)
5051
[avg](#method-avg)
5152
[chunk](#method-chunk)
5253
[collapse](#method-collapse)
5354
[combine](#method-combine)
5455
[contains](#method-contains)
56+
[containsStrict](#method-containsstrict)
5557
[count](#method-count)
5658
[diff](#method-diff)
5759
[diffKeys](#method-diffkeys)
@@ -71,15 +73,19 @@ For the remainder of this documentation, we'll discuss each method available on
7173
[implode](#method-implode)
7274
[intersect](#method-intersect)
7375
[isEmpty](#method-isempty)
76+
[isNotEmpty](#method-isnotempty)
7477
[keyBy](#method-keyby)
7578
[keys](#method-keys)
7679
[last](#method-last)
7780
[map](#method-map)
7881
[mapWithKeys](#method-mapwithkeys)
7982
[max](#method-max)
83+
[median](#method-median)
8084
[merge](#method-merge)
8185
[min](#method-min)
86+
[mode](#method-mode)
8287
[only](#method-only)
88+
[partition](#method-partition)
8389
[pipe](#method-pipe)
8490
[pluck](#method-pluck)
8591
[pop](#method-pop)
@@ -107,6 +113,7 @@ For the remainder of this documentation, we'll discuss each method available on
107113
[transform](#method-transform)
108114
[union](#method-union)
109115
[unique](#method-unique)
116+
[uniqueStrict](#method-uniquestrict)
110117
[values](#method-values)
111118
[where](#method-where)
112119
[whereStrict](#method-wherestrict)
@@ -138,25 +145,23 @@ The `all` method returns the underlying array represented by the collection:
138145

139146
// [1, 2, 3]
140147

148+
<a name="method-average"></a>
149+
#### `average()` {#collection-method}
150+
151+
Alias for the [`avg`](#method-avg) method.
152+
141153
<a name="method-avg"></a>
142154
#### `avg()` {#collection-method}
143155

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

146-
collect([1, 2, 3, 4, 5])->avg();
147-
148-
// 3
158+
$average = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->avg('foo');
149159

150-
If the collection contains nested arrays or objects, you should pass a key to use for determining which values to calculate the average:
151-
152-
$collection = collect([
153-
['name' => 'JavaScript: The Good Parts', 'pages' => 176],
154-
['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],
155-
]);
160+
// 20
156161

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

159-
// 636
164+
// 2
160165

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

244249
// false
245250

251+
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.
252+
253+
<a name="method-containsstrict"></a>
254+
#### `containsStrict()` {#collection-method}
255+
256+
This method has the same signature as the [`contains`](#method-contains) method; however, all values are compared using "strict" comparisons.
257+
246258
<a name="method-count"></a>
247259
#### `count()` {#collection-method}
248260

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

607619
// true
608620

621+
<a name="method-isnotempty"></a>
622+
#### `isNotEmpty()` {#collection-method}
623+
624+
The `isNotEmpty` method returns `true` if the collection is not empty; otherwise, `false` is returned:
625+
626+
collect([])->isNotEmpty();
627+
628+
// false
629+
609630
<a name="method-keyby"></a>
610631
#### `keyBy()` {#collection-method}
611632

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

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

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

738758
// 5
739759

760+
<a name="method-median"></a>
761+
#### `median()` {#collection-method}
762+
763+
The `median` method returns the [median value](https://en.wikipedia.org/wiki/Median) of a given key:
764+
765+
$median = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->median('foo');
766+
767+
// 15
768+
769+
$median = collect([1, 1, 2, 4])->median();
770+
771+
// 1.5
772+
740773
<a name="method-merge"></a>
741774
#### `merge()` {#collection-method}
742775

743-
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:
776+
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:
744777

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

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

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

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

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

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

774807
// 1
775808

809+
<a name="method-mode"></a>
810+
#### `mode()` {#collection-method}
811+
812+
The `mode` method returns the [mode value](https://en.wikipedia.org/wiki/Mode_(statistics)) of a given key:
813+
814+
$mode = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->mode('foo');
815+
816+
// [10]
817+
818+
$mode = collect([1, 1, 2, 4])->mode();
819+
820+
// [1]
821+
776822
<a name="method-only"></a>
777823
#### `only()` {#collection-method}
778824

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

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

837+
<a name="method-partition"></a>
838+
#### `partition()` {#collection-method}
839+
840+
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:
841+
842+
$collection = collect([1, 2, 3, 4, 5, 6]);
843+
844+
list($underThree, $aboveThree) = $collection->partition(function ($i) {
845+
return $i < 3;
846+
});
847+
791848
<a name="method-pipe"></a>
792849
#### `pipe()` {#collection-method}
793850

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

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

858-
$collection = collect(['one' => 1, 'two', => 2]);
915+
$collection = collect(['one' => 1, 'two' => 2]);
859916

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

862919
$collection->all();
863920

864-
// ['zero' => 0, 'one' => 1, 'two', => 2]
921+
// ['zero' => 0, 'one' => 1, 'two' => 2]
865922

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

9861043
// 1
9871044

988-
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:
1045+
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:
9891046

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

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

10261083
$shuffled->all();
10271084

1028-
// [3, 2, 5, 1, 4] // (generated randomly)
1085+
// [3, 2, 5, 1, 4] - (generated randomly)
10291086

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

10491106
// [5, 6]
10501107

1051-
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.
1108+
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.
10521109

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

1255-
The `toJson` method converts the collection into JSON:
1312+
The `toJson` method converts the collection into a JSON serialized string:
12561313

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

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

12891346
$union->all();
12901347

1291-
// [1 => ['a'], 2 => ['b'], [3 => ['c']]
1348+
// [1 => ['a'], 2 => ['b'], 3 => ['c']]
12921349

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

1401+
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.
1402+
1403+
<a name="method-uniquestrict"></a>
1404+
#### `uniqueStrict()` {#collection-method}
1405+
1406+
This method has the same signature as the [`unique`](#method-unique) method; however, all values are compared using "strict" comparisons.
1407+
13441408
<a name="method-values"></a>
13451409
#### `values()` {#collection-method}
13461410

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

13801444
/*
1381-
[
1382-
['product' => 'Chair', 'price' => 100],
1383-
['product' => 'Door', 'price' => 100],
1384-
]
1445+
[
1446+
['product' => 'Chair', 'price' => 100],
1447+
['product' => 'Door', 'price' => 100],
1448+
]
13851449
*/
13861450

1387-
The `where` method uses loose comparisons when checking item values. Use the [`whereStrict`](#method-wherestrict) method to filter using "strict" comparisons.
1451+
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.
13881452

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

1397-
The `whereIn` method filters the collection by a given key / value contained within the given array.
1461+
The `whereIn` method filters the collection by a given key / value contained within the given array:
13981462

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

14101474
/*
1411-
[
1412-
['product' => 'Bookcase', 'price' => 150],
1413-
['product' => 'Desk', 'price' => 200],
1414-
]
1475+
[
1476+
['product' => 'Bookcase', 'price' => 150],
1477+
['product' => 'Desk', 'price' => 200],
1478+
]
14151479
*/
14161480

1417-
The `whereIn` method uses "loose" comparisons when checking item values. Use the [`whereInStrict`](#method-whereinstrict) method to filter using strict comparisons.
1481+
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.
14181482

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

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

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

0 commit comments

Comments
 (0)