\YaLinqoOrderedEnumerable

Subclass of Enumerable supporting ordering by multiple conditions.

A sequence of values indexed by keys, which supports various operations: generation, projection, filtering, ordering, joining, grouping, aggregation etc.

To create a Enumerable, call \YaLinqo\Enumerable::from (aliased as a global function \YaLinqo\from) or any of the generation functions. To convert to array, call \YaLinqo\Enumerable::toArrayDeep or any of the conversion functions.

Summary

Methods
Properties
Constants
getIterator()
cast()
ofType()
select()
selectMany()
where()
orderByDir()
orderBy()
orderByDescending()
groupJoin()
join()
groupBy()
aggregate()
aggregateOrDefault()
average()
count()
max()
maxBy()
min()
minBy()
sum()
all()
any()
append()
concat()
contains()
distinct()
except()
intersect()
prepend()
union()
toArray()
toArrayDeep()
toList()
toListDeep()
toDictionary()
toJSON()
toLookup()
toKeys()
toValues()
toObject()
toString()
call()
each()
write()
writeLine()
cycle()
emptyEnum()
from()
generate()
toInfinity()
matches()
toNegativeInfinity()
returnEnum()
range()
rangeDown()
rangeTo()
repeat()
split()
elementAt()
elementAtOrDefault()
first()
firstOrDefault()
firstOrFallback()
last()
lastOrDefault()
lastOrFallback()
single()
singleOrDefault()
singleOrFallback()
indexOf()
lastIndexOf()
findIndex()
findLastIndex()
skip()
skipWhile()
take()
takeWhile()
thenByDir()
thenBy()
thenByDescending()
No public properties found
No constants found
tryGetArrayCopy()
toArrayDeepProc()
toListDeepProc()
No protected properties found
N/A
No private methods found
No private properties found
N/A

Methods

getIterator()

getIterator() : \Iterator

Retrieve an external iterator.

{@inheritdoc}

Returns

\Iterator

cast()

cast(string  $type) : \YaLinqo\Enumerable

Casts the elements of a sequence to the specified type.

Syntax: cast (type)

The cast method causes an error if an element cannot be cast (exact error depends on the implementation of PHP casting), to get only elements of the specified type, use \ofType.

Parameters

string $type

The type to cast the elements to. Can be one of the built-in types: array, int (integer, long), float (real, double), null (unset), object, string.

Returns

\YaLinqo\Enumerable

An sequence that contains each element of the source sequence cast to the specified type.

ofType()

ofType(string  $type) : \YaLinqo\Enumerable

Filters the elements of a sequence based on a specified type.

Syntax: ofType (type)

The ofType method returns only elements of the specified type. To instead receive an error if an element cannot be cast, use \cast.

Parameters

string $type

The type to filter the elements of the sequence on. Can be either class name or one of the predefined types: array, int (integer, long), callable (callable), float (real, double), null, string, object, numeric, scalar.

Returns

\YaLinqo\Enumerable

A sequence that contains elements from the input sequence of the specified type.

select()

select(callable  $selectorValue, callable|null  $selectorKey = null) : \YaLinqo\Enumerable

Projects each element of a sequence into a new form.

Syntax: select (selectorValue {(v, k) ==> result} [, selectorKey {(v, k) ==> result}])

This projection method requires the transform functions, selectorValue and selectorKey, to produce one key-value pair for each value in the source sequence. If selectorValue returns a value that is itself a collection, it is up to the consumer to traverse the subsequences manually. In such a situation, it might be better for your query to return a single coalesced sequence of values. To achieve this, use the \selectMany() method instead of select. Although selectMany works similarly to select, it differs in that the transform function returns a collection that is then expanded by selectMany before it is returned.

Parameters

callable $selectorValue

{(v, k) ==> value} A transform function to apply to each value.

callable|null $selectorKey

{(v, k) ==> key} A transform function to apply to each key. Default: key.

Returns

\YaLinqo\Enumerable

A sequence whose elements are the result of invoking the transform functions on each element of source.

selectMany()

selectMany(callable  $collectionSelector = null, callable|null  $resultSelectorValue = null, callable|null  $resultSelectorKey = null) : \YaLinqo\Enumerable

Projects each element of a sequence to a sequence and flattens the resulting sequences into one sequence.

Syntax: selectMany ()

The selectMany method enumerates the input sequence, where each element is a sequence, and then enumerates and yields the elements of each such sequence. That is, for each element of source, selectorValue and selectorKey are invoked and a sequence of key-value pairs is returned. selectMany then flattens this two-dimensional collection of collections into a one-dimensional sequence and returns it. For example, if a query uses selectMany to obtain the orders for each customer in a database, the result is a sequence of orders. If instead the query uses \select to obtain the orders, the collection of collections of orders is not combined and the result is a sequence of sequences of orders.

Syntax: selectMany (collectionSelector {(v, k) ==> enum})

The selectMany method enumerates the input sequence, uses transform functions to map each element to a sequence, and then enumerates and yields the elements of each such sequence.

Syntax: selectMany (collectionSelector {(v, k) ==> enum} [, resultSelectorValue {(v, k1, k2) ==> value} [, resultSelectorKey {(v, k1, k2) ==> key}]])

Projects each element of a sequence to a sequence, flattens the resulting sequences into one sequence, and invokes a result selector functions on each element therein.

The selectMany method is useful when you have to keep the elements of source in scope for query logic that occurs after the call to selectMany. If there is a bidirectional relationship between objects in the source sequence and objects returned from collectionSelector, that is, if a sequence returned from collectionSelector provides a property to retrieve the object that produced it, you do not need this overload of selectMany. Instead, you can use simpler selectMany overload and navigate back to the source object through the returned sequence.

Parameters

callable $collectionSelector

{(v, k) ==> enum} A transform function to apply to each element.

callable|null $resultSelectorValue

{(v, k1, k2) ==> value} A transform function to apply to each value of the intermediate sequence. Default: {(v, k1, k2) ==> v}.

callable|null $resultSelectorKey

{(v, k1, k2) ==> key} A transform function to apply to each key of the intermediate sequence. Default: increment.

Returns

\YaLinqo\Enumerable

A sequence whose elements are the result of invoking the one-to-many transform function on each element of the input sequence.

where()

where(callable  $predicate) : \YaLinqo\Enumerable

Filters a sequence of values based on a predicate.

Syntax: where (predicate {(v, k) ==> result})

Parameters

callable $predicate

{(v, k) ==> result} A function to test each element for a condition.

Returns

\YaLinqo\Enumerable

A sequence that contains elements from the input sequence that satisfy the condition.

orderByDir()

orderByDir(integer|boolean  $sortOrder, callable|null  $keySelector = null, callable|integer|null  $comparer = null) : \YaLinqo\OrderedEnumerable

Sorts the elements of a sequence in a particular direction (ascending, descending) according to a key.

Syntax: orderByDir (false|true [, {(v, k) ==> key} [, {(a, b) ==> diff}]])

Three methods are defined to extend the type \OrderedEnumerable, which is the return type of this method. These three methods, namely \OrderedEnumerable::thenBy, \OrderedEnumerable::thenByDescending and \OrderedEnumerable::thenByDir, enable you to specify additional sort criteria to sort a sequence. These methods also return an OrderedEnumerable, which means any number of consecutive calls to thenBy, thenByDescending or thenByDir can be made.

Because OrderedEnumerable inherits from Enumerable, you can call \orderBy, \orderByDescending or \orderByDir on the results of a call to orderBy, orderByDescending, orderByDir, thenBy, thenByDescending or thenByDir. Doing this introduces a new primary ordering that ignores the previously established ordering.

This method performs an unstable sort; that is, if the keys of two elements are equal, the order of the elements is not preserved. In contrast, a stable sort preserves the order of elements that have the same key. Internally, \usort is used.

Parameters

integer|boolean $sortOrder

A direction in which to order the elements: false or SORT_DESC for ascending (by increasing value), true or SORT_ASC for descending (by decreasing value).

callable|null $keySelector

{(v, k) ==> key} A function to extract a key from an element. Default: value.

callable|integer|null $comparer

