[RFC FS-1065.1] Addendum to RFC FS-1065: 'T option ↔ 'T voption conversion functions

RFCs/FS-1065.1-option-voption-conversion-functions.md

@@ -0,0 +1,76 @@
+# F# RFC FS-1065.1 - Addendum: functions for converting between `'T option` and `'T voption`
+
+This is an addendum to [RFC FS-1065](https://github.com/fsharp/fslang-design/blob/main/FSharp.Core-4.6.0/FS-1065-valueoption-parity.md).
+
+- [x] [Original RFC](https://github.com/fsharp/fslang-design/blob/main/FSharp.Core-4.6.0/FS-1065-valueoption-parity.md)
+- [x] [Implementation](https://github.com/dotnet/fsharp/pull/17436)
+
+# Summary
+
+We augment the `Option` and `ValueOption` modules with functions for converting `'T option` values to `'T voption` values and vice versa.
+
+# Motivation
+
+Usage of the `'T voption` type in F# code has continued to expand since its addition in [RFC FS-1057](https://github.com/fsharp/fslang-design/blob/main/FSharp.Core-4.5.0.0/FS-1057-valueoption.md). Usage of the existing `'T option` type, however, has not gone away, and the status quo is that many codebases have a mixture of `'T option` and `'T voption`.
+
+The ergonomics of this status quo are not ideal: converting between `'T option` and `'T voption` currently requires either verbose and repetitive inline pattern matching or the definition of conversion functions in every F# project.
+
+Just as the collection modules expose functions for converting between different collection types (`Array.toList`, `List.ofSeq`, etc.), adding conversion functions to the `Option` and `ValueOption` modules will reduce boilerplate and repetitive definition of trivial conversion functions in F# codebases.
+
+# Detailed design
+
+## Additions to the `Option` module
+
+```fsharp
+module Option =
+    /// <summary>Convert a value option to an option.</summary>
+    /// <param name="voption">The input value option.</param>
+    /// <returns>The resulting option.</returns>
+    [<CompiledName("OfValueOption")>]
+    val inline ofValueOption: voption: 'T voption -> 'T option
+
+    /// <summary>Convert an option to a value option.</summary>
+    /// <param name="option">The input option.</param>
+    /// <returns>The resulting value option.</returns>
+    [<CompiledName("ToValueOption")>]
+    val inline toValueOption: option: 'T option -> 'T voption
+```
+
+## Additions to the `ValueOption` module
+
+```fsharp
+module ValueOption =
+    /// <summary>Convert an option to a value option.</summary>
+    /// <param name="option">The input option.</param>
+    /// <returns>The resulting value option.</returns>
+    [<CompiledName("OfOption")>]
+    val inline ofOption: option: 'T option -> 'T voption
+
+    /// <summary>Convert a value option to an option.</summary>
+    /// <param name="voption">The input value option.</param>
+    /// <returns>The resulting option.</returns>
+    [<CompiledName("ToOption")>]
+    val inline toOption: voption: 'T voption -> 'T option
+```
+
+# Drawbacks
+
+None.
+
+# Alternatives
+
+Don't add these functions.
+
+# Compatibility
+
+This is a backwards-compatible addition to FSharp.Core.
+
+# Pragmatics
+
+# Diagnostics, tooling, performance, scaling
+
+N/A.
+
+# Unresolved questions
+
+None.