Add time and space complexity documentation to F# collection types (List, Map, Set)

src/FSharp.Core/list.fsi

@@ -23,6 +23,8 @@ module List =
     ///
     /// <returns>The resulting list of pairs.</returns>
     /// 
+    /// <remarks>This is an O(n * m) operation, where n and m are the lengths of the input lists.</remarks>
+    /// 
     /// <example id="allPairs-1">
     /// <code lang="fsharp">
     /// let people = [ "Kirk"; "Spock"; "McCoy" ]
@@ -46,6 +48,8 @@ module List =
     ///
     /// <returns>The resulting list.</returns>
     /// 
+    /// <remarks>Lists are represented as linked lists so this is an O(n) operation, where n is the length of the first list.</remarks>
+    /// 
     /// <example id="append-1">
     /// <code lang="fsharp">
     /// List.append [ 1..3 ] [ 4..7 ]
@@ -68,6 +72,8 @@ module List =
     ///
     /// <returns>The resulting average.</returns>
     /// 
+    /// <remarks>This is an O(n) operation, where n is the length of the list.</remarks>
+    /// 
     /// <example id="average-1">
     /// <code lang="fsharp">
     /// [1.0 .. 9.0] |> List.average 
@@ -93,6 +99,8 @@ module List =
     ///
     /// <returns>The resulting average.</returns>
     /// 
+    /// <remarks>This is an O(n) operation, where n is the length of the list.</remarks>
+    /// 
     /// <example id="averageBy-1"> Calculate average age of persons by extracting their age from a record type.
     /// <code lang="fsharp">
     /// type People = { Name: string; Age: int }
@@ -203,6 +211,8 @@ module List =
     /// </code>
     /// </example>
     ///
+    /// <remarks>This is an O(n) operation, where n is the length of the list.</remarks>
+    ///
     [<CompiledName("Choose")>]
     val choose: chooser:('T -> 'U option) -> list:'T list -> 'U list
 
@@ -256,6 +266,9 @@ module List =
     /// </code>
     /// The sample evaluates to <c>[1;   1; 2;   1; 2; 3;   1; 2; 3; 4]</c> (added extra spaces for easy reading)
     /// </example>
+    ///
+    /// <remarks>This is an O(n) operation, where n is the length of the list.</remarks>
+    ///
     [<CompiledName("Collect")>]
     val collect: mapping:('T -> 'U list) -> list:'T list -> 'U list
 
@@ -353,6 +366,9 @@ module List =
     /// input |> List.concat  // evaluates [1; 2; 3; 4; 5; 6; 7; 8; 9]
     /// </code>
     /// </example>
+    ///
+    /// <remarks>This is an O(n) operation, where n is the total number of elements in all the lists.</remarks>
+    ///
     [<CompiledName("Concat")>]
     val concat: lists:seq<'T list> -> 'T list
 
@@ -588,6 +604,9 @@ module List =
     /// input |> List.exists (fun (n, name) -> n > 5)      // evaluates false
     /// </code>
     /// </example>
