From ceabc3d919578e84554a9e07a89b53d84e13dd09 Mon Sep 17 00:00:00 2001 From: Stuart Turner Date: Thu, 12 Oct 2023 17:14:15 -0500 Subject: [PATCH] Update documentation for `GroupAdjacent` --- ...SuperLinq.SuperEnumerable.GroupAdjacent.md | 41 +++ .../GroupAdjacent/GroupAdjacent1.linq | 35 ++ .../GroupAdjacent/GroupAdjacent2.linq | 36 ++ .../GroupAdjacent/GroupAdjacent3.linq | 36 ++ .../GroupAdjacent/GroupAdjacent4.linq | 37 ++ .../GroupAdjacent/GroupAdjacent5.linq | 36 ++ .../GroupAdjacent/GroupAdjacent6.linq | 37 ++ Source/SuperLinq/GroupAdjacent.cs | 330 ++++++++++-------- 8 files changed, 440 insertions(+), 148 deletions(-) create mode 100644 Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.GroupAdjacent.md create mode 100644 Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent1.linq create mode 100644 Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent2.linq create mode 100644 Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent3.linq create mode 100644 Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent4.linq create mode 100644 Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent5.linq create mode 100644 Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent6.linq diff --git a/Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.GroupAdjacent.md b/Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.GroupAdjacent.md new file mode 100644 index 000000000..3baa98d41 --- /dev/null +++ b/Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.GroupAdjacent.md @@ -0,0 +1,41 @@ +--- +uid: SuperLinq.SuperEnumerable.GroupAdjacent``2(System.Collections.Generic.IEnumerable{``0},System.Func{``0,``1}) +example: [*content] +--- +The following code example shows how to group adjacent items in a sequence using `GroupAdjacent`: +[!code-csharp[](SuperLinq/GroupAdjacent/GroupAdjacent1.linq#L6-)] + +--- +uid: SuperLinq.SuperEnumerable.GroupAdjacent``2(System.Collections.Generic.IEnumerable{``0},System.Func{``0,``1},System.Collections.Generic.IEqualityComparer{``1}) +example: [*content] +--- +The following code example shows how to group adjacent items in a sequence using `GroupAdjacent`: +[!code-csharp[](SuperLinq/GroupAdjacent/GroupAdjacent2.linq#L6-)] + +--- +uid: SuperLinq.SuperEnumerable.GroupAdjacent``3(System.Collections.Generic.IEnumerable{``0},System.Func{``0,``1},System.Func{``0,``2}) +example: [*content] +--- +The following code example shows how to group adjacent items in a sequence using `GroupAdjacent`: +[!code-csharp[](SuperLinq/GroupAdjacent/GroupAdjacent3.linq#L6-)] + +--- +uid: SuperLinq.SuperEnumerable.GroupAdjacent``3(System.Collections.Generic.IEnumerable{``0},System.Func{``0,``1},System.Func{``0,``2},System.Collections.Generic.IEqualityComparer{``1}) +example: [*content] +--- +The following code example shows how to group adjacent items in a sequence using `GroupAdjacent`: +[!code-csharp[](SuperLinq/GroupAdjacent/GroupAdjacent4.linq#L6-)] + +--- +uid: SuperLinq.SuperEnumerable.GroupAdjacent``3(System.Collections.Generic.IEnumerable{``0},System.Func{``0,``1},System.Func{``1,System.Collections.Generic.IEnumerable{``0},``2}) +example: [*content] +--- +The following code example shows how to group adjacent items in a sequence using `GroupAdjacent`: +[!code-csharp[](SuperLinq/GroupAdjacent/GroupAdjacent5.linq#L6-)] + +--- +uid: SuperLinq.SuperEnumerable.GroupAdjacent``3(System.Collections.Generic.IEnumerable{``0},System.Func{``0,``1},System.Func{``1,System.Collections.Generic.IEnumerable{``0},``2},System.Collections.Generic.IEqualityComparer{``1}) +example: [*content] +--- +The following code example shows how to group adjacent items in a sequence using `GroupAdjacent`: +[!code-csharp[](SuperLinq/GroupAdjacent/GroupAdjacent6.linq#L6-)] diff --git a/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent1.linq b/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent1.linq new file mode 100644 index 000000000..2c137a4e5 --- /dev/null +++ b/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent1.linq @@ -0,0 +1,35 @@ + + SuperLinq + SuperLinq + + +var sequence = new[] +{ + (key: 1, value: 123), + (key: 1, value: 456), + (key: 1, value: 789), + (key: 2, value: 987), + (key: 2, value: 654), + (key: 2, value: 321), + (key: 3, value: 789), + (key: 3, value: 456), + (key: 3, value: 123), + (key: 1, value: 123), + (key: 1, value: 456), + (key: 1, value: 781), +}; + +// Group adjacent items +var result = sequence + .GroupAdjacent( + x => x.key); + +Console.WriteLine( + "[ " + + string.Join( + ", ", + result.Select(c => "[" + string.Join(", ", c) + "]")) + + " ]"); + +// This code produces the following output: +// [ [(1, 123), (1, 456), (1, 789)], [(2, 987), (2, 654), (2, 321)], [(3, 789), (3, 456), (3, 123)], [(1, 123), (1, 456), (1, 781)] ] diff --git a/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent2.linq b/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent2.linq new file mode 100644 index 000000000..4b9f40cd5 --- /dev/null +++ b/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent2.linq @@ -0,0 +1,36 @@ + + SuperLinq + SuperLinq + + +var sequence = new[] +{ + (key: "jan", value: 123), + (key: "Jan", value: 456), + (key: "JAN", value: 789), + (key: "feb", value: 987), + (key: "Feb", value: 654), + (key: "FEB", value: 321), + (key: "mar", value: 789), + (key: "Mar", value: 456), + (key: "MAR", value: 123), + (key: "jan", value: 123), + (key: "Jan", value: 456), + (key: "JAN", value: 781), +}; + +// Group adjacent items +var result = sequence + .GroupAdjacent( + x => x.key, + StringComparer.OrdinalIgnoreCase); + +Console.WriteLine( + "[ " + + string.Join( + ", ", + result.Select(c => "[" + string.Join(", ", c) + "]")) + + " ]"); + +// This code produces the following output: +// [ [(jan, 123), (Jan, 456), (JAN, 789)], [(feb, 987), (Feb, 654), (FEB, 321)], [(mar, 789), (Mar, 456), (MAR, 123)], [(jan, 123), (Jan, 456), (JAN, 781)] ] diff --git a/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent3.linq b/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent3.linq new file mode 100644 index 000000000..18e9749db --- /dev/null +++ b/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent3.linq @@ -0,0 +1,36 @@ + + SuperLinq + SuperLinq + + +var sequence = new[] +{ + (key: 1, value: 123), + (key: 1, value: 456), + (key: 1, value: 789), + (key: 2, value: 987), + (key: 2, value: 654), + (key: 2, value: 321), + (key: 3, value: 789), + (key: 3, value: 456), + (key: 3, value: 123), + (key: 1, value: 123), + (key: 1, value: 456), + (key: 1, value: 781), +}; + +// Group adjacent items +var result = sequence + .GroupAdjacent( + x => x.key, + x => x.value); + +Console.WriteLine( + "[ " + + string.Join( + ", ", + result.Select(c => "[" + string.Join(", ", c) + "]")) + + " ]"); + +// This code produces the following output: +// [ [(1, 123), (1, 456), (1, 789)], [(2, 987), (2, 654), (2, 321)], [(3, 789), (3, 456), (3, 123)], [(1, 123), (1, 456), (1, 781)] ] diff --git a/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent4.linq b/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent4.linq new file mode 100644 index 000000000..0e172e58e --- /dev/null +++ b/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent4.linq @@ -0,0 +1,37 @@ + + SuperLinq + SuperLinq + + +var sequence = new[] +{ + (key: "jan", value: 123), + (key: "Jan", value: 456), + (key: "JAN", value: 789), + (key: "feb", value: 987), + (key: "Feb", value: 654), + (key: "FEB", value: 321), + (key: "mar", value: 789), + (key: "Mar", value: 456), + (key: "MAR", value: 123), + (key: "jan", value: 123), + (key: "Jan", value: 456), + (key: "JAN", value: 781), +}; + +// Group adjacent items +var result = sequence + .GroupAdjacent( + x => x.key, + x => x.value, + StringComparer.OrdinalIgnoreCase); + +Console.WriteLine( + "[ " + + string.Join( + ", ", + result.Select(c => "[" + string.Join(", ", c) + "]")) + + " ]"); + +// This code produces the following output: +// [ [123, 456, 789], [987, 654, 321], [789, 456, 123], [123, 456, 781] ] diff --git a/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent5.linq b/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent5.linq new file mode 100644 index 000000000..e0eaed2dd --- /dev/null +++ b/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent5.linq @@ -0,0 +1,36 @@ + + SuperLinq + SuperLinq + + +var sequence = new[] +{ + (key: 1, value: 123), + (key: 1, value: 456), + (key: 1, value: 789), + (key: 2, value: 987), + (key: 2, value: 654), + (key: 2, value: 321), + (key: 3, value: 789), + (key: 3, value: 456), + (key: 3, value: 123), + (key: 1, value: 123), + (key: 1, value: 456), + (key: 1, value: 781), +}; + +// Group adjacent items +var result = sequence + .GroupAdjacent( + x => x.key, + (k, g) => new { Key = k, Items = "[" + string.Join(", ", g.Select(x => x.value)) + "]", }); + +Console.WriteLine( + "[ " + + string.Join( + ", ", + result) + + " ]"); + +// This code produces the following output: +// [ { Key = 1, Items = [123, 456, 789] }, { Key = 2, Items = [987, 654, 321] }, { Key = 3, Items = [789, 456, 123] }, { Key = 1, Items = [123, 456, 781] } ] diff --git a/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent6.linq b/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent6.linq new file mode 100644 index 000000000..1ac065ebb --- /dev/null +++ b/Docs/SuperLinq.Docs/apidoc/SuperLinq/GroupAdjacent/GroupAdjacent6.linq @@ -0,0 +1,37 @@ + + SuperLinq + SuperLinq + + +var sequence = new[] +{ + (key: "jan", value: 123), + (key: "Jan", value: 456), + (key: "JAN", value: 789), + (key: "feb", value: 987), + (key: "Feb", value: 654), + (key: "FEB", value: 321), + (key: "mar", value: 789), + (key: "Mar", value: 456), + (key: "MAR", value: 123), + (key: "jan", value: 123), + (key: "Jan", value: 456), + (key: "JAN", value: 781), +}; + +// Group adjacent items +var result = sequence + .GroupAdjacent( + x => x.key, + (k, g) => new { Key = k, Items = "[" + string.Join(", ", g.Select(x => x.value)) + "]", }, + StringComparer.OrdinalIgnoreCase); + +Console.WriteLine( + "[ " + + string.Join( + ", ", + result) + + " ]"); + +// This code produces the following output: +// [ { Key = jan, Items = [123, 456, 789] }, { Key = feb, Items = [987, 654, 321] }, { Key = mar, Items = [789, 456, 123] }, { Key = jan, Items = [123, 456, 781] } ] diff --git a/Source/SuperLinq/GroupAdjacent.cs b/Source/SuperLinq/GroupAdjacent.cs index 649a51018..42dbe1d88 100644 --- a/Source/SuperLinq/GroupAdjacent.cs +++ b/Source/SuperLinq/GroupAdjacent.cs @@ -5,27 +5,31 @@ namespace SuperLinq; public static partial class SuperEnumerable { /// - /// Groups the adjacent elements of a sequence according to a - /// specified key selector function. + /// Groups the adjacent elements of a sequence according to a specified key selector function. /// - /// The type of the elements of - /// . - /// The type of the key returned by - /// . - /// A sequence whose elements to group. - /// A function to extract the key for each - /// element. - /// A sequence of groupings where each grouping - /// () contains the key - /// and the adjacent elements in the same order as found in the - /// source sequence. - /// is . - /// is . + /// + /// The type of the elements of . + /// + /// + /// The type of the key returned by . + /// + /// + /// A sequence whose elements to group. + /// + /// + /// A function to extract the key for each element. + /// + /// + /// A sequence of groupings where each grouping () contains the key and + /// the adjacent elements in the same order as found in the source sequence. + /// + /// + /// or is . + /// /// - /// This method is implemented by using deferred execution and - /// streams the groupings. The grouping elements, however, are - /// buffered. Each grouping is therefore yielded as soon as it - /// is complete and before the next grouping occurs. + /// This method is implemented by using deferred execution and streams the groupings. The grouping elements, + /// however, are buffered. Each grouping is therefore yielded as soon as it is complete and before the next + /// grouping occurs. /// public static IEnumerable> GroupAdjacent( this IEnumerable source, @@ -35,30 +39,35 @@ public static IEnumerable> GroupAdjacent } /// - /// Groups the adjacent elements of a sequence according to a - /// specified key selector function and compares the keys by using a - /// specified comparer. + /// Groups the adjacent elements of a sequence according to a specified key selector function and compares the + /// keys by using a specified comparer. /// - /// The type of the elements of - /// . - /// The type of the key returned by - /// . - /// A sequence whose elements to group. - /// A function to extract the key for each - /// element. - /// An to - /// compare keys. - /// A sequence of groupings where each grouping - /// () contains the key - /// and the adjacent elements in the same order as found in the - /// source sequence. - /// is . - /// is . + /// + /// The type of the elements of . + /// + /// + /// The type of the key returned by . + /// + /// + /// A sequence whose elements to group. + /// + /// + /// A function to extract the key for each element. + /// + /// + /// An to compare keys. + /// + /// + /// A sequence of groupings where each grouping () contains the key and + /// the adjacent elements in the same order as found in the source sequence. + /// + /// + /// or is . + /// /// - /// This method is implemented by using deferred execution and - /// streams the groupings. The grouping elements, however, are - /// buffered. Each grouping is therefore yielded as soon as it - /// is complete and before the next grouping occurs. + /// This method is implemented by using deferred execution and streams the groupings. The grouping elements, + /// however, are buffered. Each grouping is therefore yielded as soon as it is complete and before the next + /// grouping occurs. /// public static IEnumerable> GroupAdjacent( this IEnumerable source, @@ -72,33 +81,40 @@ public static IEnumerable> GroupAdjacent } /// - /// Groups the adjacent elements of a sequence according to a - /// specified key selector function and projects the elements for - /// each group by using a specified function. + /// Groups the adjacent elements of a sequence according to a specified key selector function and projects the + /// elements for each group by using a specified function. /// - /// The type of the elements of - /// . - /// The type of the key returned by - /// . - /// The type of the elements in the - /// resulting groupings. - /// A sequence whose elements to group. - /// A function to extract the key for each - /// element. - /// A function to map each source - /// element to an element in the resulting grouping. - /// A sequence of groupings where each grouping - /// () contains the key - /// and the adjacent elements (of type ) - /// in the same order as found in the source sequence. - /// is . - /// is . - /// is . + /// + /// The type of the elements of . + /// + /// + /// The type of the key returned by . + /// + /// + /// The type of the elements in the resulting groupings. + /// + /// + /// A sequence whose elements to group. + /// + /// + /// A function to extract the key for each element. + /// + /// + /// A function to map each source element to an element in the resulting grouping. + /// + /// + /// A sequence of groupings where each grouping () contains the key and + /// the adjacent elements (of type ) in the same order as found in the source + /// sequence. + /// + /// + /// , , or is . + /// /// - /// This method is implemented by using deferred execution and - /// streams the groupings. The grouping elements, however, are - /// buffered. Each grouping is therefore yielded as soon as it - /// is complete and before the next grouping occurs. + /// This method is implemented by using deferred execution and streams the groupings. The grouping elements, + /// however, are buffered. Each grouping is therefore yielded as soon as it is complete and before the next + /// grouping occurs. /// public static IEnumerable> GroupAdjacent( this IEnumerable source, @@ -116,36 +132,42 @@ public static IEnumerable> GroupAdjacent - /// Groups the adjacent elements of a sequence according to a - /// specified key selector function. The keys are compared by using - /// a comparer and each group's elements are projected by using a - /// specified function. + /// Groups the adjacent elements of a sequence according to a specified key selector function. The keys are + /// compared by using a comparer and each group's elements are projected by using a specified function. /// - /// The type of the elements of - /// . - /// The type of the key returned by - /// . - /// The type of the elements in the - /// resulting groupings. - /// A sequence whose elements to group. - /// A function to extract the key for each - /// element. - /// A function to map each source - /// element to an element in the resulting grouping. - /// An to - /// compare keys. - /// A sequence of groupings where each grouping - /// () contains the key - /// and the adjacent elements (of type ) - /// in the same order as found in the source sequence. - /// is . - /// is . - /// is . + /// + /// The type of the elements of . + /// + /// + /// The type of the key returned by . + /// + /// + /// The type of the elements in the resulting groupings. + /// + /// + /// A sequence whose elements to group. + /// + /// + /// A function to extract the key for each element. + /// + /// + /// A function to map each source element to an element in the resulting grouping. + /// + /// + /// An to compare keys. + /// + /// A sequence of groupings where each grouping () contains the key and + /// the adjacent elements (of type ) in the same order as found in the source + /// sequence. + /// + /// + /// , , or is . + /// /// - /// This method is implemented by using deferred execution and - /// streams the groupings. The grouping elements, however, are - /// buffered. Each grouping is therefore yielded as soon as it - /// is complete and before the next grouping occurs. + /// This method is implemented by using deferred execution and streams the groupings. The grouping elements, + /// however, are buffered. Each grouping is therefore yielded as soon as it is complete and before the next + /// grouping occurs. /// public static IEnumerable> GroupAdjacent( this IEnumerable source, @@ -164,33 +186,39 @@ public static IEnumerable> GroupAdjacent - /// Groups the adjacent elements of a sequence according to a - /// specified key selector function. The keys are compared by using - /// a comparer and each group's elements are projected by using a - /// specified function. + /// Groups the adjacent elements of a sequence according to a specified key selector function. The keys are + /// compared by using a comparer and each group's elements are projected by using a specified function. /// - /// The type of the elements of - /// . - /// The type of the key returned by - /// . - /// The type of the elements in the - /// resulting sequence. - /// A sequence whose elements to group. - /// A function to extract the key for each - /// element. - /// A function to map each key and - /// associated source elements to a result object. - /// A collection of elements of type - /// where each element represents - /// a projection over a group and its key. - /// is . - /// is . - /// is . + /// + /// The type of the elements of . + /// + /// + /// The type of the key returned by . + /// + /// + /// The type of the elements in the resulting sequence. + /// + /// + /// A sequence whose elements to group. + /// + /// + /// A function to extract the key for each element. + /// + /// + /// A function to map each key and associated source elements to a result object. + /// + /// + /// A collection of elements of type + /// where each element represents a projection over a group and its key. + /// + /// + /// , , or is . + /// /// - /// This method is implemented by using deferred execution and - /// streams the groupings. The grouping elements, however, are - /// buffered. Each grouping is therefore yielded as soon as it - /// is complete and before the next grouping occurs. + /// This method is implemented by using deferred execution and streams the groupings. The grouping elements, + /// however, are buffered. Each grouping is therefore yielded as soon as it is complete and before the next + /// grouping occurs. /// public static IEnumerable GroupAdjacent( this IEnumerable source, @@ -203,40 +231,46 @@ public static IEnumerable GroupAdjacent( return GroupAdjacentImpl( source, keySelector, Identity, - (key, group) => resultSelector(key, group), + resultSelector, comparer: null); } /// - /// Groups the adjacent elements of a sequence according to a - /// specified key selector function. The keys are compared by using - /// a comparer and each group's elements are projected by using a - /// specified function. + /// Groups the adjacent elements of a sequence according to a specified key selector function. The keys are + /// compared by using a comparer and each group's elements are projected by using a specified function. /// - /// The type of the elements of - /// . - /// The type of the key returned by - /// . - /// The type of the elements in the - /// resulting sequence. - /// A sequence whose elements to group. - /// A function to extract the key for each - /// element. - /// A function to map each key and - /// associated source elements to a result object. - /// An to - /// compare keys. - /// A collection of elements of type - /// where each element represents - /// a projection over a group and its key. - /// is . - /// is . - /// is . + /// + /// The type of the elements of . + /// + /// + /// The type of the key returned by . + /// + /// + /// The type of the elements in the resulting sequence. + /// + /// + /// A sequence whose elements to group. + /// + /// + /// A function to extract the key for each element. + /// + /// + /// A function to map each key and associated source elements to a result object. + /// + /// + /// An to compare keys. + /// + /// + /// A collection of elements of type + /// where each element represents a projection over a group and its key. + /// + /// , , or is . + /// /// - /// This method is implemented by using deferred execution and - /// streams the groupings. The grouping elements, however, are - /// buffered. Each grouping is therefore yielded as soon as it - /// is complete and before the next grouping occurs. + /// This method is implemented by using deferred execution and streams the groupings. The grouping elements, + /// however, are buffered. Each grouping is therefore yielded as soon as it is complete and before the next + /// grouping occurs. /// public static IEnumerable GroupAdjacent( this IEnumerable source, @@ -250,7 +284,7 @@ public static IEnumerable GroupAdjacent( return GroupAdjacentImpl( source, keySelector, Identity, - (key, group) => resultSelector(key, group), + resultSelector, comparer); }