From ebba1d4acb7abea5ba15e1f7f69d1d1311465d16 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Sat, 3 Jul 2021 20:40:58 +0300 Subject: [PATCH] add missing documentation from #47231. (#54837) --- .../src/System/Linq/Queryable.cs | 175 ++++++++++++++++-- .../System.Linq/src/System/Linq/Distinct.cs | 23 +++ .../System.Linq/src/System/Linq/ElementAt.cs | 27 +-- .../System.Linq/src/System/Linq/First.cs | 13 ++ .../System.Linq/src/System/Linq/Intersect.cs | 29 +++ .../System.Linq/src/System/Linq/Last.cs | 14 +- .../System.Linq/src/System/Linq/Max.cs | 37 ++++ .../System.Linq/src/System/Linq/Min.cs | 37 ++++ .../System.Linq/src/System/Linq/Single.cs | 15 ++ .../System.Linq/src/System/Linq/Take.cs | 10 +- .../System.Linq/src/System/Linq/Union.cs | 27 +++ 11 files changed, 370 insertions(+), 37 deletions(-) diff --git a/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs b/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs index 2917955e9d269..3e2d0c4ca67b8 100644 --- a/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs +++ b/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs @@ -394,12 +394,10 @@ public static IQueryable Take(this IQueryable source, } /// Returns a specified range of contiguous elements from a sequence. + /// The type of the elements of . /// The sequence to return elements from. /// The range of elements to return, which has start and end indexes either from the start or the end. - /// The type of the elements of . - /// - /// is . - /// + /// is . /// An that contains the specified of elements from the sequence. [DynamicDependency("Take`1", typeof(Enumerable))] public static IQueryable Take(this IQueryable source, Range range) @@ -639,6 +637,13 @@ public static IQueryable Distinct(this IQueryable sou )); } + /// Returns distinct elements from a sequence according to a specified key selector function. + /// The type of the elements of . + /// The type of key to distinguish elements by. + /// The sequence to remove duplicate elements from. + /// A function to extract the key for each element. + /// An that contains distinct elements from the source sequence. + /// is . [DynamicDependency("DistinctBy`2", typeof(Enumerable))] public static IQueryable DistinctBy(this IQueryable source, Expression> keySelector) { @@ -654,6 +659,14 @@ public static IQueryable DistinctBy(this IQueryableReturns distinct elements from a sequence according to a specified key selector function. + /// The type of the elements of . + /// The type of key to distinguish elements by. + /// The sequence to remove duplicate elements from. + /// A function to extract the key for each element. + /// An to compare keys. + /// An that contains distinct elements from the source sequence. + /// is . [DynamicDependency("DistinctBy`2", typeof(Enumerable))] public static IQueryable DistinctBy(this IQueryable source, Expression> keySelector, IEqualityComparer? comparer) { @@ -669,6 +682,17 @@ public static IQueryable DistinctBy(this IQueryableSplit the elements of a sequence into chunks of size at most . + /// An whose elements to chunk. + /// Maximum size of each chunk. + /// The type of the elements of source. + /// An that contains the elements the input sequence split into chunks of size . + /// is null. + /// is below 1. + /// + /// Every chunk except the last will be of size . + /// The last chunk will contain the remaining elements and may be of a smaller size. + /// [DynamicDependency("Chunk`1", typeof(Enumerable))] public static IQueryable Chunk(this IQueryable source, int size) { @@ -793,6 +817,14 @@ public static IQueryable Union(this IQueryable source )); } + /// Produces the set union of two sequences according to a specified key selector function. + /// The type of the elements of the input sequences. + /// The type of key to identify elements by. + /// An whose distinct elements form the first set for the union. + /// An whose distinct elements form the second set for the union. + /// A function to extract the key for each element. + /// An that contains the elements from both input sequences, excluding duplicates. + /// or is . [DynamicDependency("UnionBy`2", typeof(Enumerable))] public static IQueryable UnionBy(this IQueryable source1, IEnumerable source2, Expression> keySelector) { @@ -810,6 +842,15 @@ public static IQueryable UnionBy(this IQueryableProduces the set union of two sequences according to a specified key selector function. + /// The type of the elements of the input sequences. + /// The type of key to identify elements by. + /// An whose distinct elements form the first set for the union. + /// An whose distinct elements form the second set for the union. + /// A function to extract the key for each element. + /// The to compare values. + /// An that contains the elements from both input sequences, excluding duplicates. + /// or is . [DynamicDependency("UnionBy`2", typeof(Enumerable))] public static IQueryable UnionBy(this IQueryable source1, IEnumerable source2, Expression> keySelector, IEqualityComparer? comparer) { @@ -862,6 +903,14 @@ public static IQueryable Intersect(this IQueryable so )); } + /// Produces the set intersection of two sequences according to a specified key selector function. + /// The type of the elements of the input sequences. + /// The type of key to identify elements by. + /// An whose distinct elements that also appear in will be returned. + /// An whose distinct elements that also appear in the first sequence will be returned. + /// A function to extract the key for each element. + /// A sequence that contains the elements that form the set intersection of two sequences. + /// or is . [DynamicDependency("IntersectBy`2", typeof(Enumerable))] public static IQueryable IntersectBy(this IQueryable source1, IEnumerable source2, Expression> keySelector) { @@ -881,6 +930,15 @@ public static IQueryable IntersectBy(this IQueryableProduces the set intersection of two sequences according to a specified key selector function. + /// The type of the elements of the input sequences. + /// The type of key to identify elements by. + /// An whose distinct elements that also appear in will be returned. + /// An whose distinct elements that also appear in the first sequence will be returned. + /// A function to extract the key for each element. + /// An to compare keys. + /// A sequence that contains the elements that form the set intersection of two sequences. + /// or is . [DynamicDependency("IntersectBy`2", typeof(Enumerable))] public static IQueryable IntersectBy(this IQueryable source1, IEnumerable source2, Expression> keySelector, IEqualityComparer? comparer) { @@ -1009,6 +1067,12 @@ public static TSource First(this IQueryable source, Expression CachedReflectionInfo.FirstOrDefault_TSource_1(typeof(TSource)), source.Expression)); } + /// Returns the first element of a sequence, or a default value if the sequence contains no elements. + /// The type of the elements of . + /// The to return the first element of. + /// The default value to return if the sequence is empty. + /// if is empty; otherwise, the first element in . + /// is . [DynamicDependency("FirstOrDefault`1", typeof(Enumerable))] public static TSource FirstOrDefault(this IQueryable source, TSource defaultValue) { @@ -1036,6 +1100,13 @@ public static TSource FirstOrDefault(this IQueryable source, T )); } + /// Returns the first element of the sequence that satisfies a condition or a default value if no such element is found. + /// The type of the elements of . + /// An to return an element from. + /// A function to test each element for a condition. + /// The default value to return if the sequence is empty. + /// if is empty or if no element passes the test specified by ; otherwise, the first element in that passes the test specified by . + /// or is . [DynamicDependency("FirstOrDefault`1", typeof(Enumerable))] public static TSource FirstOrDefault(this IQueryable source, Expression> predicate, TSource defaultValue) { @@ -1088,6 +1159,12 @@ public static TSource Last(this IQueryable source, Expression< CachedReflectionInfo.LastOrDefault_TSource_1(typeof(TSource)), source.Expression)); } + /// Returns the last element of a sequence, or a default value if the sequence contains no elements. + /// The type of the elements of . + /// An to return the last element of. + /// The default value to return if the sequence is empty. + /// if the source sequence is empty; otherwise, the last element in the . + /// is . [DynamicDependency("LastOrDefault`1", typeof(Enumerable))] public static TSource LastOrDefault(this IQueryable source, TSource defaultValue) { @@ -1115,6 +1192,13 @@ public static TSource LastOrDefault(this IQueryable source, TS )); } + /// Returns the last element of a sequence that satisfies a condition or a default value if no such element is found. + /// The type of the elements of . + /// An to return an element from. + /// A function to test each element for a condition. + /// The default value to return if the sequence is empty. + /// if the sequence is empty or if no elements pass the test in the predicate function; otherwise, the last element that passes the test in the predicate function. + /// or is . [DynamicDependency("LastOrDefault`1", typeof(Enumerable))] public static TSource LastOrDefault(this IQueryable source, Expression> predicate, TSource defaultValue) { @@ -1167,6 +1251,13 @@ public static TSource Single(this IQueryable source, Expressio CachedReflectionInfo.SingleOrDefault_TSource_1(typeof(TSource)), source.Expression)); } + /// Returns the only element of a sequence, or a default value if the sequence is empty; this method throws an exception if there is more than one element in the sequence. + /// The type of the elements of . + /// An to return the single element of. + /// The default value to return if the sequence is empty. + /// The single element of the input sequence, or if the sequence contains no elements. + /// is . + /// The input sequence contains more than one element. [DynamicDependency("SingleOrDefault`1", typeof(Enumerable))] public static TSource SingleOrDefault(this IQueryable source, TSource defaultValue) { @@ -1195,6 +1286,14 @@ public static TSource SingleOrDefault(this IQueryable source, )); } + /// Returns the only element of a sequence that satisfies a specified condition or a default value if no such element exists; this method throws an exception if more than one element satisfies the condition. + /// The type of the elements of . + /// An to return a single element from. + /// A function to test an element for a condition. + /// The default value to return if the sequence is empty. + /// The single element of the input sequence that satisfies the condition, or if no such element is found. + /// or is . + /// More than one element satisfies the condition in . [DynamicDependency("SingleOrDefault`1", typeof(Enumerable))] public static TSource SingleOrDefault(this IQueryable source, Expression> predicate, TSource defaultValue) { @@ -1226,15 +1325,11 @@ public static TSource ElementAt(this IQueryable source, int in } /// Returns the element at a specified index in a sequence. + /// The type of the elements of . /// An to return an element from. /// The index of the element to retrieve, which is either from the start or the end. - /// The type of the elements of . - /// - /// is . - /// - /// - /// is outside the bounds of the sequence. - /// + /// is . + /// is outside the bounds of the sequence. /// The element at the specified position in the sequence. [DynamicDependency("ElementAt`1", typeof(Enumerable))] public static TSource ElementAt(this IQueryable source, Index index) @@ -1265,15 +1360,11 @@ public static TSource ElementAt(this IQueryable source, Index } /// Returns the element at a specified index in a sequence or a default value if the index is out of range. + /// The type of the elements of . /// An to return an element from. /// The index of the element to retrieve, which is either from the start or the end. - /// The type of the elements of . - /// - /// is . - /// - /// - /// if index is outside the bounds of the sequence; otherwise, the element at the specified position in the sequence. - /// + /// is . + /// if is outside the bounds of the sequence; otherwise, the element at the specified position in the sequence. [DynamicDependency("ElementAtOrDefault`1", typeof(Enumerable))] public static TSource? ElementAtOrDefault(this IQueryable source, Index index) { @@ -1484,6 +1575,13 @@ public static long LongCount(this IQueryable source, Expressio CachedReflectionInfo.Min_TSource_1(typeof(TSource)), source.Expression)); } + /// Returns the minimum value in a generic . + /// The type of the elements of . + /// A sequence of values to determine the minimum value of. + /// The to compare values. + /// The minimum value in the sequence. + /// is . + /// No object in implements the or interface. [DynamicDependency("Min`1", typeof(Enumerable))] public static TSource? Min(this IQueryable source, IComparer? comparer) { @@ -1513,6 +1611,14 @@ public static long LongCount(this IQueryable source, Expressio )); } + /// Returns the minimum value in a generic according to a specified key selector function. + /// The type of the elements of . + /// The type of key to compare elements by. + /// A sequence of values to determine the minimum value of. + /// A function to extract the key for each element. + /// The value with the minimum key in the sequence. + /// is . + /// No key extracted from implements the or interface. [DynamicDependency("MinBy`2", typeof(Enumerable))] public static TSource? MinBy(this IQueryable source, Expression> keySelector) { @@ -1529,6 +1635,15 @@ public static long LongCount(this IQueryable source, Expressio )); } + /// Returns the minimum value in a generic according to a specified key selector function. + /// The type of the elements of . + /// The type of key to compare elements by. + /// A sequence of values to determine the minimum value of. + /// A function to extract the key for each element. + /// The to compare keys. + /// The value with the minimum key in the sequence. + /// is . + /// No key extracted from implements the or interface. [DynamicDependency("MinBy`2", typeof(Enumerable))] public static TSource? MinBy(this IQueryable source, Expression> keySelector, IComparer? comparer) { @@ -1556,7 +1671,12 @@ public static long LongCount(this IQueryable source, Expressio null, CachedReflectionInfo.Max_TSource_1(typeof(TSource)), source.Expression)); } - + /// Returns the maximum value in a generic . + /// The type of the elements of . + /// A sequence of values to determine the maximum value of. + /// The to compare values. + /// The maximum value in the sequence. + /// is . [DynamicDependency("Max`1", typeof(Enumerable))] public static TSource? Max(this IQueryable source, IComparer? comparer) { @@ -1586,6 +1706,14 @@ public static long LongCount(this IQueryable source, Expressio )); } + /// Returns the maximum value in a generic according to a specified key selector function. + /// The type of the elements of . + /// The type of key to compare elements by. + /// A sequence of values to determine the maximum value of. + /// A function to extract the key for each element. + /// The value with the maximum key in the sequence. + /// is . + /// No key extracted from implements the or interface. [DynamicDependency("MaxBy`2", typeof(Enumerable))] public static TSource? MaxBy(this IQueryable source, Expression> keySelector) { @@ -1602,6 +1730,15 @@ public static long LongCount(this IQueryable source, Expressio )); } + /// Returns the maximum value in a generic according to a specified key selector function. + /// The type of the elements of . + /// The type of key to compare elements by. + /// A sequence of values to determine the maximum value of. + /// A function to extract the key for each element. + /// The to compare keys. + /// The value with the maximum key in the sequence. + /// is . + /// No key extracted from implements the or interface. [DynamicDependency("MaxBy`2", typeof(Enumerable))] public static TSource? MaxBy(this IQueryable source, Expression> keySelector, IComparer? comparer) { diff --git a/src/libraries/System.Linq/src/System/Linq/Distinct.cs b/src/libraries/System.Linq/src/System/Linq/Distinct.cs index 008128024302b..173ac951e96dc 100644 --- a/src/libraries/System.Linq/src/System/Linq/Distinct.cs +++ b/src/libraries/System.Linq/src/System/Linq/Distinct.cs @@ -20,8 +20,31 @@ public static IEnumerable Distinct(this IEnumerable s return new DistinctIterator(source, comparer); } + /// Returns distinct elements from a sequence according to a specified key selector function. + /// The type of the elements of . + /// The type of key to distinguish elements by. + /// The sequence to remove duplicate elements from. + /// A function to extract the key for each element. + /// An that contains distinct elements from the source sequence. + /// is . + /// + /// 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 `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. + /// The method returns an unordered sequence that contains no duplicate values. The default equality comparer, , is used to compare values. + /// public static IEnumerable DistinctBy(this IEnumerable source, Func keySelector) => DistinctBy(source, keySelector, null); + /// Returns distinct elements from a sequence according to a specified key selector function. + /// The type of the elements of . + /// The type of key to distinguish elements by. + /// The sequence to remove duplicate elements from. + /// A function to extract the key for each element. + /// An to compare keys. + /// An that contains distinct elements from the source sequence. + /// is . + /// + /// 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 `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. + /// The method returns an unordered sequence that contains no duplicate values. If is , the default equality comparer, , is used to compare values. + /// public static IEnumerable DistinctBy(this IEnumerable source, Func keySelector, IEqualityComparer? comparer) { if (source is null) diff --git a/src/libraries/System.Linq/src/System/Linq/ElementAt.cs b/src/libraries/System.Linq/src/System/Linq/ElementAt.cs index 46d9399d36230..91daa6b37bbd5 100644 --- a/src/libraries/System.Linq/src/System/Linq/ElementAt.cs +++ b/src/libraries/System.Linq/src/System/Linq/ElementAt.cs @@ -38,15 +38,16 @@ public static TSource ElementAt(this IEnumerable source, int i } /// Returns the element at a specified index in a sequence. + /// The type of the elements of . /// An to return an element from. /// The index of the element to retrieve, which is either from the start or the end. - /// The type of the elements of . - /// - /// is . - /// - /// is outside the bounds of the sequence. - /// + /// is . + /// is outside the bounds of the sequence. /// The element at the specified position in the sequence. + /// + /// If the type of implements , that implementation is used to obtain the element at the specified index. Otherwise, this method obtains the specified element. + /// This method throws an exception if is out of range. To instead return a default value when the specified index is out of range, use the method. + /// public static TSource ElementAt(this IEnumerable source, Index index) { if (source == null) @@ -95,15 +96,15 @@ public static TSource ElementAt(this IEnumerable source, Index } /// Returns the element at a specified index in a sequence or a default value if the index is out of range. + /// The type of the elements of . /// An to return an element from. /// The index of the element to retrieve, which is either from the start or the end. - /// The type of the elements of . - /// - /// is . - /// - /// - /// if is outside the bounds of the sequence; otherwise, the element at the specified position in the sequence. - /// + /// is . + /// if is outside the bounds of the sequence; otherwise, the element at the specified position in the sequence. + /// + /// If the type of implements , that implementation is used to obtain the element at the specified index. Otherwise, this method obtains the specified element. + /// The default value for reference and nullable types is . + /// public static TSource? ElementAtOrDefault(this IEnumerable source, Index index) { if (source == null) diff --git a/src/libraries/System.Linq/src/System/Linq/First.cs b/src/libraries/System.Linq/src/System/Linq/First.cs index 7f59d1c63b587..1c62f547d9a03 100644 --- a/src/libraries/System.Linq/src/System/Linq/First.cs +++ b/src/libraries/System.Linq/src/System/Linq/First.cs @@ -33,6 +33,12 @@ public static TSource First(this IEnumerable source, Func(this IEnumerable source) => source.TryGetFirst(out _); + /// Returns the first element of a sequence, or a default value if the sequence contains no elements. + /// The type of the elements of . + /// The to return the first element of. + /// The default value to return if the sequence is empty. + /// if is empty; otherwise, the first element in . + /// is . public static TSource FirstOrDefault(this IEnumerable source, TSource defaultValue) { TSource? first = source.TryGetFirst(out bool found); @@ -42,6 +48,13 @@ public static TSource FirstOrDefault(this IEnumerable source, public static TSource? FirstOrDefault(this IEnumerable source, Func predicate) => source.TryGetFirst(predicate, out _); + /// Returns the first element of the sequence that satisfies a condition or a default value if no such element is found. + /// The type of the elements of . + /// An to return an element from. + /// A function to test each element for a condition. + /// The default value to return if the sequence is empty. + /// if is empty or if no element passes the test specified by ; otherwise, the first element in that passes the test specified by . + /// or is . public static TSource FirstOrDefault(this IEnumerable source, Func predicate, TSource defaultValue) { TSource? first = source.TryGetFirst(predicate, out bool found); diff --git a/src/libraries/System.Linq/src/System/Linq/Intersect.cs b/src/libraries/System.Linq/src/System/Linq/Intersect.cs index a9519a6e73a7b..b8db27d7a8472 100644 --- a/src/libraries/System.Linq/src/System/Linq/Intersect.cs +++ b/src/libraries/System.Linq/src/System/Linq/Intersect.cs @@ -24,8 +24,37 @@ public static IEnumerable Intersect(this IEnumerable return IntersectIterator(first, second, comparer); } + /// Produces the set intersection of two sequences according to a specified key selector function. + /// The type of the elements of the input sequences. + /// The type of key to identify elements by. + /// An whose distinct elements that also appear in will be returned. + /// An whose distinct elements that also appear in the first sequence will be returned. + /// A function to extract the key for each element. + /// A sequence that contains the elements that form the set intersection of two sequences. + /// or is . + /// + /// 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 `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. + /// The intersection of two sets A and B is defined as the set that contains all the elements of A that also appear in B, but no other elements. + /// When the object returned by this method is enumerated, `Intersect` yields distinct elements occurring in both sequences in the order in which they appear in . + /// The default equality comparer, , is used to compare values. + /// public static IEnumerable IntersectBy(this IEnumerable first, IEnumerable second, Func keySelector) => IntersectBy(first, second, keySelector, null); + /// Produces the set intersection of two sequences according to a specified key selector function. + /// The type of the elements of the input sequences. + /// The type of key to identify elements by. + /// An whose distinct elements that also appear in will be returned. + /// An whose distinct elements that also appear in the first sequence will be returned. + /// A function to extract the key for each element. + /// An to compare keys. + /// A sequence that contains the elements that form the set intersection of two sequences. + /// or is . + /// + /// 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 `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. + /// The intersection of two sets A and B is defined as the set that contains all the elements of A that also appear in B, but no other elements. + /// When the object returned by this method is enumerated, `Intersect` yields distinct elements occurring in both sequences in the order in which they appear in . + /// If is , the default equality comparer, , is used to compare values. + /// public static IEnumerable IntersectBy(this IEnumerable first, IEnumerable second, Func keySelector, IEqualityComparer? comparer) { if (first is null) diff --git a/src/libraries/System.Linq/src/System/Linq/Last.cs b/src/libraries/System.Linq/src/System/Linq/Last.cs index 16318de2574cc..cebe4d0932887 100644 --- a/src/libraries/System.Linq/src/System/Linq/Last.cs +++ b/src/libraries/System.Linq/src/System/Linq/Last.cs @@ -33,7 +33,12 @@ public static TSource Last(this IEnumerable source, Func(this IEnumerable source) => source.TryGetLast(out _); - + /// Returns the last element of a sequence, or a default value if the sequence contains no elements. + /// The type of the elements of . + /// An to return the last element of. + /// The default value to return if the sequence is empty. + /// if the source sequence is empty; otherwise, the last element in the . + /// is . public static TSource LastOrDefault(this IEnumerable source, TSource defaultValue) { TSource? last = source.TryGetLast(out bool found); @@ -43,6 +48,13 @@ public static TSource LastOrDefault(this IEnumerable source, T public static TSource? LastOrDefault(this IEnumerable source, Func predicate) => source.TryGetLast(predicate, out _); + /// Returns the last element of a sequence that satisfies a condition or a default value if no such element is found. + /// The type of the elements of . + /// An to return an element from. + /// A function to test each element for a condition. + /// The default value to return if the sequence is empty. + /// if the sequence is empty or if no elements pass the test in the predicate function; otherwise, the last element that passes the test in the predicate function. + /// or is . public static TSource LastOrDefault(this IEnumerable source, Func predicate, TSource defaultValue) { var last = source.TryGetLast(predicate, out bool found); diff --git a/src/libraries/System.Linq/src/System/Linq/Max.cs b/src/libraries/System.Linq/src/System/Linq/Max.cs index 8e1afcb339762..6a847068c5fa6 100644 --- a/src/libraries/System.Linq/src/System/Linq/Max.cs +++ b/src/libraries/System.Linq/src/System/Linq/Max.cs @@ -442,6 +442,19 @@ public static decimal Max(this IEnumerable source) } public static TSource? Max(this IEnumerable source) => Max(source, comparer: null); + + /// Returns the maximum value in a generic sequence. + /// The type of the elements of . + /// A sequence of values to determine the maximum value of. + /// The to compare values. + /// The maximum value in the sequence. + /// is . + /// No object in implements the or interface. + /// + /// If type implements , the method uses that implementation to compare values. Otherwise, if type implements , that implementation is used to compare values. + /// If is a reference type and the source sequence is empty or contains only values that are , this method returns . + /// In Visual Basic query expression syntax, an `Aggregate Into Max()` clause translates to an invocation of . + /// public static TSource? Max(this IEnumerable source, IComparer? comparer) { if (source == null) @@ -512,7 +525,31 @@ public static decimal Max(this IEnumerable source) return value; } + /// Returns the maximum value in a generic sequence according to a specified key selector function. + /// The type of the elements of . + /// The type of key to compare elements by. + /// A sequence of values to determine the maximum value of. + /// A function to extract the key for each element. + /// The value with the maximum key in the sequence. + /// is . + /// No key extracted from implements the or interface. + /// + /// If is a reference type and the source sequence is empty or contains only values that are , this method returns . + /// public static TSource? MaxBy(this IEnumerable source, Func keySelector) => MaxBy(source, keySelector, null); + + /// Returns the maximum value in a generic sequence according to a specified key selector function. + /// The type of the elements of . + /// The type of key to compare elements by. + /// A sequence of values to determine the maximum value of. + /// A function to extract the key for each element. + /// The to compare keys. + /// The value with the maximum key in the sequence. + /// is . + /// No key extracted from implements the or interface. + /// + /// If is a reference type and the source sequence is empty or contains only values that are , this method returns . + /// public static TSource? MaxBy(this IEnumerable source, Func keySelector, IComparer? comparer) { if (source == null) diff --git a/src/libraries/System.Linq/src/System/Linq/Min.cs b/src/libraries/System.Linq/src/System/Linq/Min.cs index 2504dc5ed8c23..a66b0cfcf88fd 100644 --- a/src/libraries/System.Linq/src/System/Linq/Min.cs +++ b/src/libraries/System.Linq/src/System/Linq/Min.cs @@ -400,6 +400,19 @@ public static decimal Min(this IEnumerable source) } public static TSource? Min(this IEnumerable source) => Min(source, comparer: null); + + /// Returns the minimum value in a generic sequence. + /// The type of the elements of . + /// A sequence of values to determine the minimum value of. + /// The to compare values. + /// The minimum value in the sequence. + /// is . + /// No object in implements the or interface. + /// + /// If type implements , the method uses that implementation to compare values. Otherwise, if type implements , that implementation is used to compare values. + /// If is a reference type and the source sequence is empty or contains only values that are , this method returns . + /// In Visual Basic query expression syntax, an `Aggregate Into Max()` clause translates to an invocation of . + /// public static TSource? Min(this IEnumerable source, IComparer? comparer) { if (source == null) @@ -470,7 +483,31 @@ public static decimal Min(this IEnumerable source) return value; } + /// Returns the minimum value in a generic sequence according to a specified key selector function. + /// The type of the elements of . + /// The type of key to compare elements by. + /// A sequence of values to determine the minimum value of. + /// A function to extract the key for each element. + /// The value with the minimum key in the sequence. + /// is . + /// No key extracted from implements the or interface. + /// + /// If is a reference type and the source sequence is empty or contains only values that are , this method returns . + /// public static TSource? MinBy(this IEnumerable source, Func keySelector) => MinBy(source, keySelector, comparer: null); + + /// Returns the minimum value in a generic sequence according to a specified key selector function. + /// The type of the elements of . + /// The type of key to compare elements by. + /// A sequence of values to determine the minimum value of. + /// A function to extract the key for each element. + /// The to compare keys. + /// The value with the minimum key in the sequence. + /// is . + /// No key extracted from implements the or interface. + /// + /// If is a reference type and the source sequence is empty or contains only values that are , this method returns . + /// public static TSource? MinBy(this IEnumerable source, Func keySelector, IComparer? comparer) { if (source == null) diff --git a/src/libraries/System.Linq/src/System/Linq/Single.cs b/src/libraries/System.Linq/src/System/Linq/Single.cs index 6455a841c9c46..9e35009e6175f 100644 --- a/src/libraries/System.Linq/src/System/Linq/Single.cs +++ b/src/libraries/System.Linq/src/System/Linq/Single.cs @@ -32,6 +32,13 @@ public static TSource Single(this IEnumerable source, Func(this IEnumerable source) => source.TryGetSingle(out _); + /// Returns the only element of a sequence, or a default value if the sequence is empty; this method throws an exception if there is more than one element in the sequence. + /// The type of the elements of . + /// An to return the single element of. + /// The default value to return if the sequence is empty. + /// The single element of the input sequence, or if the sequence contains no elements. + /// is . + /// The input sequence contains more than one element. public static TSource SingleOrDefault(this IEnumerable source, TSource defaultValue) { var single = source.TryGetSingle(out bool found); @@ -41,6 +48,14 @@ public static TSource SingleOrDefault(this IEnumerable source, public static TSource? SingleOrDefault(this IEnumerable source, Func predicate) => source.TryGetSingle(predicate, out _); + /// Returns the only element of a sequence that satisfies a specified condition or a default value if no such element exists; this method throws an exception if more than one element satisfies the condition. + /// The type of the elements of . + /// An to return a single element from. + /// A function to test an element for a condition. + /// The default value to return if the sequence is empty. + /// The single element of the input sequence that satisfies the condition, or if no such element is found. + /// or is . + /// More than one element satisfies the condition in . public static TSource SingleOrDefault(this IEnumerable source, Func predicate, TSource defaultValue) { var single = source.TryGetSingle(predicate, out bool found); diff --git a/src/libraries/System.Linq/src/System/Linq/Take.cs b/src/libraries/System.Linq/src/System/Linq/Take.cs index dbb859348a7cd..649ce99faeefa 100644 --- a/src/libraries/System.Linq/src/System/Linq/Take.cs +++ b/src/libraries/System.Linq/src/System/Linq/Take.cs @@ -21,13 +21,15 @@ public static IEnumerable Take(this IEnumerable sourc } /// Returns a specified range of contiguous elements from a sequence. + /// The type of the elements of . /// The sequence to return elements from. /// The range of elements to return, which has start and end indexes either from the start or the end. - /// The type of the elements of . - /// - /// is . - /// + /// is . /// An that contains the specified of elements from the sequence. + /// + /// 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 `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. + /// enumerates and yields elements whose indices belong to the specified . + /// public static IEnumerable Take(this IEnumerable source, Range range) { if (source == null) diff --git a/src/libraries/System.Linq/src/System/Linq/Union.cs b/src/libraries/System.Linq/src/System/Linq/Union.cs index bc7eb36843d72..6031498bbce54 100644 --- a/src/libraries/System.Linq/src/System/Linq/Union.cs +++ b/src/libraries/System.Linq/src/System/Linq/Union.cs @@ -26,8 +26,35 @@ public static IEnumerable Union(this IEnumerable firs return first is UnionIterator union && AreEqualityComparersEqual(comparer, union._comparer) ? union.Union(second) : new UnionIterator2(first, second, comparer); } + /// Produces the set union of two sequences according to a specified key selector function. + /// The type of the elements of the input sequences. + /// The type of key to identify elements by. + /// An whose distinct elements form the first set for the union. + /// An whose distinct elements form the second set for the union. + /// A function to extract the key for each element. + /// An that contains the elements from both input sequences, excluding duplicates. + /// or is . + /// + /// 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 `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. + /// The default equality comparer, , is used to compare values. + /// When the object returned by this method is enumerated, enumerates and in that order and yields each element that has not already been yielded. + /// public static IEnumerable UnionBy(this IEnumerable first, IEnumerable second, Func keySelector) => UnionBy(first, second, keySelector, null); + /// Produces the set union of two sequences according to a specified key selector function. + /// The type of the elements of the input sequences. + /// The type of key to identify elements by. + /// An whose distinct elements form the first set for the union. + /// An whose distinct elements form the second set for the union. + /// A function to extract the key for each element. + /// The to compare values. + /// An that contains the elements from both input sequences, excluding duplicates. + /// or is . + /// + /// 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 `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic. + /// If is , the default equality comparer, , is used to compare values. + /// When the object returned by this method is enumerated, enumerates and in that order and yields each element that has not already been yielded. + /// public static IEnumerable UnionBy(this IEnumerable first, IEnumerable second, Func keySelector, IEqualityComparer? comparer) { if (first is null)