Implement Array.where, List.where

Commits:
    Implementing "where" for Array and List

    Alphabetical order in .fsi files

    Show possible System.ArgumentNullException in docs for Array.where

    Make XML docs more specific for Array.where and List.where

    Make it more obvious that Array.where = Array.filter

    Adding surface area fir Array.where and List.where

    Array.filter already does a null check. No need to do this in Array.where

src/fsharp/FSharp.Core.Unittests/FSharp.Core/Microsoft.FSharp.Collections/ArrayModule.fs

@@ -451,6 +451,38 @@ type ArrayModule() =
         
         ()   
 
+
+    [<Test>]
+    member this.Where() =
+        // integer array
+        let intArr = [| 1..20 |]
+        let funcInt x = if (x%5 = 0) then true else false
+        let resultInt = Array.where funcInt intArr
+        if resultInt <> [|5;10;15;20|] then Assert.Fail()
+        
+        // string array
+        let strArr = [|"Lists"; "are"; "a"; "commonly"; "data";"structor" |]
+        let funcStr (x:string) = if (x.Length > 4) then true else false
+        let resultStr = Array.where funcStr strArr
+        if resultStr <> [|"Lists";  "commonly"; "structor" |] then Assert.Fail()
+        
+        // empty array
+        let emptyArr:int[] = [| |]
+        let resultEpt = Array.where funcInt emptyArr
+        if resultEpt <> [| |] then Assert.Fail()
+
+        // null array
+        let nullArr = null:string[] 
+        CheckThrowsArgumentNullException (fun () ->  Array.where funcStr nullArr |> ignore) 
+        
+        ()   
+
+    [<Test>]
+    member this.``where should work like filter``() =
+        Assert.AreEqual([||], Array.where (fun x -> x % 2 = 0) [||])
+        Assert.AreEqual([|0;2;4;6;8|], Array.where (fun x -> x % 2 = 0) [|0..9|])
+        Assert.AreEqual([|"a";"b";"c"|], Array.where (fun _ -> true) [|"a";"b";"c"|])
+
     [<Test>]
     member this.Find() =
         // integer array

src/fsharp/FSharp.Core.Unittests/FSharp.Core/Microsoft.FSharp.Collections/ListModule.fs

@@ -228,6 +228,35 @@ type ListModule() =
             
         ()   
 
+    [<Test>]
+    member this.Where() =
+        // integer List
+        let intArr = [ 1..20 ]
+        let funcInt x = if (x%5 = 0) then true else false
+        let resultInt = List.where funcInt intArr        
+        Assert.AreEqual([5;10;15;20], resultInt)
+        
+        // string List
+        let strArr = ["."; ".."; "..."; "...."] 
+        let funcStr (x:string) = if (x.Length >2) then true else false
+        let resultStr = List.where funcStr strArr        
+        Assert.AreEqual(["..."; "...."], resultStr)
+        
+        // empty List
+        let emptyArr:int list = [ ]
+        let resultEpt = List.where funcInt emptyArr        
+        Assert.AreEqual(emptyArr, resultEpt)
+            
+        ()   
+
+    [<Test>]
+    member this.``where should work like filter``() =
+        Assert.AreEqual([], List.where (fun x -> x % 2 = 0) [])
+        Assert.AreEqual([0;2;4;6;8], List.where (fun x -> x % 2 = 0) [0..9])
+        Assert.AreEqual(["a";"b";"c"], List.where (fun _ -> true) ["a";"b";"c"])
+
+        ()
+
     [<Test>]
     member this.Find() =
         // integer List

src/fsharp/FSharp.Core.Unittests/SurfaceArea.4.0.fs

