diff --git a/src/fsharp/FSharp.Core/list.fsi b/src/fsharp/FSharp.Core/list.fsi index 4be7c133e23..906b2028cb9 100644 --- a/src/fsharp/FSharp.Core/list.fsi +++ b/src/fsharp/FSharp.Core/list.fsi @@ -22,6 +22,18 @@ namespace Microsoft.FSharp.Collections /// The second input list. /// /// The resulting list of pairs. + /// + /// + /// + /// let people = ["Kirk"; "Spock"; "McCoy"] + /// let numbers = [1;2] + /// people |> List.allPairs numbers + /// + /// The sample evaluates to + /// + /// [(1, "Kirk"); (1, "Spock"); (1, "McCoy"); (2, "Kirk"); (2, "Spock"); (2, "McCoy")] + /// + /// [] val allPairs: list1:'T1 list -> list2:'T2 list -> ('T1 * 'T2) list @@ -32,8 +44,16 @@ namespace Microsoft.FSharp.Collections /// The second input list. /// /// The resulting list. + /// + /// + /// + /// List.append [1..3] [4..7] // evaluates [1; 2; 3; 4; 5; 6; 7] + /// + /// [4..7] |> List.append [1..3] // evaluates [1; 2; 3; 4; 5; 6; 7] + /// + /// [] - val append: list1:'T list -> list2:'T list -> 'T list + val append: list1: 'T list -> list2: 'T list -> 'T list /// Returns the average of the elements in the list. /// @@ -43,10 +63,24 @@ namespace Microsoft.FSharp.Collections /// Thrown when the list is empty. /// /// The resulting average. + /// + /// + /// + /// [1.0 .. 9.0] |> List.average // evaluates 5.0 + /// + /// + /// + /// + /// + /// [1 .. 9] |> List.average + /// + /// The sample does not compile because The type 'int' does not support the operator 'DivideByInt' + /// (see averageBy examples for a solution) + /// [] - val inline average : list:^T list -> ^T - when ^T : (static member ( + ) : ^T * ^T -> ^T) - and ^T : (static member DivideByInt : ^T*int -> ^T) + val inline average : list:^T list -> ^T + when ^T : (static member (+) : ^T * ^T -> ^T) + and ^T : (static member DivideByInt : ^T*int -> ^T) and ^T : (static member Zero : ^T) /// Returns the average of the elements generated by applying the function to each element of the list. @@ -58,9 +92,29 @@ namespace Microsoft.FSharp.Collections /// Thrown when the list is empty. /// /// The resulting average. + /// + /// Average the age of persons by extracting the age from records + /// + /// type People = { + /// name: string + /// age: int } + /// let getAgeAsFloat person = float person.age + /// let people = + /// [ { name = "Kirk"; age = 26 } + /// { name = "Spock"; age = 90 } + /// { name = "McCoy"; age = 37 } ] + /// people |> List.averageBy getAgeAsFloat // evaluates 51.0 + /// + /// + /// + /// Average a list of integer numbers by converting to float + /// + /// [1 .. 9] |> List.averageBy float // evaluates 5.0 + /// + /// [] - val inline averageBy : projection:('T -> ^U) -> list:'T list -> ^U - when ^U : (static member ( + ) : ^U * ^U -> ^U) + val inline averageBy: projection:('T -> ^U) -> list:'T list -> ^U + when ^U : (static member (+) : ^U * ^U -> ^U) and ^U : (static member DivideByInt : ^U*int -> ^U) and ^U : (static member Zero : ^U) @@ -72,6 +126,39 @@ namespace Microsoft.FSharp.Collections /// The input list. /// /// The list comprising the values selected from the chooser function. + /// + /// + /// + /// type Happiness = AlwaysHappy | MostOfTheTimeGrumpy + /// type People = { + /// name: string + /// happiness: Happiness } + /// let takeJustHappyPersons person = + /// match person.happiness with + /// | AlwaysHappy -> Some person.name + /// | MostOfTheTimeGrumpy -> None + /// let candidatesForTheTrip = + /// [ { name = "SpongeBob"; happiness = AlwaysHappy } + /// { name = "Patrick"; happiness = AlwaysHappy } + /// { name = "Squidward"; happiness = MostOfTheTimeGrumpy } ] + /// candidatesForTheTrip |> List.choose takeJustHappyPersons + /// + /// The sample evaluates to [ "SpongeBob"; "Patrick" ] + /// + /// + /// + /// + /// // Using the identity function "id" (is defined like fun x -> x) + /// let input1 = [ Some 1; None; Some 3; None ] + /// input1 |> List.choose id // evaluates [1; 3] + /// + /// let input2: int option list = [] + /// input2 |> List.choose id // evaluates [] (notice that has the type "int list") + /// + /// let input3: string option list =[ None; None ] + /// input3 |> List.choose id // evaluates [] (notice that has the type "string list") + /// + /// [] val choose: chooser:('T -> 'U option) -> list:'T list -> 'U list @@ -83,6 +170,24 @@ namespace Microsoft.FSharp.Collections /// The list divided into chunks. /// /// Thrown when chunkSize is not positive. + /// + /// + /// + /// [1 .. 10 ] |> List.chunkBySize 3 // evaluates + /// + /// Evaluates to [[1; 2; 3]; [4; 5; 6]; [7; 8; 9]; [10]] . Please notice the last chunk. + /// + /// + /// let output2 = [1 .. 5 ] |> List.chunkBySize 10 + /// + /// Evaluates to [[1; 2; 3; 4; 5]] + /// + /// + /// let input : string list = [] + /// let output3 = input |> List.chunkBySize 10 + /// + /// Evaluates to []. Please notice that has the type string list list. + /// [] val chunkBySize: chunkSize:int -> list:'T list -> 'T list list @@ -92,6 +197,13 @@ namespace Microsoft.FSharp.Collections /// The input list. /// /// The concatenation of the transformed sublists. + /// + /// For each positive number in the array we are generating all the previous positive numbers + /// + /// [1..4] |> List.collect (fun x -> [1..x]) + /// + /// The sample evaluates to [1; 1; 2; 1; 2; 3; 1; 2; 3; 4] (added extra spaces for easy reading) + /// [] val collect: mapping:('T -> 'U list) -> list:'T list -> 'U list @@ -115,6 +227,15 @@ namespace Microsoft.FSharp.Collections /// The input sequence of lists. /// /// The resulting concatenated list. + /// + /// + /// + /// let input = [ [1;2] + /// [3;4;5] + /// [6;7;8;9] ] + /// input |> List.concat // evaluates [1; 2; 3; 4; 5; 6; 7; 8; 9] + /// + /// [] val concat: lists:seq<'T list> -> 'T list @@ -124,6 +245,18 @@ namespace Microsoft.FSharp.Collections /// The input list. /// /// True if the input list contains the specified element; false otherwise. + /// + /// + /// + /// [1..9] |> List.contains 0 // evaluates false + /// + /// [1..9] |> List.contains 3 // evaluates true + /// + /// let input = [1, "SpongeBob"; 2, "Patrick"; 3, "Squidward"; 4, "Mr. Krabs"] + /// input |> List.contains (2, "Patrick") // evaluates true + /// input |> List.contains (22, "Patrick") // evaluates false + /// + /// [] val inline contains: value:'T -> source:'T list -> bool when 'T : equality @@ -134,6 +267,13 @@ namespace Microsoft.FSharp.Collections /// The input list. /// /// The result list. + /// + /// + /// + /// let input = [6;1;2;3;1;4;5;5] + /// input |> List.distinct // evaluates [6; 1; 2; 3; 4; 5] + /// + /// [] val distinct: list:'T list -> 'T list when 'T : equality @@ -145,6 +285,14 @@ namespace Microsoft.FSharp.Collections /// The input list. /// /// The result list. + /// + /// + /// + /// let isEven x = 0 = x % 2 + /// let input = [6;1;2;3;1;4;5;5] + /// input |> List.distinctBy isEven // evaluates [6; 1] + /// + /// [] val distinctBy: projection:('T -> 'Key) -> list:'T list -> 'T list when 'Key : equality @@ -156,6 +304,14 @@ namespace Microsoft.FSharp.Collections /// The input list. /// /// The result list. + /// + /// Counting the number of occurrences of chars + /// + /// let input = ['H'; 'a'; 'p'; 'p'; 'i'; 'n'; 'e'; 's'; 's'] + /// input |> List.countBy id + /// + /// Evalutes [('H', 1); ('a', 1); ('p', 2); ('i', 1); ('n', 1); ('e', 1); ('s', 2)] + /// [] val countBy : projection:('T -> 'Key) -> list:'T list -> ('Key * int) list when 'Key : equality @@ -167,6 +323,13 @@ namespace Microsoft.FSharp.Collections /// The list split into chunks. /// /// Thrown when count is not positive. + /// + /// + /// + /// [1..10] |> List.splitInto 2 // evaluates [[1; 2; 3; 4; 5]; [6; 7; 8; 9; 10]] + /// [1..10] |> List.splitInto 4 // evaluates [[1; 2; 3]; [4; 5; 6]; [7; 8]; [9; 10]] + /// + /// [] val splitInto: count:int -> list:'T list -> 'T list list @@ -185,6 +348,20 @@ namespace Microsoft.FSharp.Collections /// A list that contains the distinct elements of list that do not appear in itemsToExclude. /// /// Thrown when itemsToExclude is null. + /// + /// + /// + /// let input = [1, "Kirk"; 2, "Spock"; 3, "Kenobi"] + /// input |> List.except [3, "Kenobi"] // evaluates [(1, "Kirk"); (2, "Spock")] + /// + /// + /// + /// + /// + /// [0..10] |> List.except [1..5] // evaluates [0; 6; 7; 8; 9; 10] + /// [1..5] |> List.except [0..10] // evaluates [] + /// + /// [] val except: itemsToExclude:seq<'T> -> list:'T list -> 'T list when 'T : equality @@ -195,6 +372,27 @@ namespace Microsoft.FSharp.Collections /// The only element of the list. /// /// Thrown when the input does not have precisely one element. + /// + /// + /// + /// ["the chosen one"] |> List.exactlyOne // evaluates "the chosen one" + /// + /// + /// + /// + /// + /// let input : string list = [] + /// input |> List.exactlyOne + /// + /// Will throw the exception: System.ArgumentException: The input sequence was empty + /// + /// + /// + /// + /// [1..5] |> List.exactlyOne + /// + /// Will throw the exception: System.ArgumentException: The input sequence contains more than one element + /// [] val exactlyOne: list:'T list -> 'T @@ -203,6 +401,14 @@ namespace Microsoft.FSharp.Collections /// The input list. /// /// The only element of the list or None. + /// + /// + /// + /// [1] |> List.tryExactlyOne // evaluates Some 1 + /// [1;2] |> List.tryExactlyOne // evaluates None + /// ([] : int list) |> List.tryExactlyOne // evaluates None + /// + /// [] val tryExactlyOne: list:'T list -> 'T option @@ -215,6 +421,16 @@ namespace Microsoft.FSharp.Collections /// The input list. /// /// True if any element satisfies the predicate. + /// + /// + /// + /// let input = [1, "Kirk"; 2, "Spock"; 3, "Kenobi"] + /// + /// input |> List.exists (fun x -> x = (3, "Kenobi")) // evaluates true + /// + /// input |> List.exists (fun (n, name) -> n > 5) // evaluates false + /// + /// [] val exists: predicate:('T -> bool) -> list:'T list -> bool @@ -233,6 +449,18 @@ namespace Microsoft.FSharp.Collections /// Thrown when the input lists differ in length. /// /// True if any pair of elements satisfy the predicate. + /// + /// Check if the sum of pairs (from 2 different lists) have at least one even number + /// + /// let anEvenSum a b = 0 = (a + b) % 2 + /// + /// ([1..4], [2..5]) + /// ||> List.exists2 anEvenSum // evaluates false + /// + /// ([1..4], [2;4;5;6]) + /// ||> List.exists2 anEvenSum // evaluates true + /// + /// [] val exists2: predicate:('T1 -> 'T2 -> bool) -> list1:'T1 list -> list2:'T2 list -> bool @@ -246,6 +474,17 @@ namespace Microsoft.FSharp.Collections /// all the elements of the list. /// /// The first element that satisfies the predicate. + /// + /// + /// + /// let isEven x = 0 = x % 2 + /// let isGreaterThan x y = y > x + /// let input = [1, "Luke"; 2, "Kirk"; 3, "Spock"; 4, "Kenobi"] + /// + /// input |> List.find (fun (x,_) -> isEven x) // evaluates (2, "Kirk") + /// input |> List.find (fun (x,_) -> x |> isGreaterThan 6) // raises an exception + /// + /// [] val find: predicate:('T -> bool) -> list:'T list -> 'T @@ -259,6 +498,17 @@ namespace Microsoft.FSharp.Collections /// all the elements of the list. /// /// The last element that satisfies the predicate. + /// + /// + /// + /// let isEven x = 0 = x % 2 + /// let isGreaterThan x y = y > x + /// let input = [1, "Luke"; 2, "Kirk"; 3, "Spock"; 4, "Kenobi"] + /// + /// input |> List.findBack (fun (x,_) -> isEven x) // evaluates (4, "Kenobi") + /// input |> List.findBack (fun (x,_) -> x |> isGreaterThan 6) // raises an exception + /// + /// [] val findBack: predicate:('T -> bool) -> list:'T list -> 'T @@ -273,6 +523,17 @@ namespace Microsoft.FSharp.Collections /// elements of the list. /// /// The index of the first element that satisfies the predicate. + /// + /// + /// + /// let isEven x = 0 = x % 2 + /// let isGreaterThan x y = y > x + /// let input = [1, "Luke"; 2, "Kirk"; 3, "Spock"; 4, "Kenobi"] + /// + /// input |> List.findIndex (fun (x,_) -> isEven x) // evaluates 1 + /// input |> List.findIndex (fun (x,_) -> x |> isGreaterThan 6) // raises an exception + /// + /// [] val findIndex: predicate:('T -> bool) -> list:'T list -> int @@ -287,6 +548,17 @@ namespace Microsoft.FSharp.Collections /// elements of the list. /// /// The index of the last element that satisfies the predicate. + /// + /// + /// + /// let isEven x = 0 = x % 2 + /// let isGreaterThan x y = y > x + /// let input = [1, "Luke"; 2, "Kirk"; 3, "Spock"; 4, "Kenobi"] + /// + /// input |> List.findIndexBack (fun (x,_) -> isEven x) // evaluates 3 + /// input |> List.findIndexBack (fun (x,_) -> x |> isGreaterThan 6) // raises an exception + /// + /// [] val findIndexBack: predicate:('T -> bool) -> list:'T list -> int @@ -297,6 +569,16 @@ namespace Microsoft.FSharp.Collections /// The input list. /// /// A list containing only the elements that satisfy the predicate. + /// + /// + /// + /// let input = [1, "Luke"; 2, "Kirk"; 3, "Kenobi"; 4, "Spock"] + /// let isComingFromStarTrek (x,_) = isEven x + /// + /// input |> List.filter isComingFromStarTrek + /// + /// Evaluates to [(2, "Kirk"); (4, "Spock")] + /// [] val filter: predicate:('T -> bool) -> list:'T list -> 'T list @@ -312,6 +594,34 @@ namespace Microsoft.FSharp.Collections /// The input list. /// /// The final state value. + /// + /// Making the sum of squares for the first 5 natural numbers + /// + /// (0, [1..5]) ||> List.fold (fun s v -> s + v * v) // evaluates 55 + /// + /// + /// + /// Shopping for fruits hungry, you tend to take more of each as the hunger grows + /// + /// type Fruit = Apple | Pear | Orange + /// type BagItem = { fruit: Fruit; quantity: int } + /// let takeMore (previous: BagItem list) fruit = + /// let toTakeThisTime = + /// match previous with + /// | bagItem :: otherBagItems -> bagItem.quantity + 1 + /// | [] -> 1 + /// { fruit = fruit; quantity = toTakeThisTime } :: previous + /// let input = [ Apple; Pear; Orange ] + /// + /// ([], input) ||> List.fold takeMore + /// + /// Evaluates to + /// + /// [{ fruit = Orange; quantity = 3 } + /// { fruit = Pear; quantity = 2 } + /// { fruit = Apple; quantity = 1 }] + /// + /// [] val fold<'T,'State> : folder:('State -> 'T -> 'State) -> state:'State -> list:'T list -> 'State @@ -338,6 +648,34 @@ namespace Microsoft.FSharp.Collections /// The initial state. /// /// The state object after the folding function is applied to each element of the list. + /// + /// Making the sum of squares for the first 5 natural numbers + /// + /// ([1..5], 0) ||> List.foldBack (fun v s -> s + v * v) // evaluates 55 + /// + /// + /// + /// Shopping for fruits hungry, you tend to take more of each as the hunger grows + /// + /// type Fruit = Apple | Pear | Orange + /// type BagItem = { fruit: Fruit; quantity: int } + /// let takeMore fruit (previous: BagItem list) = + /// let toTakeThisTime = + /// match previous with + /// | bagItem :: otherBagItems -> bagItem.quantity + 1 + /// | [] -> 1 + /// { fruit = fruit; quantity = toTakeThisTime } :: previous + /// let input = [ Apple; Pear; Orange ] + /// + /// (input, []) ||> List.foldBack takeMore + /// + /// Evaluates to + /// + /// [{ fruit = Apple; quantity = 3 } + /// { fruit = Pear; quantity = 2 } + /// { fruit = Orange; quantity = 1 }] + /// + /// [] val foldBack<'T,'State> : folder:('T -> 'State -> 'State) -> list:'T list -> state:'State -> 'State @@ -867,7 +1205,7 @@ namespace Microsoft.FSharp.Collections /// The resulting sum. [] val inline sum : list:^T list -> ^T - when ^T : (static member ( + ) : ^T * ^T -> ^T) + when ^T : (static member (+) : ^T * ^T -> ^T) and ^T : (static member Zero : ^T) /// Returns the sum of the results generated by applying the function to each element of the list. @@ -878,7 +1216,7 @@ namespace Microsoft.FSharp.Collections /// The resulting sum. [] val inline sumBy : projection:('T -> ^U) -> list:'T list -> ^U - when ^U : (static member ( + ) : ^U * ^U -> ^U) + when ^U : (static member (+) : ^U * ^U -> ^U) and ^U : (static member Zero : ^U) /// Returns the list after removing the first element. diff --git a/src/fsharp/FSharp.Core/string.fsi b/src/fsharp/FSharp.Core/string.fsi index 73174bc6bbd..a77d4cbb160 100644 --- a/src/fsharp/FSharp.Core/string.fsi +++ b/src/fsharp/FSharp.Core/string.fsi @@ -30,14 +30,16 @@ namespace Microsoft.FSharp.Core /// The following samples shows how to interspace spaces in a text /// /// let input = "Stefan says: Hi!" - /// input |> String.collect (sprintf "%c ") // evaluates "S t e f a n s a y s : H i ! " + /// input |> String.collect (sprintf "%c ") /// + /// The sample evaluates to "S t e f a n s a y s : H i ! " /// /// /// How to show the ASCII representation of a very secret text /// - /// "Secret" |> String.collect (fun chr -> int chr |> sprintf "%d ") // evaluates "83 101 99 114 101 116 " + /// "Secret" |> String.collect (fun chr -> int chr |> sprintf "%d ") /// + /// The sample evaluates to "83 101 99 114 101 116 " /// [] val collect: mapping:(char -> string) -> str:string -> string @@ -147,8 +149,9 @@ namespace Microsoft.FSharp.Core /// /// Enumerate digits ASCII codes /// - /// String.init 10 (fun i -> int '0' + i |> sprintf "%d ") // evaluates "48 49 50 51 52 53 54 55 56 57 " + /// String.init 10 (fun i -> int '0' + i |> sprintf "%d ") /// + /// The sample evaluates to: "48 49 50 51 52 53 54 55 56 57 " /// [] val init: count:int -> initializer:(int -> string) -> string @@ -162,8 +165,9 @@ namespace Microsoft.FSharp.Core /// /// let input = "Hello" /// input |> String.iter (fun c -> printfn "%c %d" c (int c)) - /// // evaluates unit - /// // prints: + /// + /// The sample evaluates as unit, but prints: + /// /// H 72 /// e 101 /// l 108 @@ -185,8 +189,9 @@ namespace Microsoft.FSharp.Core /// /// let input = "Hello" /// input |> String.iteri (fun i c -> printfn "%d. %c %d" (i + 1) c (int c)) - /// // evaluates unit - /// // prints: + /// + /// The sample evaluates as unit, but prints: + /// /// 1. H 72 /// 2. e 101 /// 3. l 108