{(a, b) ==> diff} Difference between a and b: <0 if a<b; 0 if a==b; >0 if a>b. Can also be a combination of SORT_ flags.

Returns

\YaLinqo\OrderedEnumerable

orderBy()

orderBy(callable|null  $keySelector = null, callable|integer|null  $comparer = null) : \YaLinqo\OrderedEnumerable

Sorts the elements of a sequence in ascending order according to a key.

Syntax: orderBy ([{(v, k) ==> key} [, {(a, b) ==> diff}]])

Three methods are defined to extend the type \OrderedEnumerable, which is the return type of this method. These three methods, namely \OrderedEnumerable::thenBy, \OrderedEnumerable::thenByDescending and \OrderedEnumerable::thenByDir, enable you to specify additional sort criteria to sort a sequence. These methods also return an OrderedEnumerable, which means any number of consecutive calls to thenBy, thenByDescending or thenByDir can be made.

Because OrderedEnumerable inherits from Enumerable, you can call \orderBy, \orderByDescending or \orderByDir on the results of a call to orderBy, orderByDescending, orderByDir, thenBy, thenByDescending or thenByDir. Doing this introduces a new primary ordering that ignores the previously established ordering.

This method performs an unstable sort; that is, if the keys of two elements are equal, the order of the elements is not preserved. In contrast, a stable sort preserves the order of elements that have the same key. Internally, \usort is used.

Parameters

callable|null $keySelector

{(v, k) ==> key} A function to extract a key from an element. Default: value.

callable|integer|null $comparer

{(a, b) ==> diff} Difference between a and b: <0 if a<b; 0 if a==b; >0 if a>b. Can also be a combination of SORT_ flags.

Returns

\YaLinqo\OrderedEnumerable

orderByDescending()

orderByDescending(callable|null  $keySelector = null, callable|integer|null  $comparer = null) : \YaLinqo\OrderedEnumerable

Sorts the elements of a sequence in descending order according to a key.

Syntax: orderByDescending ([{(v, k) ==> key} [, {(a, b) ==> diff}]])

Three methods are defined to extend the type \OrderedEnumerable, which is the return type of this method. These three methods, namely \OrderedEnumerable::thenBy, \OrderedEnumerable::thenByDescending and \OrderedEnumerable::thenByDir, enable you to specify additional sort criteria to sort a sequence. These methods also return an OrderedEnumerable, which means any number of consecutive calls to thenBy, thenByDescending or thenByDir can be made.

Because OrderedEnumerable inherits from Enumerable, you can call \orderBy, \orderByDescending or \orderByDir on the results of a call to orderBy, orderByDescending, orderByDir, thenBy, thenByDescending or thenByDir. Doing this introduces a new primary ordering that ignores the previously established ordering.

This method performs an unstable sort; that is, if the keys of two elements are equal, the order of the elements is not preserved. In contrast, a stable sort preserves the order of elements that have the same key. Internally, \usort is used.

Parameters

callable|null $keySelector

{(v, k) ==> key} A function to extract a key from an element. Default: value.

callable|integer|null $comparer

{(a, b) ==> diff} Difference between a and b: <0 if a<b; 0 if a==b; >0 if a>b. Can also be a combination of SORT_ flags.

Returns

\YaLinqo\OrderedEnumerable

groupJoin()

groupJoin(array|\Iterator|\IteratorAggregate|\YaLinqo\Enumerable  $inner, callable|null  $outerKeySelector = null, callable|null  $innerKeySelector = null, callable|null  $resultSelectorValue = null, callable|null  $resultSelectorKey = null) : \YaLinqo\Enumerable

Correlates the elements of two sequences based on equality of keys and groups the results.

Syntax: groupJoin (inner [, outerKeySelector {(v, k) ==> key} [, innerKeySelector {(v, k) ==> key} [, resultSelectorValue {(v, e, k) ==> value} [, resultSelectorKey {(v, e, k) ==> key}]]]])

GroupJoin produces hierarchical results, which means that elements from outer are paired with collections of matching elements from inner. GroupJoin enables you to base your results on a whole set of matches for each element of outer. If there are no correlated elements in inner for a given element of outer, the sequence of matches for that element will be empty but will still appear in the results.

The resultSelectorValue and resultSelectorKey functions are called only one time for each outer element together with a collection of all the inner elements that match the outer element. This differs from the \join method, in which the result selector function is invoked on pairs that contain one element from outer and one element from inner. GroupJoin preserves the order of the elements of outer, and for each element of outer, the order of the matching elements from inner.

GroupJoin has no direct equivalent in traditional relational database terms. However, this method does implement a superset of inner joins and left outer joins. Both of these operations can be written in terms of a grouped join.

Parameters

array|\Iterator|\IteratorAggregate|\YaLinqo\Enumerable $inner

The second (inner) sequence to join to the first (source, outer) sequence.

callable|null $outerKeySelector

{(v, k) ==> key} A function to extract the join key from each element of the first sequence. Default: key.

callable|null $innerKeySelector

{(v, k) ==> key} A function to extract the join key from each element of the second sequence. Default: key.

callable|null $resultSelectorValue

{(v, e, k) ==> value} A function to create a result value from an element from the first sequence and a collection of matching elements from the second sequence. Default: {(v, e, k) ==> array(v, e)}.

callable|null $resultSelectorKey

{(v, e, k) ==> key} A function to create a result key from an element from the first sequence and a collection of matching elements from the second sequence. Default: {(v, e, k) ==> k} (keys returned by outerKeySelector and innerKeySelector functions).

Returns

\YaLinqo\Enumerable

A sequence that contains elements that are obtained by performing a grouped join on two sequences.

join()

join(array|\Iterator|\IteratorAggregate|\YaLinqo\Enumerable  $inner, callable|null  $outerKeySelector = null, callable|null  $innerKeySelector = null, callable|null  $resultSelectorValue = null, callable|null  $resultSelectorKey = null) : \YaLinqo\Enumerable

Correlates the elements of two sequences based on matching keys.

Syntax: join (inner [, outerKeySelector {(v, k) ==> key} [, innerKeySelector {(v, k) ==> key} [, resultSelectorValue {(v1, v2, k) ==> value} [, resultSelectorKey {(v1, v2, k) ==> key}]]]])

A join refers to the operation of correlating the elements of two sources of information based on a common key. Join brings the two information sources and the keys by which they are matched together in one method call. This differs from the use of \selectMany, which requires more than one method call to perform the same operation.

Join preserves the order of the elements of the source, and for each of these elements, the order of the matching elements of inner.

In relational database terms, the Join method implements an inner equijoin. 'Inner' means that only elements that have a match in the other sequence are included in the results. An 'equijoin' is a join in which the keys are compared for equality. A left outer join operation has no dedicated standard query operator, but can be performed by using the \groupJoin method.

Parameters

array|\Iterator|\IteratorAggregate|\YaLinqo\Enumerable $inner

The sequence to join to the source sequence.

callable|null $outerKeySelector

{(v, k) ==> key} A function to extract the join key from each element of the source sequence. Default: key.

callable|null $innerKeySelector

{(v, k) ==> key} A function to extract the join key from each element of the second sequence. Default: key.

callable|null $resultSelectorValue

{(v1, v2, k) ==> result} A function to create a result value from two matching elements. Default: {(v1, v2, k) ==> array(v1, v2)}.

callable|null $resultSelectorKey

{(v1, v2, k) ==> result} A function to create a result key from two matching elements. Default: {(v1, v2, k) ==> k} (keys returned by outerKeySelector and innerKeySelector functions).

Returns

\YaLinqo\Enumerable

groupBy()

groupBy(callable|null  $keySelector = null, callable|null  $valueSelector = null, callable|null  $resultSelectorValue = null, callable|null  $resultSelectorKey = null) : \YaLinqo\Enumerable

Groups the elements of a sequence by its keys or a specified key selector function.

Syntax: groupBy ()

Groups the elements of a sequence by its keys.

Syntax: groupBy (keySelector {(v, k) ==> key})

Groups the elements of a sequence according to a specified key selector function.

Syntax: groupBy (keySelector {(v, k) ==> key}, valueSelector {(v, k) ==> value})