+    ///
+    /// <remarks>This is an O(n) operation in the worst case, where n is the length of the list.</remarks>
+    ///
     [<CompiledName("Exists")>]
     val exists: predicate:('T -> bool) -> list:'T list -> bool
 
@@ -644,6 +663,9 @@ module List =
     /// input |> List.find (fun (x,_) -> x |> isGreaterThan 6)  // raises an exception
     /// </code>
     /// </example>
+    ///
+    /// <remarks>This is an O(n) operation in the worst case, where n is the length of the list.</remarks>
+    ///
     [<CompiledName("Find")>]
     val find: predicate:('T -> bool) -> list:'T list -> 'T
 
@@ -747,6 +769,9 @@ module List =
     /// </code>
     /// Evaluates to <c>[(2, "Kirk"); (4, "Spock")]</c>
     /// </example>
+    ///
+    /// <remarks>This is an O(n) operation, where n is the length of the list.</remarks>
+    ///
     [<CompiledName("Filter")>]
     val filter: predicate:('T -> bool) -> list:'T list -> 'T list
 
@@ -793,6 +818,9 @@ module List =
     ///   { fruit = Apple; quantity = 1 }]
     /// </code>
     /// </example>
+    ///
+    /// <remarks>This is an O(n) operation, where n is the length of the list.</remarks>
+    ///
     [<CompiledName("Fold")>]
     val fold<'T,'State> : folder:('State -> 'T -> 'State) -> state:'State -> list:'T list -> 'State
 
@@ -935,6 +963,9 @@ module List =
     /// [1; 2] |> List.forall isEven // evaluates to false
     /// </code>
     /// </example>
+    ///
+    /// <remarks>This is an O(n) operation in the worst case, where n is the length of the list.</remarks>
+    ///
     [<CompiledName("ForAll")>]
     val forall: predicate:('T -> bool) -> list:'T list -> bool
 
@@ -1028,6 +1059,9 @@ module List =
     /// </code>
     /// Throws <c>ArgumentException</c>
     /// </example>
+    ///
+    /// <remarks>This is an O(1) operation.</remarks>
+    ///
     [<CompiledName("Head")>]
     val head: list:'T list -> 'T
 
@@ -1093,6 +1127,9 @@ module List =
     /// </code>
     /// Evaluates to <c>false</c>
     /// </example>
+    ///
+    /// <remarks>This is an O(1) operation.</remarks>
+    ///
     [<CompiledName("IsEmpty")>]
     val isEmpty: list:'T list -> bool
 
@@ -1122,6 +1159,9 @@ module List =
     /// </code>
     /// Throws <c>ArgumentException</c>
     /// </example>
+    ///
+    /// <remarks>Lists are represented as linked lists so this is an O(n) operation, where n is the index.</remarks>
+    ///
     [<CompiledName("Item")>]
     val item: index:int -> list:'T list -> 'T
 
@@ -1261,6 +1301,9 @@ module List =
     /// </code>
     /// Evaluates to <c>3</c>
     /// </example>
+    ///
+    /// <remarks>Lists are represented as linked lists so this is an O(n) operation, where n is the length of the list.</remarks>
+    ///
     [<CompiledName("Length")>]
     val length: list:'T list -> int
 
@@ -1303,6 +1346,9 @@ module List =
     /// </code>
     /// Evaluates to <c>[ 1; 3; 2 ]</c>
     /// </example>
+    ///
+    /// <remarks>This is an O(n) operation, where n is the length of the list.</remarks>
+    ///
     [<CompiledName("Map")>]
     val map: mapping:('T -> 'U) -> list:'T list -> 'U list
 
@@ -1785,6 +1831,9 @@ module List =
     /// </code>
     /// Evaluates to <c>[ 2; 1; 0 ]</c>.
     /// </example>
+    ///
+    /// <remarks>This is an O(n) operation, where n is the length of the list.</remarks>
+    ///
     [<CompiledName("Reverse")>]
     val rev: list:'T list -> 'T list
 
@@ -2097,6 +2146,8 @@ module List =
     /// Evaluates to <c>["bb"; "ccc"]</c>
     /// </example>
     ///
+    /// <remarks>This is an O(1) operation.</remarks>
+    ///
     [<CompiledName("Tail")>]
     val tail: list:'T list -> 'T list
 
@@ -2337,6 +2388,9 @@ module List =
     /// </code>
     /// Evaluates to <c>None</c>
     /// </example>
+    ///
+    /// <remarks>This is an O(n) operation in the worst case, where n is the length of the list.</remarks>
+    ///
     [<CompiledName("TryFind")>]
     val tryFind: predicate:('T -> bool) -> list:'T list -> 'T option
 

src/FSharp.Core/map.fsi

@@ -24,6 +24,8 @@ type Map<[<EqualityConditionalOn>] 'Key, [<EqualityConditionalOn; ComparisonCond
     ///
     /// <returns>The resulting map.</returns>
     ///
+    /// <remarks>Maps are represented as binary trees so this is an O(log n) operation, where n is the number of bindings in the map.</remarks>
+    ///
     /// <example id="member-add-1">
     /// <code lang="fsharp">
     /// let sample = Map [ (1, "a"); (2, "b") ]
@@ -95,6 +97,9 @@ type Map<[<EqualityConditionalOn>] 'Key, [<EqualityConditionalOn; ComparisonCond
     /// sample.ContainsKey 3 // evaluates to false
     /// </code>
     /// </example>
+    ///
+    /// <remarks>Maps are represented as binary trees so this is an O(log n) operation, where n is the number of bindings in the map.</remarks>
+    ///
     member ContainsKey: key: 'Key -> bool
 
     /// <summary>The number of bindings in the map.</summary>
@@ -106,6 +111,9 @@ type Map<[<EqualityConditionalOn>] 'Key, [<EqualityConditionalOn; ComparisonCond
     /// sample.Count // evaluates to 2
     /// </code>
     /// </example>
+    ///
+    /// <remarks>Maps are represented as binary trees so this is an O(n) operation, where n is the number of bindings in the map.</remarks>
+    ///
     member Count: int
 
     /// <summary>Lookup an element in the map. Raise <c>KeyNotFoundException</c> if no binding
@@ -124,6 +132,9 @@ type Map<[<EqualityConditionalOn>] 'Key, [<EqualityConditionalOn; ComparisonCond
     /// sample.[3] // throws KeyNotFoundException
     /// </code>
     /// </example>
+    ///
+    /// <remarks>Maps are represented as binary trees so this is an O(log n) operation, where n is the number of bindings in the map.</remarks>
+    ///
     member Item: key: 'Key -> 'Value with get
 
     /// <summary>Removes an element from the domain of the map. No exception is raised if the element is not present.</summary>
@@ -140,6 +151,9 @@ type Map<[<EqualityConditionalOn>] 'Key, [<EqualityConditionalOn; ComparisonCond
     /// sample.Remove 3 // equal to sample
     /// </code>
     /// </example>
+    ///
+    /// <remarks>Maps are represented as binary trees so this is an O(log n) operation, where n is the number of bindings in the map.</remarks>
+    ///
     member Remove: key: 'Key -> Map<'Key, 'Value>
 
     /// <summary>Lookup an element in the map, returning a <c>Some</c> value if the element is in the domain
@@ -157,6 +171,9 @@ type Map<[<EqualityConditionalOn>] 'Key, [<EqualityConditionalOn; ComparisonCond
     /// sample.TryFind 3 // evaluates to None
     /// </code>
     /// </example>
+    ///
+    /// <remarks>Maps are represented as binary trees so this is an O(log n) operation, where n is the number of bindings in the map.</remarks>
+    ///
     member TryFind: key: 'Key -> 'Value option
 
     /// <summary>Lookup an element in the map, assigning to <c>value</c> if the element is in the domain
@@ -377,6 +394,9 @@ module Map =
     /// emptyMap |> Map.isEmpty // evaluates to false
     /// </code>
     /// </example>
+    ///
+    /// <remarks>This is an O(1) operation.</remarks>
+    ///
     [<CompiledName("IsEmpty")>]
     val isEmpty: table: Map<'Key, 'T> -> bool
 

src/FSharp.Core/set.fsi

@@ -50,6 +50,9 @@ type Set<[<EqualityConditionalOn>] 'T when 'T: comparison> =
     /// </code>
     /// The sample evaluates to the following output: <c>The new set is: set [1; 2]</c>
     /// </example>
+    ///
+    /// <remarks>Sets are represented as binary trees so this is an O(log n) operation, where n is the number of elements in the set.</remarks>
+    ///
     member Add: value: 'T -> Set<'T>
 
     /// <summary>A useful shortcut for Set.remove. Note this operation produces a new set
@@ -67,6 +70,9 @@ type Set<[<EqualityConditionalOn>] 'T when 'T: comparison> =
     /// </code>
     /// The sample evaluates to the following output: <c>The new set is: set [2]</c>
     /// </example>
+    ///
+    /// <remarks>Sets are represented as binary trees so this is an O(log n) operation, where n is the number of elements in the set.</remarks>
+    ///
     member Remove: value: 'T -> Set<'T>
 
     /// <summary>The number of elements in the set</summary>
@@ -78,6 +84,9 @@ type Set<[<EqualityConditionalOn>] 'T when 'T: comparison> =
     /// </code>
     /// The sample evaluates to the following output: <c>The set has 3 elements</c>
     /// </example>
+    ///
+    /// <remarks>Sets are represented as binary trees so this is an O(n) operation, where n is the number of elements in the set.</remarks>
+    ///
     member Count: int
 
     /// <summary>A useful shortcut for Set.contains. See the Set module for further operations on sets.</summary>
@@ -93,6 +102,9 @@ type Set<[<EqualityConditionalOn>] 'T when 'T: comparison> =
     /// </code>
     /// The sample evaluates to the following output: <c>Does the set contain 1? false</c>
     /// </example>
+    ///
+    /// <remarks>Sets are represented as binary trees so this is an O(log n) operation, where n is the number of elements in the set.</remarks>
+    ///
     member Contains: value: 'T -> bool
 
     /// <summary>A useful shortcut for Set.isEmpty. See the Set module for further operations on sets.</summary>
@@ -547,6 +559,9 @@ module Set =
     /// </code>
     /// The sample evaluates to the following output: <c>The intersection of set [1; 2; 3] and set [2; 3; 4] is set [2; 3]</c>
     /// </example>
+    ///
+    /// <remarks>This is an O(n + m) operation, where n and m are the sizes of the input sets.</remarks>
+    ///
     [<CompiledName("Intersect")>]
     val intersect: set1: Set<'T> -> set2: Set<'T> -> Set<'T>
 
@@ -590,6 +605,9 @@ module Set =
     /// </code>
     /// The sample evaluates to the following output: <c>The union of set [1; 2; 3] and set [2; 3; 4] is set [1; 2; 3; 4]</c>
     /// </example>
+    ///
+    /// <remarks>This is an O(n + m) operation, where n and m are the sizes of the input sets.</remarks>
+    ///
     [<CompiledName("Union")>]
     val union: set1: Set<'T> -> set2: Set<'T> -> Set<'T>
 
@@ -631,6 +649,9 @@ module Set =
     /// </code>
     /// The sample evaluates to the following output: <c>Is the set empty? false</c>
     /// </example>
+    ///
+    /// <remarks>This is an O(1) operation.</remarks>
+    ///
     [<CompiledName("IsEmpty")>]
     val isEmpty: set: Set<'T> -> bool
 
@@ -836,5 +857,8 @@ module Set =
     /// </code>
     /// The sample evaluates to the following output: <c>The difference of set [1; 2; 3] and set [2; 3; 4] is set [1]</c>
     /// </example>
+    ///
+    /// <remarks>This is an O(n + m) operation, where n and m are the sizes of the input sets.</remarks>
+    ///
     [<CompiledName("Difference")>]
     val difference: set1: Set<'T> -> set2: Set<'T> -> Set<'T>