1<?php
2
3namespace Illuminate\Support;
4
5use Countable;
6use Illuminate\Contracts\Support\Arrayable;
7use Illuminate\Contracts\Support\Jsonable;
8use IteratorAggregate;
9use JsonSerializable;
10
11interface Enumerable extends Arrayable, Countable, IteratorAggregate, Jsonable, JsonSerializable
12{
13    /**
14     * Create a new collection instance if the value isn't one already.
15     *
16     * @param  mixed  $items
17     * @return static
18     */
19    public static function make($items = []);
20
21    /**
22     * Create a new instance by invoking the callback a given amount of times.
23     *
24     * @param  int  $number
25     * @param  callable|null  $callback
26     * @return static
27     */
28    public static function times($number, callable $callback = null);
29
30    /**
31     * Create a collection with the given range.
32     *
33     * @param  int  $from
34     * @param  int  $to
35     * @return static
36     */
37    public static function range($from, $to);
38
39    /**
40     * Wrap the given value in a collection if applicable.
41     *
42     * @param  mixed  $value
43     * @return static
44     */
45    public static function wrap($value);
46
47    /**
48     * Get the underlying items from the given collection if applicable.
49     *
50     * @param  array|static  $value
51     * @return array
52     */
53    public static function unwrap($value);
54
55    /**
56     * Create a new instance with no items.
57     *
58     * @return static
59     */
60    public static function empty();
61
62    /**
63     * Get all items in the enumerable.
64     *
65     * @return array
66     */
67    public function all();
68
69    /**
70     * Alias for the "avg" method.
71     *
72     * @param  callable|string|null  $callback
73     * @return mixed
74     */
75    public function average($callback = null);
76
77    /**
78     * Get the median of a given key.
79     *
80     * @param  string|array|null  $key
81     * @return mixed
82     */
83    public function median($key = null);
84
85    /**
86     * Get the mode of a given key.
87     *
88     * @param  string|array|null  $key
89     * @return array|null
90     */
91    public function mode($key = null);
92
93    /**
94     * Collapse the items into a single enumerable.
95     *
96     * @return static
97     */
98    public function collapse();
99
100    /**
101     * Alias for the "contains" method.
102     *
103     * @param  mixed  $key
104     * @param  mixed  $operator
105     * @param  mixed  $value
106     * @return bool
107     */
108    public function some($key, $operator = null, $value = null);
109
110    /**
111     * Determine if an item exists, using strict comparison.
112     *
113     * @param  mixed  $key
114     * @param  mixed  $value
115     * @return bool
116     */
117    public function containsStrict($key, $value = null);
118
119    /**
120     * Get the average value of a given key.
121     *
122     * @param  callable|string|null  $callback
123     * @return mixed
124     */
125    public function avg($callback = null);
126
127    /**
128     * Determine if an item exists in the enumerable.
129     *
130     * @param  mixed  $key
131     * @param  mixed  $operator
132     * @param  mixed  $value
133     * @return bool
134     */
135    public function contains($key, $operator = null, $value = null);
136
137    /**
138     * Cross join with the given lists, returning all possible permutations.
139     *
140     * @param  mixed  ...$lists
141     * @return static
142     */
143    public function crossJoin(...$lists);
144
145    /**
146     * Dump the collection and end the script.
147     *
148     * @param  mixed  ...$args
149     * @return void
150     */
151    public function dd(...$args);
152
153    /**
154     * Dump the collection.
155     *
156     * @return $this
157     */
158    public function dump();
159
160    /**
161     * Get the items that are not present in the given items.
162     *
163     * @param  mixed  $items
164     * @return static
165     */
166    public function diff($items);
167
168    /**
169     * Get the items that are not present in the given items, using the callback.
170     *
171     * @param  mixed  $items
172     * @param  callable  $callback
173     * @return static
174     */
175    public function diffUsing($items, callable $callback);
176
177    /**
178     * Get the items whose keys and values are not present in the given items.
179     *
180     * @param  mixed  $items
181     * @return static
182     */
183    public function diffAssoc($items);
184
185    /**
186     * Get the items whose keys and values are not present in the given items, using the callback.
187     *
188     * @param  mixed  $items
189     * @param  callable  $callback
190     * @return static
191     */
192    public function diffAssocUsing($items, callable $callback);
193
194    /**
195     * Get the items whose keys are not present in the given items.
196     *
197     * @param  mixed  $items
198     * @return static
199     */
200    public function diffKeys($items);
201
202    /**
203     * Get the items whose keys are not present in the given items, using the callback.
204     *
205     * @param  mixed  $items
206     * @param  callable  $callback
207     * @return static
208     */
209    public function diffKeysUsing($items, callable $callback);
210
211    /**
212     * Retrieve duplicate items.
213     *
214     * @param  callable|string|null  $callback
215     * @param  bool  $strict
216     * @return static
217     */
218    public function duplicates($callback = null, $strict = false);
219
220    /**
221     * Retrieve duplicate items using strict comparison.
222     *
223     * @param  callable|string|null  $callback
224     * @return static
225     */
226    public function duplicatesStrict($callback = null);
227
228    /**
229     * Execute a callback over each item.
230     *
231     * @param  callable  $callback
232     * @return $this
233     */
234    public function each(callable $callback);
235
236    /**
237     * Execute a callback over each nested chunk of items.
238     *
239     * @param  callable  $callback
240     * @return static
241     */
242    public function eachSpread(callable $callback);
243
244    /**
245     * Determine if all items pass the given truth test.
246     *
247     * @param  string|callable  $key
248     * @param  mixed  $operator
249     * @param  mixed  $value
250     * @return bool
251     */
252    public function every($key, $operator = null, $value = null);
253
254    /**
255     * Get all items except for those with the specified keys.
256     *
257     * @param  mixed  $keys
258     * @return static
259     */
260    public function except($keys);
261
262    /**
263     * Run a filter over each of the items.
264     *
265     * @param  callable|null  $callback
266     * @return static
267     */
268    public function filter(callable $callback = null);
269
270    /**
271     * Apply the callback if the value is truthy.
272     *
273     * @param  bool  $value
274     * @param  callable  $callback
275     * @param  callable|null  $default
276     * @return static|mixed
277     */
278    public function when($value, callable $callback, callable $default = null);
279
280    /**
281     * Apply the callback if the collection is empty.
282     *
283     * @param  callable  $callback
284     * @param  callable|null  $default
285     * @return static|mixed
286     */
287    public function whenEmpty(callable $callback, callable $default = null);
288
289    /**
290     * Apply the callback if the collection is not empty.
291     *
292     * @param  callable  $callback
293     * @param  callable|null  $default
294     * @return static|mixed
295     */
296    public function whenNotEmpty(callable $callback, callable $default = null);
297
298    /**
299     * Apply the callback if the value is falsy.
300     *
301     * @param  bool  $value
302     * @param  callable  $callback
303     * @param  callable|null  $default
304     * @return static|mixed
305     */
306    public function unless($value, callable $callback, callable $default = null);
307
308    /**
309     * Apply the callback unless the collection is empty.
310     *
311     * @param  callable  $callback
312     * @param  callable|null  $default
313     * @return static|mixed
314     */
315    public function unlessEmpty(callable $callback, callable $default = null);
316
317    /**
318     * Apply the callback unless the collection is not empty.
319     *
320     * @param  callable  $callback
321     * @param  callable|null  $default
322     * @return static|mixed
323     */
324    public function unlessNotEmpty(callable $callback, callable $default = null);
325
326    /**
327     * Filter items by the given key value pair.
328     *
329     * @param  string  $key
330     * @param  mixed  $operator
331     * @param  mixed  $value
332     * @return static
333     */
334    public function where($key, $operator = null, $value = null);
335
336    /**
337     * Filter items where the value for the given key is null.
338     *
339     * @param  string|null  $key
340     * @return static
341     */
342    public function whereNull($key = null);
343
344    /**
345     * Filter items where the value for the given key is not null.
346     *
347     * @param  string|null  $key
348     * @return static
349     */
350    public function whereNotNull($key = null);
351
352    /**
353     * Filter items by the given key value pair using strict comparison.
354     *
355     * @param  string  $key
356     * @param  mixed  $value
357     * @return static
358     */
359    public function whereStrict($key, $value);
360
361    /**
362     * Filter items by the given key value pair.
363     *
364     * @param  string  $key
365     * @param  mixed  $values
366     * @param  bool  $strict
367     * @return static
368     */
369    public function whereIn($key, $values, $strict = false);
370
371    /**
372     * Filter items by the given key value pair using strict comparison.
373     *
374     * @param  string  $key
375     * @param  mixed  $values
376     * @return static
377     */
378    public function whereInStrict($key, $values);
379
380    /**
381     * Filter items such that the value of the given key is between the given values.
382     *
383     * @param  string  $key
384     * @param  array  $values
385     * @return static
386     */
387    public function whereBetween($key, $values);
388
389    /**
390     * Filter items such that the value of the given key is not between the given values.
391     *
392     * @param  string  $key
393     * @param  array  $values
394     * @return static
395     */
396    public function whereNotBetween($key, $values);
397
398    /**
399     * Filter items by the given key value pair.
400     *
401     * @param  string  $key
402     * @param  mixed  $values
403     * @param  bool  $strict
404     * @return static
405     */
406    public function whereNotIn($key, $values, $strict = false);
407
408    /**
409     * Filter items by the given key value pair using strict comparison.
410     *
411     * @param  string  $key
412     * @param  mixed  $values
413     * @return static
414     */
415    public function whereNotInStrict($key, $values);
416
417    /**
418     * Filter the items, removing any items that don't match the given type(s).
419     *
420     * @param  string|string[]  $type
421     * @return static
422     */
423    public function whereInstanceOf($type);
424
425    /**
426     * Get the first item from the enumerable passing the given truth test.
427     *
428     * @param  callable|null  $callback
429     * @param  mixed  $default
430     * @return mixed
431     */
432    public function first(callable $callback = null, $default = null);
433
434    /**
435     * Get the first item by the given key value pair.
436     *
437     * @param  string  $key
438     * @param  mixed  $operator
439     * @param  mixed  $value
440     * @return mixed
441     */
442    public function firstWhere($key, $operator = null, $value = null);
443
444    /**
445     * Get a flattened array of the items in the collection.
446     *
447     * @param  int  $depth
448     * @return static
449     */
450    public function flatten($depth = INF);
451
452    /**
453     * Flip the values with their keys.
454     *
455     * @return static
456     */
457    public function flip();
458
459    /**
460     * Get an item from the collection by key.
461     *
462     * @param  mixed  $key
463     * @param  mixed  $default
464     * @return mixed
465     */
466    public function get($key, $default = null);
467
468    /**
469     * Group an associative array by a field or using a callback.
470     *
471     * @param  array|callable|string  $groupBy
472     * @param  bool  $preserveKeys
473     * @return static
474     */
475    public function groupBy($groupBy, $preserveKeys = false);
476
477    /**
478     * Key an associative array by a field or using a callback.
479     *
480     * @param  callable|string  $keyBy
481     * @return static
482     */
483    public function keyBy($keyBy);
484
485    /**
486     * Determine if an item exists in the collection by key.
487     *
488     * @param  mixed  $key
489     * @return bool
490     */
491    public function has($key);
492
493    /**
494     * Concatenate values of a given key as a string.
495     *
496     * @param  string  $value
497     * @param  string|null  $glue
498     * @return string
499     */
500    public function implode($value, $glue = null);
501
502    /**
503     * Intersect the collection with the given items.
504     *
505     * @param  mixed  $items
506     * @return static
507     */
508    public function intersect($items);
509
510    /**
511     * Intersect the collection with the given items by key.
512     *
513     * @param  mixed  $items
514     * @return static
515     */
516    public function intersectByKeys($items);
517
518    /**
519     * Determine if the collection is empty or not.
520     *
521     * @return bool
522     */
523    public function isEmpty();
524
525    /**
526     * Determine if the collection is not empty.
527     *
528     * @return bool
529     */
530    public function isNotEmpty();
531
532    /**
533     * Join all items from the collection using a string. The final items can use a separate glue string.
534     *
535     * @param  string  $glue
536     * @param  string  $finalGlue
537     * @return string
538     */
539    public function join($glue, $finalGlue = '');
540
541    /**
542     * Get the keys of the collection items.
543     *
544     * @return static
545     */
546    public function keys();
547
548    /**
549     * Get the last item from the collection.
550     *
551     * @param  callable|null  $callback
552     * @param  mixed  $default
553     * @return mixed
554     */
555    public function last(callable $callback = null, $default = null);
556
557    /**
558     * Run a map over each of the items.
559     *
560     * @param  callable  $callback
561     * @return static
562     */
563    public function map(callable $callback);
564
565    /**
566     * Run a map over each nested chunk of items.
567     *
568     * @param  callable  $callback
569     * @return static
570     */
571    public function mapSpread(callable $callback);
572
573    /**
574     * Run a dictionary map over the items.
575     *
576     * The callback should return an associative array with a single key/value pair.
577     *
578     * @param  callable  $callback
579     * @return static
580     */
581    public function mapToDictionary(callable $callback);
582
583    /**
584     * Run a grouping map over the items.
585     *
586     * The callback should return an associative array with a single key/value pair.
587     *
588     * @param  callable  $callback
589     * @return static
590     */
591    public function mapToGroups(callable $callback);
592
593    /**
594     * Run an associative map over each of the items.
595     *
596     * The callback should return an associative array with a single key/value pair.
597     *
598     * @param  callable  $callback
599     * @return static
600     */
601    public function mapWithKeys(callable $callback);
602
603    /**
604     * Map a collection and flatten the result by a single level.
605     *
606     * @param  callable  $callback
607     * @return static
608     */
609    public function flatMap(callable $callback);
610
611    /**
612     * Map the values into a new class.
613     *
614     * @param  string  $class
615     * @return static
616     */
617    public function mapInto($class);
618
619    /**
620     * Merge the collection with the given items.
621     *
622     * @param  mixed  $items
623     * @return static
624     */
625    public function merge($items);
626
627    /**
628     * Recursively merge the collection with the given items.
629     *
630     * @param  mixed  $items
631     * @return static
632     */
633    public function mergeRecursive($items);
634
635    /**
636     * Create a collection by using this collection for keys and another for its values.
637     *
638     * @param  mixed  $values
639     * @return static
640     */
641    public function combine($values);
642
643    /**
644     * Union the collection with the given items.
645     *
646     * @param  mixed  $items
647     * @return static
648     */
649    public function union($items);
650
651    /**
652     * Get the min value of a given key.
653     *
654     * @param  callable|string|null  $callback
655     * @return mixed
656     */
657    public function min($callback = null);
658
659    /**
660     * Get the max value of a given key.
661     *
662     * @param  callable|string|null  $callback
663     * @return mixed
664     */
665    public function max($callback = null);
666
667    /**
668     * Create a new collection consisting of every n-th element.
669     *
670     * @param  int  $step
671     * @param  int  $offset
672     * @return static
673     */
674    public function nth($step, $offset = 0);
675
676    /**
677     * Get the items with the specified keys.
678     *
679     * @param  mixed  $keys
680     * @return static
681     */
682    public function only($keys);
683
684    /**
685     * "Paginate" the collection by slicing it into a smaller collection.
686     *
687     * @param  int  $page
688     * @param  int  $perPage
689     * @return static
690     */
691    public function forPage($page, $perPage);
692
693    /**
694     * Partition the collection into two arrays using the given callback or key.
695     *
696     * @param  callable|string  $key
697     * @param  mixed  $operator
698     * @param  mixed  $value
699     * @return static
700     */
701    public function partition($key, $operator = null, $value = null);
702
703    /**
704     * Push all of the given items onto the collection.
705     *
706     * @param  iterable  $source
707     * @return static
708     */
709    public function concat($source);
710
711    /**
712     * Get one or a specified number of items randomly from the collection.
713     *
714     * @param  int|null  $number
715     * @return static|mixed
716     *
717     * @throws \InvalidArgumentException
718     */
719    public function random($number = null);
720
721    /**
722     * Reduce the collection to a single value.
723     *
724     * @param  callable  $callback
725     * @param  mixed  $initial
726     * @return mixed
727     */
728    public function reduce(callable $callback, $initial = null);
729
730    /**
731     * Replace the collection items with the given items.
732     *
733     * @param  mixed  $items
734     * @return static
735     */
736    public function replace($items);
737
738    /**
739     * Recursively replace the collection items with the given items.
740     *
741     * @param  mixed  $items
742     * @return static
743     */
744    public function replaceRecursive($items);
745
746    /**
747     * Reverse items order.
748     *
749     * @return static
750     */
751    public function reverse();
752
753    /**
754     * Search the collection for a given value and return the corresponding key if successful.
755     *
756     * @param  mixed  $value
757     * @param  bool  $strict
758     * @return mixed
759     */
760    public function search($value, $strict = false);
761
762    /**
763     * Shuffle the items in the collection.
764     *
765     * @param  int|null  $seed
766     * @return static
767     */
768    public function shuffle($seed = null);
769
770    /**
771     * Skip the first {$count} items.
772     *
773     * @param  int  $count
774     * @return static
775     */
776    public function skip($count);
777
778    /**
779     * Skip items in the collection until the given condition is met.
780     *
781     * @param  mixed  $value
782     * @return static
783     */
784    public function skipUntil($value);
785
786    /**
787     * Skip items in the collection while the given condition is met.
788     *
789     * @param  mixed  $value
790     * @return static
791     */
792    public function skipWhile($value);
793
794    /**
795     * Get a slice of items from the enumerable.
796     *
797     * @param  int  $offset
798     * @param  int|null  $length
799     * @return static
800     */
801    public function slice($offset, $length = null);
802
803    /**
804     * Split a collection into a certain number of groups.
805     *
806     * @param  int  $numberOfGroups
807     * @return static
808     */
809    public function split($numberOfGroups);
810
811    /**
812     * Chunk the collection into chunks of the given size.
813     *
814     * @param  int  $size
815     * @return static
816     */
817    public function chunk($size);
818
819    /**
820     * Chunk the collection into chunks with a callback.
821     *
822     * @param  callable  $callback
823     * @return static
824     */
825    public function chunkWhile(callable $callback);
826
827    /**
828     * Sort through each item with a callback.
829     *
830     * @param  callable|null|int  $callback
831     * @return static
832     */
833    public function sort($callback = null);
834
835    /**
836     * Sort items in descending order.
837     *
838     * @param  int  $options
839     * @return static
840     */
841    public function sortDesc($options = SORT_REGULAR);
842
843    /**
844     * Sort the collection using the given callback.
845     *
846     * @param  callable|string  $callback
847     * @param  int  $options
848     * @param  bool  $descending
849     * @return static
850     */
851    public function sortBy($callback, $options = SORT_REGULAR, $descending = false);
852
853    /**
854     * Sort the collection in descending order using the given callback.
855     *
856     * @param  callable|string  $callback
857     * @param  int  $options
858     * @return static
859     */
860    public function sortByDesc($callback, $options = SORT_REGULAR);
861
862    /**
863     * Sort the collection keys.
864     *
865     * @param  int  $options
866     * @param  bool  $descending
867     * @return static
868     */
869    public function sortKeys($options = SORT_REGULAR, $descending = false);
870
871    /**
872     * Sort the collection keys in descending order.
873     *
874     * @param  int  $options
875     * @return static
876     */
877    public function sortKeysDesc($options = SORT_REGULAR);
878
879    /**
880     * Get the sum of the given values.
881     *
882     * @param  callable|string|null  $callback
883     * @return mixed
884     */
885    public function sum($callback = null);
886
887    /**
888     * Take the first or last {$limit} items.
889     *
890     * @param  int  $limit
891     * @return static
892     */
893    public function take($limit);
894
895    /**
896     * Take items in the collection until the given condition is met.
897     *
898     * @param  mixed  $value
899     * @return static
900     */
901    public function takeUntil($value);
902
903    /**
904     * Take items in the collection while the given condition is met.
905     *
906     * @param  mixed  $value
907     * @return static
908     */
909    public function takeWhile($value);
910
911    /**
912     * Pass the collection to the given callback and then return it.
913     *
914     * @param  callable  $callback
915     * @return $this
916     */
917    public function tap(callable $callback);
918
919    /**
920     * Pass the enumerable to the given callback and return the result.
921     *
922     * @param  callable  $callback
923     * @return mixed
924     */
925    public function pipe(callable $callback);
926
927    /**
928     * Get the values of a given key.
929     *
930     * @param  string|array  $value
931     * @param  string|null  $key
932     * @return static
933     */
934    public function pluck($value, $key = null);
935
936    /**
937     * Create a collection of all elements that do not pass a given truth test.
938     *
939     * @param  callable|mixed  $callback
940     * @return static
941     */
942    public function reject($callback = true);
943
944    /**
945     * Return only unique items from the collection array.
946     *
947     * @param  string|callable|null  $key
948     * @param  bool  $strict
949     * @return static
950     */
951    public function unique($key = null, $strict = false);
952
953    /**
954     * Return only unique items from the collection array using strict comparison.
955     *
956     * @param  string|callable|null  $key
957     * @return static
958     */
959    public function uniqueStrict($key = null);
960
961    /**
962     * Reset the keys on the underlying array.
963     *
964     * @return static
965     */
966    public function values();
967
968    /**
969     * Pad collection to the specified length with a value.
970     *
971     * @param  int  $size
972     * @param  mixed  $value
973     * @return static
974     */
975    public function pad($size, $value);
976
977    /**
978     * Count the number of items in the collection using a given truth test.
979     *
980     * @param  callable|null  $callback
981     * @return static
982     */
983    public function countBy($callback = null);
984
985    /**
986     * Zip the collection together with one or more arrays.
987     *
988     * e.g. new Collection([1, 2, 3])->zip([4, 5, 6]);
989     *      => [[1, 4], [2, 5], [3, 6]]
990     *
991     * @param  mixed  ...$items
992     * @return static
993     */
994    public function zip($items);
995
996    /**
997     * Collect the values into a collection.
998     *
999     * @return \Illuminate\Support\Collection
1000     */
1001    public function collect();
1002
1003    /**
1004     * Convert the collection to its string representation.
1005     *
1006     * @return string
1007     */
1008    public function __toString();
1009
1010    /**
1011     * Add a method to the list of proxied methods.
1012     *
1013     * @param  string  $method
1014     * @return void
1015     */
1016    public static function proxy($method);
1017
1018    /**
1019     * Dynamically access collection proxies.
1020     *
1021     * @param  string  $key
1022     * @return mixed
1023     *
1024     * @throws \Exception
1025     */
1026    public function __get($key);
1027}
1028