Groups the elements of a sequence according to a specified key selector function and projects the elements for each group by using a specified function.

Syntax: groupBy (keySelector {(v, k) ==> key}, valueSelector {(v, k) ==> value}, resultSelectorValue {(e, k) ==> value} [, resultSelectorKey {(e, k) ==> key}])

Groups the elements of a sequence according to a specified key selector function and creates a result value from each group and its key.

For all overloads except the last: the groupBy method returns a sequence of sequences, one inner sequence for each distinct key that was encountered. The outer sequence is yielded in an order based on the order of the elements in source that produced the first key of each inner sequence. Elements in a inner sequence are yielded in the order they appear in source.

Parameters

callable|null $keySelector

{(v, k) ==> key} A function to extract the key for each element. Default: key.

callable|null $valueSelector

{(v, k) ==> value} A function to map each source element to a value in the inner sequence.

callable|null $resultSelectorValue

{(e, k) ==> value} A function to create a result value from each group.

callable|null $resultSelectorKey

{(e, k) ==> key} A function to create a result key from each group.

Returns

\YaLinqo\Enumerable

A sequence of sequences indexed by a key.

aggregate()

aggregate(callable  $func, mixed  $seed = null) : mixed

Applies an accumulator function over a sequence. If seed is not null, its value is used as the initial accumulator value.

Syntax: aggregate (func {(a, v, k) ==> accum} [, seed])

Aggregate method makes it simple to perform a calculation over a sequence of values. This method works by calling func one time for each element in source. Each time func is called, aggregate passes both the element from the sequence and an aggregated value (as the first argument to func). If seed is null, the first element of source is used as the initial aggregate value. The result of func replaces the previous aggregated value. Aggregate returns the final result of func.

To simplify common aggregation operations, the standard query operators also include a general purpose count method, \count, and four numeric aggregation methods, namely \min, \max, \sum, and \average.

Parameters

callable $func

{(a, v, k) ==> accum} An accumulator function to be invoked on each element.

mixed $seed

If seed is not null, the first element is used as seed. Default: null.

Throws

\UnexpectedValueException

If seed is null and sequence contains no elements.

Returns

mixed —

The final accumulator value.

aggregateOrDefault()

aggregateOrDefault(callable  $func, mixed  $seed = null, mixed  $default = null) : mixed

Applies an accumulator function over a sequence. If seed is not null, its value is used as the initial accumulator value.

aggregateOrDefault (func {(a, v, k) ==> accum} [, seed [, default]])

Aggregate method makes it simple to perform a calculation over a sequence of values. This method works by calling func one time for each element in source. Each time func is called, aggregate passes both the element from the sequence and an aggregated value (as the first argument to func). If seed is null, the first element of source is used as the initial aggregate value. The result of func replaces the previous aggregated value. Aggregate returns the final result of func. If source sequence is empty, default is returned.

To simplify common aggregation operations, the standard query operators also include a general purpose count method, \count, and four numeric aggregation methods, namely \min, \max, \sum, and \average.

Parameters

callable $func

{(a, v, k) ==> accum} An accumulator function to be invoked on each element.

mixed $seed

If seed is not null, the first element is used as seed. Default: null.

mixed $default

Value to return if sequence is empty. Default: null.

Returns

mixed —

The final accumulator value, or default if sequence is empty.

average()

average(callable|null  $selector = null) : \YaLinqo\number

Computes the average of a sequence of numeric values.

Syntax: average ()

Computes the average of a sequence of numeric values.

Syntax: average (selector {(v, k) ==> result})

Computes the average of a sequence of numeric values that are obtained by invoking a transform function on each element of the input sequence.

Parameters

callable|null $selector

{(v, k) ==> result} A transform function to apply to each element. Default: value.

Throws

\UnexpectedValueException

If sequence contains no elements.

Returns

\YaLinqo\number —

The average of the sequence of values.

count()

count(callable|null  $predicate = null) : integer

Returns the number of elements in a sequence.

Syntax: count ()

If source iterator implements \Countable, that implementation is used to obtain the count of elements. Otherwise, this method determines the count.

Syntax: count (predicate {(v, k) ==> result})

Returns a number that represents how many elements in the specified sequence satisfy a condition.

Parameters

callable|null $predicate

{(v, k) ==> result} A function to test each element for a condition. Default: null.

Returns

integer —

The number of elements in the input sequence.

max()

max(callable|null  $selector = null) : \YaLinqo\number

Returns the maximum value in a sequence of values.

Syntax: max ()

Returns the maximum value in a sequence of values.

Syntax: max (selector {(v, k) ==> value})

Invokes a transform function on each element of a sequence and returns the maximum value.

Parameters

callable|null $selector

{(v, k) ==> value} A transform function to apply to each element. Default: value.

Throws

\UnexpectedValueException

If sequence contains no elements.

Returns

\YaLinqo\number —

The maximum value in the sequence.

maxBy()

maxBy(callable  $comparer, callable|null  $selector = null) : \YaLinqo\number

Returns the maximum value in a sequence of values, using specified comparer.

Syntax: maxBy (comparer {(a, b) ==> diff})

Returns the maximum value in a sequence of values, using specified comparer.

Syntax: maxBy (comparer {(a, b) ==> diff}, selector {(v, k) ==> value})

Invokes a transform function on each element of a sequence and returns the maximum value, using specified comparer.

Parameters

callable $comparer

{(a, b) ==> diff} Difference between a and b: <0 if a<b; 0 if a==b; >0 if a>b

callable|null $selector

{(v, k) ==> value} A transform function to apply to each element. Default: value.

Throws

\UnexpectedValueException

If sequence contains no elements.

Returns

\YaLinqo\number —

The maximum value in the sequence.

min()

min(callable|null  $selector = null) : \YaLinqo\number

Returns the minimum value in a sequence of values.

Syntax: min ()

Returns the minimum value in a sequence of values.

Syntax: min (selector {(v, k) ==> value})

Invokes a transform function on each element of a sequence and returns the minimum value.

Parameters

callable|null $selector

{(v, k) ==> value} A transform function to apply to each element. Default: value.

Throws

\UnexpectedValueException

If sequence contains no elements.

Returns

\YaLinqo\number —

The minimum value in the sequence.

minBy()

minBy(callable  $comparer, callable|null  $selector = null) : \YaLinqo\number

Returns the minimum value in a sequence of values, using specified comparer.

Syntax: minBy (comparer {(a, b) ==> diff})

Returns the minimum value in a sequence of values, using specified comparer.

Syntax: minBy (comparer {(a, b) ==> diff}, selector {(v, k) ==> value})

Invokes a transform function on each element of a sequence and returns the minimum value, using specified comparer.

Parameters

callable $comparer

{(a, b) ==> diff} Difference between a and b: <0 if a<b; 0 if a==b; >0 if a>b

callable|null $selector

{(v, k) ==> value} A transform function to apply to each element. Default: value.

Throws

\UnexpectedValueException

If sequence contains no elements.

Returns

\YaLinqo\number —

The minimum value in the sequence.

sum()

sum(callable|null  $selector = null) : \YaLinqo\number

Computes the sum of a sequence of values.

Syntax: sum ()

Computes the sum of a sequence of values.

Syntax: sum (selector {(v, k) ==> result})

Computes the sum of the sequence of values that are obtained by invoking a transform function on each element of the input sequence.

This method returns zero if source contains no elements.

Parameters

callable|null $selector

{(v, k) ==> result} A transform function to apply to each element.

Returns

\YaLinqo\number —

The sum of the values in the sequence.

all()

all(callable  $predicate) : boolean

Determines whether all elements of a sequence satisfy a condition.

Syntax: all (predicate {(v, k) ==> result})

Determines whether all elements of a sequence satisfy a condition. The enumeration of source is stopped as soon as the result can be determined.

Parameters

callable $predicate

{(v, k) ==> result} A function to test each element for a condition.

Returns

boolean —

true if every element of the source sequence passes the test in the specified predicate, or if the sequence is empty; otherwise, false.

any()

any(callable|null  $predicate = null) : boolean

