1
|
|
|
<?php |
2
|
|
|
|
3
|
|
|
namespace DusanKasan\Knapsack; |
4
|
|
|
|
5
|
|
|
use DusanKasan\Knapsack\Exceptions\InvalidReturnValue; |
6
|
|
|
|
7
|
|
|
trait CollectionTrait |
8
|
|
|
{ |
9
|
|
|
/** |
10
|
|
|
* Converts $collection to array. If there are multiple items with the same key, only the last will be preserved. |
11
|
|
|
* |
12
|
|
|
* @return array |
13
|
|
|
*/ |
14
|
70 |
|
public function toArray() |
15
|
|
|
{ |
16
|
70 |
|
return toArray($this->getItems()); |
17
|
|
|
} |
18
|
|
|
|
19
|
|
|
/** |
20
|
|
|
* Returns a lazy collection of items for which $function returned true. |
21
|
|
|
* |
22
|
|
|
* @param callable|null $function ($value, $key) |
23
|
|
|
* @return Collection |
24
|
|
|
*/ |
25
|
2 |
|
public function filter(callable $function = null) |
26
|
|
|
{ |
27
|
2 |
|
return filter($this->getItems(), $function); |
28
|
|
|
} |
29
|
|
|
|
30
|
|
|
/** |
31
|
|
|
* Returns a lazy collection of distinct items. The comparison is the same as in in_array. |
32
|
|
|
* |
33
|
|
|
* @return Collection |
34
|
|
|
*/ |
35
|
1 |
|
public function distinct() |
36
|
|
|
{ |
37
|
1 |
|
return distinct($this->getItems()); |
38
|
|
|
} |
39
|
|
|
|
40
|
|
|
/** |
41
|
|
|
* Returns a lazy collection with items from all $collections passed as argument appended together |
42
|
|
|
* |
43
|
|
|
* @param array|\Traversable ...$collections |
44
|
|
|
* @return Collection |
45
|
|
|
*/ |
46
|
1 |
|
public function concat(...$collections) |
47
|
|
|
{ |
48
|
1 |
|
return concat($this, ...$collections); |
49
|
|
|
} |
50
|
|
|
|
51
|
|
|
/** |
52
|
|
|
* Returns collection where each item is changed to the output of executing $function on each key/item. |
53
|
|
|
* |
54
|
|
|
* @param callable $function |
55
|
|
|
* @return Collection |
56
|
|
|
*/ |
57
|
8 |
|
public function map(callable $function) |
58
|
|
|
{ |
59
|
8 |
|
return map($this->getItems(), $function); |
60
|
|
|
} |
61
|
|
|
|
62
|
|
|
/** |
63
|
|
|
* Reduces the collection to single value by iterating over the collection and calling $function while |
64
|
|
|
* passing $startValue and current key/item as parameters. The output of $function is used as $startValue in |
65
|
|
|
* next iteration. The output of $function on last element is the return value of this function. If |
66
|
|
|
* $convertToCollection is true and the return value is a collection (array|Traversable) an instance of Collection |
67
|
|
|
* is returned. |
68
|
|
|
* |
69
|
|
|
* @param callable $function ($tmpValue, $value, $key) |
70
|
|
|
* @param mixed $startValue |
71
|
|
|
* @param bool $convertToCollection |
72
|
|
|
* @return mixed|Collection |
73
|
|
|
*/ |
74
|
2 |
|
public function reduce(callable $function, $startValue, $convertToCollection = false) |
75
|
|
|
{ |
76
|
2 |
|
$result = reduce($this->getItems(), $function, $startValue); |
77
|
|
|
|
78
|
2 |
|
return ($convertToCollection && isCollection($result)) ? new Collection($result) : $result; |
79
|
|
|
} |
80
|
|
|
|
81
|
|
|
/** |
82
|
|
|
* Returns a lazy collection with one or multiple levels of nesting flattened. Removes all nesting when no value |
83
|
|
|
* is passed. |
84
|
|
|
* |
85
|
|
|
* @param int $depth How many levels should be flatten, default (-1) is infinite. |
86
|
|
|
* @return Collection |
87
|
|
|
*/ |
88
|
1 |
|
public function flatten($depth = -1) |
89
|
|
|
{ |
90
|
1 |
|
return flatten($this->getItems(), $depth); |
91
|
|
|
} |
92
|
|
|
|
93
|
|
|
/** |
94
|
|
|
* Returns a non-lazy collection sorted using $function($item1, $item2, $key1, $key2 ). $function should |
95
|
|
|
* return true if first item is larger than the second and false otherwise. |
96
|
|
|
* |
97
|
|
|
* @param callable $function ($value1, $value2, $key1, $key2) |
98
|
|
|
* @return Collection |
99
|
|
|
*/ |
100
|
2 |
|
public function sort(callable $function) |
101
|
|
|
{ |
102
|
2 |
|
return \DusanKasan\Knapsack\sort($this->getItems(), $function); |
103
|
|
|
} |
104
|
|
|
|
105
|
|
|
/** |
106
|
|
|
* Returns lazy collection items of which are part of the original collection from item number $from to item |
107
|
|
|
* number $to. The items before $from are also iterated over, just not returned. |
108
|
|
|
* |
109
|
|
|
* @param int $from |
110
|
|
|
* @param int $to If omitted, will slice until end |
111
|
|
|
* @return Collection |
112
|
|
|
*/ |
113
|
1 |
|
public function slice($from, $to = -1) |
114
|
|
|
{ |
115
|
1 |
|
return slice($this->getItems(), $from, $to); |
116
|
|
|
} |
117
|
|
|
|
118
|
|
|
/** |
119
|
|
|
* Returns collection which items are separated into groups indexed by the return value of $function. |
120
|
|
|
* |
121
|
|
|
* @param callable $function ($value, $key) |
122
|
|
|
* @return Collection |
123
|
|
|
*/ |
124
|
1 |
|
public function groupBy(callable $function) |
125
|
|
|
{ |
126
|
1 |
|
return groupBy($this->getItems(), $function); |
127
|
|
|
} |
128
|
|
|
|
129
|
|
|
/** |
130
|
|
|
* Returns collection where items are separated into groups indexed by the value at given key. |
131
|
|
|
* |
132
|
|
|
* @param mixed $key |
133
|
|
|
* @return Collection |
134
|
|
|
*/ |
135
|
1 |
|
public function groupByKey($key) |
136
|
|
|
{ |
137
|
1 |
|
return groupByKey($this->getItems(), $key); |
138
|
|
|
} |
139
|
|
|
|
140
|
|
|
/** |
141
|
|
|
* Returns a lazy collection in which $function is executed for each item. |
142
|
|
|
* |
143
|
|
|
* @param callable $function ($value, $key) |
144
|
|
|
* @return Collection |
145
|
|
|
*/ |
146
|
1 |
|
public function each(callable $function) |
147
|
|
|
{ |
148
|
1 |
|
return \DusanKasan\Knapsack\each($this->getItems(), $function); |
149
|
|
|
} |
150
|
|
|
|
151
|
|
|
/** |
152
|
|
|
* Returns the number of items in this collection. |
153
|
|
|
* |
154
|
|
|
* @return int |
155
|
|
|
*/ |
156
|
6 |
|
public function size() |
157
|
|
|
{ |
158
|
6 |
|
return size($this->getItems()); |
159
|
|
|
} |
160
|
|
|
|
161
|
|
|
/** |
162
|
|
|
* Returns value at the key $key. If multiple values have this key, return first. If no value has this key, throw |
163
|
|
|
* ItemNotFound. If $convertToCollection is true and the return value is a collection (array|Traversable) an |
164
|
|
|
* instance of Collection will be returned. |
165
|
|
|
* |
166
|
|
|
* @param mixed $key |
167
|
|
|
* @param bool $convertToCollection |
168
|
|
|
* @return mixed|Collection |
169
|
|
|
* @throws \DusanKasan\Knapsack\Exceptions\ItemNotFound |
170
|
|
|
*/ |
171
|
5 |
|
public function get($key, $convertToCollection = false) |
172
|
|
|
{ |
173
|
5 |
|
$result = get($this->getItems(), $key); |
174
|
|
|
|
175
|
5 |
|
return ($convertToCollection && isCollection($result)) ? new Collection($result) : $result; |
176
|
|
|
} |
177
|
|
|
|
178
|
|
|
/** |
179
|
|
|
* Returns item at the key $key. If multiple items have this key, return first. If no item has this key, return |
180
|
|
|
* $ifNotFound. If no value has this key, throw ItemNotFound. If $convertToCollection is true and the return value |
181
|
|
|
* is a collection (array|Traversable) an instance of Collection will be returned. |
182
|
|
|
* |
183
|
|
|
* @param mixed $key |
184
|
|
|
* @param mixed $default |
185
|
|
|
* @param bool $convertToCollection |
186
|
|
|
* @return mixed|Collection |
187
|
|
|
* @throws \DusanKasan\Knapsack\Exceptions\ItemNotFound |
188
|
|
|
*/ |
189
|
1 |
|
public function getOrDefault($key, $default = null, $convertToCollection = false) |
190
|
|
|
{ |
191
|
1 |
|
$result = getOrDefault($this->getItems(), $key, $default); |
192
|
|
|
|
193
|
1 |
|
return ($convertToCollection && isCollection($result)) ? new Collection($result) : $result; |
194
|
|
|
} |
195
|
|
|
|
196
|
|
|
/** |
197
|
|
|
* Returns first value matched by $function. If no value matches, return $default. If $convertToCollection is true |
198
|
|
|
* and the return value is a collection (array|Traversable) an instance of Collection will be returned. |
199
|
|
|
* |
200
|
|
|
* @param callable $function |
201
|
|
|
* @param mixed|null $default |
202
|
|
|
* @param bool $convertToCollection |
203
|
|
|
* @return mixed|Collection |
204
|
|
|
*/ |
205
|
1 |
|
public function find(callable $function, $default = null, $convertToCollection = false) |
206
|
|
|
{ |
207
|
1 |
|
$result = find($this->getItems(), $function, $default); |
208
|
|
|
|
209
|
1 |
|
return ($convertToCollection && isCollection($result)) ? new Collection($result) : $result; |
210
|
|
|
} |
211
|
|
|
|
212
|
|
|
/** |
213
|
|
|
* Returns a non-lazy collection of items whose keys are the return values of $function and values are the number of |
214
|
|
|
* items in this collection for which the $function returned this value. |
215
|
|
|
* |
216
|
|
|
* @param callable $function |
217
|
|
|
* @return Collection |
218
|
|
|
*/ |
219
|
1 |
|
public function countBy(callable $function) |
220
|
|
|
{ |
221
|
1 |
|
return countBy($this->getItems(), $function); |
222
|
|
|
} |
223
|
|
|
|
224
|
|
|
/** |
225
|
|
|
* Returns a lazy collection by changing keys of this collection for each item to the result of $function for |
226
|
|
|
* that item. |
227
|
|
|
* |
228
|
|
|
* @param callable $function |
229
|
|
|
* @return Collection |
230
|
|
|
*/ |
231
|
3 |
|
public function indexBy(callable $function) |
232
|
|
|
{ |
233
|
3 |
|
return indexBy($this->getItems(), $function); |
234
|
|
|
} |
235
|
|
|
|
236
|
|
|
/** |
237
|
|
|
* Returns true if $function returns true for every item in this collection, false otherwise. |
238
|
|
|
* |
239
|
|
|
* @param callable $function |
240
|
|
|
* @return bool |
241
|
|
|
*/ |
242
|
1 |
|
public function every(callable $function) |
243
|
|
|
{ |
244
|
1 |
|
return every($this->getItems(), $function); |
245
|
|
|
} |
246
|
|
|
|
247
|
|
|
/** |
248
|
|
|
* Returns true if $function returns true for at least one item in this collection, false otherwise. |
249
|
|
|
* |
250
|
|
|
* @param callable $function |
251
|
|
|
* @return bool |
252
|
|
|
*/ |
253
|
1 |
|
public function some(callable $function) |
254
|
|
|
{ |
255
|
1 |
|
return some($this->getItems(), $function); |
256
|
|
|
} |
257
|
|
|
|
258
|
|
|
/** |
259
|
|
|
* Returns true if $value is present in the collection. |
260
|
|
|
* |
261
|
|
|
* @param mixed $value |
262
|
|
|
* @return bool |
263
|
|
|
*/ |
264
|
1 |
|
public function contains($value) |
265
|
|
|
{ |
266
|
1 |
|
return contains($this->getItems(), $value); |
267
|
|
|
} |
268
|
|
|
|
269
|
|
|
/** |
270
|
|
|
* Returns collection of items in this collection in reverse order. |
271
|
|
|
* |
272
|
|
|
* @return Collection |
273
|
|
|
*/ |
274
|
1 |
|
public function reverse() |
275
|
|
|
{ |
276
|
1 |
|
return reverse($this->getItems()); |
277
|
1 |
|
} |
278
|
|
|
|
279
|
|
|
/** |
280
|
|
|
* Reduce the collection to single value. Walks from right to left. If $convertToCollection is true and the return |
281
|
|
|
* value is a collection (array|Traversable) an instance of Collection is returned. |
282
|
|
|
* |
283
|
|
|
* @param callable $function Must take 2 arguments, intermediate value and item from the iterator. |
284
|
|
|
* @param mixed $startValue |
285
|
|
|
* @param bool $convertToCollection |
286
|
|
|
* @return mixed|Collection |
287
|
|
|
*/ |
288
|
1 |
|
public function reduceRight(callable $function, $startValue, $convertToCollection = false) |
289
|
|
|
{ |
290
|
1 |
|
$result = reduceRight($this->getItems(), $function, $startValue); |
291
|
|
|
|
292
|
1 |
|
return ($convertToCollection && isCollection($result)) ? new Collection($result) : $result; |
293
|
|
|
} |
294
|
|
|
|
295
|
|
|
/** |
296
|
|
|
* A form of slice that returns first $numberOfItems items. |
297
|
|
|
* |
298
|
|
|
* @param int $numberOfItems |
299
|
|
|
* @return Collection |
300
|
|
|
*/ |
301
|
9 |
|
public function take($numberOfItems) |
302
|
|
|
{ |
303
|
9 |
|
return take($this->getItems(), $numberOfItems); |
304
|
|
|
} |
305
|
|
|
|
306
|
|
|
/** |
307
|
|
|
* A form of slice that returns all but first $numberOfItems items. |
308
|
|
|
* |
309
|
|
|
* @param int $numberOfItems |
310
|
|
|
* @return Collection |
311
|
|
|
*/ |
312
|
2 |
|
public function drop($numberOfItems) |
313
|
|
|
{ |
314
|
2 |
|
return drop($this->getItems(), $numberOfItems); |
315
|
|
|
} |
316
|
|
|
|
317
|
|
|
/** |
318
|
|
|
* Returns collection of values from this collection but with keys being numerical from 0 upwards. |
319
|
|
|
* |
320
|
|
|
* @return Collection |
321
|
|
|
*/ |
322
|
13 |
|
public function values() |
323
|
|
|
{ |
324
|
13 |
|
return values($this->getItems()); |
325
|
|
|
} |
326
|
|
|
|
327
|
|
|
/** |
328
|
|
|
* Returns a lazy collection without elements matched by $function. |
329
|
|
|
* |
330
|
|
|
* @param callable $function |
331
|
|
|
* @return Collection |
332
|
|
|
*/ |
333
|
1 |
|
public function reject(callable $function) |
334
|
|
|
{ |
335
|
1 |
|
return reject($this->getItems(), $function); |
336
|
|
|
} |
337
|
|
|
|
338
|
|
|
/** |
339
|
|
|
* Returns a lazy collection of the keys of this collection. |
340
|
|
|
* |
341
|
|
|
* @return Collection |
342
|
|
|
*/ |
343
|
1 |
|
public function keys() |
344
|
|
|
{ |
345
|
1 |
|
return keys($this->getItems()); |
346
|
|
|
} |
347
|
|
|
|
348
|
|
|
/** |
349
|
|
|
* Returns a lazy collection of items of this collection separated by $separator |
350
|
|
|
* |
351
|
|
|
* @param mixed $separator |
352
|
|
|
* @return Collection |
353
|
|
|
*/ |
354
|
1 |
|
public function interpose($separator) |
355
|
|
|
{ |
356
|
1 |
|
return interpose($this->getItems(), $separator); |
357
|
|
|
} |
358
|
|
|
|
359
|
|
|
/** |
360
|
|
|
* Returns a lazy collection with last $numberOfItems items skipped. These are still iterated over, just skipped. |
361
|
|
|
* |
362
|
|
|
* @param int $numberOfItems |
363
|
|
|
* @return Collection |
364
|
|
|
*/ |
365
|
1 |
|
public function dropLast($numberOfItems = 1) |
366
|
|
|
{ |
367
|
1 |
|
return dropLast($this->getItems(), $numberOfItems); |
368
|
|
|
} |
369
|
|
|
|
370
|
|
|
/** |
371
|
|
|
* Returns a lazy collection of first item from first collection, first item from second, second from first and |
372
|
|
|
* so on. Accepts any number of collections. |
373
|
|
|
* |
374
|
|
|
* @param array|\Traversable ...$collections |
375
|
|
|
* @return Collection |
376
|
|
|
*/ |
377
|
1 |
|
public function interleave(...$collections) |
378
|
|
|
{ |
379
|
1 |
|
return interleave($this->getItems(), ...$collections); |
380
|
|
|
} |
381
|
|
|
|
382
|
|
|
/** |
383
|
|
|
* Returns an infinite lazy collection of items in this collection repeated infinitely. |
384
|
|
|
* |
385
|
|
|
* @return Collection |
386
|
|
|
*/ |
387
|
1 |
|
public function cycle() |
388
|
|
|
{ |
389
|
1 |
|
return cycle($this->getItems()); |
390
|
|
|
} |
391
|
|
|
|
392
|
|
|
/** |
393
|
|
|
* Returns a lazy collection of items of this collection with $value added as first element. If $key is not provided |
394
|
|
|
* it will be next integer index. |
395
|
|
|
* |
396
|
|
|
* @param mixed $value |
397
|
|
|
* @param mixed|null $key |
398
|
|
|
* @return Collection |
399
|
|
|
*/ |
400
|
2 |
|
public function prepend($value, $key = null) |
401
|
|
|
{ |
402
|
2 |
|
return prepend($this->getItems(), $value, $key); |
403
|
|
|
} |
404
|
|
|
|
405
|
|
|
/** |
406
|
|
|
* Returns a lazy collection of items of this collection with $value added as last element. If $key is not provided |
407
|
|
|
* it will be next integer index. |
408
|
|
|
* |
409
|
|
|
* @param mixed $value |
410
|
|
|
* @param mixed $key |
411
|
|
|
* @return Collection |
412
|
|
|
*/ |
413
|
6 |
|
public function append($value, $key = null) |
414
|
|
|
{ |
415
|
6 |
|
return append($this->getItems(), $value, $key); |
416
|
|
|
} |
417
|
|
|
|
418
|
|
|
/** |
419
|
|
|
* Returns a lazy collection by removing items from this collection until first item for which $function returns |
420
|
|
|
* false. |
421
|
|
|
* |
422
|
|
|
* @param callable $function |
423
|
|
|
* @return Collection |
424
|
|
|
*/ |
425
|
1 |
|
public function dropWhile(callable $function) |
426
|
|
|
{ |
427
|
1 |
|
return dropWhile($this->getItems(), $function); |
428
|
|
|
} |
429
|
|
|
|
430
|
|
|
/** |
431
|
|
|
* Returns a lazy collection which is a result of calling map($function) and then flatten(1) |
432
|
|
|
* |
433
|
|
|
* @param callable $function |
434
|
|
|
* @return Collection |
435
|
|
|
*/ |
436
|
1 |
|
public function mapcat(callable $function) |
437
|
|
|
{ |
438
|
1 |
|
return mapcat($this->getItems(), $function); |
439
|
|
|
} |
440
|
|
|
|
441
|
|
|
/** |
442
|
|
|
* Returns a lazy collection of items from the start of the ollection until the first item for which $function |
443
|
|
|
* returns false. |
444
|
|
|
* |
445
|
|
|
* @param callable $function |
446
|
|
|
* @return Collection |
447
|
|
|
*/ |
448
|
1 |
|
public function takeWhile(callable $function) |
449
|
|
|
{ |
450
|
1 |
|
return takeWhile($this->getItems(), $function); |
451
|
|
|
} |
452
|
|
|
|
453
|
|
|
/** |
454
|
|
|
* Returns a collection of [take($position), drop($position)] |
455
|
|
|
* |
456
|
|
|
* @param int $position |
457
|
|
|
* @return Collection |
458
|
|
|
*/ |
459
|
1 |
|
public function splitAt($position) |
460
|
|
|
{ |
461
|
1 |
|
return splitAt($this->getItems(), $position); |
462
|
|
|
} |
463
|
|
|
|
464
|
|
|
/** |
465
|
|
|
* Returns a collection of [takeWhile($predicament), dropWhile($predicament] |
466
|
|
|
* |
467
|
|
|
* @param callable $function |
468
|
|
|
* @return Collection |
469
|
|
|
*/ |
470
|
5 |
|
public function splitWith(callable $function) |
471
|
|
|
{ |
472
|
1 |
|
return splitWith($this->getItems(), $function); |
473
|
5 |
|
} |
474
|
|
|
|
475
|
|
|
/** |
476
|
|
|
* Returns a lazy collection with items from this collection but values that are found in keys of $replacementMap |
477
|
|
|
* are replaced by their values. |
478
|
|
|
* |
479
|
|
|
* @param array|\Traversable $replacementMap |
480
|
|
|
* @return Collection |
481
|
|
|
*/ |
482
|
1 |
|
public function replace($replacementMap) |
483
|
|
|
{ |
484
|
1 |
|
return replace($this->getItems(), $replacementMap); |
485
|
|
|
} |
486
|
|
|
|
487
|
|
|
/** |
488
|
|
|
* Returns a lazy collection of reduction steps. |
489
|
|
|
* |
490
|
|
|
* @param callable $function |
491
|
|
|
* @param mixed $startValue |
492
|
|
|
* @return Collection |
493
|
|
|
*/ |
494
|
1 |
|
public function reductions(callable $function, $startValue) |
495
|
|
|
{ |
496
|
1 |
|
return reductions($this->getItems(), $function, $startValue); |
497
|
|
|
} |
498
|
|
|
|
499
|
|
|
/** |
500
|
|
|
* Returns a lazy collection of every nth item in this collection |
501
|
|
|
* |
502
|
|
|
* @param int $step |
503
|
|
|
* @return Collection |
504
|
|
|
*/ |
505
|
1 |
|
public function takeNth($step) |
506
|
|
|
{ |
507
|
1 |
|
return takeNth($this->getItems(), $step); |
508
|
|
|
} |
509
|
|
|
|
510
|
|
|
/** |
511
|
|
|
* Returns a non-collection of shuffled items from this collection |
512
|
|
|
* |
513
|
|
|
* @return Collection |
514
|
|
|
*/ |
515
|
1 |
|
public function shuffle() |
516
|
|
|
{ |
517
|
1 |
|
return \DusanKasan\Knapsack\shuffle($this->getItems()); |
518
|
|
|
} |
519
|
|
|
|
520
|
|
|
/** |
521
|
|
|
* Returns a lazy collection of collections of $numberOfItems items each, at $step step |
522
|
|
|
* apart. If $step is not supplied, defaults to $numberOfItems, i.e. the partitions |
523
|
|
|
* do not overlap. If a $padding collection is supplied, use its elements as |
524
|
|
|
* necessary to complete last partition up to $numberOfItems items. In case there are |
525
|
|
|
* not enough padding elements, return a partition with less than $numberOfItems items. |
526
|
|
|
* |
527
|
|
|
* @param int $numberOfItems |
528
|
|
|
* @param int $step |
529
|
|
|
* @param array|\Traversable $padding |
530
|
|
|
* @return Collection |
531
|
|
|
*/ |
532
|
1 |
|
public function partition($numberOfItems, $step = 0, $padding = []) |
533
|
|
|
{ |
534
|
1 |
|
return partition($this->getItems(), $numberOfItems, $step, $padding); |
535
|
|
|
} |
536
|
|
|
|
537
|
|
|
/** |
538
|
|
|
* Creates a lazy collection of collections created by partitioning this collection every time $function will |
539
|
|
|
* return different result. |
540
|
|
|
* |
541
|
|
|
* @param callable $function |
542
|
|
|
* @return Collection |
543
|
|
|
*/ |
544
|
1 |
|
public function partitionBy(callable $function) |
545
|
|
|
{ |
546
|
1 |
|
return partitionBy($this->getItems(), $function); |
547
|
|
|
} |
548
|
|
|
|
549
|
|
|
/** |
550
|
|
|
* Returns true if this collection is empty. False otherwise. |
551
|
|
|
* |
552
|
|
|
* @return bool |
553
|
|
|
*/ |
554
|
3 |
|
public function isEmpty() |
555
|
|
|
{ |
556
|
3 |
|
return isEmpty($this->getItems()); |
557
|
|
|
} |
558
|
|
|
|
559
|
|
|
/** |
560
|
|
|
* Opposite of isEmpty. |
561
|
|
|
* |
562
|
|
|
* @return bool |
563
|
|
|
*/ |
564
|
2 |
|
public function isNotEmpty() |
565
|
|
|
{ |
566
|
2 |
|
return isNotEmpty($this->getItems()); |
567
|
|
|
} |
568
|
|
|
|
569
|
|
|
/** |
570
|
|
|
* Returns a collection where keys are distinct items from this collection and their values are number of |
571
|
|
|
* occurrences of each value. |
572
|
|
|
* |
573
|
|
|
* @return Collection |
574
|
|
|
*/ |
575
|
1 |
|
public function frequencies() |
576
|
|
|
{ |
577
|
1 |
|
return frequencies($this->getItems()); |
578
|
|
|
} |
579
|
|
|
|
580
|
|
|
/** |
581
|
|
|
* Returns first item of this collection. If the collection is empty, throws ItemNotFound. If $convertToCollection |
582
|
|
|
* is true and the return value is a collection (array|Traversable) an instance of Collection is returned. |
583
|
|
|
* |
584
|
|
|
* @param bool $convertToCollection |
585
|
|
|
* @return mixed|Collection |
586
|
|
|
* @throws \DusanKasan\Knapsack\Exceptions\ItemNotFound |
587
|
|
|
*/ |
588
|
11 |
|
public function first($convertToCollection = false) |
589
|
|
|
{ |
590
|
11 |
|
$result = first($this->getItems()); |
591
|
|
|
|
592
|
10 |
|
return ($convertToCollection && isCollection($result)) ? new Collection($result) : $result; |
593
|
|
|
} |
594
|
|
|
|
595
|
|
|
/** |
596
|
|
|
* Returns last item of this collection. If the collection is empty, throws ItemNotFound. If $convertToCollection |
597
|
|
|
* is true and the return value is a collection (array|Traversable) it is converted to Collection. |
598
|
|
|
* |
599
|
|
|
* @param bool $convertToCollection |
600
|
|
|
* @return mixed|Collection |
601
|
|
|
* @throws \DusanKasan\Knapsack\Exceptions\ItemNotFound |
602
|
|
|
*/ |
603
|
2 |
|
public function last($convertToCollection = false) |
604
|
|
|
{ |
605
|
2 |
|
$result = last($this->getItems()); |
606
|
|
|
|
607
|
1 |
|
return ($convertToCollection && isCollection($result)) ? new Collection($result) : $result; |
608
|
|
|
} |
609
|
|
|
|
610
|
|
|
/** |
611
|
|
|
* Realizes collection - turns lazy collection into non-lazy one by iterating over it and storing the key/values. |
612
|
|
|
* |
613
|
|
|
* @return Collection |
614
|
|
|
*/ |
615
|
1 |
|
public function realize() |
616
|
|
|
{ |
617
|
1 |
|
return realize($this->getItems()); |
618
|
|
|
} |
619
|
|
|
|
620
|
|
|
/** |
621
|
|
|
* Returns the second item in this collection or throws ItemNotFound if the collection is empty or has 1 item. If |
622
|
|
|
* $convertToCollection is true and the return value is a collection (array|Traversable) it is converted to |
623
|
|
|
* Collection. |
624
|
|
|
* |
625
|
|
|
* @param bool $convertToCollection |
626
|
|
|
* @return mixed|Collection |
627
|
|
|
* @throws \DusanKasan\Knapsack\Exceptions\ItemNotFound |
628
|
|
|
*/ |
629
|
6 |
|
public function second($convertToCollection = false) |
630
|
|
|
{ |
631
|
6 |
|
$result = second($this->getItems()); |
632
|
|
|
|
633
|
5 |
|
return ($convertToCollection && isCollection($result)) ? new Collection($result) : $result; |
634
|
|
|
} |
635
|
|
|
|
636
|
|
|
/** |
637
|
|
|
* Combines the values of this collection as keys, with values of $collection as values. The resulting collection |
638
|
|
|
* has length equal to the size of smaller collection. |
639
|
|
|
* |
640
|
|
|
* @param array|\Traversable $collection |
641
|
|
|
* @return Collection |
642
|
|
|
* @throws \DusanKasan\Knapsack\Exceptions\ItemNotFound |
643
|
|
|
*/ |
644
|
1 |
|
public function combine($collection) |
645
|
|
|
{ |
646
|
1 |
|
return combine($this->getItems(), $collection); |
647
|
|
|
} |
648
|
|
|
|
649
|
|
|
/** |
650
|
|
|
* Returns a lazy collection without the items associated to any of the keys from $keys. |
651
|
|
|
* |
652
|
|
|
* @param array|\Traversable $keys |
653
|
|
|
* @return Collection |
654
|
|
|
*/ |
655
|
1 |
|
public function except($keys) |
656
|
|
|
{ |
657
|
1 |
|
return except($this->getItems(), $keys); |
658
|
|
|
} |
659
|
|
|
|
660
|
|
|
/** |
661
|
|
|
* Returns a lazy collection of items associated to any of the keys from $keys. |
662
|
|
|
* |
663
|
|
|
* @param array|\Traversable $keys |
664
|
|
|
* @return Collection |
665
|
|
|
*/ |
666
|
1 |
|
public function only($keys) |
667
|
|
|
{ |
668
|
1 |
|
return only($this->getItems(), $keys); |
669
|
|
|
} |
670
|
|
|
|
671
|
|
|
/** |
672
|
|
|
* Returns a lazy collection of items that are in $this but are not in any of the other arguments, indexed by the |
673
|
|
|
* keys from the first collection. Note that the ...$collections are iterated non-lazily. |
674
|
|
|
* |
675
|
|
|
* @param array|\Traversable ...$collections |
676
|
|
|
* @return Collection |
677
|
|
|
*/ |
678
|
1 |
|
public function diff(...$collections) |
679
|
|
|
{ |
680
|
1 |
|
return diff($this->getItems(), ...$collections); |
681
|
|
|
} |
682
|
|
|
|
683
|
|
|
/** |
684
|
|
|
* Returns a lazy collection where keys and values are flipped. |
685
|
|
|
* |
686
|
|
|
* @return Collection |
687
|
|
|
*/ |
688
|
1 |
|
public function flip() |
689
|
|
|
{ |
690
|
1 |
|
return flip($this->getItems()); |
691
|
|
|
} |
692
|
|
|
|
693
|
|
|
/** |
694
|
|
|
* Checks for the existence of an item with$key in this collection. |
695
|
|
|
* |
696
|
|
|
* @param mixed $key |
697
|
|
|
* @return bool |
698
|
|
|
*/ |
699
|
1 |
|
public function has($key) |
700
|
|
|
{ |
701
|
1 |
|
return has($this->getItems(), $key); |
702
|
|
|
} |
703
|
|
|
|
704
|
|
|
/** |
705
|
|
|
* Returns a lazy collection of non-lazy collections of items from nth position from this collection and each |
706
|
|
|
* passed collection. Stops when any of the collections don't have an item at the nth position. |
707
|
|
|
* |
708
|
|
|
* @param array|\Traversable ...$collections |
709
|
|
|
* @return Collection |
710
|
|
|
*/ |
711
|
1 |
|
public function zip(...$collections) |
712
|
|
|
{ |
713
|
1 |
|
array_unshift($collections, $this->getItems()); |
714
|
|
|
|
715
|
1 |
|
return zip(...$collections); |
716
|
|
|
} |
717
|
|
|
|
718
|
|
|
/** |
719
|
|
|
* Uses a $transformer callable that takes a Collection and returns Collection on itself. |
720
|
|
|
* |
721
|
|
|
* @param callable $transformer Collection => Collection |
722
|
|
|
* @return Collection |
723
|
|
|
* @throws InvalidReturnValue |
724
|
|
|
*/ |
725
|
1 |
|
public function transform(callable $transformer) |
726
|
|
|
{ |
727
|
1 |
|
$items = $this->getItems(); |
728
|
|
|
|
729
|
1 |
|
$transformed = $transformer($items instanceof Collection ? $items : new Collection($items)); |
730
|
|
|
|
731
|
1 |
|
if (!($transformed instanceof Collection)) { |
732
|
1 |
|
throw new InvalidReturnValue; |
733
|
|
|
} |
734
|
|
|
|
735
|
1 |
|
return $transformed; |
736
|
|
|
} |
737
|
|
|
|
738
|
|
|
/** |
739
|
|
|
* Transpose each item in a collection, interchanging the row and column indexes. |
740
|
|
|
* Can only transpose collections of collections. Otherwise an InvalidArgument is raised. |
741
|
|
|
* |
742
|
|
|
* @return Collection |
743
|
|
|
*/ |
744
|
3 |
|
public function transpose() |
745
|
|
|
{ |
746
|
3 |
|
return transpose($this->getItems()); |
747
|
|
|
} |
748
|
|
|
|
749
|
|
|
/** |
750
|
|
|
* Extracts data from collection items by dot separated key path. Supports the * wildcard. If a key contains \ or |
751
|
|
|
* it must be escaped using \ character. |
752
|
|
|
* |
753
|
|
|
* @param mixed $keyPath |
754
|
|
|
* @return Collection |
755
|
|
|
*/ |
756
|
1 |
|
public function extract($keyPath) |
757
|
|
|
{ |
758
|
1 |
|
return \DusanKasan\Knapsack\extract($this->getItems(), $keyPath); |
759
|
|
|
} |
760
|
|
|
|
761
|
|
|
/** |
762
|
|
|
* Returns a lazy collection of items that are in $this and all the other arguments, indexed by the keys from |
763
|
|
|
* the first collection. Note that the ...$collections are iterated non-lazily. |
764
|
|
|
* |
765
|
|
|
* @param array|\Traversable ...$collections |
766
|
|
|
* @return Collection |
767
|
|
|
*/ |
768
|
1 |
|
public function intersect(...$collections) |
769
|
|
|
{ |
770
|
1 |
|
return intersect($this->getItems(), ...$collections); |
771
|
|
|
} |
772
|
|
|
|
773
|
|
|
/** |
774
|
|
|
* Checks whether this collection has exactly $size items. |
775
|
|
|
* |
776
|
|
|
* @param int $size |
777
|
|
|
* @return bool |
778
|
|
|
*/ |
779
|
1 |
|
public function sizeIs($size) |
780
|
|
|
{ |
781
|
1 |
|
return sizeIs($this->getItems(), $size); |
782
|
|
|
} |
783
|
|
|
|
784
|
|
|
/** |
785
|
|
|
* Checks whether this collection has less than $size items. |
786
|
|
|
* |
787
|
|
|
* @param int $size |
788
|
|
|
* @return bool |
789
|
|
|
*/ |
790
|
1 |
|
public function sizeIsLessThan($size) |
791
|
|
|
{ |
792
|
1 |
|
return sizeIsLessThan($this->getItems(), $size); |
793
|
|
|
} |
794
|
|
|
|
795
|
|
|
/** |
796
|
|
|
* Checks whether this collection has more than $size items. |
797
|
|
|
* |
798
|
|
|
* @param int $size |
799
|
|
|
* @return bool |
800
|
|
|
*/ |
801
|
1 |
|
public function sizeIsGreaterThan($size) |
802
|
|
|
{ |
803
|
1 |
|
return sizeIsGreaterThan($this->getItems(), $size); |
804
|
|
|
} |
805
|
|
|
|
806
|
|
|
/** |
807
|
|
|
* Checks whether this collection has between $fromSize to $toSize items. $toSize can be |
808
|
|
|
* smaller than $fromSize. |
809
|
|
|
* |
810
|
|
|
* @param int $fromSize |
811
|
|
|
* @param int $toSize |
812
|
|
|
* @return bool |
813
|
|
|
*/ |
814
|
1 |
|
public function sizeIsBetween($fromSize, $toSize) |
815
|
|
|
{ |
816
|
1 |
|
return sizeIsBetween($this->getItems(), $fromSize, $toSize); |
817
|
|
|
} |
818
|
|
|
|
819
|
|
|
/** |
820
|
|
|
* Returns a sum of all values in this collection. |
821
|
|
|
* |
822
|
|
|
* @return int|float |
823
|
|
|
*/ |
824
|
1 |
|
public function sum() |
825
|
|
|
{ |
826
|
1 |
|
return sum($this->getItems()); |
827
|
|
|
} |
828
|
|
|
|
829
|
|
|
/** |
830
|
|
|
* Returns average of values from this collection. |
831
|
|
|
* |
832
|
|
|
* @return int|float |
833
|
|
|
*/ |
834
|
2 |
|
public function average() |
835
|
|
|
{ |
836
|
2 |
|
return average($this->getItems()); |
837
|
|
|
} |
838
|
|
|
|
839
|
|
|
/** |
840
|
|
|
* Returns maximal value from this collection. |
841
|
|
|
* |
842
|
|
|
* @return mixed |
843
|
|
|
*/ |
844
|
2 |
|
public function max() |
845
|
|
|
{ |
846
|
2 |
|
return \DusanKasan\Knapsack\max($this->getItems()); |
847
|
|
|
} |
848
|
|
|
|
849
|
|
|
/** |
850
|
|
|
* Returns minimal value from this collection. |
851
|
|
|
* |
852
|
|
|
* @return mixed |
853
|
|
|
*/ |
854
|
2 |
|
public function min() |
855
|
|
|
{ |
856
|
2 |
|
return \DusanKasan\Knapsack\min($this->getItems()); |
857
|
|
|
} |
858
|
|
|
|
859
|
|
|
/** |
860
|
|
|
* Returns a string by concatenating the collection values into a string. |
861
|
|
|
* |
862
|
|
|
* @return string |
863
|
|
|
*/ |
864
|
1 |
|
public function toString() |
865
|
|
|
{ |
866
|
1 |
|
return toString($this->getItems()); |
867
|
|
|
} |
868
|
|
|
|
869
|
|
|
/** |
870
|
|
|
* Returns a lazy collection with items from $collection, but items with keys that are found in keys of |
871
|
|
|
* $replacementMap are replaced by their values. |
872
|
|
|
* |
873
|
|
|
* @param array|\Traversable $replacementMap |
874
|
|
|
* @return Collection |
875
|
|
|
*/ |
876
|
1 |
|
public function replaceByKeys($replacementMap) |
877
|
|
|
{ |
878
|
1 |
|
return replaceByKeys($this->getItems(), $replacementMap); |
879
|
|
|
} |
880
|
|
|
|
881
|
|
|
/** |
882
|
|
|
* /** |
883
|
|
|
* Dumps this collection into array (recursively). |
884
|
|
|
* |
885
|
|
|
* - scalars are returned as they are, |
886
|
|
|
* - array of class name => properties (name => value and only properties accessible for this class) |
887
|
|
|
* is returned for objects, |
888
|
|
|
* - arrays or Traversables are returned as arrays, |
889
|
|
|
* - for anything else result of calling gettype($input) is returned |
890
|
|
|
* |
891
|
|
|
* If specified, $maxItemsPerCollection will only leave specified number of items in collection, |
892
|
|
|
* appending a new element at end '>>>' if original collection was longer. |
893
|
|
|
* |
894
|
|
|
* If specified, $maxDepth will only leave specified n levels of nesting, replacing elements |
895
|
|
|
* with '^^^' once the maximum nesting level was reached. |
896
|
|
|
* |
897
|
|
|
* If a collection with duplicate keys is encountered, the duplicate keys (except the first one) |
898
|
|
|
* will be change into a format originalKey//duplicateCounter where duplicateCounter starts from |
899
|
|
|
* 1 at the first duplicate. So [0 => 1, 0 => 2] will become [0 => 1, '0//1' => 2] |
900
|
|
|
* |
901
|
|
|
* @param int|null $maxItemsPerCollection |
902
|
|
|
* @param int|null $maxDepth |
903
|
|
|
* @return array |
904
|
|
|
*/ |
905
|
1 |
|
public function dump($maxItemsPerCollection = null, $maxDepth = null) |
906
|
|
|
{ |
907
|
1 |
|
return dump($this->getItems(), $maxItemsPerCollection, $maxDepth); |
908
|
|
|
} |
909
|
|
|
|
910
|
|
|
/** |
911
|
|
|
* Calls dump on this collection and then prints it using the var_export. |
912
|
|
|
* |
913
|
|
|
* @param int|null $maxItemsPerCollection |
914
|
|
|
* @param int|null $maxDepth |
915
|
|
|
* @return Collection |
916
|
|
|
*/ |
917
|
1 |
|
public function printDump($maxItemsPerCollection = null, $maxDepth = null) |
918
|
|
|
{ |
919
|
1 |
|
return printDump($this->getItems(), $maxItemsPerCollection, $maxDepth); |
920
|
|
|
} |
921
|
|
|
|
922
|
|
|
/** |
923
|
|
|
* @return array|\Traversable |
924
|
|
|
*/ |
925
|
103 |
|
protected function getItems() |
926
|
|
|
{ |
927
|
103 |
|
return $this; |
928
|
|
|
} |
929
|
|
|
} |
930
|
|
|
|