org.apache.calcite.linq4j.ExtendedEnumerable Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to you under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.calcite.linq4j;
import org.apache.calcite.linq4j.function.BigDecimalFunction1;
import org.apache.calcite.linq4j.function.DoubleFunction1;
import org.apache.calcite.linq4j.function.EqualityComparer;
import org.apache.calcite.linq4j.function.FloatFunction1;
import org.apache.calcite.linq4j.function.Function0;
import org.apache.calcite.linq4j.function.Function1;
import org.apache.calcite.linq4j.function.Function2;
import org.apache.calcite.linq4j.function.IntegerFunction1;
import org.apache.calcite.linq4j.function.LongFunction1;
import org.apache.calcite.linq4j.function.NullableBigDecimalFunction1;
import org.apache.calcite.linq4j.function.NullableDoubleFunction1;
import org.apache.calcite.linq4j.function.NullableFloatFunction1;
import org.apache.calcite.linq4j.function.NullableIntegerFunction1;
import org.apache.calcite.linq4j.function.NullableLongFunction1;
import org.apache.calcite.linq4j.function.Predicate1;
import org.apache.calcite.linq4j.function.Predicate2;
import org.checkerframework.checker.nullness.qual.Nullable;
import org.checkerframework.checker.nullness.qual.PolyNull;
import org.checkerframework.framework.qual.Covariant;
import java.math.BigDecimal;
import java.util.Collection;
import java.util.Comparator;
import java.util.List;
import java.util.Map;
/**
* Extension methods in {@link Enumerable}.
*
* @param Element type
*/
@Covariant(0)
public interface ExtendedEnumerable {
/**
* Performs an operation for each member of this enumeration.
*
* Returns the value returned by the function for the last element in
* this enumeration, or null if this enumeration is empty.
*
* @param func Operation
* @param Return type
*/
@Nullable R foreach(Function1 func);
/**
* Applies an accumulator function over a
* sequence.
*/
@Nullable TSource aggregate(Function2<@Nullable TSource, TSource, TSource> func);
/**
* Applies an accumulator function over a
* sequence. The specified seed value is used as the initial
* accumulator value.
*
* If {@code seed} is not null, the result is never null.
*/
@PolyNull TAccumulate aggregate(@PolyNull TAccumulate seed,
Function2<@PolyNull TAccumulate, TSource, @PolyNull TAccumulate> func);
/**
* Applies an accumulator function over a
* sequence. The specified seed value is used as the initial
* accumulator value, and the specified function is used to select
* the result value.
*/
TResult aggregate(TAccumulate seed,
Function2 func,
Function1 selector);
/**
* Determines whether all elements of a sequence
* satisfy a condition.
*/
boolean all(Predicate1 predicate);
/**
* Determines whether a sequence contains any
* elements. (Defined by Enumerable.)
*/
boolean any();
/**
* Determines whether any element of a sequence
* satisfies a condition.
*/
boolean any(Predicate1 predicate);
/**
* Returns the input typed as {@code Enumerable}.
*
* This method has no effect
* other than to change the compile-time type of source from a type that
* implements {@code Enumerable} to {@code Enumerable}
* itself.
*
* {@code asEnumerable(Enumerable)} can be used to choose
* between query implementations when a sequence implements
* {@code Enumerable} but also has a different set of public query
* methods available. For example, given a generic class Table that implements
* {@code Enumerable} and has its own methods such as {@code where},
* {@code select}, and {@code selectMany}, a call to {@code where} would
* invoke the public {@code where} method of {@code Table}. A {@code Table}
* type that represents a database table could have a {@code where} method
* that takes the predicate argument as an expression tree and converts the
* tree to SQL for remote execution. If remote execution is not desired, for
* example because the predicate invokes a local method, the
* {@code asEnumerable} method can be used to hide the custom methods
* and instead make the standard query operators available.
*/
Enumerable asEnumerable();
/**
* Converts an Enumerable to a {@link Queryable}.
*
* If the type of source implements {@code Queryable}, this method
* returns it directly. Otherwise, it returns a {@code Queryable} that
* executes queries by calling the equivalent query operator methods in
* {@code Enumerable} instead of those in {@code Queryable}.
*
*
Analogous to the LINQ's Enumerable.AsQueryable extension method.
*
* @return A queryable
*/
Queryable asQueryable();
/**
* Computes the average of a sequence of Decimal
* values that are obtained by invoking a transform function on
* each element of the input sequence.
*/
BigDecimal average(BigDecimalFunction1 selector);
/**
* Computes the average of a sequence of nullable
* Decimal values that are obtained by invoking a transform
* function on each element of the input sequence.
*/
BigDecimal average(NullableBigDecimalFunction1 selector);
/**
* Computes the average of a sequence of Double
* values that are obtained by invoking a transform function on
* each element of the input sequence.
*/
double average(DoubleFunction1 selector);
/**
* Computes the average of a sequence of nullable
* Double values that are obtained by invoking a transform
* function on each element of the input sequence.
*/
Double average(NullableDoubleFunction1 selector);
/**
* Computes the average of a sequence of int values
* that are obtained by invoking a transform function on each
* element of the input sequence.
*/
int average(IntegerFunction1 selector);
/**
* Computes the average of a sequence of nullable
* int values that are obtained by invoking a transform function
* on each element of the input sequence.
*/
Integer average(NullableIntegerFunction1 selector);
/**
* Computes the average of a sequence of long values
* that are obtained by invoking a transform function on each
* element of the input sequence.
*/
long average(LongFunction1 selector);
/**
* Computes the average of a sequence of nullable
* long values that are obtained by invoking a transform function
* on each element of the input sequence.
*/
Long average(NullableLongFunction1 selector);
/**
* Computes the average of a sequence of Float
* values that are obtained by invoking a transform function on
* each element of the input sequence.
*/
float average(FloatFunction1 selector);
/**
* Computes the average of a sequence of nullable
* Float values that are obtained by invoking a transform
* function on each element of the input sequence.
*/
Float average(NullableFloatFunction1 selector);
/**
* Converts the elements of this Enumerable to the specified type.
*
* This method is implemented by using deferred execution. The immediate
* return value is an object that stores all the information that is
* required to perform the action. The query represented by this method is
* not executed until the object is enumerated either by calling its
* {@link Enumerable#enumerator} method directly or by using
* {@code for (... in ...)}.
*
*
If an element cannot be cast to type TResult, the
* {@link Enumerator#current()} method will throw a
* {@link ClassCastException} a exception when the element it accessed. To
* obtain only those elements that can be cast to type TResult, use the
* {@link #ofType(Class)} method instead.
*
* @see EnumerableDefaults#cast
* @see #ofType(Class)
*/
Enumerable cast(Class clazz);
/**
* Concatenates two sequences.
*/
Enumerable concat(Enumerable enumerable1);
/**
* Determines whether a sequence contains a specified
* element by using the default equality comparer.
*/
boolean contains(TSource element);
/**
* Determines whether a sequence contains a specified
* element by using a specified {@code EqualityComparer}.
*/
boolean contains(TSource element, EqualityComparer comparer);
/**
* Returns the number of elements in a
* sequence.
*/
int count();
/**
* Returns a number that represents how many elements
* in the specified sequence satisfy a condition.
*/
int count(Predicate1 predicate);
/**
* Returns the elements of the specified sequence or
* the type parameter's default value in a singleton collection if
* the sequence is empty.
*/
Enumerable<@Nullable TSource> defaultIfEmpty();
/**
* Returns the elements of the specified sequence or
* the specified value in a singleton collection if the sequence
* is empty.
*
* If {@code value} is not null, the result is never null.
*/
Enumerable<@PolyNull TSource> defaultIfEmpty(@PolyNull TSource value);
/**
* Returns distinct elements from a sequence by using
* the default equality comparer to compare values.
*/
Enumerable distinct();
/**
* Returns distinct elements from a sequence by using
* a specified {@code EqualityComparer} to compare values.
*/
Enumerable distinct(EqualityComparer comparer);
/**
* Returns the element at a specified index in a
* sequence.
*/
TSource elementAt(int index);
/**
* Returns the element at a specified index in a
* sequence or a default value if the index is out of
* range.
*/
@Nullable TSource elementAtOrDefault(int index);
/**
* Produces the set difference of two sequences by
* using the default equality comparer to compare values,
* eliminate duplicates. (Defined by Enumerable.)
*/
Enumerable except(Enumerable enumerable1);
/**
* Produces the set difference of two sequences by
* using the default equality comparer to compare values,
* using {@code all} to indicate whether to eliminate duplicates.
* (Defined by Enumerable.)
*/
Enumerable except(Enumerable enumerable1, boolean all);
/**
* Produces the set difference of two sequences by
* using the specified {@code EqualityComparer} to compare
* values, eliminate duplicates.
*/
Enumerable except(Enumerable enumerable1,
EqualityComparer comparer);
/**
* Produces the set difference of two sequences by
* using the specified {@code EqualityComparer} to compare
* values, using {@code all} to indicate whether to eliminate duplicates.
*/
Enumerable except(Enumerable enumerable1,
EqualityComparer comparer, boolean all);
/**
* Returns the first element of a sequence. (Defined
* by Enumerable.)
*/
TSource first();
/**
* Returns the first element in a sequence that
* satisfies a specified condition.
*/
TSource first(Predicate1 predicate);
/**
* Returns the first element of a sequence, or a
* default value if the sequence contains no elements.
*/
@Nullable TSource firstOrDefault();
/**
* Returns the first element of the sequence that
* satisfies a condition or a default value if no such element is
* found.
*/
@Nullable TSource firstOrDefault(Predicate1 predicate);
/**
* Groups the elements of a sequence according to a
* specified key selector function.
*/
Enumerable> groupBy(
Function1 keySelector);
/**
* Groups the elements of a sequence according to a
* specified key selector function and compares the keys by using
* a specified comparer.
*/
Enumerable> groupBy(
Function1 keySelector, EqualityComparer comparer);
/**
* 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.
*/
Enumerable> groupBy(
Function1 keySelector,
Function1 elementSelector);
/**
* Groups the elements of a sequence according to a
* key selector function. The keys are compared by using a
* comparer and each group's elements are projected by using a
* specified function.
*/
Enumerable> groupBy(
Function1 keySelector,
Function1 elementSelector, EqualityComparer comparer);
/**
* Groups the elements of a sequence according to a
* specified key selector function and creates a result value from
* each group and its key.
*/
Enumerable groupBy(
Function1 keySelector,
Function2, TResult> resultSelector);
/**
* Groups the elements of a sequence according to a
* specified key selector function and creates a result value from
* each group and its key. The keys are compared by using a
* specified comparer.
*/
Enumerable groupBy(
Function1 keySelector,
Function2, TResult> resultSelector,
EqualityComparer comparer);
/**
* Groups the elements of a sequence according to a
* specified key selector function and creates a result value from
* each group and its key. The elements of each group are
* projected by using a specified function.
*/
Enumerable groupBy(
Function1 keySelector,
Function1 elementSelector,
Function2, TResult> resultSelector);
/**
* Groups the elements of a sequence according to a
* specified key selector function and creates a result value from
* each group and its key. Key values are compared by using a
* specified comparer, and the elements of each group are
* projected by using a specified function.
*/
Enumerable groupBy(
Function1 keySelector,
Function1 elementSelector,
Function2, TResult> resultSelector,
EqualityComparer comparer);
/**
* Groups the elements of a sequence according to a
* specified key selector function, initializing an accumulator for each
* group and adding to it each time an element with the same key is seen.
* Creates a result value from each accumulator and its key using a
* specified function.
*/
Enumerable groupBy(
Function1 keySelector,
Function0 accumulatorInitializer,
Function2 accumulatorAdder,
Function2 resultSelector);
/**
* Groups the elements of a sequence according to a
* specified key selector function, initializing an accumulator for each
* group and adding to it each time an element with the same key is seen.
* Creates a result value from each accumulator and its key using a
* specified function. Key values are compared by using a
* specified comparer.
*/
Enumerable groupBy(
Function1 keySelector,
Function0 accumulatorInitializer,
Function2 accumulatorAdder,
Function2 resultSelector,
EqualityComparer comparer);
/**
* Group keys are sorted already. Key values are compared by using a
* specified comparator. Groups the elements of a sequence according to a
* specified key selector function and initializing one accumulator at a time.
* Go over elements sequentially, adding to accumulator each time an element
* with the same key is seen. When key changes, creates a result value from the
* accumulator and then re-initializes the accumulator. In the case of NULL values
* in group keys, the comparator must be able to support NULL values by giving a
* consistent sort ordering.
*/
Enumerable sortedGroupBy(
Function1 keySelector,
Function0 accumulatorInitializer,
Function2 accumulatorAdder,
Function2 resultSelector,
Comparator comparator);
/**
* Correlates the elements of two sequences based on
* equality of keys and groups the results. The default equality
* comparer is used to compare keys.
*/
Enumerable groupJoin(
Enumerable inner, Function1 outerKeySelector,
Function1 innerKeySelector,
Function2, TResult> resultSelector);
/**
* Correlates the elements of two sequences based on
* key equality and groups the results. A specified
* {@code EqualityComparer} is used to compare keys.
*/
Enumerable groupJoin(
Enumerable inner, Function1 outerKeySelector,
Function1 innerKeySelector,
Function2, TResult> resultSelector,
EqualityComparer comparer);
/**
* Produces the set intersection of two sequences by
* using the default equality comparer to compare values,
* eliminate duplicates. (Defined by Enumerable.)
*/
Enumerable intersect(Enumerable enumerable1);
/**
* Produces the set intersection of two sequences by
* using the default equality comparer to compare values,
* using {@code all} to indicate whether to eliminate duplicates.
* (Defined by Enumerable.)
*/
Enumerable intersect(Enumerable enumerable1, boolean all);
/**
* Produces the set intersection of two sequences by
* using the specified {@code EqualityComparer} to compare
* values, eliminate duplicates.
*/
Enumerable intersect(Enumerable enumerable1,
EqualityComparer comparer);
/**
* Produces the set intersection of two sequences by
* using the specified {@code EqualityComparer} to compare
* values, using {@code all} to indicate whether to eliminate duplicates.
*/
Enumerable intersect(Enumerable enumerable1,
EqualityComparer comparer, boolean all);
/**
* Copies the contents of this sequence into a collection.
*/
> C into(C sink);
/**
* Removes the contents of this sequence from a collection.
*/
> C removeAll(C sink);
/**
* Correlates the elements of two sequences based on
* matching keys. The default equality comparer is used to compare
* keys.
*/
Enumerable hashJoin(Enumerable inner,
Function1 outerKeySelector,
Function1 innerKeySelector,
Function2 resultSelector);
/**
* Correlates the elements of two sequences based on
* matching keys. A specified {@code EqualityComparer} is used to
* compare keys.
*/
Enumerable hashJoin(Enumerable inner,
Function1 outerKeySelector,
Function1 innerKeySelector,
Function2 resultSelector,
EqualityComparer comparer);
/**
* Correlates the elements of two sequences based on matching keys, with
* optional outer join semantics. A specified
* {@code EqualityComparer} is used to compare keys.
*
* A left join generates nulls on right, and vice versa:
*
*
* Join types
*
* Join type
* generateNullsOnLeft
* generateNullsOnRight
*
* INNER false false LEFT false true RIGHT true false FULL true true
*/
Enumerable hashJoin(Enumerable inner,
Function1 outerKeySelector,
Function1 innerKeySelector,
Function2 resultSelector,
EqualityComparer comparer,
boolean generateNullsOnLeft, boolean generateNullsOnRight);
/**
* Correlates the elements of two sequences based on matching keys, with
* optional outer join semantics. A specified
* {@code EqualityComparer} is used to compare keys.
*
* A left join generates nulls on right, and vice versa:
*
*
* Join types
*
* Join type
* generateNullsOnLeft
* generateNullsOnRight
*
* INNER false false LEFT false true RIGHT true false FULL true true
*
* A predicate is used to filter the join result per-row
*/
Enumerable hashJoin(Enumerable inner,
Function1 outerKeySelector,
Function1 innerKeySelector,
Function2 resultSelector,
EqualityComparer comparer,
boolean generateNullsOnLeft, boolean generateNullsOnRight,
Predicate2 predicate);
/**
* For each row of the current enumerable returns the correlated rows
* from the {@code inner} enumerable (nested loops join).
*
* @param joinType inner, left, semi or anti join type
* @param inner generator of inner enumerable
* @param resultSelector selector of the result. For semi/anti join
* inner argument is always null.
*/
Enumerable correlateJoin(
JoinType joinType, Function1> inner,
Function2 resultSelector);
/**
* Returns the last element of a sequence. (Defined
* by Enumerable.)
*/
TSource last();
/**
* Returns the last element of a sequence that
* satisfies a specified condition.
*/
TSource last(Predicate1 predicate);
/**
* Returns the last element of a sequence, or a
* default value if the sequence contains no elements.
*/
@Nullable TSource lastOrDefault();
/**
* Returns the last element of a sequence that
* satisfies a condition or a default value if no such element is
* found.
*/
@Nullable TSource lastOrDefault(Predicate1 predicate);
/**
* Returns an long that represents the total number
* of elements in a sequence.
*/
long longCount();
/**
* Returns an long that represents how many elements
* in a sequence satisfy a condition.
*/
long longCount(Predicate1 predicate);
/**
* Returns the maximum value in a generic
* sequence.
*/
@Nullable TSource max();
/**
* Invokes a transform function on each element of a
* sequence and returns the maximum Decimal value.
*/
@Nullable BigDecimal max(BigDecimalFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the maximum nullable Decimal
* value.
*/
@Nullable BigDecimal max(NullableBigDecimalFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the maximum Double value.
*/
double max(DoubleFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the maximum nullable Double
* value.
*/
@Nullable Double max(NullableDoubleFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the maximum int value.
*/
int max(IntegerFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the maximum nullable int value. (Defined
* by Enumerable.)
*/
@Nullable Integer max(NullableIntegerFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the maximum long value.
*/
long max(LongFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the maximum nullable long value. (Defined
* by Enumerable.)
*/
@Nullable Long max(NullableLongFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the maximum Float value.
*/
float max(FloatFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the maximum nullable Float
* value.
*/
@Nullable Float max(NullableFloatFunction1 selector);
/**
* Invokes a transform function on each element of a
* generic sequence and returns the maximum resulting
* value.
*/
> @Nullable TResult max(
Function1 selector);
/**
* Returns the minimum value in a generic
* sequence.
*/
@Nullable TSource min();
/**
* Invokes a transform function on each element of a
* sequence and returns the minimum Decimal value.
*/
@Nullable BigDecimal min(BigDecimalFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the minimum nullable Decimal
* value.
*/
@Nullable BigDecimal min(NullableBigDecimalFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the minimum Double value.
*/
double min(DoubleFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the minimum nullable Double
* value.
*/
@Nullable Double min(NullableDoubleFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the minimum int value.
*/
int min(IntegerFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the minimum nullable int value. (Defined
* by Enumerable.)
*/
@Nullable Integer min(NullableIntegerFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the minimum long value.
*/
long min(LongFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the minimum nullable long value. (Defined
* by Enumerable.)
*/
@Nullable Long min(NullableLongFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the minimum Float value.
*/
float min(FloatFunction1 selector);
/**
* Invokes a transform function on each element of a
* sequence and returns the minimum nullable Float
* value.
*/
@Nullable Float min(NullableFloatFunction1 selector);
/**
* Invokes a transform function on each element of a
* generic sequence and returns the minimum resulting
* value.
*/
> @Nullable TResult min(
Function1 selector);
/**
* Filters the elements of an Enumerable based on a
* specified type.
*
* Analogous to LINQ's Enumerable.OfType extension method.
*
* @param clazz Target type
* @param Target type
*
* @return Collection of T2
*/
Enumerable ofType(Class clazz);
/**
* Sorts the elements of a sequence in ascending
* order according to a key.
*/
Enumerable orderBy(
Function1 keySelector);
/**
* Sorts the elements of a sequence in ascending
* order by using a specified comparer.
*/
Enumerable orderBy(Function1 keySelector,
Comparator comparator);
/**
* Sorts the elements of a sequence in descending
* order according to a key.
*/
Enumerable orderByDescending(
Function1 keySelector);
/**
* Sorts the elements of a sequence in descending
* order by using a specified comparer.
*/
Enumerable orderByDescending(
Function1 keySelector, Comparator comparator);
/**
* Inverts the order of the elements in a
* sequence.
*/
Enumerable reverse();
/**
* Projects each element of a sequence into a new
* form.
*/
Enumerable select(Function1 selector);
/**
* Projects each element of a sequence into a new
* form by incorporating the element's index.
*/
Enumerable select(
Function2 selector);
/**
* Projects each element of a sequence to an
* {@code Enumerable} and flattens the resulting sequences into one
* sequence.
*/
Enumerable selectMany(
Function1> selector);
/**
* Projects each element of a sequence to an
* {@code Enumerable}, and flattens the resulting sequences into one
* sequence. The index of each source element is used in the
* projected form of that element.
*/
Enumerable selectMany(
Function2> selector);
/**
* Projects each element of a sequence to an
* {@code Enumerable}, flattens the resulting sequences into one
* sequence, and invokes a result selector function on each
* element therein. The index of each source element is used in
* the intermediate projected form of that element.
*/
Enumerable selectMany(
Function2> collectionSelector,
Function2 resultSelector);
/**
* Projects each element of a sequence to an
* {@code Enumerable