Determines whether a sequence contains any elements.

Syntax: any ()

Determines whether a sequence contains any elements. The enumeration of source is stopped as soon as the result can be determined.

Syntax: any (predicate {(v, k) ==> result})

Determines whether any element of a sequence exists or satisfies a condition. The enumeration of source is stopped as soon as the result can be determined.

Parameters

callable|null $predicate

{(v, k) ==> result} A function to test each element for a condition. Default: null.

Returns

boolean —

If predicate is null: true if the source sequence contains any elements; otherwise, false. If predicate is not null: true if any elements in the source sequence pass the test in the specified predicate; otherwise, false.

append()

append(mixed  $value, mixed  $key = null) : \YaLinqo\Enumerable

Appends a value to the end of the sequence.

Syntax: append (other, value)

Appends a value to the end of the sequence with null key.

Syntax: append (other, value, key)

Appends a value to the end of the sequence with the specified key.

Parameters

mixed $value

The value to append.

mixed $key

The key of the value to append.

Returns

\YaLinqo\Enumerable

A new sequence that ends with the value.

concat()

concat(array|\Iterator|\IteratorAggregate|\YaLinqo\Enumerable  $other) : \YaLinqo\Enumerable

Concatenates two sequences.

This method differs from the \union method because the concat method returns all the original elements in the input sequences. The union method returns only unique elements.

Syntax: concat (other)

Parameters

array|\Iterator|\IteratorAggregate|\YaLinqo\Enumerable $other

The sequence to concatenate to the source sequence.

Returns

\YaLinqo\Enumerable

A sequence that contains the concatenated elements of the two input sequences.

contains()

contains(  $value) : boolean

Determines whether a sequence contains a specified element.

Syntax: contains (value)

Determines whether a sequence contains a specified element. Enumeration is terminated as soon as a matching element is found.

Parameters

$value

mixed The value to locate in the sequence.

Returns

boolean —

true if the source sequence contains an element that has the specified value; otherwise, false.

distinct()

distinct(callable|null  $keySelector = null) : \YaLinqo\Enumerable

Returns distinct elements from a sequence.

Element keys are values identifying elements. They are used as array keys and are subject to the same rules as array keys, for example, integer 100 and string "100" are considered equal.

Syntax: distinct ()

Returns distinct elements from a sequence using values as element keys.

Syntax: distinct (keySelector {(v, k) ==> value})

Returns distinct elements from a sequence using values produced by keySelector as element keys.

Parameters

callable|null $keySelector

{(v, k) ==> value} A function to extract the element key from each element. Default: value.

Returns

\YaLinqo\Enumerable

A sequence that contains distinct elements of the input sequence.

except()

except(array|\Iterator|\IteratorAggregate|\YaLinqo\Enumerable  $other, callable|null  $keySelector = null) : \YaLinqo\Enumerable

Produces the set difference of two sequences. The set difference of two sets is defined as the members of the first set that do not appear in the second set.

Element keys are values identifying elements. They are used as array keys and are subject to the same rules as array keys, for example, integer 100 and string "100" are considered equal.

Syntax: distinct (other)

Produces the set difference of two sequences using values as element keys.

Syntax: distinct (other, keySelector {(v, k) ==> value})

Produces the set difference of two sequences using values produced by keySelector as element keys.

Parameters

array|\Iterator|\IteratorAggregate|\YaLinqo\Enumerable $other

A sequence whose elements that also occur in the source sequence will cause those elements to be removed from the returned sequence.

callable|null $keySelector

{(v, k) ==> key} A function to extract the element key from each element. Default: value.

Returns

\YaLinqo\Enumerable

A sequence that contains the set difference of the elements of two sequences.

intersect()

intersect(array|\Iterator|\IteratorAggregate|\YaLinqo\Enumerable  $other, callable|null  $keySelector = null) : \YaLinqo\Enumerable

Produces the set intersection of two sequences. The intersection of two sets is defined as the set that contains all the elements of the first set that also appear in the second set, but no other elements.

Element keys are values identifying elements. They are used as array keys and are subject to the same rules as array keys, for example, integer 100 and string "100" are considered equal.

Syntax: intersect (other)

Produces the set intersection of two sequences using values as element keys.

Syntax: intersect (other, keySelector {(v, k) ==> value})

Produces the set intersection of two sequences using values produced by keySelector as element keys.

Parameters

array|\Iterator|\IteratorAggregate|\YaLinqo\Enumerable $other

A sequence whose distinct elements that also appear in the first sequence will be returned.

callable|null $keySelector

{(v, k) ==> key} A function to extract the element key from each element. Default: value.

Returns

\YaLinqo\Enumerable

A sequence that contains the elements that form the set intersection of two sequences.

prepend()

prepend(mixed  $value, mixed  $key = null) : \YaLinqo\Enumerable

Adds a value to the beginning of the sequence.

Syntax: prepend (other, value)

Adds a value to the beginning of the sequence with null key.

Syntax: prepend (other, value, key)

Adds a value to the beginning of the sequence with the specified key.

Parameters

mixed $value

The value to prepend.

mixed $key

The key of the value to prepend.

Returns

\YaLinqo\Enumerable

A new sequence that begins with the value.

union()

union(array|\Iterator|\IteratorAggregate|\YaLinqo\Enumerable  $other, callable|null  $keySelector = null) : \YaLinqo\Enumerable

Produces the set union of two sequences.

Element keys are values identifying elements. They are used as array keys and are subject to the same rules as array keys, for example, integer 100 and string "100" are considered equal.

This method excludes duplicates from the return set. This is different behavior to the \concat method, which returns all the elements in the input sequences including duplicates.

Syntax: union (other)

Produces the set union of two sequences using values as element keys.

Syntax: union (other, keySelector {(v, k) ==> value})

Produces the set union of two sequences using values produced by keySelector as element keys.

Parameters

array|\Iterator|\IteratorAggregate|\YaLinqo\Enumerable $other

A sequence whose distinct elements form the second set for the union.

callable|null $keySelector

{(v, k) ==> key} A function to extract the element key from each element. Default: value.

Returns

\YaLinqo\Enumerable

A sequence that contains the elements from both input sequences, excluding duplicates.

toArray()

toArray() : array

Creates an array from a sequence.

Syntax: toArray ()

The toArray method forces immediate query evaluation and returns an array that contains the query results.

The toArray method does not traverse into elements of the sequence, only the sequence itself is converted. That is, if elements of the sequence are \Traversable or arrays containing Traversable values, they will remain as is. To traverse deeply, you can use \toArrayDeep method.

Keys from the sequence are preserved. If the source sequence contains multiple values with the same key, the result array will only contain the latter value. To discard keys, you can use \toList method. To preserve all values and keys, you can use \toLookup method.

Returns

array —

An array that contains the elements from the input sequence.

toArrayDeep()

toArrayDeep() : array

Creates an array from a sequence, traversing deeply.

Syntax: toArrayDeep ()

The toArrayDeep method forces immediate query evaluation and returns an array that contains the query results.

The toArrayDeep method traverses into elements of the sequence. That is, if elements of the sequence are \Traversable or arrays containing Traversable values, they will be converted to arrays too. To convert only the sequence itself, you can use \toArray method.

Keys from the sequence are preserved. If the source sequence contains multiple values with the same key, the result array will only contain the latter value. To discard keys, you can use \toListDeep method. To preserve all values and keys, you can use \toLookup method.

Returns

array —

An array that contains the elements from the input sequence.

toList()

toList() : array

Creates an array from a sequence, with sequental integer keys.

Syntax: toList ()

The toList method forces immediate query evaluation and returns an array that contains the query results.

The toList method does not traverse into elements of the sequence, only the sequence itself is converted. That is, if elements of the sequence are \Traversable or arrays containing Traversable values, they will remain as is. To traverse deeply, you can use \toListDeep method.

Keys from the sequence are discarded. To preserve keys and lose values with the same keys, you can use \toArray method. To preserve all values and keys, you can use \toLookup method.

Returns

array —

An array that contains the elements from the input sequence.

toListDeep()

toListDeep() : array

Creates an array from a sequence, with sequental integer keys.

