Adds Value/Option.ofNull and bindNull (#164)

TheAngryByrd · web-flow · commit 3765b232b0f1 · 2022-01-11T09:51:29.000-05:00
diff --git a/src/FsToolkit.ErrorHandling/Option.fs b/src/FsToolkit.ErrorHandling/Option.fs
@@ -3,22 +3,22 @@ namespace FsToolkit.ErrorHandling
 [<RequireQualifiedAccess>]
 module Option =
 
-    let ofValueOption (vopt: _ voption) =
+    let inline ofValueOption (vopt: _ voption) =
         match vopt with
         | ValueSome v -> Some v
         | ValueNone -> None
 
-    let toValueOption (opt: _ option) =
+    let inline toValueOption (opt: _ option) =
         match opt with
         | Some v -> ValueSome v
         | None -> ValueNone
 
-    let traverseResult f opt =
+    let inline traverseResult f opt =
         match opt with
         | None -> Ok None
         | Some v -> f v |> Result.map Some
 
-    let sequenceResult opt = traverseResult id opt
+    let inline sequenceResult opt = traverseResult id opt
 
 #if !FABLE_COMPILER
     let inline tryParse< ^T when ^T: (static member TryParse : string * byref< ^T > -> bool) and ^T: (new : unit -> ^T)>
@@ -50,13 +50,48 @@ module Option =
     /// <param name="option1">The input option</param>
     /// <param name="option2">The input option</param>
     /// <returns></returns>
-    let zip (option1: 'a option) (option2: 'b option) =
+    let inline zip (option1: 'a option) (option2: 'b option) =
         match option1, option2 with
         | Some v1, Some v2 -> Some(v1, v2)
         | _ -> None
 
 
-    let ofResult =
-        function
+    let inline ofResult (r: Result<_, _>) =
+        match r with
         | Ok v -> Some v
         | Error _ -> None
+
+    /// <summary>
+    /// Convert a potentially null value to an option.
+    ///
+    /// This is different from <see cref="FSharp.Core.Option.ofObj">Option.ofObj</see> where it doesn't require the value to be constrained to null.
+    /// This is beneficial where third party APIs may generate a record type using reflection and it can be null.
+    /// See <a href="https://latkin.org/blog/2015/05/18/null-checking-considerations-in-f-its-harder-than-you-think/">Null-checking considerations in F#</a> for more details.
+    /// </summary>
+    /// <param name="value">The potentially null value</param>
+    /// <returns>An option</returns>
+    /// <seealso cref="FSharp.Core.Option.ofObj"/>
+    let inline ofNull (value: 'nullableValue) =
+        if System.Object.ReferenceEquals(value, null) then
+            None
+        else
+            Some value
+
+
+    /// <summary>
+    ///
+    /// <c>bindNull binder option</c> evaluates to <c>match option with None -> None | Some x -> binder x |> Option.ofNull</c>
+    ///
+    /// Automatically onverts the result of binder that is pontentially null into an option.
+    /// </summary>
+    /// <param name="binder">A function that takes the value of type 'value from an option and transforms it into
+    /// a value of type 'nullableValue.</param>
+    /// <param name="option">The input option</param>
+    /// <typeparam name="'value"></typeparam>
+    /// <typeparam name="'nullableValue"></typeparam>
+    /// <returns>An option of the output type of the binder.</returns>
+    /// <seealso cref="ofNull"/>
+    let inline bindNull (binder: 'value -> 'nullableValue) (option: Option<'value>) =
+        match option with
+        | Some x -> binder x |> ofNull
+        | None -> None
diff --git a/src/FsToolkit.ErrorHandling/ValueOption.fs b/src/FsToolkit.ErrorHandling/ValueOption.fs
@@ -4,22 +4,22 @@ namespace FsToolkit.ErrorHandling
 [<RequireQualifiedAccess>]
 module ValueOption =
 
-    let ofOption (opt: 'a option) =
+    let inline ofOption (opt: 'a option) =
         match opt with
         | Some v -> ValueSome v
         | None -> ValueNone
 
-    let toOption (vopt: 'a voption) =
+    let inline toOption (vopt: 'a voption) =
         match vopt with
         | ValueSome v -> Some v
         | ValueNone -> None
 
-    let traverseResult f vopt =
+    let inline traverseResult f vopt =
         match vopt with
         | ValueNone -> Ok ValueNone
         | ValueSome v -> f v |> Result.map ValueSome
 
-    let sequenceResult opt = traverseResult id opt
+    let inline sequenceResult opt = traverseResult id opt
 
     let inline tryParse< ^T when ^T: (static member TryParse : string * byref< ^T > -> bool) and ^T: (new : unit -> ^T)>
         valueToParse
@@ -49,15 +49,51 @@ module ValueOption =
     /// <param name="voption1">The input option</param>
     /// <param name="voption2">The input option</param>
     /// <returns></returns>
-    let zip (voption1: 'a voption) (voption2: 'b voption) =
+    let inline zip (voption1: 'a voption) (voption2: 'b voption) =
         match voption1, voption2 with
         | ValueSome v1, ValueSome v2 -> ValueSome(v1, v2)
         | _ -> ValueNone
 
 
-    let ofResult =
-        function
+    let inline ofResult (result: Result<_, _>) =
+        match result with
         | Ok v -> ValueSome v
         | Error _ -> ValueNone
 
+
+    /// <summary>
+    /// Convert a potentially null value to an ValueOption.
+    ///
+    /// This is different from <see cref="FSharp.Core.ValueOption.ofObj">ValueOption.ofObj</see> where it doesn't require the value to be constrained to null.
+    /// This is beneficial where third party APIs may generate a record type using reflection and it can be null.
+    /// See <a href="https://latkin.org/blog/2015/05/18/null-checking-considerations-in-f-its-harder-than-you-think/">Null-checking considerations in F#</a> for more details.
+    /// </summary>
+    /// <param name="value">The potentially null value</param>
+    /// <returns>An ValueOption</returns>
+    /// <seealso cref="FSharp.Core.ValueOption.ofObj"/>
+    let inline ofNull (value: 'nullableValue) =
+        if System.Object.ReferenceEquals(value, null) then
+            ValueNone
+        else
+            ValueSome value
+
+
+    /// <summary>
+    ///
+    /// <c>bindNull binder voption</c> evaluates to <c>match voption with ValueNone -> ValueNone | ValueSome x -> binder x |> ValueOption.ofNull</c>
+    ///
+    /// Automatically onverts the result of binder that is pontentially null into an Valueoption.
+    /// </summary>
+    /// <param name="binder">A function that takes the value of type 'value from an voption and transforms it into
+    /// a value of type 'nullableValue.</param>
+    /// <param name="voption">The input voption</param>
+    /// <typeparam name="'value"></typeparam>
+    /// <typeparam name="'nullableValue"></typeparam>
+    /// <returns>A voption of the output type of the binder.</returns>
+    /// <seealso cref="ofNull"/>
+    let inline bindNull (binder: 'value -> 'nullableValue) (voption: ValueOption<'value>) =
+        match voption with
+        | ValueSome x -> binder x |> ofNull
+        | ValueNone -> ValueNone
+
 #endif
diff --git a/tests/FsToolkit.ErrorHandling.Tests/Option.fs b/tests/FsToolkit.ErrorHandling.Tests/Option.fs
@@ -84,10 +84,43 @@ let ofResultTests =
               Expect.equal (Option.ofResult (Error "x")) None "Error _" ]
 
 
+let ofNullTests =
+    testList
+        "Option.ofNull Tests"
+        [ testCase "A not null value"
+          <| fun _ ->
+              let someValue = "hello"
+              Expect.equal (Option.ofNull someValue) (Some someValue) ""
+          testCase "A null value"
+          <| fun _ ->
+              let (someValue: string) = null
+              Expect.equal (Option.ofNull someValue) (None) "" ]
+
+let bindNullTests =
+    testList
+        "Option.bindNull Tests"
+        [ testCase "Some notNull"
+          <| fun _ ->
+              let value1 = Some "world"
+              let someBinder _ = "hello"
+              Expect.equal (Option.bindNull someBinder value1) (Some "hello") ""
+          testCase "Some null"
+          <| fun _ ->
+              let value1 = Some "world"
+              let someBinder _ = null
+              Expect.equal (Option.bindNull someBinder value1) (None) ""
+          testCase "None"
+          <| fun _ ->
+              let value1 = None
+              let someBinder _ = "won't hit here"
+              Expect.equal (Option.bindNull someBinder value1) (None) "" ]
+
 let allTests =
     testList
         "Option Tests"
         [ traverseResultTests
           tryParseTests
           tryGetValueTests
-          ofResultTests ]
+          ofResultTests
+          ofNullTests
+          bindNullTests ]
diff --git a/tests/FsToolkit.ErrorHandling.Tests/ValueOption.fs b/tests/FsToolkit.ErrorHandling.Tests/ValueOption.fs
@@ -87,14 +87,46 @@ let ofResultTests =
               Expect.equal (ValueOption.ofResult (Ok "abc")) (ValueSome "abc") "Ok string"
               Expect.equal (ValueOption.ofResult (Error "x")) ValueNone "Error _" ]
 
+let ofNullTests =
+    testList
+        "ValueOption.ofNull Tests"
+        [ testCase "A not null value"
+          <| fun _ ->
+              let someValue = "hello"
+              Expect.equal (ValueOption.ofNull someValue) (ValueSome someValue) ""
+          testCase "A null value"
+          <| fun _ ->
+              let (someValue: string) = null
+              Expect.equal (ValueOption.ofNull someValue) (ValueNone) "" ]
+
+let bindNullTests =
+    testList
+        "ValueOption.bindNull Tests"
+        [ testCase "ValueSome notNull"
+          <| fun _ ->
+              let value1 = ValueSome "world"
+              let someBinder _ = "hello"
+              Expect.equal (ValueOption.bindNull someBinder value1) (ValueSome "hello") ""
+          testCase "ValueSome null"
+          <| fun _ ->
+              let value1 = ValueSome "world"
+              let someBinder _ = null
+              Expect.equal (ValueOption.bindNull someBinder value1) (ValueNone) ""
+          testCase "ValueNone"
+          <| fun _ ->
+              let value1 = ValueNone
+              let someBinder _ = "won't hit here"
+              Expect.equal (ValueOption.bindNull someBinder value1) (ValueNone) "" ]
 
 let allTests =
     testList
         "ValueOption Tests"
         [ traverseResultTests
           tryParseTests
           tryGetValueTests
-          ofResultTests ]
+          ofResultTests
+          ofNullTests
+          bindNullTests ]
 #else
 
 let allTests = testList "ValueOption Tests" []
