From a7f00b27c676f164c1ec376a8d101f86f7d2a4a4 Mon Sep 17 00:00:00 2001 From: Shay Rojansky Date: Tue, 7 Jan 2025 23:12:33 +0100 Subject: [PATCH 1/5] XML docs for LINQ Join, LeftJoin, RightJoin See https://github.com/dotnet/runtime/pull/110872#discussion_r1904235291 --- .../src/System/Linq/Queryable.cs | 596 ++++++++++++++++++ .../System.Linq/src/System/Linq/Join.cs | 203 ++++++ .../System.Linq/src/System/Linq/LeftJoin.cs | 201 ++++++ .../System.Linq/src/System/Linq/RightJoin.cs | 199 ++++++ 4 files changed, 1199 insertions(+) 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 0bfe55333b9f1..308c2a5a1ba42 100644 --- a/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs +++ b/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs @@ -178,6 +178,104 @@ private static Expression GetSourceExpression(IEnumerable sour return q != null ? q.Expression : Expression.Constant(source, typeof(IEnumerable)); } + /// + /// Correlates the elements of two sequences based on matching keys. + /// The default equality comparer is used to compare keys. + /// + /// The first sequence to join. + /// The sequence to join to the first sequence. + /// A function to extract the join key from each element of the first sequence. + /// A function to extract the join key from each element of the second sequence. + /// A function to create a result element from two matching elements. + /// The type of the elements of the first sequence. + /// The type of the elements of the second sequence. + /// The type of the keys returned by the key selector functions. + /// The type of the result elements. + /// An that has elements of type that are obtained by performing an inner join on two sequences. + /// or or or or is . + /// + /// + /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. + /// + /// + /// class Person + /// { + /// public string Name { get; set; } + /// } + /// + /// class Pet + /// { + /// public string Name { get; set; } + /// public Person Owner { get; set; } + /// } + /// + /// public static void JoinEx1() + /// { + /// Person magnus = new Person { Name = "Hedlund, Magnus" }; + /// Person terry = new Person { Name = "Adams, Terry" }; + /// Person charlotte = new Person { Name = "Weiss, Charlotte" }; + /// Person tom = new Person { Name = "Chapkin, Tom" }; + /// + /// Pet barley = new Pet { Name = "Barley", Owner = terry }; + /// Pet boots = new Pet { Name = "Boots", Owner = terry }; + /// Pet whiskers = new Pet { Name = "Whiskers", Owner = charlotte }; + /// Pet daisy = new Pet { Name = "Daisy", Owner = magnus }; + /// + /// List{Person} people = new List{Person} { magnus, terry, charlotte, tom }; + /// List{Pet} pets = new List{Pet} { barley, boots, whiskers, daisy }; + /// + /// // Create a list of Person-Pet pairs where + /// // each element is an anonymous type that contains a + /// // Pet's name and the name of the Person that owns the Pet. + /// var query = + /// people.Join(pets, + /// person => person, + /// pet => pet.Owner, + /// (person, pet) => + /// new { OwnerName = person.Name, Pet = pet.Name }); + /// + /// foreach (var obj in query) + /// { + /// Console.WriteLine( + /// "{0} - {1}", + /// obj.OwnerName, + /// obj.Pet); + /// } + /// } + /// + /// /* + /// This code produces the following output: + /// + /// Hedlund, Magnus - Daisy + /// Adams, Terry - Barley + /// Adams, Terry - Boots + /// Weiss, Charlotte - Whiskers + /// */ + /// + /// + /// + /// + /// This method has at least one parameter of type whose type argument is one of the types. + /// For these parameters, you can pass in a lambda expression and it will be compiled to an . + /// + /// + /// The method + /// generates a that represents calling + /// + /// itself as a constructed generic method. + /// It then passes the to the method of the represented by the property of the parameter. + /// + /// + /// The query behavior that occurs as a result of executing an expression tree that represents calling + /// + /// depends on the implementation of the type of the parameter. + /// The expected behavior is that of an inner join. + /// The and functions are used to extract keys from and , respectively. + /// These keys are compared for equality to match elements from each sequence. + /// A pair of elements is stored for each element in that matches an element in . + /// Then the function is invoked to project a result object from each pair of matching elements. + /// + /// [DynamicDependency("Join`4", typeof(Enumerable))] public static IQueryable Join(this IQueryable outer, IEnumerable inner, Expression> outerKeySelector, Expression> innerKeySelector, Expression> resultSelector) { @@ -194,6 +292,106 @@ public static IQueryable Join(this IQuer outer.Expression, GetSourceExpression(inner), Expression.Quote(outerKeySelector), Expression.Quote(innerKeySelector), Expression.Quote(resultSelector))); } + /// + /// Correlates the elements of two sequences based on matching keys. + /// The default equality comparer is used to compare keys. + /// + /// The first sequence to join. + /// The sequence to join to the first sequence. + /// A function to extract the join key from each element of the first sequence. + /// A function to extract the join key from each element of the second sequence. + /// A function to create a result element from two matching elements. + /// An to hash and compare keys. + /// The type of the elements of the first sequence. + /// The type of the elements of the second sequence. + /// The type of the keys returned by the key selector functions. + /// The type of the result elements. + /// An that has elements of type that are obtained by performing an inner join on two sequences. + /// or or or or is . + /// + /// + /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. + /// + /// + /// class Person + /// { + /// public string Name { get; set; } + /// } + /// + /// class Pet + /// { + /// public string Name { get; set; } + /// public Person Owner { get; set; } + /// } + /// + /// public static void JoinEx1() + /// { + /// Person magnus = new Person { Name = "Hedlund, Magnus" }; + /// Person terry = new Person { Name = "Adams, Terry" }; + /// Person charlotte = new Person { Name = "Weiss, Charlotte" }; + /// Person tom = new Person { Name = "Chapkin, Tom" }; + /// + /// Pet barley = new Pet { Name = "Barley", Owner = terry }; + /// Pet boots = new Pet { Name = "Boots", Owner = terry }; + /// Pet whiskers = new Pet { Name = "Whiskers", Owner = charlotte }; + /// Pet daisy = new Pet { Name = "Daisy", Owner = magnus }; + /// + /// List{Person} people = new List{Person} { magnus, terry, charlotte, tom }; + /// List{Pet} pets = new List{Pet} { barley, boots, whiskers, daisy }; + /// + /// // Join the list of Person objects and the list of Pet objects + /// // to create a list of person-pet pairs where each element is + /// // an anonymous type that contains the name of pet and the name + /// // of the person that owns the pet. + /// var query = + /// people.AsQueryable().Join(pets, + /// person => person, + /// pet => pet.Owner, + /// (person, pet) => + /// new { OwnerName = person.Name, Pet = pet.Name }); + /// + /// foreach (var obj in query) + /// { + /// Console.WriteLine( + /// "{0} - {1}", + /// obj.OwnerName, + /// obj.Pet); + /// } + /// } + /// + /// /* + /// This code produces the following output: + /// + /// Hedlund, Magnus - Daisy + /// Adams, Terry - Barley + /// Adams, Terry - Boots + /// Weiss, Charlotte - Whiskers + /// */ + /// + /// + /// + /// + /// This method has at least one parameter of type whose type argument is one of the types. + /// For these parameters, you can pass in a lambda expression and it will be compiled to an . + /// + /// + /// The method + /// generates a that represents calling + /// + /// itself as a constructed generic method. + /// It then passes the to the method of the represented by the property of the parameter. + /// + /// + /// The query behavior that occurs as a result of executing an expression tree that represents calling + /// + /// depends on the implementation of the type of the parameter. + /// The expected behavior is that of an inner join. + /// The and functions are used to extract keys from and , respectively. + /// These keys are compared for equality to match elements from each sequence. + /// A pair of elements is stored for each element in that matches an element in . + /// Then the function is invoked to project a result object from each pair of matching elements. + /// + /// [DynamicDependency("Join`4", typeof(Enumerable))] public static IQueryable Join(this IQueryable outer, IEnumerable inner, Expression> outerKeySelector, Expression> innerKeySelector, Expression> resultSelector, IEqualityComparer? comparer) { @@ -242,6 +440,106 @@ public static IQueryable GroupJoin(this outer.Expression, GetSourceExpression(inner), Expression.Quote(outerKeySelector), Expression.Quote(innerKeySelector), Expression.Quote(resultSelector), Expression.Constant(comparer, typeof(IEqualityComparer)))); } + /// + /// Correlates the elements of two sequences based on matching keys; elements of the first sequence are returned regardless of whether matching elements are found in the second sequence. + /// The default equality comparer is used to compare keys. + /// + /// The first sequence to join. + /// The sequence to join to the first sequence. + /// A function to extract the join key from each element of the first sequence. + /// A function to extract the join key from each element of the second sequence. + /// A function to create a result element from two matching elements. + /// An to hash and compare keys. + /// The type of the elements of the first sequence. + /// The type of the elements of the second sequence. + /// The type of the keys returned by the key selector functions. + /// The type of the result elements. + /// An that has elements of type that are obtained by performing a left outer join on two sequences. + /// or or or or is . + /// + /// + /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. + /// + /// + /// class Person + /// { + /// public string Name { get; set; } + /// } + /// + /// class Pet + /// { + /// public string Name { get; set; } + /// public Person Owner { get; set; } + /// } + /// + /// public static void LeftJoin() + /// { + /// Person magnus = new Person { Name = "Hedlund, Magnus" }; + /// Person terry = new Person { Name = "Adams, Terry" }; + /// Person charlotte = new Person { Name = "Weiss, Charlotte" }; + /// Person tom = new Person { Name = "Chapkin, Tom" }; + /// + /// Pet barley = new Pet { Name = "Barley", Owner = terry }; + /// Pet boots = new Pet { Name = "Boots", Owner = terry }; + /// Pet whiskers = new Pet { Name = "Whiskers", Owner = charlotte }; + /// Pet daisy = new Pet { Name = "Daisy", Owner = magnus }; + /// + /// List{Person} people = new List{Person} { magnus, terry, charlotte, tom }; + /// List{Pet} pets = new List{Pet} { barley, boots, whiskers, daisy }; + /// + /// // Create a list of Person-Pet pairs where + /// // each element is an anonymous type that contains a + /// // Pet's name and the name of the Person that owns the Pet. + /// var query = + /// people.AsQueryable().LeftJoin(pets, + /// person => person, + /// pet => pet.Owner, + /// (person, pet) => + /// new { OwnerName = person.Name, Pet = pet?.Name }); + /// + /// foreach (var obj in query) + /// { + /// Console.WriteLine( + /// "{0} - {1}", + /// obj.OwnerName, + /// obj.Pet ?? "NONE"); + /// } + /// } + /// + /// /* + /// This code produces the following output: + /// + /// Hedlund, Magnus - Daisy + /// Adams, Terry - Barley + /// Adams, Terry - Boots + /// Weiss, Charlotte - Whiskers + /// Chapkin, Tom - NONE + /// */ + /// + /// + /// + /// + /// This method has at least one parameter of type whose type argument is one of the types. + /// For these parameters, you can pass in a lambda expression and it will be compiled to an . + /// + /// + /// The method + /// generates a that represents calling + /// + /// itself as a constructed generic method. + /// It then passes the to the method of the represented by the property of the parameter. + /// + /// + /// The query behavior that occurs as a result of executing an expression tree that represents calling + /// + /// depends on the implementation of the type of the parameter. + /// The expected behavior is that of a left outer join. + /// The and functions are used to extract keys from and , respectively. + /// These keys are compared for equality to match elements from each sequence. + /// A pair of elements is stored for each element in that matches an element in , plus a pair for each element in that has no matches in . + /// Then the function is invoked to project a result object from each pair of elements. + /// + /// [DynamicDependency("LeftJoin`4", typeof(Enumerable))] public static IQueryable LeftJoin(this IQueryable outer, IEnumerable inner, Expression> outerKeySelector, Expression> innerKeySelector, Expression> resultSelector) { @@ -258,6 +556,106 @@ public static IQueryable LeftJoin(this I outer.Expression, GetSourceExpression(inner), Expression.Quote(outerKeySelector), Expression.Quote(innerKeySelector), Expression.Quote(resultSelector))); } + /// + /// Correlates the elements of two sequences based on matching keys; elements of the first sequence are returned regardless of whether matching elements are found in the second sequence. + /// The default equality comparer is used to compare keys. + /// + /// The first sequence to join. + /// The sequence to join to the first sequence. + /// A function to extract the join key from each element of the first sequence. + /// A function to extract the join key from each element of the second sequence. + /// A function to create a result element from two matching elements. + /// An to hash and compare keys. + /// The type of the elements of the first sequence. + /// The type of the elements of the second sequence. + /// The type of the keys returned by the key selector functions. + /// The type of the result elements. + /// An that has elements of type that are obtained by performing a left outer join on two sequences. + /// or or or or is . + /// + /// + /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. + /// + /// + /// class Person + /// { + /// public string Name { get; set; } + /// } + /// + /// class Pet + /// { + /// public string Name { get; set; } + /// public Person Owner { get; set; } + /// } + /// + /// public static void LeftJoin() + /// { + /// Person magnus = new Person { Name = "Hedlund, Magnus" }; + /// Person terry = new Person { Name = "Adams, Terry" }; + /// Person charlotte = new Person { Name = "Weiss, Charlotte" }; + /// Person tom = new Person { Name = "Chapkin, Tom" }; + /// + /// Pet barley = new Pet { Name = "Barley", Owner = terry }; + /// Pet boots = new Pet { Name = "Boots", Owner = terry }; + /// Pet whiskers = new Pet { Name = "Whiskers", Owner = charlotte }; + /// Pet daisy = new Pet { Name = "Daisy", Owner = magnus }; + /// + /// List{Person} people = new List{Person} { magnus, terry, charlotte, tom }; + /// List{Pet} pets = new List{Pet} { barley, boots, whiskers, daisy }; + /// + /// // Create a list of Person-Pet pairs where + /// // each element is an anonymous type that contains a + /// // Pet's name and the name of the Person that owns the Pet. + /// var query = + /// people.AsQueryable().LeftJoin(pets, + /// person => person, + /// pet => pet.Owner, + /// (person, pet) => + /// new { OwnerName = person.Name, Pet = pet?.Name }); + /// + /// foreach (var obj in query) + /// { + /// Console.WriteLine( + /// "{0} - {1}", + /// obj.OwnerName, + /// obj.Pet ?? "NONE"); + /// } + /// } + /// + /// /* + /// This code produces the following output: + /// + /// Hedlund, Magnus - Daisy + /// Adams, Terry - Barley + /// Adams, Terry - Boots + /// Weiss, Charlotte - Whiskers + /// Chapkin, Tom - NONE + /// */ + /// + /// + /// + /// + /// This method has at least one parameter of type whose type argument is one of the types. + /// For these parameters, you can pass in a lambda expression and it will be compiled to an . + /// + /// + /// The method + /// generates a that represents calling + /// + /// itself as a constructed generic method. + /// It then passes the to the method of the represented by the property of the parameter. + /// + /// + /// The query behavior that occurs as a result of executing an expression tree that represents calling + /// + /// depends on the implementation of the type of the parameter. + /// The expected behavior is that of a left outer join. + /// The and functions are used to extract keys from and , respectively. + /// These keys are compared for equality to match elements from each sequence. + /// A pair of elements is stored for each element in that matches an element in , plus a pair for each element in that has no matches in . + /// Then the function is invoked to project a result object from each pair of elements. + /// + /// [DynamicDependency("LeftJoin`4", typeof(Enumerable))] public static IQueryable LeftJoin(this IQueryable outer, IEnumerable inner, Expression> outerKeySelector, Expression> innerKeySelector, Expression> resultSelector, IEqualityComparer? comparer) { @@ -472,6 +870,105 @@ public static IOrderedQueryable OrderByDescending(this I source.Expression, Expression.Quote(keySelector), Expression.Constant(comparer, typeof(IComparer)))); } + /// + /// Correlates the elements of two sequences based on matching keys; elements of the second sequence are returned regardless of whether matching elements are found in the first sequence. + /// The default equality comparer is used to compare keys. + /// + /// The first sequence to join. + /// The sequence to join to the first sequence. + /// A function to extract the join key from each element of the first sequence. + /// A function to extract the join key from each element of the second sequence. + /// A function to create a result element from two matching elements. + /// An to hash and compare keys. + /// The type of the elements of the first sequence. + /// The type of the elements of the second sequence. + /// The type of the keys returned by the key selector functions. + /// The type of the result elements. + /// An that has elements of type that are obtained by performing a right outer join on two sequences. + /// or or or or is . + /// + /// + /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. + /// + /// + /// class Person + /// { + /// public string Name { get; set; } + /// } + /// + /// class Pet + /// { + /// public string Name { get; set; } + /// public Person Owner { get; set; } + /// } + /// + /// public static void LeftJoin() + /// { + /// Person magnus = new Person { Name = "Hedlund, Magnus" }; + /// Person terry = new Person { Name = "Adams, Terry" }; + /// Person charlotte = new Person { Name = "Weiss, Charlotte" }; + /// Person tom = new Person { Name = "Chapkin, Tom" }; + /// + /// Pet barley = new Pet { Name = "Barley", Owner = terry }; + /// Pet boots = new Pet { Name = "Boots", Owner = terry }; + /// Pet whiskers = new Pet { Name = "Whiskers", Owner = charlotte }; + /// Pet daisy = new Pet { Name = "Daisy", Owner = magnus }; + /// + /// List{Person} people = new List{Person} { terry, charlotte, tom }; + /// List{Pet} pets = new List{Pet} { barley, boots, whiskers, daisy }; + /// + /// // Create a list of Person-Pet pairs where + /// // each element is an anonymous type that contains a + /// // Pet's name and the name of the Person that owns the Pet. + /// var query = + /// people.AsQueryable().RightJoin(pets, + /// person => person, + /// pet => pet.Owner, + /// (person, pet) => + /// new { OwnerName = person?.Name, Pet = pet.Name }); + /// + /// foreach (var obj in query) + /// { + /// Console.WriteLine( + /// "{0} - {1}", + /// obj.OwnerName ?? "NONE", + /// obj.Pet); + /// } + /// } + /// + /// /* + /// This code produces the following output: + /// + /// NONE - Daisy + /// Adams, Terry - Barley + /// Adams, Terry - Boots + /// Weiss, Charlotte - Whiskers + /// */ + /// + /// + /// + /// + /// This method has at least one parameter of type whose type argument is one of the types. + /// For these parameters, you can pass in a lambda expression and it will be compiled to an . + /// + /// + /// The method + /// generates a that represents calling + /// + /// itself as a constructed generic method. + /// It then passes the to the method of the represented by the property of the parameter. + /// + /// + /// The query behavior that occurs as a result of executing an expression tree that represents calling + /// + /// depends on the implementation of the type of the parameter. + /// The expected behavior is that of a right outer join. + /// The and functions are used to extract keys from and , respectively. + /// These keys are compared for equality to match elements from each sequence. + /// A pair of elements is stored for each element in that matches an element in , plus a pair for each element in that has no matches in . + /// Then the function is invoked to project a result object from each pair of elements. + /// + /// [DynamicDependency("RightJoin`4", typeof(Enumerable))] public static IQueryable RightJoin(this IQueryable outer, IEnumerable inner, Expression> outerKeySelector, Expression> innerKeySelector, Expression> resultSelector) { @@ -488,6 +985,105 @@ public static IQueryable RightJoin(this outer.Expression, GetSourceExpression(inner), Expression.Quote(outerKeySelector), Expression.Quote(innerKeySelector), Expression.Quote(resultSelector))); } + /// + /// Correlates the elements of two sequences based on matching keys; elements of the second sequence are returned regardless of whether matching elements are found in the first sequence. + /// The default equality comparer is used to compare keys. + /// + /// The first sequence to join. + /// The sequence to join to the first sequence. + /// A function to extract the join key from each element of the first sequence. + /// A function to extract the join key from each element of the second sequence. + /// A function to create a result element from two matching elements. + /// An to hash and compare keys. + /// The type of the elements of the first sequence. + /// The type of the elements of the second sequence. + /// The type of the keys returned by the key selector functions. + /// The type of the result elements. + /// An that has elements of type that are obtained by performing a right outer join on two sequences. + /// or or or or is . + /// + /// + /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. + /// + /// + /// class Person + /// { + /// public string Name { get; set; } + /// } + /// + /// class Pet + /// { + /// public string Name { get; set; } + /// public Person Owner { get; set; } + /// } + /// + /// public static void LeftJoin() + /// { + /// Person magnus = new Person { Name = "Hedlund, Magnus" }; + /// Person terry = new Person { Name = "Adams, Terry" }; + /// Person charlotte = new Person { Name = "Weiss, Charlotte" }; + /// Person tom = new Person { Name = "Chapkin, Tom" }; + /// + /// Pet barley = new Pet { Name = "Barley", Owner = terry }; + /// Pet boots = new Pet { Name = "Boots", Owner = terry }; + /// Pet whiskers = new Pet { Name = "Whiskers", Owner = charlotte }; + /// Pet daisy = new Pet { Name = "Daisy", Owner = magnus }; + /// + /// List{Person} people = new List{Person} { terry, charlotte, tom }; + /// List{Pet} pets = new List{Pet} { barley, boots, whiskers, daisy }; + /// + /// // Create a list of Person-Pet pairs where + /// // each element is an anonymous type that contains a + /// // Pet's name and the name of the Person that owns the Pet. + /// var query = + /// people.AsQueryable().RightJoin(pets, + /// person => person, + /// pet => pet.Owner, + /// (person, pet) => + /// new { OwnerName = person?.Name, Pet = pet.Name }); + /// + /// foreach (var obj in query) + /// { + /// Console.WriteLine( + /// "{0} - {1}", + /// obj.OwnerName ?? "NONE", + /// obj.Pet); + /// } + /// } + /// + /// /* + /// This code produces the following output: + /// + /// NONE - Daisy + /// Adams, Terry - Barley + /// Adams, Terry - Boots + /// Weiss, Charlotte - Whiskers + /// */ + /// + /// + /// + /// + /// This method has at least one parameter of type whose type argument is one of the types. + /// For these parameters, you can pass in a lambda expression and it will be compiled to an . + /// + /// + /// The method + /// generates a that represents calling + /// + /// itself as a constructed generic method. + /// It then passes the to the method of the represented by the property of the parameter. + /// + /// + /// The query behavior that occurs as a result of executing an expression tree that represents calling + /// + /// depends on the implementation of the type of the parameter. + /// The expected behavior is that of a right outer join. + /// The and functions are used to extract keys from and , respectively. + /// These keys are compared for equality to match elements from each sequence. + /// A pair of elements is stored for each element in that matches an element in , plus a pair for each element in that has no matches in . + /// Then the function is invoked to project a result object from each pair of elements. + /// + /// [DynamicDependency("RightJoin`4", typeof(Enumerable))] public static IQueryable RightJoin(this IQueryable outer, IEnumerable inner, Expression> outerKeySelector, Expression> innerKeySelector, Expression> resultSelector, IEqualityComparer? comparer) { diff --git a/src/libraries/System.Linq/src/System/Linq/Join.cs b/src/libraries/System.Linq/src/System/Linq/Join.cs index e9fc4a73afc09..d8946cddba9db 100644 --- a/src/libraries/System.Linq/src/System/Linq/Join.cs +++ b/src/libraries/System.Linq/src/System/Linq/Join.cs @@ -7,9 +7,212 @@ namespace System.Linq { public static partial class Enumerable { + /// + /// Correlates the elements of two sequences based on matching keys. + /// The default equality comparer is used to compare keys. + /// + /// The first sequence to join. + /// The sequence to join to the first sequence. + /// A function to extract the join key from each element of the first sequence. + /// A function to extract the join key from each element of the second sequence. + /// A function to create a result element from two matching elements. + /// The type of the elements of the first sequence. + /// The type of the elements of the second sequence. + /// The type of the keys returned by the key selector functions. + /// The type of the result elements. + /// An that has elements of type that are obtained by performing an inner join on two sequences. + /// or or or or is . + /// + /// + /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. + /// + /// + /// class Person + /// { + /// public string Name { get; set; } + /// } + /// + /// class Pet + /// { + /// public string Name { get; set; } + /// public Person Owner { get; set; } + /// } + /// + /// public static void JoinEx1() + /// { + /// Person magnus = new Person { Name = "Hedlund, Magnus" }; + /// Person terry = new Person { Name = "Adams, Terry" }; + /// Person charlotte = new Person { Name = "Weiss, Charlotte" }; + /// Person tom = new Person { Name = "Chapkin, Tom" }; + /// + /// Pet barley = new Pet { Name = "Barley", Owner = terry }; + /// Pet boots = new Pet { Name = "Boots", Owner = terry }; + /// Pet whiskers = new Pet { Name = "Whiskers", Owner = charlotte }; + /// Pet daisy = new Pet { Name = "Daisy", Owner = magnus }; + /// + /// List{Person} people = new List{Person} { magnus, terry, charlotte, tom }; + /// List{Pet} pets = new List{Pet} { barley, boots, whiskers, daisy }; + /// + /// // Create a list of Person-Pet pairs where + /// // each element is an anonymous type that contains a + /// // Pet's name and the name of the Person that owns the Pet. + /// var query = + /// people.Join(pets, + /// person => person, + /// pet => pet.Owner, + /// (person, pet) => + /// new { OwnerName = person.Name, Pet = pet.Name }); + /// + /// foreach (var obj in query) + /// { + /// Console.WriteLine( + /// "{0} - {1}", + /// obj.OwnerName, + /// obj.Pet); + /// } + /// } + /// + /// /* + /// This code produces the following output: + /// + /// Hedlund, Magnus - Daisy + /// Adams, Terry - Barley + /// Adams, Terry - Boots + /// Weiss, Charlotte - Whiskers + /// */ + /// + /// + /// + /// + /// 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 C# or For Each in Visual Basic. + /// + /// + /// The default equality comparer, , is used to hash and compare keys. + /// + /// + /// A join refers to the operation of correlating the elements of two sources of information based on a common key. + /// + /// brings the two information sources and the keys by which they are matched together in one method call. + /// + /// + /// In relational database terms, the method implements an inner equijoin. + /// 'Inner' means that only elements that have a match in the other sequence are included in the results. + /// An 'equijoin' is a join in which the keys are compared for equality. + /// An left outer join can be performed using the + /// method, + /// and a right outer join can be performed using the + /// method, + /// For more information, see Join operations. + /// + /// public static IEnumerable Join(this IEnumerable outer, IEnumerable inner, Func outerKeySelector, Func innerKeySelector, Func resultSelector) => Join(outer, inner, outerKeySelector, innerKeySelector, resultSelector, comparer: null); + /// + /// Correlates the elements of two sequences based on matching keys. + /// The default equality comparer is used to compare keys. + /// + /// The first sequence to join. + /// The sequence to join to the first sequence. + /// A function to extract the join key from each element of the first sequence. + /// A function to extract the join key from each element of the second sequence. + /// A function to create a result element from two matching elements. + /// An to hash and compare keys. + /// The type of the elements of the first sequence. + /// The type of the elements of the second sequence. + /// The type of the keys returned by the key selector functions. + /// The type of the result elements. + /// An that has elements of type that are obtained by performing an inner join on two sequences. + /// or or or or is . + /// + /// + /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. + /// + /// + /// class Person + /// { + /// public string Name { get; set; } + /// } + /// + /// class Pet + /// { + /// public string Name { get; set; } + /// public Person Owner { get; set; } + /// } + /// + /// public static void JoinEx1() + /// { + /// Person magnus = new Person { Name = "Hedlund, Magnus" }; + /// Person terry = new Person { Name = "Adams, Terry" }; + /// Person charlotte = new Person { Name = "Weiss, Charlotte" }; + /// Person tom = new Person { Name = "Chapkin, Tom" }; + /// + /// Pet barley = new Pet { Name = "Barley", Owner = terry }; + /// Pet boots = new Pet { Name = "Boots", Owner = terry }; + /// Pet whiskers = new Pet { Name = "Whiskers", Owner = charlotte }; + /// Pet daisy = new Pet { Name = "Daisy", Owner = magnus }; + /// + /// List{Person} people = new List{Person} { magnus, terry, charlotte, tom }; + /// List{Pet} pets = new List{Pet} { barley, boots, whiskers, daisy }; + /// + /// // Create a list of Person-Pet pairs where + /// // each element is an anonymous type that contains a + /// // Pet's name and the name of the Person that owns the Pet. + /// var query = + /// people.Join(pets, + /// person => person, + /// pet => pet.Owner, + /// (person, pet) => + /// new { OwnerName = person.Name, Pet = pet.Name }); + /// + /// foreach (var obj in query) + /// { + /// Console.WriteLine( + /// "{0} - {1}", + /// obj.OwnerName, + /// obj.Pet); + /// } + /// } + /// + /// /* + /// This code produces the following output: + /// + /// Hedlund, Magnus - Daisy + /// Adams, Terry - Barley + /// Adams, Terry - Boots + /// Weiss, Charlotte - Whiskers + /// */ + /// + /// + /// + /// + /// 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 C# or For Each in Visual Basic. + /// + /// + /// The default equality comparer, , is used to hash and compare keys. + /// + /// + /// A join refers to the operation of correlating the elements of two sources of information based on a common key. + /// + /// brings the two information sources and the keys by which they are matched together in one method call. + /// + /// + /// In relational database terms, the method implements an inner equijoin. + /// 'Inner' means that only elements that have a match in the other sequence are included in the results. + /// An 'equijoin' is a join in which the keys are compared for equality. + /// An left outer join can be performed using the + /// method, + /// and a right outer join can be performed using the + /// method, + /// For more information, see Join operations. + /// + /// public static IEnumerable Join(this IEnumerable outer, IEnumerable inner, Func outerKeySelector, Func innerKeySelector, Func resultSelector, IEqualityComparer? comparer) { if (outer is null) diff --git a/src/libraries/System.Linq/src/System/Linq/LeftJoin.cs b/src/libraries/System.Linq/src/System/Linq/LeftJoin.cs index 10130cc7eddc2..a9427404a8701 100644 --- a/src/libraries/System.Linq/src/System/Linq/LeftJoin.cs +++ b/src/libraries/System.Linq/src/System/Linq/LeftJoin.cs @@ -7,9 +7,210 @@ namespace System.Linq { public static partial class Enumerable { + /// + /// Correlates the elements of two sequences based on matching keys; elements of the first sequence are returned regardless of whether matching elements are found in the second sequence. + /// The default equality comparer is used to compare keys. + /// + /// The first sequence to join. + /// The sequence to join to the first sequence. + /// A function to extract the join key from each element of the first sequence. + /// A function to extract the join key from each element of the second sequence. + /// A function to create a result element from two matching elements. + /// The type of the elements of the first sequence. + /// The type of the elements of the second sequence. + /// The type of the keys returned by the key selector functions. + /// The type of the result elements. + /// An that has elements of type that are obtained by performing a left outer join on two sequences. + /// or or or or is . + /// + /// + /// The following code example demonstrates how to use to perform aa left outer join of two sequences based on a common key. + /// + /// + /// class Person + /// { + /// public string Name { get; set; } + /// } + /// + /// class Pet + /// { + /// public string Name { get; set; } + /// public Person Owner { get; set; } + /// } + /// + /// public static void LeftJoin() + /// { + /// Person magnus = new Person { Name = "Hedlund, Magnus" }; + /// Person terry = new Person { Name = "Adams, Terry" }; + /// Person charlotte = new Person { Name = "Weiss, Charlotte" }; + /// Person tom = new Person { Name = "Chapkin, Tom" }; + /// + /// Pet barley = new Pet { Name = "Barley", Owner = terry }; + /// Pet boots = new Pet { Name = "Boots", Owner = terry }; + /// Pet whiskers = new Pet { Name = "Whiskers", Owner = charlotte }; + /// Pet daisy = new Pet { Name = "Daisy", Owner = magnus }; + /// + /// List{Person} people = new List{Person} { magnus, terry, charlotte, tom }; + /// List{Pet} pets = new List{Pet} { barley, boots, whiskers, daisy }; + /// + /// // Create a list of Person-Pet pairs where + /// // each element is an anonymous type that contains a + /// // Pet's name and the name of the Person that owns the Pet. + /// var query = + /// people.LeftJoin(pets, + /// person => person, + /// pet => pet.Owner, + /// (person, pet) => + /// new { OwnerName = person.Name, Pet = pet?.Name }); + /// + /// foreach (var obj in query) + /// { + /// Console.WriteLine( + /// "{0} - {1}", + /// obj.OwnerName, + /// obj.Pet ?? "NONE"); + /// } + /// } + /// + /// /* + /// This code produces the following output: + /// + /// Hedlund, Magnus - Daisy + /// Adams, Terry - Barley + /// Adams, Terry - Boots + /// Weiss, Charlotte - Whiskers + /// Chapkin, Tom - NONE + /// */ + /// + /// + /// + /// + /// 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 C# or For Each in Visual Basic. + /// + /// + /// The default equality comparer, , is used to hash and compare keys. + /// + /// + /// A join refers to the operation of correlating the elements of two sources of information based on a common key. + /// + /// brings the two information sources and the keys by which they are matched together in one method call. + /// + /// + /// In relational database terms, the method implements an outer left equijoin. + /// 'Outer left' means that elements of the first sequence are returned regardless of whether matching elements are found in the other sequence. + /// An 'equijoin' is a join in which the keys are compared for equality. + /// An inner join - where only elements that have a match in the other sequence are included in the results - can be performed using the + /// method. + /// For more information, see Join operations. + /// + /// public static IEnumerable LeftJoin(this IEnumerable outer, IEnumerable inner, Func outerKeySelector, Func innerKeySelector, Func resultSelector) => LeftJoin(outer, inner, outerKeySelector, innerKeySelector, resultSelector, comparer: null); + /// + /// Correlates the elements of two sequences based on matching keys; elements of the first sequence are returned regardless of whether matching elements are found in the second sequence. + /// The default equality comparer is used to compare keys. + /// + /// The first sequence to join. + /// The sequence to join to the first sequence. + /// A function to extract the join key from each element of the first sequence. + /// A function to extract the join key from each element of the second sequence. + /// A function to create a result element from two matching elements. + /// An to hash and compare keys. + /// The type of the elements of the first sequence. + /// The type of the elements of the second sequence. + /// The type of the keys returned by the key selector functions. + /// The type of the result elements. + /// An that has elements of type that are obtained by performing a left outer join on two sequences. + /// or or or or is . + /// + /// + /// The following code example demonstrates how to use to perform aa left outer join of two sequences based on a common key. + /// + /// + /// class Person + /// { + /// public string Name { get; set; } + /// } + /// + /// class Pet + /// { + /// public string Name { get; set; } + /// public Person Owner { get; set; } + /// } + /// + /// public static void LeftJoin() + /// { + /// Person magnus = new Person { Name = "Hedlund, Magnus" }; + /// Person terry = new Person { Name = "Adams, Terry" }; + /// Person charlotte = new Person { Name = "Weiss, Charlotte" }; + /// Person tom = new Person { Name = "Chapkin, Tom" }; + /// + /// Pet barley = new Pet { Name = "Barley", Owner = terry }; + /// Pet boots = new Pet { Name = "Boots", Owner = terry }; + /// Pet whiskers = new Pet { Name = "Whiskers", Owner = charlotte }; + /// Pet daisy = new Pet { Name = "Daisy", Owner = magnus }; + /// + /// List{Person} people = new List{Person} { magnus, terry, charlotte, tom }; + /// List{Pet} pets = new List{Pet} { barley, boots, whiskers, daisy }; + /// + /// // Create a list of Person-Pet pairs where + /// // each element is an anonymous type that contains a + /// // Pet's name and the name of the Person that owns the Pet. + /// var query = + /// people.LeftJoin(pets, + /// person => person, + /// pet => pet.Owner, + /// (person, pet) => + /// new { OwnerName = person.Name, Pet = pet?.Name }); + /// + /// foreach (var obj in query) + /// { + /// Console.WriteLine( + /// "{0} - {1}", + /// obj.OwnerName, + /// obj.Pet ?? "NONE"); + /// } + /// } + /// + /// /* + /// This code produces the following output: + /// + /// Hedlund, Magnus - Daisy + /// Adams, Terry - Barley + /// Adams, Terry - Boots + /// Weiss, Charlotte - Whiskers + /// Chapkin, Tom - NONE + /// */ + /// + /// + /// + /// + /// 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 C# or For Each in Visual Basic. + /// + /// + /// The default equality comparer, , is used to hash and compare keys. + /// + /// + /// A join refers to the operation of correlating the elements of two sources of information based on a common key. + /// + /// brings the two information sources and the keys by which they are matched together in one method call. + /// + /// + /// In relational database terms, the method implements an outer left equijoin. + /// 'Outer left' means that elements of the first sequence are returned regardless of whether matching elements are found in the other sequence. + /// An 'equijoin' is a join in which the keys are compared for equality. + /// An inner join - where only elements that have a match in the other sequence are included in the results - can be performed using the + /// method. + /// For more information, see Join operations. + /// + /// public static IEnumerable LeftJoin(this IEnumerable outer, IEnumerable inner, Func outerKeySelector, Func innerKeySelector, Func resultSelector, IEqualityComparer? comparer) { if (outer is null) diff --git a/src/libraries/System.Linq/src/System/Linq/RightJoin.cs b/src/libraries/System.Linq/src/System/Linq/RightJoin.cs index b2524136c9c9c..c87b9f3817b14 100644 --- a/src/libraries/System.Linq/src/System/Linq/RightJoin.cs +++ b/src/libraries/System.Linq/src/System/Linq/RightJoin.cs @@ -7,9 +7,208 @@ namespace System.Linq { public static partial class Enumerable { + /// + /// Correlates the elements of two sequences based on matching keys; elements of the second sequence are returned regardless of whether matching elements are found in the first sequence. + /// The default equality comparer is used to compare keys. + /// + /// The first sequence to join. + /// The sequence to join to the first sequence. + /// A function to extract the join key from each element of the first sequence. + /// A function to extract the join key from each element of the second sequence. + /// A function to create a result element from two matching elements. + /// The type of the elements of the first sequence. + /// The type of the elements of the second sequence. + /// The type of the keys returned by the key selector functions. + /// The type of the result elements. + /// An that has elements of type that are obtained by performing a right outer join on two sequences. + /// or or or or is . + /// + /// + /// The following code example demonstrates how to use to perform aa left outer join of two sequences based on a common key. + /// + /// + /// class Person + /// { + /// public string Name { get; set; } + /// } + /// + /// class Pet + /// { + /// public string Name { get; set; } + /// public Person Owner { get; set; } + /// } + /// + /// public static void LeftJoin() + /// { + /// Person magnus = new Person { Name = "Hedlund, Magnus" }; + /// Person terry = new Person { Name = "Adams, Terry" }; + /// Person charlotte = new Person { Name = "Weiss, Charlotte" }; + /// Person tom = new Person { Name = "Chapkin, Tom" }; + /// + /// Pet barley = new Pet { Name = "Barley", Owner = terry }; + /// Pet boots = new Pet { Name = "Boots", Owner = terry }; + /// Pet whiskers = new Pet { Name = "Whiskers", Owner = charlotte }; + /// Pet daisy = new Pet { Name = "Daisy", Owner = magnus }; + /// + /// List{Person} people = new List{Person} { terry, charlotte, tom }; + /// List{Pet} pets = new List{Pet} { barley, boots, whiskers, daisy }; + /// + /// // Create a list of Person-Pet pairs where + /// // each element is an anonymous type that contains a + /// // Pet's name and the name of the Person that owns the Pet. + /// var query = + /// people.RightJoin(pets, + /// person => person, + /// pet => pet.Owner, + /// (person, pet) => + /// new { OwnerName = person?.Name, Pet = pet.Name }); + /// + /// foreach (var obj in query) + /// { + /// Console.WriteLine( + /// "{0} - {1}", + /// obj.OwnerName ?? "NONE", + /// obj.Pet); + /// } + /// } + /// + /// /* + /// This code produces the following output: + /// + /// NONE - Daisy + /// Adams, Terry - Barley + /// Adams, Terry - Boots + /// Weiss, Charlotte - Whiskers + /// */ + /// + /// + /// + /// + /// 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 C# or For Each in Visual Basic. + /// + /// + /// The default equality comparer, , is used to hash and compare keys. + /// + /// + /// A join refers to the operation of correlating the elements of two sources of information based on a common key. + /// + /// brings the two information sources and the keys by which they are matched together in one method call. + /// + /// + /// In relational database terms, the method implements an outer right equijoin. + /// 'Outer right' means that elements of the second sequence are returned regardless of whether matching elements are found in the other sequence. + /// An 'equijoin' is a join in which the keys are compared for equality. + /// An inner join - where only elements that have a match in the other sequence are included in the results - can be performed using the + /// method. + /// For more information, see Join operations. + /// + /// public static IEnumerable RightJoin(this IEnumerable outer, IEnumerable inner, Func outerKeySelector, Func innerKeySelector, Func resultSelector) => RightJoin(outer, inner, outerKeySelector, innerKeySelector, resultSelector, comparer: null); + /// + /// Correlates the elements of two sequences based on matching keys; elements of the second sequence are returned regardless of whether matching elements are found in the first sequence. + /// The default equality comparer is used to compare keys. + /// + /// The first sequence to join. + /// The sequence to join to the first sequence. + /// A function to extract the join key from each element of the first sequence. + /// A function to extract the join key from each element of the second sequence. + /// A function to create a result element from two matching elements. + /// An to hash and compare keys. + /// The type of the elements of the first sequence. + /// The type of the elements of the second sequence. + /// The type of the keys returned by the key selector functions. + /// The type of the result elements. + /// An that has elements of type that are obtained by performing a right outer join on two sequences. + /// or or or or is . + /// + /// + /// The following code example demonstrates how to use to perform aa left outer join of two sequences based on a common key. + /// + /// + /// class Person + /// { + /// public string Name { get; set; } + /// } + /// + /// class Pet + /// { + /// public string Name { get; set; } + /// public Person Owner { get; set; } + /// } + /// + /// public static void LeftJoin() + /// { + /// Person magnus = new Person { Name = "Hedlund, Magnus" }; + /// Person terry = new Person { Name = "Adams, Terry" }; + /// Person charlotte = new Person { Name = "Weiss, Charlotte" }; + /// Person tom = new Person { Name = "Chapkin, Tom" }; + /// + /// Pet barley = new Pet { Name = "Barley", Owner = terry }; + /// Pet boots = new Pet { Name = "Boots", Owner = terry }; + /// Pet whiskers = new Pet { Name = "Whiskers", Owner = charlotte }; + /// Pet daisy = new Pet { Name = "Daisy", Owner = magnus }; + /// + /// List{Person} people = new List{Person} { terry, charlotte, tom }; + /// List{Pet} pets = new List{Pet} { barley, boots, whiskers, daisy }; + /// + /// // Create a list of Person-Pet pairs where + /// // each element is an anonymous type that contains a + /// // Pet's name and the name of the Person that owns the Pet. + /// var query = + /// people.RightJoin(pets, + /// person => person, + /// pet => pet.Owner, + /// (person, pet) => + /// new { OwnerName = person?.Name, Pet = pet.Name }); + /// + /// foreach (var obj in query) + /// { + /// Console.WriteLine( + /// "{0} - {1}", + /// obj.OwnerName ?? "NONE", + /// obj.Pet); + /// } + /// } + /// + /// /* + /// This code produces the following output: + /// + /// NONE - Daisy + /// Adams, Terry - Barley + /// Adams, Terry - Boots + /// Weiss, Charlotte - Whiskers + /// */ + /// + /// + /// + /// + /// 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 C# or For Each in Visual Basic. + /// + /// + /// The default equality comparer, , is used to hash and compare keys. + /// + /// + /// A join refers to the operation of correlating the elements of two sources of information based on a common key. + /// + /// brings the two information sources and the keys by which they are matched together in one method call. + /// + /// + /// In relational database terms, the method implements an outer right equijoin. + /// 'Outer right' means that elements of the second sequence are returned regardless of whether matching elements are found in the other sequence. + /// An 'equijoin' is a join in which the keys are compared for equality. + /// An inner join - where only elements that have a match in the other sequence are included in the results - can be performed using the + /// method. + /// For more information, see Join operations. + /// + /// public static IEnumerable RightJoin(this IEnumerable outer, IEnumerable inner, Func outerKeySelector, Func innerKeySelector, Func resultSelector, IEqualityComparer? comparer) { if (outer is null) From 4f10979c6bd9cd04a1675d31c0bed1754bc94bf6 Mon Sep 17 00:00:00 2001 From: Shay Rojansky Date: Sun, 12 Jan 2025 14:54:53 +0100 Subject: [PATCH 2/5] Remove nullability annotations in the docs --- .../src/System/Linq/Queryable.cs | 8 ++++---- src/libraries/System.Linq/src/System/Linq/Join.cs | 12 ++++++------ .../System.Linq/src/System/Linq/LeftJoin.cs | 8 ++++---- .../System.Linq/src/System/Linq/RightJoin.cs | 12 ++++++------ 4 files changed, 20 insertions(+), 20 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 308c2a5a1ba42..5760bf5ad0595 100644 --- a/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs +++ b/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs @@ -458,7 +458,7 @@ public static IQueryable GroupJoin(this /// or or or or is . /// /// - /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. + /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. /// /// /// class Person @@ -574,7 +574,7 @@ public static IQueryable LeftJoin(this I /// or or or or is . /// /// - /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. + /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. /// /// /// class Person @@ -888,7 +888,7 @@ public static IOrderedQueryable OrderByDescending(this I /// or or or or is . /// /// - /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. + /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. /// /// /// class Person @@ -1003,7 +1003,7 @@ public static IQueryable RightJoin(this /// or or or or is . /// /// - /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. + /// The following code example demonstrates how to use to perform an inner join of two sequences based on a common key. /// /// /// class Person diff --git a/src/libraries/System.Linq/src/System/Linq/Join.cs b/src/libraries/System.Linq/src/System/Linq/Join.cs index d8946cddba9db..ae615d27a6a78 100644 --- a/src/libraries/System.Linq/src/System/Linq/Join.cs +++ b/src/libraries/System.Linq/src/System/Linq/Join.cs @@ -94,7 +94,7 @@ public static partial class Enumerable /// /// /// A join refers to the operation of correlating the elements of two sources of information based on a common key. - /// + /// /// brings the two information sources and the keys by which they are matched together in one method call. /// /// @@ -102,9 +102,9 @@ public static partial class Enumerable /// 'Inner' means that only elements that have a match in the other sequence are included in the results. /// An 'equijoin' is a join in which the keys are compared for equality. /// An left outer join can be performed using the - /// method, + /// method, /// and a right outer join can be performed using the - /// method, + /// method, /// For more information, see Join operations. /// /// @@ -199,7 +199,7 @@ public static IEnumerable Join(this IEnu /// /// /// A join refers to the operation of correlating the elements of two sources of information based on a common key. - /// + /// /// brings the two information sources and the keys by which they are matched together in one method call. /// /// @@ -207,9 +207,9 @@ public static IEnumerable Join(this IEnu /// 'Inner' means that only elements that have a match in the other sequence are included in the results. /// An 'equijoin' is a join in which the keys are compared for equality. /// An left outer join can be performed using the - /// method, + /// method, /// and a right outer join can be performed using the - /// method, + /// method, /// For more information, see Join operations. /// /// diff --git a/src/libraries/System.Linq/src/System/Linq/LeftJoin.cs b/src/libraries/System.Linq/src/System/Linq/LeftJoin.cs index a9427404a8701..605403cea51b8 100644 --- a/src/libraries/System.Linq/src/System/Linq/LeftJoin.cs +++ b/src/libraries/System.Linq/src/System/Linq/LeftJoin.cs @@ -95,11 +95,11 @@ public static partial class Enumerable /// /// /// A join refers to the operation of correlating the elements of two sources of information based on a common key. - /// + /// /// brings the two information sources and the keys by which they are matched together in one method call. /// /// - /// In relational database terms, the method implements an outer left equijoin. + /// In relational database terms, the method implements an outer left equijoin. /// 'Outer left' means that elements of the first sequence are returned regardless of whether matching elements are found in the other sequence. /// An 'equijoin' is a join in which the keys are compared for equality. /// An inner join - where only elements that have a match in the other sequence are included in the results - can be performed using the @@ -199,11 +199,11 @@ public static IEnumerable LeftJoin(this /// /// /// A join refers to the operation of correlating the elements of two sources of information based on a common key. - /// + /// /// brings the two information sources and the keys by which they are matched together in one method call. /// /// - /// In relational database terms, the method implements an outer left equijoin. + /// In relational database terms, the method implements an outer left equijoin. /// 'Outer left' means that elements of the first sequence are returned regardless of whether matching elements are found in the other sequence. /// An 'equijoin' is a join in which the keys are compared for equality. /// An inner join - where only elements that have a match in the other sequence are included in the results - can be performed using the diff --git a/src/libraries/System.Linq/src/System/Linq/RightJoin.cs b/src/libraries/System.Linq/src/System/Linq/RightJoin.cs index c87b9f3817b14..edc41571ee7b2 100644 --- a/src/libraries/System.Linq/src/System/Linq/RightJoin.cs +++ b/src/libraries/System.Linq/src/System/Linq/RightJoin.cs @@ -24,7 +24,7 @@ public static partial class Enumerable /// or or or or is . /// /// - /// The following code example demonstrates how to use to perform aa left outer join of two sequences based on a common key. + /// The following code example demonstrates how to use to perform aa left outer join of two sequences based on a common key. /// /// /// class Person @@ -94,11 +94,11 @@ public static partial class Enumerable /// /// /// A join refers to the operation of correlating the elements of two sources of information based on a common key. - /// + /// /// brings the two information sources and the keys by which they are matched together in one method call. /// /// - /// In relational database terms, the method implements an outer right equijoin. + /// In relational database terms, the method implements an outer right equijoin. /// 'Outer right' means that elements of the second sequence are returned regardless of whether matching elements are found in the other sequence. /// An 'equijoin' is a join in which the keys are compared for equality. /// An inner join - where only elements that have a match in the other sequence are included in the results - can be performed using the @@ -127,7 +127,7 @@ public static IEnumerable RightJoin(this /// or or or or is . /// /// - /// The following code example demonstrates how to use to perform aa left outer join of two sequences based on a common key. + /// The following code example demonstrates how to use to perform aa left outer join of two sequences based on a common key. /// /// /// class Person @@ -197,11 +197,11 @@ public static IEnumerable RightJoin(this /// /// /// A join refers to the operation of correlating the elements of two sources of information based on a common key. - /// + /// /// brings the two information sources and the keys by which they are matched together in one method call. /// /// - /// In relational database terms, the method implements an outer right equijoin. + /// In relational database terms, the method implements an outer right equijoin. /// 'Outer right' means that elements of the second sequence are returned regardless of whether matching elements are found in the other sequence. /// An 'equijoin' is a join in which the keys are compared for equality. /// An inner join - where only elements that have a match in the other sequence are included in the results - can be performed using the From 19146a93bd9e95f512d13ec0c4c2f59a0c52b2d4 Mon Sep 17 00:00:00 2001 From: Shay Rojansky Date: Sun, 12 Jan 2025 14:59:28 +0100 Subject: [PATCH 3/5] Fix some incorrect xml code references --- .../src/System/Linq/Queryable.cs | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 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 5760bf5ad0595..8c64356d03b57 100644 --- a/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs +++ b/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs @@ -263,7 +263,7 @@ private static Expression GetSourceExpression(IEnumerable sour /// generates a that represents calling /// /// itself as a constructed generic method. - /// It then passes the to the method of the represented by the property of the parameter. + /// It then passes the to the method of the represented by the property of the parameter. /// /// /// The query behavior that occurs as a result of executing an expression tree that represents calling @@ -379,7 +379,7 @@ public static IQueryable Join(this IQuer /// generates a that represents calling /// /// itself as a constructed generic method. - /// It then passes the to the method of the represented by the property of the parameter. + /// It then passes the to the method of the represented by the property of the parameter. /// /// /// The query behavior that occurs as a result of executing an expression tree that represents calling @@ -449,7 +449,6 @@ public static IQueryable GroupJoin(this /// A function to extract the join key from each element of the first sequence. /// A function to extract the join key from each element of the second sequence. /// A function to create a result element from two matching elements. - /// An to hash and compare keys. /// The type of the elements of the first sequence. /// The type of the elements of the second sequence. /// The type of the keys returned by the key selector functions. @@ -527,7 +526,7 @@ public static IQueryable GroupJoin(this /// generates a that represents calling /// /// itself as a constructed generic method. - /// It then passes the to the method of the represented by the property of the parameter. + /// It then passes the to the method of the represented by the property of the parameter. /// /// /// The query behavior that occurs as a result of executing an expression tree that represents calling @@ -643,7 +642,7 @@ public static IQueryable LeftJoin(this I /// generates a that represents calling /// /// itself as a constructed generic method. - /// It then passes the to the method of the represented by the property of the parameter. + /// It then passes the to the method of the represented by the property of the parameter. /// /// /// The query behavior that occurs as a result of executing an expression tree that represents calling @@ -879,7 +878,6 @@ public static IOrderedQueryable OrderByDescending(this I /// A function to extract the join key from each element of the first sequence. /// A function to extract the join key from each element of the second sequence. /// A function to create a result element from two matching elements. - /// An to hash and compare keys. /// The type of the elements of the first sequence. /// The type of the elements of the second sequence. /// The type of the keys returned by the key selector functions. @@ -956,7 +954,7 @@ public static IOrderedQueryable OrderByDescending(this I /// generates a that represents calling /// /// itself as a constructed generic method. - /// It then passes the to the method of the represented by the property of the parameter. + /// It then passes the to the method of the represented by the property of the parameter. /// /// /// The query behavior that occurs as a result of executing an expression tree that represents calling @@ -1071,7 +1069,7 @@ public static IQueryable RightJoin(this /// generates a that represents calling /// /// itself as a constructed generic method. - /// It then passes the to the method of the represented by the property of the parameter. + /// It then passes the to the method of the represented by the property of the parameter. /// /// /// The query behavior that occurs as a result of executing an expression tree that represents calling From 676a0300070cbc1d949be9b87c84098289adc6a7 Mon Sep 17 00:00:00 2001 From: Shay Rojansky Date: Sun, 12 Jan 2025 15:00:20 +0100 Subject: [PATCH 4/5] Correct sample method names --- src/libraries/System.Linq/src/System/Linq/RightJoin.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libraries/System.Linq/src/System/Linq/RightJoin.cs b/src/libraries/System.Linq/src/System/Linq/RightJoin.cs index edc41571ee7b2..8b0e638fd7a9f 100644 --- a/src/libraries/System.Linq/src/System/Linq/RightJoin.cs +++ b/src/libraries/System.Linq/src/System/Linq/RightJoin.cs @@ -38,7 +38,7 @@ public static partial class Enumerable /// public Person Owner { get; set; } /// } /// - /// public static void LeftJoin() + /// public static void RightJoin() /// { /// Person magnus = new Person { Name = "Hedlund, Magnus" }; /// Person terry = new Person { Name = "Adams, Terry" }; @@ -141,7 +141,7 @@ public static IEnumerable RightJoin(this /// public Person Owner { get; set; } /// } /// - /// public static void LeftJoin() + /// public static void RightJoin() /// { /// Person magnus = new Person { Name = "Hedlund, Magnus" }; /// Person terry = new Person { Name = "Adams, Terry" }; From 607dbb941a54815ee648598b6fb0b55deddfe4c5 Mon Sep 17 00:00:00 2001 From: Shay Rojansky Date: Sun, 12 Jan 2025 15:09:43 +0100 Subject: [PATCH 5/5] Correct summaries --- .../src/System/Linq/Queryable.cs | 18 ++++++------------ .../System.Linq/src/System/Linq/Join.cs | 6 ++---- .../System.Linq/src/System/Linq/LeftJoin.cs | 6 ++---- .../System.Linq/src/System/Linq/RightJoin.cs | 6 ++---- 4 files changed, 12 insertions(+), 24 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 8c64356d03b57..71e7727a586e6 100644 --- a/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs +++ b/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs @@ -179,8 +179,7 @@ private static Expression GetSourceExpression(IEnumerable sour } /// - /// Correlates the elements of two sequences based on matching keys. - /// The default equality comparer is used to compare keys. + /// Correlates the elements of two sequences based on matching keys. The default equality comparer is used to compare keys. /// /// The first sequence to join. /// The sequence to join to the first sequence. @@ -293,8 +292,7 @@ public static IQueryable Join(this IQuer } /// - /// Correlates the elements of two sequences based on matching keys. - /// The default equality comparer is used to compare keys. + /// Correlates the elements of two sequences based on matching keys. A specified is used to compare keys. /// /// The first sequence to join. /// The sequence to join to the first sequence. @@ -441,8 +439,7 @@ public static IQueryable GroupJoin(this } /// - /// Correlates the elements of two sequences based on matching keys; elements of the first sequence are returned regardless of whether matching elements are found in the second sequence. - /// The default equality comparer is used to compare keys. + /// Correlates the elements of two sequences based on matching keys. The default equality comparer is used to compare keys. /// /// The first sequence to join. /// The sequence to join to the first sequence. @@ -556,8 +553,7 @@ public static IQueryable LeftJoin(this I } /// - /// Correlates the elements of two sequences based on matching keys; elements of the first sequence are returned regardless of whether matching elements are found in the second sequence. - /// The default equality comparer is used to compare keys. + /// Correlates the elements of two sequences based on matching keys. A specified is used to compare keys. /// /// The first sequence to join. /// The sequence to join to the first sequence. @@ -870,8 +866,7 @@ public static IOrderedQueryable OrderByDescending(this I } /// - /// Correlates the elements of two sequences based on matching keys; elements of the second sequence are returned regardless of whether matching elements are found in the first sequence. - /// The default equality comparer is used to compare keys. + /// Correlates the elements of two sequences based on matching keys. The default equality comparer is used to compare keys. /// /// The first sequence to join. /// The sequence to join to the first sequence. @@ -984,8 +979,7 @@ public static IQueryable RightJoin(this } /// - /// Correlates the elements of two sequences based on matching keys; elements of the second sequence are returned regardless of whether matching elements are found in the first sequence. - /// The default equality comparer is used to compare keys. + /// Correlates the elements of two sequences based on matching keys. A specified is used to compare keys. /// /// The first sequence to join. /// The sequence to join to the first sequence. diff --git a/src/libraries/System.Linq/src/System/Linq/Join.cs b/src/libraries/System.Linq/src/System/Linq/Join.cs index ae615d27a6a78..677f6bd0eb8b3 100644 --- a/src/libraries/System.Linq/src/System/Linq/Join.cs +++ b/src/libraries/System.Linq/src/System/Linq/Join.cs @@ -8,8 +8,7 @@ namespace System.Linq public static partial class Enumerable { /// - /// Correlates the elements of two sequences based on matching keys. - /// The default equality comparer is used to compare keys. + /// Correlates the elements of two sequences based on matching keys. The default equality comparer is used to compare keys. /// /// The first sequence to join. /// The sequence to join to the first sequence. @@ -112,8 +111,7 @@ public static IEnumerable Join(this IEnu Join(outer, inner, outerKeySelector, innerKeySelector, resultSelector, comparer: null); /// - /// Correlates the elements of two sequences based on matching keys. - /// The default equality comparer is used to compare keys. + /// Correlates the elements of two sequences based on matching keys. A specified is used to compare keys. /// /// The first sequence to join. /// The sequence to join to the first sequence. diff --git a/src/libraries/System.Linq/src/System/Linq/LeftJoin.cs b/src/libraries/System.Linq/src/System/Linq/LeftJoin.cs index 605403cea51b8..097e2453d0167 100644 --- a/src/libraries/System.Linq/src/System/Linq/LeftJoin.cs +++ b/src/libraries/System.Linq/src/System/Linq/LeftJoin.cs @@ -8,8 +8,7 @@ namespace System.Linq public static partial class Enumerable { /// - /// Correlates the elements of two sequences based on matching keys; elements of the first sequence are returned regardless of whether matching elements are found in the second sequence. - /// The default equality comparer is used to compare keys. + /// Correlates the elements of two sequences based on matching keys. The default equality comparer is used to compare keys. /// /// The first sequence to join. /// The sequence to join to the first sequence. @@ -111,8 +110,7 @@ public static IEnumerable LeftJoin(this LeftJoin(outer, inner, outerKeySelector, innerKeySelector, resultSelector, comparer: null); /// - /// Correlates the elements of two sequences based on matching keys; elements of the first sequence are returned regardless of whether matching elements are found in the second sequence. - /// The default equality comparer is used to compare keys. + /// Correlates the elements of two sequences based on matching keys. A specified is used to compare keys. /// /// The first sequence to join. /// The sequence to join to the first sequence. diff --git a/src/libraries/System.Linq/src/System/Linq/RightJoin.cs b/src/libraries/System.Linq/src/System/Linq/RightJoin.cs index 8b0e638fd7a9f..2485b7c13a281 100644 --- a/src/libraries/System.Linq/src/System/Linq/RightJoin.cs +++ b/src/libraries/System.Linq/src/System/Linq/RightJoin.cs @@ -8,8 +8,7 @@ namespace System.Linq public static partial class Enumerable { /// - /// Correlates the elements of two sequences based on matching keys; elements of the second sequence are returned regardless of whether matching elements are found in the first sequence. - /// The default equality comparer is used to compare keys. + /// Correlates the elements of two sequences based on matching keys. The default equality comparer is used to compare keys. /// /// The first sequence to join. /// The sequence to join to the first sequence. @@ -110,8 +109,7 @@ public static IEnumerable RightJoin(this RightJoin(outer, inner, outerKeySelector, innerKeySelector, resultSelector, comparer: null); /// - /// Correlates the elements of two sequences based on matching keys; elements of the second sequence are returned regardless of whether matching elements are found in the first sequence. - /// The default equality comparer is used to compare keys. + /// Correlates the elements of two sequences based on matching keys. A specified is used to compare keys. /// /// The first sequence to join. /// The sequence to join to the first sequence.