Skip to content

Commit c986c52

Browse files
viceroypenguinviceroypenguin
committed
Update documentation for OrderBy and ThenBy 
1 parent a255443 commit c986c52

File tree

4 files changed

+197
-38
lines changed

4 files changed

+197
-38
lines changed

‎Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.OrderBy.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
uid: SuperLinq.SuperEnumerable.OrderBy``2(System.Collections.Generic.IEnumerable{``0},System.Func{``0,``1},SuperLinq.OrderByDirection)
3+
example: [*content]
4+
---
5+
The following code example demonstrates how to sort a sequence using `OrderBy` and `ThenBy`.
6+
[!code-csharp[](SuperLinq/OrderBy/OrderBy1.linq#L6-)]
7+
8+
---
9+
uid: SuperLinq.SuperEnumerable.ThenBy``2(System.Linq.IOrderedEnumerable{``0},System.Func{``0,``1},SuperLinq.OrderByDirection)
10+
example: [*content]
11+
---
12+
The following code example demonstrates how to sort a sequence using `OrderBy` and `ThenBy`.
13+
[!code-csharp[](SuperLinq/OrderBy/OrderBy1.linq#L6-)]
14+
15+
---
16+
uid: SuperLinq.SuperEnumerable.OrderBy``2(System.Collections.Generic.IEnumerable{``0},System.Func{``0,``1},System.Collections.Generic.IComparer{``1},SuperLinq.OrderByDirection)
17+
example: [*content]
18+
---
19+
The following code example demonstrates how to sort a sequence using `OrderBy` and `ThenBy`.
20+
[!code-csharp[](SuperLinq/OrderBy/OrderBy2.linq#L6-)]
21+
22+
---
23+
uid: SuperLinq.SuperEnumerable.ThenBy``2(System.Linq.IOrderedEnumerable{``0},System.Func{``0,``1},System.Collections.Generic.IComparer{``1},SuperLinq.OrderByDirection)
24+
example: [*content]
25+
---
26+
The following code example demonstrates how to sort a sequence using `OrderBy` and `ThenBy`.
27+
[!code-csharp[](SuperLinq/OrderBy/OrderBy2.linq#L6-)]

‎Docs/SuperLinq.Docs/apidoc/SuperLinq/OrderBy/OrderBy1.linq

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<Query Kind="Statements">
2+
<NuGetReference>SuperLinq</NuGetReference>
3+
<Namespace>SuperLinq</Namespace>
4+
</Query>
5+
6+
var fruits = new[]
7+
{
8+
"grape", "passionfruit", "banana", "Mango",
9+
"Orange", "raspberry", "apple", "blueberry",
10+
};
11+
12+
// Sort the strings first by their length and then
13+
// alphabetically by passing the identity selector function.
14+
var result = fruits
15+
.OrderBy(fruit => fruit.Length)
16+
.ThenBy(fruit => fruit);
17+
18+
Console.WriteLine(
19+
"[" +
20+
string.Join(", ", result) +
21+
"]");
22+
23+
// This code produces the following output:
24+
// [apple, grape, Mango, banana, Orange, blueberry, raspberry, passionfruit]

‎Docs/SuperLinq.Docs/apidoc/SuperLinq/OrderBy/OrderBy2.linq

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<Query Kind="Statements">
2+
<NuGetReference>SuperLinq</NuGetReference>
3+
<Namespace>SuperLinq</Namespace>
4+
</Query>
5+
6+
var fruits = new[]
7+
{
8+
"grape", "passionfruit", "banana", "Mango",
9+
"Orange", "raspberry", "apple", "blueberry",
10+
};
11+
12+
// Sort the strings first by their length and then
13+
// alphabetically by passing the identity selector function.
14+
var result = fruits
15+
.OrderBy(fruit => fruit.Length)
16+
.ThenBy(fruit => fruit, StringComparer.Ordinal);
17+
18+
Console.WriteLine(
19+
"[" +
20+
string.Join(", ", result) +
21+
"]");
22+
23+
// This code produces the following output:
24+
// [Mango, apple, grape, Orange, banana, blueberry, raspberry, passionfruit]

‎Source/SuperLinq/OrderBy.cs

Lines changed: 122 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -3,72 +3,156 @@
33
public static partial class SuperEnumerable
44
{
55
/// <summary>
6-
/// Sorts the elements of a sequence in a particular direction (ascending, descending) according to a key
6+
/// Sorts the elements of a sequence in a particular direction (ascending, descending) according to a key
77
/// </summary>
8-
/// <typeparam name="T">The type of the elements in the source sequence</typeparam>
9-
/// <typeparam name="TKey">The type of the key used to order elements</typeparam>
10-
/// <param name="source">The sequence to order</param>
11-
/// <param name="keySelector">A key selector function</param>
12-
/// <param name="direction">A direction in which to order the elements (ascending, descending)</param>
13-
/// <returns>An ordered copy of the source sequence</returns>
14-
8+
/// <typeparam name="T">
9+
/// The type of the elements in the source sequence
10+
/// </typeparam>
11+
/// <typeparam name="TKey">
12+
/// The type of the key used to order elements
13+
/// </typeparam>
14+
/// <param name="source">
15+
/// The sequence to order
16+
/// </param>
17+
/// <param name="keySelector">
18+
/// A key selector function
19+
/// </param>
20+
/// <param name="direction">
21+
/// A direction in which to order the elements (ascending, descending)
22+
/// </param>
23+
/// <exception cref="ArgumentNullException">
24+
/// <paramref name="source"/> or <paramref name="keySelector"/> is <see langword="null"/>.
25+
/// </exception>
26+
/// <returns>
27+
/// An ordered copy of the source sequence
28+
/// </returns>
29+
/// <remarks>
30+
/// <para>
31+
/// This method is implemented by using deferred execution. However, <paramref name="source"/> will be consumed
32+
/// in it's entirety immediately when first element of the returned sequence is consumed.
33+
/// </para>
34+
/// </remarks>
1535
public static IOrderedEnumerable<T> OrderBy<T, TKey>(this IEnumerable<T> source, Func<T, TKey> keySelector, OrderByDirection direction)
1636
{
1737
return OrderBy(source, keySelector, null, direction);
1838
}
1939

2040
/// <summary>
21-
/// Sorts the elements of a sequence in a particular direction (ascending, descending) according to a key
41+
/// Sorts the elements of a sequence in a particular direction (ascending, descending) according to a key
2242
/// </summary>
23-
/// <typeparam name="T">The type of the elements in the source sequence</typeparam>
24-
/// <typeparam name="TKey">The type of the key used to order elements</typeparam>
25-
/// <param name="source">The sequence to order</param>
26-
/// <param name="keySelector">A key selector function</param>
27-
/// <param name="direction">A direction in which to order the elements (ascending, descending)</param>
28-
/// <param name="comparer">A comparer used to define the semantics of element comparison</param>
29-
/// <returns>An ordered copy of the source sequence</returns>
30-
43+
/// <typeparam name="T">
44+
/// The type of the elements in the source sequence
45+
/// </typeparam>
46+
/// <typeparam name="TKey">
47+
/// The type of the key used to order elements
48+
/// </typeparam>
49+
/// <param name="source">
50+
/// The sequence to order
51+
/// </param>
52+
/// <param name="keySelector">
53+
/// A key selector function
54+
/// </param>
55+
/// <param name="comparer">
56+
/// An <see cref="IComparer{T}"/> to compare keys
57+
/// </param>
58+
/// <param name="direction">
59+
/// A direction in which to order the elements (ascending, descending)
60+
/// </param>
61+
/// <exception cref="ArgumentNullException">
62+
/// <paramref name="source"/> or <paramref name="keySelector"/> is <see langword="null"/>.
63+
/// </exception>
64+
/// <returns>
65+
/// An ordered copy of the source sequence
66+
/// </returns>
67+
/// <remarks>
68+
/// <para>
69+
/// This method is implemented by using deferred execution. However, <paramref name="source"/> will be consumed
70+
/// in it's entirety immediately when first element of the returned sequence is consumed.
71+
/// </para>
72+
/// </remarks>
3173
public static IOrderedEnumerable<T> OrderBy<T, TKey>(this IEnumerable<T> source, Func<T, TKey> keySelector, IComparer<TKey>? comparer, OrderByDirection direction)
3274
{
3375
Guard.IsNotNull(source);
3476
Guard.IsNotNull(keySelector);
3577
return direction == OrderByDirection.Ascending
36-
? source.OrderBy(keySelector, comparer)
37-
: source.OrderByDescending(keySelector, comparer);
78+
? source.OrderBy(keySelector, comparer)
79+
: source.OrderByDescending(keySelector, comparer);
3880
}
3981

4082
/// <summary>
41-
/// Performs a subsequent ordering of elements in a sequence in a particular direction (ascending, descending) according to a key
83+
/// Performs a subsequent ordering of elements of a sequence in a particular direction (ascending, descending) according to a key
4284
/// </summary>
43-
/// <typeparam name="T">The type of the elements in the source sequence</typeparam>
44-
/// <typeparam name="TKey">The type of the key used to order elements</typeparam>
45-
/// <param name="source">The sequence to order</param>
46-
/// <param name="keySelector">A key selector function</param>
47-
/// <param name="direction">A direction in which to order the elements (ascending, descending)</param>
48-
/// <returns>An ordered copy of the source sequence</returns>
49-
85+
/// <typeparam name="T">
86+
/// The type of the elements in the source sequence
87+
/// </typeparam>
88+
/// <typeparam name="TKey">
89+
/// The type of the key used to order elements
90+
/// </typeparam>
91+
/// <param name="source">
92+
/// The sequence to order
93+
/// </param>
94+
/// <param name="keySelector">
95+
/// A key selector function
96+
/// </param>
97+
/// <param name="direction">
98+
/// A direction in which to order the elements (ascending, descending)
99+
/// </param>
100+
/// <exception cref="ArgumentNullException">
101+
/// <paramref name="source"/> or <paramref name="keySelector"/> is <see langword="null"/>.
102+
/// </exception>
103+
/// <returns>
104+
/// An ordered copy of the source sequence
105+
/// </returns>
106+
/// <remarks>
107+
/// <para>
108+
/// This method is implemented by using deferred execution. However, <paramref name="source"/> will be consumed
109+
/// in it's entirety immediately when first element of the returned sequence is consumed.
110+
/// </para>
111+
/// </remarks>
50112
public static IOrderedEnumerable<T> ThenBy<T, TKey>(this IOrderedEnumerable<T> source, Func<T, TKey> keySelector, OrderByDirection direction)
51113
{
52114
return ThenBy(source, keySelector, null, direction);
53115
}
54116

55117
/// <summary>
56-
/// Performs a subsequent ordering of elements in a sequence in a particular direction (ascending, descending) according to a key
118+
/// Performs a subsequent ordering of elements of a sequence in a particular direction (ascending, descending) according to a key
57119
/// </summary>
58-
/// <typeparam name="T">The type of the elements in the source sequence</typeparam>
59-
/// <typeparam name="TKey">The type of the key used to order elements</typeparam>
60-
/// <param name="source">The sequence to order</param>
61-
/// <param name="keySelector">A key selector function</param>
62-
/// <param name="direction">A direction in which to order the elements (ascending, descending)</param>
63-
/// <param name="comparer">A comparer used to define the semantics of element comparison</param>
64-
/// <returns>An ordered copy of the source sequence</returns>
65-
120+
/// <typeparam name="T">
121+
/// The type of the elements in the source sequence
122+
/// </typeparam>
123+
/// <typeparam name="TKey">
124+
/// The type of the key used to order elements
125+
/// </typeparam>
126+
/// <param name="source">
127+
/// The sequence to order
128+
/// </param>
129+
/// <param name="keySelector">
130+
/// A key selector function
131+
/// </param>
132+
/// <param name="comparer">
133+
/// An <see cref="IComparer{T}"/> to compare keys
134+
/// </param>
135+
/// <param name="direction">
136+
/// A direction in which to order the elements (ascending, descending)
137+
/// </param>
138+
/// <exception cref="ArgumentNullException">
139+
/// <paramref name="source"/> or <paramref name="keySelector"/> is <see langword="null"/>.
140+
/// </exception>
141+
/// <returns>
142+
/// An ordered copy of the source sequence
143+
/// </returns>
144+
/// <remarks>
145+
/// <para>
146+
/// This method is implemented by using deferred execution. However, <paramref name="source"/> will be consumed
147+
/// in it's entirety immediately when first element of the returned sequence is consumed.
148+
/// </para>
149+
/// </remarks>
66150
public static IOrderedEnumerable<T> ThenBy<T, TKey>(this IOrderedEnumerable<T> source, Func<T, TKey> keySelector, IComparer<TKey>? comparer, OrderByDirection direction)
67151
{
68152
Guard.IsNotNull(source);
69153
Guard.IsNotNull(keySelector);
70154
return direction == OrderByDirection.Ascending
71-
? source.ThenBy(keySelector, comparer)
72-
: source.ThenByDescending(keySelector, comparer);
155+
? source.ThenBy(keySelector, comparer)
156+
: source.ThenByDescending(keySelector, comparer);
73157
}
74158
}

0 commit comments

Comments
 (0)