From ea3f57f66f0c0589aaea64611697312f4f6af486 Mon Sep 17 00:00:00 2001 From: Stuart Turner Date: Sat, 11 Nov 2023 18:34:45 -0600 Subject: [PATCH] Update documentation for `Segment` --- .../SuperLinq.SuperEnumerable.Segment.md | 21 +++++ .../apidoc/SuperLinq/Segment/Segment1.linq | 38 ++++++++ .../apidoc/SuperLinq/Segment/Segment2.linq | 40 +++++++++ .../apidoc/SuperLinq/Segment/Segment3.linq | 40 +++++++++ Source/SuperLinq/Segment.cs | 87 ++++++++++++++----- 5 files changed, 205 insertions(+), 21 deletions(-) create mode 100644 Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.Segment.md create mode 100644 Docs/SuperLinq.Docs/apidoc/SuperLinq/Segment/Segment1.linq create mode 100644 Docs/SuperLinq.Docs/apidoc/SuperLinq/Segment/Segment2.linq create mode 100644 Docs/SuperLinq.Docs/apidoc/SuperLinq/Segment/Segment3.linq diff --git a/Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.Segment.md b/Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.Segment.md new file mode 100644 index 000000000..a7239fb7b --- /dev/null +++ b/Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.Segment.md @@ -0,0 +1,21 @@ +--- +uid: SuperLinq.SuperEnumerable.Segment``1(System.Collections.Generic.IEnumerable{``0},System.Func{``0,System.Boolean}) +example: [*content] +--- +The following code example demonstrates how to split a sequence based on a segment detector using `Segment`. +[!code-csharp[](SuperLinq/Segment/Segment1.linq#L6-)] + +--- +uid: SuperLinq.SuperEnumerable.Segment``1(System.Collections.Generic.IEnumerable{``0},System.Func{``0,System.Int32,System.Boolean}) +example: [*content] +--- +The following code example demonstrates how to split a sequence based on a segment detector using `Segment`. +[!code-csharp[](SuperLinq/Segment/Segment2.linq#L6-)] + +--- +uid: SuperLinq.SuperEnumerable.Segment``1(System.Collections.Generic.IEnumerable{``0},System.Func{``0,``0,System.Int32,System.Boolean}) +example: [*content] +--- +The following code example demonstrates how to split a sequence based on a segment detector using `Segment`. +[!code-csharp[](SuperLinq/Segment/Segment3.linq#L6-)] + diff --git a/Docs/SuperLinq.Docs/apidoc/SuperLinq/Segment/Segment1.linq b/Docs/SuperLinq.Docs/apidoc/SuperLinq/Segment/Segment1.linq new file mode 100644 index 000000000..427c93036 --- /dev/null +++ b/Docs/SuperLinq.Docs/apidoc/SuperLinq/Segment/Segment1.linq @@ -0,0 +1,38 @@ + + 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 + .Segment( + x => x.key[0] == 'm'); + +Console.WriteLine( + "[" + Environment.NewLine + + string.Join( + ", " + Environment.NewLine, + result.Select(c => " [" + string.Join(", ", c) + "]")) + + Environment.NewLine + "]"); + +// 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/Segment/Segment2.linq b/Docs/SuperLinq.Docs/apidoc/SuperLinq/Segment/Segment2.linq new file mode 100644 index 000000000..5d7501252 --- /dev/null +++ b/Docs/SuperLinq.Docs/apidoc/SuperLinq/Segment/Segment2.linq @@ -0,0 +1,40 @@ + + 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 + .Segment( + (x, i) => i % 3 == 0); + +Console.WriteLine( + "[" + Environment.NewLine + + string.Join( + ", " + Environment.NewLine, + result.Select(c => " [" + string.Join(", ", c) + "]")) + + Environment.NewLine + "]"); + +// 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/Segment/Segment3.linq b/Docs/SuperLinq.Docs/apidoc/SuperLinq/Segment/Segment3.linq new file mode 100644 index 000000000..a0d204878 --- /dev/null +++ b/Docs/SuperLinq.Docs/apidoc/SuperLinq/Segment/Segment3.linq @@ -0,0 +1,40 @@ + + 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 + .Segment( + (cur, prev, i) => !string.Equals(cur.key[..1], prev.key[..1], StringComparison.OrdinalIgnoreCase)); + +Console.WriteLine( + "[" + Environment.NewLine + + string.Join( + ", " + Environment.NewLine, + result.Select(c => " [" + string.Join(", ", c) + "]")) + + Environment.NewLine + "]"); + +// 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/Source/SuperLinq/Segment.cs b/Source/SuperLinq/Segment.cs index 483a9bdde..f944eb075 100644 --- a/Source/SuperLinq/Segment.cs +++ b/Source/SuperLinq/Segment.cs @@ -3,16 +3,31 @@ public static partial class SuperEnumerable { /// - /// Divides a sequence into multiple sequences by using a segment detector based on the original sequence + /// Divides a sequence into multiple sequences by using a segment detector based on the original sequence /// - /// The type of the elements in the sequence - /// The sequence to segment - /// A function, which returns if the given element begins a new segment, and otherwise - /// A sequence of segment, each of which is a portion of the original sequence + /// + /// The type of the elements in the sequence + /// + /// + /// The sequence to segment + /// + /// + /// A function, which returns if the given element begins a new segment, and otherwise + /// /// - /// Thrown if either or are . + /// or is . /// - + /// + /// A sequence of segment, each of which is a portion of the original sequence + /// + /// + /// + /// 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> Segment(this IEnumerable source, Func newSegmentPredicate) { Guard.IsNotNull(newSegmentPredicate); @@ -21,16 +36,31 @@ public static IEnumerable> Segment(this IEnumerable source, } /// - /// Divides a sequence into multiple sequences by using a segment detector based on the original sequence + /// Divides a sequence into multiple sequences by using a segment detector based on the original sequence /// - /// The type of the elements in the sequence - /// The sequence to segment - /// A function, which returns if the given element or index indicate a new segment, and otherwise - /// A sequence of segment, each of which is a portion of the original sequence + /// + /// The type of the elements in the sequence + /// + /// + /// The sequence to segment + /// + /// + /// A function, which returns if the given element and index begins a new segment, and + /// otherwise + /// /// - /// Thrown if either or are . + /// or is . /// - + /// + /// A sequence of segment, each of which is a portion of the original sequence + /// + /// + /// + /// 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> Segment(this IEnumerable source, Func newSegmentPredicate) { Guard.IsNotNull(newSegmentPredicate); @@ -39,16 +69,31 @@ public static IEnumerable> Segment(this IEnumerable source, } /// - /// Divides a sequence into multiple sequences by using a segment detector based on the original sequence + /// Divides a sequence into multiple sequences by using a segment detector based on the original sequence /// - /// The type of the elements in the sequence - /// The sequence to segment - /// A function, which returns if the given current element, previous element or index indicate a new segment, and otherwise - /// A sequence of segment, each of which is a portion of the original sequence + /// + /// The type of the elements in the sequence + /// + /// + /// The sequence to segment + /// + /// + /// A function, which returns if the given current element, previous element, and index + /// begins a new segment, and otherwise + /// /// - /// Thrown if either or are . + /// or is . /// - + /// + /// A sequence of segment, each of which is a portion of the original sequence + /// + /// + /// + /// 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> Segment(this IEnumerable source, Func newSegmentPredicate) { Guard.IsNotNull(source);