@@ -156,6 +156,7 @@ Microsoft.FSharp.Collections.ArrayModule: T[] Reverse[T](T[])
 Microsoft.FSharp.Collections.ArrayModule: T[] SortBy[T,TKey](Microsoft.FSharp.Core.FSharpFunc`2[T,TKey], T[])
 Microsoft.FSharp.Collections.ArrayModule: T[] SortWith[T](Microsoft.FSharp.Core.FSharpFunc`2[T,Microsoft.FSharp.Core.FSharpFunc`2[T,System.Int32]], T[])
 Microsoft.FSharp.Collections.ArrayModule: T[] Sort[T](T[])
+Microsoft.FSharp.Collections.ArrayModule: T[] Where[T](Microsoft.FSharp.Core.FSharpFunc`2[T,System.Boolean], T[])
 Microsoft.FSharp.Collections.ArrayModule: T[] ZeroCreate[T](Int32)
 Microsoft.FSharp.Collections.ArrayModule: Void CopyTo[T](T[], Int32, T[], Int32, Int32)
 Microsoft.FSharp.Collections.ArrayModule: Void Fill[T](T[], Int32, Int32, T)
@@ -292,6 +293,7 @@ Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Collections.FSharpList
 Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Collections.FSharpList`1[T] SortWith[T](Microsoft.FSharp.Core.FSharpFunc`2[T,Microsoft.FSharp.Core.FSharpFunc`2[T,System.Int32]], Microsoft.FSharp.Collections.FSharpList`1[T])
 Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Collections.FSharpList`1[T] Sort[T](Microsoft.FSharp.Collections.FSharpList`1[T])
 Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Collections.FSharpList`1[T] Tail[T](Microsoft.FSharp.Collections.FSharpList`1[T])
+Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Collections.FSharpList`1[T] Where[T](Microsoft.FSharp.Core.FSharpFunc`2[T,System.Boolean], Microsoft.FSharp.Collections.FSharpList`1[T])
 Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Core.FSharpOption`1[System.Int32] TryFindIndex[T](Microsoft.FSharp.Core.FSharpFunc`2[T,System.Boolean], Microsoft.FSharp.Collections.FSharpList`1[T])
 Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Core.FSharpOption`1[TResult] TryPick[T,TResult](Microsoft.FSharp.Core.FSharpFunc`2[T,Microsoft.FSharp.Core.FSharpOption`1[TResult]], Microsoft.FSharp.Collections.FSharpList`1[T])
 Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Core.FSharpOption`1[T] TryFind[T](Microsoft.FSharp.Core.FSharpFunc`2[T,System.Boolean], Microsoft.FSharp.Collections.FSharpList`1[T])

src/fsharp/FSharp.Core.Unittests/SurfaceArea.Portable.fs

@@ -150,6 +150,7 @@ Microsoft.FSharp.Collections.ArrayModule: T[] Reverse[T](T[])
 Microsoft.FSharp.Collections.ArrayModule: T[] SortBy[T,TKey](Microsoft.FSharp.Core.FSharpFunc`2[T,TKey], T[])
 Microsoft.FSharp.Collections.ArrayModule: T[] SortWith[T](Microsoft.FSharp.Core.FSharpFunc`2[T,Microsoft.FSharp.Core.FSharpFunc`2[T,System.Int32]], T[])
 Microsoft.FSharp.Collections.ArrayModule: T[] Sort[T](T[])