Syntax: toListDeep ()

The toListDeep method forces immediate query evaluation and returns an array that contains the query results.

The toListDeep method traverses into elements of the sequence. That is, if elements of the sequence are \Traversable or arrays containing Traversable values, they will be converted to arrays too. To convert only the sequence itself, you can use \toList method.

Keys from the sequence are discarded. To preserve keys and lose values with the same keys, you can use \toArrayDeep method. To preserve all values and keys, you can use \toLookup method.

Returns

array —

An array that contains the elements from the input sequence.

toDictionary()

toDictionary(callable|null  $keySelector = null, callable|null  $valueSelector = null) : array

Creates an array from a sequence according to specified key selector and value selector functions.

Syntax: toDictionary ([keySelector {(v, k) ==> key} [, valueSelector {(v, k) ==> value}]])

The toDictionary method returns an array, a one-to-one dictionary that maps keys to values. If the source sequence contains multiple values with the same key, the result array will only contain the latter value.

Parameters

callable|null $keySelector

{(v, k) ==> key} A function to extract a key from each element. Default: key.

callable|null $valueSelector

{(v, k) ==> value} A transform function to produce a result value from each element. Default: value.

Returns

array —

An array that contains keys and values selected from the input sequence.

toJSON()

toJSON(integer  $options) : string

Returns a string containing the JSON representation of sequence (converted to array).

Syntax: toJSON ([options])

This function only works with UTF-8 encoded data.

Parameters

integer $options

Bitmask consisting of JSON_HEX_QUOT, JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS, JSON_NUMERIC_CHECK, JSON_PRETTY_PRINT, JSON_UNESCAPED_SLASHES, JSON_FORCE_OBJECT, JSON_UNESCAPED_UNICODE. Default: 0.

Returns

string —

A JSON encoded string on success or false on failure.

toLookup()

toLookup(callable|null  $keySelector = null, callable|null  $valueSelector = null) : array

Creates an array from a sequence according to specified key selector and value selector functions.

Syntax: toLookup ([keySelector {(v, k) ==> key} [, valueSelector {(v, k) ==> value}]])

The toLookup method returns an array, a one-to-many dictionary that maps keys to arrays of values.

Parameters

callable|null $keySelector

{(v, k) ==> key} A function to extract a key from each element. Default: key.

callable|null $valueSelector

{(v, k) ==> value} A transform function to produce a result value from each element. Default: value.

Returns

array —

An array that contains keys and value arrays selected from the input sequence.

toKeys()

toKeys() : \YaLinqo\Enumerable

Returns a sequence of keys from the source sequence.

Syntax: toKeys ()

Returns

\YaLinqo\Enumerable

A sequence with keys from the source sequence as values and sequental integers as keys.

toValues()

toValues() : \YaLinqo\Enumerable

Returns a sequence of values from the source sequence; keys are discarded.

Syntax: toValues ()

Returns

\YaLinqo\Enumerable

A sequence with the same values and sequental integers as keys.

toObject()

toObject(callable|null  $propertySelector = null, callable|null  $valueSelector = null) : \stdClass

Transform the sequence to an object.

Syntax: toObject ([propertySelector {(v, k) ==> name} [, valueSelector {(v, k) ==> value}]])

Parameters

callable|null $propertySelector

{(v, k) ==> name} A function to extract a property name from an element. Must return a valid PHP identifier. Default: key.

callable|null $valueSelector

{(v, k) ==> value} A function to extract a property value from an element. Default: value.

Returns

\stdClass

toString()

toString(string  $separator = '', callable|null  $valueSelector = null) : string

Returns a string containing a string representation of all the sequence values, with the separator string between each element.

Syntax: toString ([separator [, selector]])

Parameters

string $separator

A string separating values in the result string. Default: ''.

callable|null $valueSelector

{(v, k) ==> value} A transform function to apply to each element. Default: value.

Returns

string

call()

call(callable  $action) : \YaLinqo\Enumerable

Invokes an action for each element in the sequence.

Syntax: process (action {(v, k) ==> void})

Process method does not start enumeration itself. To force enumeration, you can use \each method.

Original LINQ method name: do.

Parameters

callable $action

{(v, k) ==> void} The action to invoke for each element in the sequence.

Returns

\YaLinqo\Enumerable

The source sequence with the side-effecting behavior applied.

each()

each(callable  $action = null) 

Invokes an action for each element in the sequence.

Syntax: each (action {(v, k) ==> void})

Each method forces enumeration. To just add side-effect without enumerating, you can use \process method.

Original LINQ method name: foreach.

Parameters

callable $action

{(v, k) ==> void} The action to invoke for each element in the sequence.

write()

write(string  $separator = '', callable|null  $selector = null) 

Output the result of calling {@link toString} method.

Syntax: write ([separator [, selector]])

Parameters

string $separator

A string separating values in the result string. Default: ''.

callable|null $selector

{(v, k) ==> value} A transform function to apply to each element. Default: value.

writeLine()

writeLine(callable|null  $selector = null) : string

Output all the sequence values, with a new line after each element.

Syntax: writeLine ([selector])

Parameters

callable|null $selector

{(v, k) ==> value} A transform function to apply to each element. Default: value.

Returns

string

cycle()

cycle(array|\Iterator|\IteratorAggregate|\YaLinqo\Enumerable  $source) : \YaLinqo\Enumerable

Cycles through the source sequence.

Syntax: cycle (source)

Source keys are discarded.

Parameters

array|\Iterator|\IteratorAggregate|\YaLinqo\Enumerable $source

Source sequence.

Throws

\InvalidArgumentException

If source is not array or Traversible or Enumerable.

\UnexpectedValueException

If source contains no elements (checked during enumeration).

Returns

\YaLinqo\Enumerable

Endless list of items repeating the source sequence.

emptyEnum()

emptyEnum() : \YaLinqo\Enumerable

Returns an empty sequence.

Syntax: emptyEnum ()

Returns

\YaLinqo\Enumerable

from()

from(array|\Iterator|\IteratorAggregate|\Traversable|\YaLinqo\Enumerable  $source) : \YaLinqo\Enumerable

Converts source into Enumerable sequence.

Syntax: from (source)

Result depends on the type of source:

  • array: Enumerable from ArrayIterator;
  • Enumerable: Enumerable source itself;
  • Iterator: Enumerable from Iterator;
  • IteratorAggregate: Enumerable from Iterator returned from getIterator() method;
  • Traversable: Enumerable from the result of foreach over source.

Parameters

array|\Iterator|\IteratorAggregate|\Traversable|\YaLinqo\Enumerable $source

Value to convert into Enumerable sequence.

Throws

\InvalidArgumentException

If source is not array or Traversible or Enumerable.

Returns

\YaLinqo\Enumerable

generate()

generate(callable  $funcValue, mixed  $seedValue = null, callable|null  $funcKey = null, mixed  $seedKey = null) : \YaLinqo\Enumerable

Generates a sequence by mimicking a for loop.

Syntax: generate (funcValue {(v, k) ==> value} [, seedValue [, funcKey {(v, k) ==> key} [, seedKey]]])

If seedValue is null, the first value will be the result of calling funcValue on seedValue and seedKey. The same applies for seedKey.

Parameters

callable $funcValue

{(v, k) ==> value} State update function to run on value after every iteration of the generator loop. Default: value.

mixed $seedValue

Initial state of the generator loop for values. Default: null.

callable|null $funcKey

{(v, k) ==> key} State update function to run on key after every iteration of the generator loop. Default: increment.

mixed $seedKey

Initial state of the generator loop ofr keys. Default: 0.

Returns

\YaLinqo\Enumerable

toInfinity()

toInfinity(integer  $start, integer  $step = 1) : \YaLinqo\Enumerable

Generates a sequence of integral numbers to infinity.

Syntax: toInfinity ([start [, step]])

Parameters

integer $start

The first integer in the sequence. Default: 0.

integer $step

The difference between adjacent integers. Default: 1.

Returns

\YaLinqo\Enumerable

matches()

matches(string  $subject, string  $pattern, integer  $flags = PREG_SET_ORDER) : \YaLinqo\Enumerable

