Added Option functions and Added Missing Documentation (#246)

* WIP

* WIP

* WIP doc updates

* Moved some docs to a more applicable location. Added sequence and traverse option list functions

* Updated zip documentation

* Added unit tests

Author: 1eyewonder

gitbook/SUMMARY.md

@@ -29,15 +29,20 @@
       * [ofChoice](result/ofChoice.md)
 
   * Option
-    * [bind](pr.md)
-    * [bindNull](pr.md)
+    * [bind](option/bind.md)
+    * [bindNull](option/bindNull.md)
     * [Computation Expression](option/ce.md)
-    * [either](pr.md)
-    * [map](pr.md)
-    * [zip](pr.md)
+    * [either](option/either.md)
+    * [map](option/map.md)
+    * [map2](option/map2.md)
+    * [map3](option/map3.md)
+    * [tee Functions](option/teeFunctions.md)
+    * [zip](option/zip.md)
     * Lists
-      * [traverseResult](option/traverseResult.md)
-      * [sequenceResult](option/sequenceResult.md)
+        * [traverseOptionM](option/traverseOptionM.md)
+        * [sequenceOptionM](option/sequenceOptionM.md)
+        * [traverseVOptionM](option/traverseVOptionM.md)
+        * [sequenceVOptionM](option/sequenceVOptionM.md)
     * Transforms
       * [ofNull](option/ofNull.md)
       * [ofPair](option/ofPair.md)
@@ -57,6 +62,9 @@
     * [Operators](resultOption/operators.md)
     * [zip](resultOption/zip.md)
     * [zipError](resultOption/zipError.md)
+    * Lists
+      * [traverseResult](resultOption/traverseResult.md)
+      * [sequenceResult](resultOption/sequenceResult.md)
     * Transforms
       * [ofChoice](resultOption/ofChoice.md)
       * [ofOption](resultOption/ofOption.md)

gitbook/option/bind.md

@@ -0,0 +1,51 @@
+# Option.bind
+
+Namespace: `FsToolkit.ErrorHandling`
+
+## Function Signature
+
+```fsharp
+('TInput -> 'TOutput option) -> 'TInput option -> 'TOutput option
+```
+
+## Examples
+
+Take the following function for example
+
+```fsharp
+// string -> int option
+let tryParseInt (s: string) =
+    match Int32.TryParse(s) with
+    | true, i -> Some i
+    | false, _ -> None
+```
+
+### Example 1
+
+```fsharp
+let opt : int option =
+    Some "123" // string option
+    |> Option.bind tryParseInt // int option
+
+// Some 123
+```
+
+### Example 2
+
+```fsharp
+let opt : int option =
+    Some "Not a number" // string option
+    |> Option.bind tryParseInt // int option
+
+// None
+```
+
+### Example 3
+
+```fsharp
+let opt : int option =
+    None // string option
+    |> Option.bind tryParseInt // int option
+
+// None
+```

gitbook/option/bindNull.md

@@ -0,0 +1,46 @@
+# Option.bindNull
+
+Namespace: `FsToolkit.ErrorHandling`
+
+## Function Signature
+
+```fsharp
+('T -> 'nullableValue) -> 'T option -> 'nullableValue option
+```
+
+## Examples
+
+
+### Example 1
+
+```fsharp
+open System
+
+let userInput = Some 12
+let toNullable<'T> x = Nullable x
+
+Option.bindNull toNullable userInput
+// Some 12
+```
+
+### Example 2
+
+```fsharp
+open System
+
+let userInput : Option<int> = None
+let toNullable<'T> x = Nullable x
+
+Option.bindNull toNullable userInput
+// None
+```
+
+### Example 3
+
+```fsharp
+let userInput = Some 12
+Option.bindNull string userInput
+// Some "12"
+```
+
+

gitbook/option/either.md

@@ -0,0 +1,30 @@
+# Option.either
+
+Namespace: `FsToolkit.ErrorHandling`
+
+## Function Signature
+
+Provide two functions to execute depending on the value of the option. If the option is `Some`, the first function will be executed. If the option is `None`, the second function will be executed.
+
+```fsharp
+('T-> 'output) -> (unit -> 'output) -> 'T option -> 'output
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+Option.either (fun x -> x * 2) (fun () -> 0) (Some 5)
+
+// 10
+```
+
+### Example 2
+
+```fsharp
+Option.either (fun x -> x * 2) (fun () -> 0) None
+
+// 0
+```
+

gitbook/option/map.md

@@ -0,0 +1,30 @@
+# Option.map
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Apply a function to the value of an option if it is `Some`. If the option is `None`, return `None`.
+
+## Function Signature
+
+```fsharp
+('TInput-> 'TOutput) -> 'TInput option -> 'TOutput option
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+Option.map (fun x -> x + 1) (Some 1)
+
+// Some 2
+```
+
+### Example 2
+
+```fsharp
+Option.map (fun x -> x + 1) None
+
+// None
+```
+

gitbook/option/map2.md

@@ -0,0 +1,37 @@
+# Option.map2
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Apply a function to the values of two options if they are `Some`. If either option is `None`, return `None`.
+
+## Function Signature
+
+```fsharp
+('TInput1 -> 'TInput2 -> 'TOutput) -> 'TInput1 option -> 'TInput2 option -> 'TOutput option
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+Option.map2 (fun x y -> x + y) (Some 1) (Some 2)
+
+// Some 3
+```
+
+### Example 2
+
+```fsharp
+Option.map2 (fun x y -> x + y) (Some 1) None
+
+// None
+```
+
+### Example 3
+
+```fsharp
+Option.map2 (fun x y -> x + y) None (Some 2)
+
+// None
+```

gitbook/option/map3.md

@@ -0,0 +1,45 @@
+# Option.map3
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Apply a function to the values of three options if they are `Some`. If any option is `None`, return `None`.
+
+## Function Signature
+
+```fsharp
+('TInput1 -> 'TInput2 -> 'TInput3 -> 'TOutput) -> 'TInput1 option -> 'TInput2 option -> 'TInput3 option -> 'TOutput option
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+Option.map3 (fun x y z -> x + y + z) (Some 1) (Some 2) (Some 3)
+
+// Some 6
+```
+
+### Example 2
+
+```fsharp
+Option.map3 (fun x y z -> x + y + z) (Some 1) (Some 2) None
+
+// None
+```
+
+### Example 3
+
+```fsharp
+Option.map3 (fun x y z -> x + y + z) (Some 1) None (Some 3)
+
+// None
+```
+
+### Example 4
+
+```fsharp
+Option.map3 (fun x y z -> x + y + z) None (Some 2) (Some 3)
+
+// None
+```

gitbook/option/ofPair.md

@@ -25,3 +25,25 @@ let opt = Option.ofPair (true, 1)
 let opt = Option.ofPair (false, 1)
 // None
 ```
+
+### Example 3
+
+Instead of using this code snippet,
+
+```fsharp
+match Int32.TryParse "12" with
+| true, x -> x
+| false, _ -> 0
+
+// 12
+```
+
+you could use `Option.ofPair` if it better suits your use case
+
+```fsharp
+match Int32.TryParse "12" |> Option.ofPair with
+| Some x -> x
+| None -> 0
+
+// 12
+```

gitbook/option/sequenceOptionM.md

@@ -0,0 +1,41 @@
+# List.sequenceOptionM
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Applies the monadic function `id` to each element in the input list, and returns the result as an option. If any element in the list is None, the entire result will be None.
+
+## Function Signature
+
+```fsharp
+'a option list -> 'a list option
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+let myList =
+    [
+        Some 123
+        Some 456
+        Some 789
+    ]
+
+List.sequenceOptionM myList
+// Some [123; 456; 789]
+```
+
+### Example 2
+
+```fsharp
+let myList =
+    [
+        Some 123
+        None
+        Some 789
+    ]
+
+List.sequenceOptionM myList
+// None
+```

gitbook/option/sequenceVOptionM.md

@@ -0,0 +1,41 @@
+# List.sequenceVOptionM
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Applies the monadic function `id` to each element in the input list, and returns the result as an option. If any element in the list is ValueNone, the entire result will be ValueNone.
+
+## Function Signature
+
+```fsharp
+'a voption list -> 'a list voption
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+let myList =
+    [
+        ValueSome 123
+        ValueSome 456
+        ValueSome 789
+    ]
+
+List.sequenceVOptionM myList
+// ValueSome [123; 456; 789]
+```
+
+### Example 2
+
+```fsharp
+let myList =
+    [
+        ValueSome 123
+        ValueNone
+        ValueSome 789
+    ]
+
+List.sequenceVOptionM myList
+// ValueNone
+```