+Microsoft.FSharp.Collections.ArrayModule: T[] Where[T](Microsoft.FSharp.Core.FSharpFunc`2[T,System.Boolean], T[])
 Microsoft.FSharp.Collections.ArrayModule: T[] ZeroCreate[T](Int32)
 Microsoft.FSharp.Collections.ArrayModule: Void CopyTo[T](T[], Int32, T[], Int32, Int32)
 Microsoft.FSharp.Collections.ArrayModule: Void Fill[T](T[], Int32, Int32, T)
@@ -286,6 +287,7 @@ Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Collections.FSharpList
 Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Collections.FSharpList`1[T] SortWith[T](Microsoft.FSharp.Core.FSharpFunc`2[T,Microsoft.FSharp.Core.FSharpFunc`2[T,System.Int32]], Microsoft.FSharp.Collections.FSharpList`1[T])
 Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Collections.FSharpList`1[T] Sort[T](Microsoft.FSharp.Collections.FSharpList`1[T])
 Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Collections.FSharpList`1[T] Tail[T](Microsoft.FSharp.Collections.FSharpList`1[T])
+Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Collections.FSharpList`1[T] Where[T](Microsoft.FSharp.Core.FSharpFunc`2[T,System.Boolean], Microsoft.FSharp.Collections.FSharpList`1[T])
 Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Core.FSharpOption`1[System.Int32] TryFindIndex[T](Microsoft.FSharp.Core.FSharpFunc`2[T,System.Boolean], Microsoft.FSharp.Collections.FSharpList`1[T])
 Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Core.FSharpOption`1[TResult] TryPick[T,TResult](Microsoft.FSharp.Core.FSharpFunc`2[T,Microsoft.FSharp.Core.FSharpOption`1[TResult]], Microsoft.FSharp.Collections.FSharpList`1[T])
 Microsoft.FSharp.Collections.ListModule: Microsoft.FSharp.Core.FSharpOption`1[T] TryFind[T](Microsoft.FSharp.Core.FSharpFunc`2[T,System.Boolean], Microsoft.FSharp.Collections.FSharpList`1[T])

src/fsharp/FSharp.Core/array.fs

@@ -296,6 +296,9 @@ namespace Microsoft.FSharp.Collections
                 if f x then res.Add(x)
             res.ToArray()
 
+        [<CompiledName("Where")>]
+        let where f (array: _[]) = filter f array
+
         [<CompiledName("Partition")>]
         let partition f (array: _[]) = 
             checkNonNull "array" array

src/fsharp/FSharp.Core/array.fsi

@@ -600,6 +600,16 @@ namespace Microsoft.FSharp.Collections
         [<CompiledName("Unzip3")>]
         val unzip3: array:('T1 * 'T2 * 'T3)[] -> ('T1[] * 'T2[] * 'T3[])
 
+        /// <summary>Returns a new array containing only the elements of the array
+        /// for which the given predicate returns "true".</summary>
+        /// <param name="predicate">The function to test the input elements.</param>
+        /// <param name="array">The input array.</param>
+        /// <returns>An array containing the elements for which the given predicate returns true.</returns>
+        ///
+        /// <exception cref="System.ArgumentNullException">Thrown when the input array is null.</exception>    
+        [<CompiledName("Where")>]
+        val where: predicate:('T -> bool) -> array:'T[] -> 'T[]
+
         /// <summary>Combines the two arrays into an array of pairs. The two arrays must have equal lengths, otherwise an <c>ArgumentException</c> is
         /// raised.</summary>
         /// <param name="array1">The first input array.</param>

src/fsharp/FSharp.Core/list.fs

@@ -319,6 +319,9 @@ namespace Microsoft.FSharp.Collections
         [<CompiledName("Filter")>]
         let filter f x = Microsoft.FSharp.Primitives.Basics.List.filter f x
 
+        [<CompiledName("Where")>]
+        let where f x = Microsoft.FSharp.Primitives.Basics.List.filter f x
+
         [<CompiledName("Partition")>]
         let partition p x = Microsoft.FSharp.Primitives.Basics.List.partition p x
             

src/fsharp/FSharp.Core/list.fsi

@@ -553,6 +553,14 @@ namespace Microsoft.FSharp.Collections
         /// <returns>Three lists of split elements.</returns>
         [<CompiledName("Unzip3")>]
         val unzip3: list:('T1 * 'T2 * 'T3) list -> ('T1 list * 'T2 list * 'T3 list)
+        
+        /// <summary>Returns a new list containing only the elements of the list
+        /// for which the given predicate returns "true"</summary>
+        /// <param name="predicate">The function to test the input elements.</param>
+        /// <param name="list">The input list.</param>
+        /// <returns>A list containing only the elements that satisfy the predicate.</returns>
+        [<CompiledName("Where")>]
+        val where: predicate:('T -> bool) -> list:'T list -> 'T list
 
         /// <summary>Combines the two lists into a list of pairs. The two lists must have equal lengths.</summary>
         /// <param name="list1">The first input list.</param>