Searches subject for all matches to the regular expression given in pattern and enumerates them in the order specified by flags. After the first match is found, the subsequent searches are continued on from end of the last match.

Syntax: matches (subject, pattern [, flags])

Parameters

string $subject

The input string.

string $pattern

The pattern to search for, as a string.

integer $flags

Can be a combination of the following flags: PREG_PATTERN_ORDER, PREG_SET_ORDER, PREG_OFFSET_CAPTURE. Default: PREG_SET_ORDER.

Returns

\YaLinqo\Enumerable

toNegativeInfinity()

toNegativeInfinity(integer  $start, integer  $step = 1) : \YaLinqo\Enumerable

Generates a sequence of integral numbers to negative infinity.

Syntax: toNegativeInfinity ([start [, step]])

Parameters

integer $start

The first integer in the sequence. Default: 0.

integer $step

The difference between adjacent integers. Default: 1.

Returns

\YaLinqo\Enumerable

returnEnum()

returnEnum(mixed  $element) : \YaLinqo\Enumerable

Returns a sequence that contains a single element with a specified value.

Syntax: returnEnum (element)

Parameters

mixed $element

The single element in the resulting sequence.

Returns

\YaLinqo\Enumerable

Observable sequence containing the single specified element.

range()

range(integer  $start, integer  $count, integer  $step = 1) : \YaLinqo\Enumerable

Generates a sequence of integral numbers, beginning with start and containing count elements.

Syntax: range (start, count [, step])

Keys in the generated sequence are sequental: 0, 1, 2 etc.

Example: range(3, 4, 2) = 3, 5, 7, 9.

Parameters

integer $start

The value of the first integer in the sequence.

integer $count

The number of integers to generate.

integer $step

The difference between adjacent integers. Default: 1.

Returns

\YaLinqo\Enumerable

A sequence that contains a range of integral numbers.

rangeDown()

rangeDown(integer  $start, integer  $count, integer  $step = 1) : \YaLinqo\Enumerable

Generates a reversed sequence of integral numbers, beginning with start and containing count elements.

Syntax: rangeDown (start, count [, step])

Keys in the generated sequence are sequental: 0, 1, 2 etc.

Example: rangeDown(9, 4, 2) = 9, 7, 5, 3.

Parameters

integer $start

The value of the first integer in the sequence.

integer $count

The number of integers to generate.

integer $step

The difference between adjacent integers. Default: 1.

Returns

\YaLinqo\Enumerable

A sequence that contains a range of integral numbers.

rangeTo()

rangeTo(integer  $start, integer  $end, integer  $step = 1) : \YaLinqo\Enumerable

Generates a sequence of integral numbers within a specified range from start to end.

Syntax: rangeTo (start, end [, step])

Keys in the generated sequence are sequental: 0, 1, 2 etc.

Example: rangeTo(3, 9, 2) = 3, 5, 7, 9.

Parameters

integer $start

The value of the first integer in the sequence.

integer $end

The value of the last integer in the sequence (not included).

integer $step

The difference between adjacent integers. Default: 1.

Throws

\InvalidArgumentException

If step is not a positive number.

Returns

\YaLinqo\Enumerable

A sequence that contains a range of integral numbers.

repeat()

repeat(integer  $element, integer  $count = null) : \YaLinqo\Enumerable

Generates an sequence that contains one repeated value.

Syntax: repeat (element)

Generates an endless sequence that contains one repeated value.

Syntax: repeat (element, count)

Generates a sequence of specified length that contains one repeated value.

Keys in the generated sequence are sequental: 0, 1, 2 etc.

Parameters

integer $element

The value to be repeated.

integer $count

The number of times to repeat the value in the generated sequence. Default: null.

Throws

\InvalidArgumentException

If count is less than 0.

Returns

\YaLinqo\Enumerable

A sequence that contains a repeated value.

split()

split(string  $subject, string  $pattern, integer  $flags) : \YaLinqo\Enumerable

Split the given string by a regular expression.

Syntax: split (subject, pattern [, flags])

Parameters

string $subject

The input string.

string $pattern

The pattern to search for, as a string.

integer $flags

flags can be any combination of the following flags: PREG_SPLIT_NO_EMPTY, PREG_SPLIT_DELIM_CAPTURE, PREG_SPLIT_OFFSET_CAPTURE. Default: 0.

Returns

\YaLinqo\Enumerable

elementAt()

elementAt(mixed  $key) : mixed

Returns the value at a specified key in a sequence.

Syntax: elementAt (key)

Returns the value at a specified key in a sequence.

If the type of source iterator implements \ArrayAccess, that implementation is used to obtain the value at the specified key. Otherwise, this method obtains the specified value.

This method throws an exception if key is not found. To instead return a default value when the specified key is not found, use the \elementAtOrDefault method.

Parameters

mixed $key

The key of the value to retrieve.

Throws

\UnexpectedValueException

If sequence does not contain value with specified key.

Returns

mixed —

The value at the key in the source sequence.

elementAtOrDefault()

elementAtOrDefault(mixed  $key, mixed  $default = null) : mixed

Returns the value at a specified key in a sequence or a default value if the key is not found.

Syntax: elementAtOrDefault (key [, default])

If the type of source iterator implements \ArrayAccess, that implementation is used to obtain the value at the specified key. Otherwise, this method obtains the specified value.

Parameters

mixed $key

The key of the value to retrieve.

mixed $default

Value to return if sequence does not contain value with specified key. Default: null.

Returns

mixed —

default value if the key is not found in the source sequence; otherwise, the value at the specified key in the source sequence.

first()

first(callable|null  $predicate = null) : mixed

Returns the first element of a sequence.

Syntax: first ()

Returns the first element of a sequence.

The first method throws an exception if source contains no elements. To instead return a default value when the source sequence is empty, use the \firstOrDefault method.

Syntax: first (predicate {(v, k) ==> result})

Returns the first element in a sequence that satisfies a specified condition.

The first method throws an exception if no matching element is found in source. To instead return a default value when no matching element is found, use the \firstOrDefault method.

Parameters

callable|null $predicate

{(v, k) ==> result} A function to test each element for a condition. Default: true.

Throws

\UnexpectedValueException

If source contains no matching elements.

Returns

mixed —

If predicate is null: the first element in the specified sequence. If predicate is not null: The first element in the sequence that passes the test in the specified predicate function.

firstOrDefault()

firstOrDefault(mixed  $default = null, callable|null  $predicate = null) : mixed

Returns the first element of a sequence, or a default value if the sequence contains no elements.

Syntax: firstOrDefault ([default])

Returns the first element of a sequence, or a default value if the sequence contains no elements.

Syntax: firstOrDefault ([default [, predicate {(v, k) ==> result}]])

Returns the first element of the sequence that satisfies a condition or a default value if no such element is found.

If obtaining the default value is a costly operation, use \firstOrFallback method to avoid overhead.

Parameters

mixed $default

A default value.

callable|null $predicate

{(v, k) ==> result} A function to test each element for a condition. Default: true.

Returns

mixed —

If predicate is null: default value if source is empty; otherwise, the first element in source. If predicate is not null: default value if source is empty or if no element passes the test specified by predicate; otherwise, the first element in source that passes the test specified by predicate.

firstOrFallback()

firstOrFallback(callable  $fallback, callable|null  $predicate = null) : mixed

Returns the first element of a sequence, or the result of calling a fallback function if the sequence contains no elements.

Syntax: firstOrFallback ([fallback {() ==> value}])

Returns the first element of a sequence, or the result of calling a fallback function if the sequence contains no elements.

Syntax: firstOrFallback ([fallback {() ==> value} [, predicate {(v, k) ==> result}]])

Returns the first element of the sequence that satisfies a condition or the result of calling a fallback function if no such element is found.

The fallback function is not executed if a matching element is found. Use the firstOrFallback method if obtaining the default value is a costly operation to avoid overhead. Otherwise, use \firstOrDefault.

Parameters

callable $fallback

{() ==> value} A fallback function to return the default element.

callable|null $predicate

{(v, k) ==> result} A function to test each element for a condition. Default: true.

Returns

mixed —

If predicate is null: the result of calling a fallback function if source is empty; otherwise, the first element in source. If predicate is not null: the result of calling a fallback function if source is empty or if no element passes the test specified by predicate; otherwise, the first element in source that passes the test specified by predicate.

last()

last(callable|null  $predicate = null) : mixed

Returns the last element of a sequence.

Syntax: last ()

Returns the last element of a sequence.

The last method throws an exception if source contains no elements. To instead return a default value when the source sequence is empty, use the \lastOrDefault method.

Syntax: last (predicate {(v, k) ==> result})

Returns the last element in a sequence that satisfies a specified condition.

The last method throws an exception if no matching element is found in source. To instead return a default value when no matching element is found, use the \lastOrDefault method.

Parameters

callable|null $predicate

{(v, k) ==> result} A function to test each element for a condition. Default: true.

Throws

\UnexpectedValueException

If source contains no matching elements.

Returns

mixed —

If predicate is null: the last element in the specified sequence. If predicate is not null: The last element in the sequence that passes the test in the specified predicate function.

lastOrDefault()

lastOrDefault(mixed  $default = null, callable|null  $predicate = null) : mixed

Returns the last element of a sequence, or a default value if the sequence contains no elements.

Syntax: lastOrDefault ([default])

Returns the last element of a sequence, or a default value if the sequence contains no elements.

Syntax: lastOrDefault ([default [, predicate {(v, k) ==> result}]])

Returns the last element of the sequence that satisfies a condition or a default value if no such element is found.

If obtaining the default value is a costly operation, use \lastOrFallback method to avoid overhead.

Parameters

mixed $default

A default value.

callable|null $predicate

{(v, k) ==> result} A function to test each element for a condition. Default: true.

Returns

mixed —

If predicate is null: default value if source is empty; otherwise, the last element in source. If predicate is not null: default value if source is empty or if no element passes the test specified by predicate; otherwise, the last element in source that passes the test specified by predicate.

lastOrFallback()

lastOrFallback(callable  $fallback, callable|null  $predicate = null) : mixed

Returns the last element of a sequence, or the result of calling a fallback function if the sequence contains no elements.

Syntax: lastOrFallback ([fallback {() ==> value}])

Returns the last element of a sequence, or the result of calling a fallback function if the sequence contains no elements.

Syntax: lastOrFallback ([fallback {() ==> value} [, predicate {(v, k) ==> result}]])

Returns the last element of the sequence that satisfies a condition or the result of calling a fallback function if no such element is found.

The fallback function is not executed if a matching element is found. Use the lastOrFallback method if obtaining the default value is a costly operation to avoid overhead. Otherwise, use \lastOrDefault.

Parameters

callable $fallback

{() ==> value} A fallback function to return the default element.

callable|null $predicate

{(v, k) ==> result} A function to test each element for a condition. Default: true.

Returns

mixed —

If predicate is null: the result of calling a fallback function if source is empty; otherwise, the last element in source. If predicate is not null: the result of calling a fallback function if source is empty or if no element passes the test specified by predicate; otherwise, the last element in source that passes the test specified by predicate.

single()

single(callable|null  $predicate = null) : mixed

Returns the only element of a sequence, and throws an exception if there is not exactly one element in the sequence.

Syntax: single ()

Returns the only element of a sequence, and throws an exception if there is not exactly one element in the sequence.

The single method throws an exception if source contains no elements. To instead return a default value when the source sequence is empty, use the \singleOrDefault method.

Syntax: single (predicate {(v, k) ==> result})

Returns the only element of a sequence that satisfies a specified condition.

The single method throws an exception if no matching element is found in source. To instead return a default value when no matching element is found, use the \singleOrDefault method.

Parameters

callable|null $predicate

{(v, k) ==> result} A function to test each element for a condition. Default: true.

Throws

\UnexpectedValueException

If source contains no matching elements or more than one matching element.

Returns

mixed —

If predicate is null: the single element of the input sequence. If predicate is not null: The single element of the sequence that passes the test in the specified predicate function.

singleOrDefault()

singleOrDefault(mixed  $default = null, callable|null  $predicate = null) : mixed

Returns the only element of a sequence, or a default value if the sequence contains no elements.

Syntax: singleOrDefault ([default])

Returns the only element of a sequence, or a default value if the sequence contains no elements.

Syntax: singleOrDefault ([default [, predicate {(v, k) ==> result}]])

Returns the only element of the sequence that satisfies a condition or a default value if no such element is found.

If obtaining the default value is a costly operation, use \singleOrFallback method to avoid overhead.

Parameters

mixed $default

A default value.

callable|null $predicate

{(v, k) ==> result} A function to test each element for a condition. Default: true.

Throws

\UnexpectedValueException

If source contains more than one matching element.

Returns

mixed —

If predicate is null: default value if source is empty; otherwise, the single element of the source. If predicate is not null: default value if source is empty or if no element passes the test specified by predicate; otherwise, the single element of the source that passes the test specified by predicate.

singleOrFallback()

singleOrFallback(callable  $fallback, callable|null  $predicate = null) : mixed

Returns the only element of a sequence, or the result of calling a fallback function if the sequence contains no elements.

Syntax: singleOrFallback ([fallback {() ==> value}])

Returns the only element of a sequence, or the result of calling a fallback function if the sequence contains no elements.

Syntax: singleOrFallback ([fallback {() ==> value} [, predicate {(v, k) ==> result}]])

Returns the only element of the sequence that satisfies a condition or the result of calling a fallback function if no such element is found.

The fallback function is not executed if a matching element is found. Use the singleOrFallback method if obtaining the default value is a costly operation to avoid overhead. Otherwise, use \singleOrDefault.

Parameters

callable $fallback

{() ==> value} A fallback function to return the default element.

callable|null $predicate

{(v, k) ==> result} A function to test each element for a condition. Default: true.

Throws

\UnexpectedValueException

If source contains more than one matching element.

Returns

mixed —

If predicate is null: the result of calling a fallback function if source is empty; otherwise, the single element of the source. If predicate is not null: the result of calling a fallback function if source is empty or if no element passes the test specified by predicate; otherwise, the single element of the source that passes the test specified by predicate.

indexOf()

indexOf(mixed  $value) : mixed

Searches for the specified value and returns the key of the first occurrence.

Syntax: indexOf (value)

To search for the zero-based index of the first occurence, call \toValues method first.

Parameters

mixed $value

The value to locate in the sequence.

Returns

mixed —

The key of the first occurrence of value, if found; otherwise, null.

lastIndexOf()

lastIndexOf(mixed  $value) : mixed

Searches for the specified value and returns the key of the last occurrence.

Syntax: lastIndexOf (value)

To search for the zero-based index of the last occurence, call \toValues method first.

Parameters

mixed $value

The value to locate in the sequence.

Returns

mixed —

The key of the last occurrence of value, if found; otherwise, null.

findIndex()

findIndex(callable  $predicate) : mixed

Searches for an element that matches the conditions defined by the specified predicate, and returns the key of the first occurrence.

Syntax: findIndex (predicate {(v, k) ==> result})

To search for the zero-based index of the first occurence, call \toValues method first.

Parameters

callable $predicate

{(v, k) ==> result} A function that defines the conditions of the element to search for.

Returns

mixed —

The key of the first occurrence of an element that matches the conditions defined by predicate, if found; otherwise, null.

findLastIndex()

findLastIndex(callable  $predicate) : mixed

Searches for an element that matches the conditions defined by the specified predicate, and returns the key of the last occurrence.

Syntax: findLastIndex (predicate {(v, k) ==> result})

To search for the zero-based index of the last occurence, call \toValues method first.

Parameters

callable $predicate

{(v, k) ==> result} A function that defines the conditions of the element to search for.

Returns

mixed —

The key of the last occurrence of an element that matches the conditions defined by predicate, if found; otherwise, null.

skip()

skip(integer  $count) : \YaLinqo\Enumerable

Bypasses a specified number of elements in a sequence and then returns the remaining elements.

Syntax: skip (count)

If source contains fewer than count elements, an empty sequence is returned. If count is less than or equal to zero, all elements of source are yielded.

The \take and skip methods are functional complements. Given a sequence coll and an integer n, concatenating the results of coll->take(n) and coll->skip(n) yields the same sequence as coll.

Parameters

integer $count

The number of elements to skip before returning the remaining elements.

Returns

\YaLinqo\Enumerable

A sequence that contains the elements that occur after the specified index in the input sequence.

skipWhile()

skipWhile(callable  $predicate) : \YaLinqo\Enumerable

Bypasses elements in a sequence as long as a specified condition is true and then returns the remaining elements.

Syntax: skipWhile (predicate {(v, k) ==> result})

This method tests each element of source by using predicate and skips the element if the result is true. After the predicate function returns false for an element, that element and the remaining elements in source are yielded and there are no more invocations of predicate. If predicate returns true for all elements in the sequence, an empty sequence is returned.

The \takeWhile and skipWhile methods are functional complements. Given a sequence coll and a pure function p, concatenating the results of coll->takeWhile(p) and coll->skipWhile(p) yields the same sequence as coll.

Parameters

callable $predicate

{(v, k) ==> result} A function to test each element for a condition.

Returns

\YaLinqo\Enumerable

A sequence that contains the elements from the input sequence starting at the first element in the linear series that does not pass the test specified by predicate.

take()

take(integer  $count) : \YaLinqo\Enumerable

Returns a specified number of contiguous elements from the start of a sequence.

Syntax: take (count)

Take enumerates source and yields elements until count elements have been yielded or source contains no more elements. If count is less than or equal to zero, source is not enumerated and an empty sequence is returned.

The take and \skip methods are functional complements. Given a sequence coll and an integer n, concatenating the results of coll->take(n) and coll->skip(n) yields the same sequence as coll.

Parameters

integer $count

The number of elements to return.

Returns

\YaLinqo\Enumerable

A sequence that contains the specified number of elements from the start of the input sequence.

takeWhile()

takeWhile(callable  $predicate) : \YaLinqo\Enumerable

Returns elements from a sequence as long as a specified condition is true.

Syntax: takeWhile (predicate {(v, k) ==> result})

The takeWhile method tests each element of source by using predicate and yields the element if the result is true. Enumeration stops when the predicate function returns false for an element or when source contains no more elements.

The takeWhile and \skipWhile methods are functional complements. Given a sequence coll and a pure function p, concatenating the results of coll->takeWhile(p) and coll->skipWhile(p) yields the same sequence as coll.

Parameters

callable $predicate

{(v, k) ==> result} A function to test each element for a condition.

Returns

\YaLinqo\Enumerable

A sequence that contains the elements from the input sequence that occur before the element at which the test no longer passes.

thenByDir()

thenByDir(integer|boolean  $sortOrder, callable|null  $keySelector = null, callable|integer|null  $comparer = null) : \YaLinqo\OrderedEnumerable

<p><b>Syntax</b>: thenByDir (false|true [, {{(v, k) ==> key} [, {{(a, b) ==> diff}]]) <p>Performs a subsequent ordering of elements in a sequence in a particular direction (ascending, descending) according to a key.

Three methods are defined to extend the type OrderedEnumerable, which is the return type of this method. These three methods, namely \thenBy, \thenByDescending and \thenByDir, enable you to specify additional sort criteria to sort a sequence. These methods also return an OrderedEnumerable, which means any number of consecutive calls to thenBy, thenByDescending or thenByDir can be made.

Because OrderedEnumerable inherits from \Enumerable, you can call \Enumerable::orderBy, \Enumerable::orderByDescending or \Enumerable::orderByDir on the results of a call to orderBy, orderByDescending, orderByDir, thenBy, thenByDescending or thenByDir. Doing this introduces a new primary ordering that ignores the previously established ordering.

This method performs an unstable sort; that is, if the keys of two elements are equal, the order of the elements is not preserved. In contrast, a stable sort preserves the order of elements that have the same key. Internally, \usort is used.

Parameters

integer|boolean $sortOrder

A direction in which to order the elements: false or SORT_DESC for ascending (by increasing value), true or SORT_ASC for descending (by decreasing value).

callable|null $keySelector

{(v, k) ==> key} A function to extract a key from an element. Default: value.

callable|integer|null $comparer

{(a, b) ==> diff} Difference between a and b: <0 if a<b; 0 if a==b; >0 if a>b. Can also be a combination of SORT_ flags.

Returns

\YaLinqo\OrderedEnumerable

thenBy()

thenBy(callable|null  $keySelector = null, callable|integer|null  $comparer = null) : \YaLinqo\OrderedEnumerable

<p><b>Syntax</b>: thenBy ([{{(v, k) ==> key} [, {{(a, b) ==> diff}]]) <p>Performs a subsequent ordering of the elements in a sequence in ascending order according to a key.

Three methods are defined to extend the type OrderedEnumerable, which is the return type of this method. These three methods, namely \thenBy, \thenByDescending and \thenByDir, enable you to specify additional sort criteria to sort a sequence. These methods also return an OrderedEnumerable, which means any number of consecutive calls to thenBy, thenByDescending or thenByDir can be made.

Because OrderedEnumerable inherits from \Enumerable, you can call \Enumerable::orderBy, \Enumerable::orderByDescending or \Enumerable::orderByDir on the results of a call to orderBy, orderByDescending, orderByDir, thenBy, thenByDescending or thenByDir. Doing this introduces a new primary ordering that ignores the previously established ordering.

This method performs an unstable sort; that is, if the keys of two elements are equal, the order of the elements is not preserved. In contrast, a stable sort preserves the order of elements that have the same key. Internally, \usort is used.

Parameters

callable|null $keySelector

{(v, k) ==> key} A function to extract a key from an element. Default: value.

callable|integer|null $comparer

{(a, b) ==> diff} Difference between a and b: <0 if a<b; 0 if a==b; >0 if a>b. Can also be a combination of SORT_ flags.

Returns

\YaLinqo\OrderedEnumerable

thenByDescending()

thenByDescending(callable|null  $keySelector = null, callable|integer|null  $comparer = null) : \YaLinqo\OrderedEnumerable

<p><b>Syntax</b>: thenByDescending ([{{(v, k) ==> key} [, {{(a, b) ==> diff}]]) <p>Performs a subsequent ordering of the elements in a sequence in descending order according to a key.

Three methods are defined to extend the type OrderedEnumerable, which is the return type of this method. These three methods, namely \thenBy, \thenByDescending and \thenByDir, enable you to specify additional sort criteria to sort a sequence. These methods also return an OrderedEnumerable, which means any number of consecutive calls to thenBy, thenByDescending or thenByDir can be made.

Because OrderedEnumerable inherits from \Enumerable, you can call \Enumerable::orderBy, \Enumerable::orderByDescending or \Enumerable::orderByDir on the results of a call to orderBy, orderByDescending, orderByDir, thenBy, thenByDescending or thenByDir. Doing this introduces a new primary ordering that ignores the previously established ordering.

This method performs an unstable sort; that is, if the keys of two elements are equal, the order of the elements is not preserved. In contrast, a stable sort preserves the order of elements that have the same key. Internally, \usort is used.

Parameters

callable|null $keySelector

{(v, k) ==> key} A function to extract a key from an element. Default: value.

callable|integer|null $comparer

{(a, b) ==> diff} Difference between a and b: <0 if a<b; 0 if a==b; >0 if a>b. Can also be a combination of SORT_ flags.

Returns

\YaLinqo\OrderedEnumerable

tryGetArrayCopy()

tryGetArrayCopy() : array|null

If the sequence wraps an array directly, return it, otherwise return null.

Returns

array|null —

Wrapped array, null otherwise.

toArrayDeepProc()

toArrayDeepProc(  $enum) : array

Proc for {@link toArrayDeep}.

Parameters

$enum

\Traversable Source sequence.

Returns

array —

An array that contains the elements from the input sequence.

toListDeepProc()

toListDeepProc(  $enum) : array

Proc for {@link toListDeep}.

Parameters

$enum

\Traversable Source sequence.

Returns

array —

An array that contains the elements from the input sequence.