diff --git a/docs/fsharp/language-reference/active-patterns.md b/docs/fsharp/language-reference/active-patterns.md index cbc8ae04de099..d7960e5c975b7 100644 --- a/docs/fsharp/language-reference/active-patterns.md +++ b/docs/fsharp/language-reference/active-patterns.md @@ -177,6 +177,26 @@ let (|Int|_|) str = The attribute must be specified, because the use of a struct return is not inferred from simply changing the return type to `ValueOption`. For more information, see [RFC FS-1039](https://github.com/fsharp/fslang-design/blob/main/FSharp-6.0/FS-1039-struct-representation-for-active-patterns.md). +## Null active patterns + +In F# 9, nullability related active patterns were added. + +The first one is `| Null | NonNull x |`, which is a recommended way to handle possible nulls. In the following example, parameter `s` is inferred nullable via this active pattern usage: + +```fsharp + let len s = + match s with + | Null -> -1 + | NonNull s -> String.length s +``` + +If you rather want to automatically throw `NullReferenceException`, you can use the `| NonNullQuick |` pattern: + +```fsharp +let len (NonNullQuick str) = // throws if the argument is null + String.length str +``` + ## See also - [F# Language Reference](index.md) diff --git a/docs/fsharp/language-reference/compiler-directives.md b/docs/fsharp/language-reference/compiler-directives.md index a94b560561768..b467d5339cf6d 100644 --- a/docs/fsharp/language-reference/compiler-directives.md +++ b/docs/fsharp/language-reference/compiler-directives.md @@ -52,6 +52,28 @@ let str = "Debugging!" #endif ``` +## NULLABLE directive + +Starting with F# 9, you can enable nullable reference types in the project: + +```xml +enable +``` + +This automatically sets `NULLABLE` directive to the build. It's useful while initially rolling out the feature, to conditionally change conflicting code by `#if NULLABLE` hash directives: + +```fsharp +#if NULLABLE +let length (arg: 'T when 'T: not null) = + Seq.length arg +#else +let length arg = + match arg with + | null -> -1 + | s -> Seq.length s +#endif +``` + ## Line Directives When building, the compiler reports errors in F# code by referencing line numbers on which each error occurs. These line numbers start at 1 for the first line in a file. However, if you are generating F# source code from another tool, the line numbers in the generated code are generally not of interest, because the errors in the generated F# code most likely arise from another source. The `#line` directive provides a way for authors of tools that generate F# source code to pass information about the original line numbers and source files to the generated F# code. diff --git a/docs/fsharp/language-reference/compiler-options.md b/docs/fsharp/language-reference/compiler-options.md index ef5f3bc91fc0b..e25ef30c96b9f 100644 --- a/docs/fsharp/language-reference/compiler-options.md +++ b/docs/fsharp/language-reference/compiler-options.md @@ -18,6 +18,7 @@ The following table shows compiler options listed alphabetically. Some of the F# |`--allsigs`|Generates a new (or regenerates an existing) signature file for each source file in the compilation. For more information about signature files, see [Signatures](signature-files.md).| |`-a filename.fs`|Generates a library from the specified file. This option is a short form of `--target:library filename.fs`.| |`--baseaddress:address`|Specifies the preferred base address at which to load a DLL.

This compiler option is equivalent to the C# compiler option of the same name. For more information, see [/baseaddress (C# Compiler Options)](../../csharp/language-reference/compiler-options/advanced.md#baseaddress).| +|--checknulls[+|-]|Enables [nullable reference types](./values/null-values.md#null-values-starting-with-f-9), added in F# 9.| |`--codepage:id`|Specifies which code page to use during compilation if the required page isn't the current default code page for the system.

This compiler option is equivalent to the C# compiler option of the same name. For more information, see [/code pages (C# Compiler Options)](../../csharp/language-reference/compiler-options/advanced.md#codepage).| |`--consolecolors`|Specifies that errors and warnings use color-coded text on the console.| |`--crossoptimize[+ or -]`|Enables or disables cross-module optimizations.| diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 339af09765c7c..85bed67294c7d 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -27,6 +27,7 @@ Where lists appear in F# Interactive option arguments, list elements are separat |------|-----------| |**--**|Used to instruct F# Interactive to treat remaining arguments as command-line arguments to the F# program or script, which you can access in code by using the list **fsi.CommandLineArgs**.| |**--checked**[**+**|**-**]|Same as the **fsc.exe** compiler option. For more information, see [Compiler Options](compiler-options.md).| +|**--checknulls**[**+**|**-**]|Same as the **fsc.exe** compiler option. For more information, see [Compiler Options](compiler-options.md).| |**--codepage:<int>**|Same as the **fsc.exe** compiler option. For more information, see [Compiler Options](compiler-options.md).| |**--consolecolors**[**+**|**-**]|Outputs warning and error messages in color.| |**--compilertool:<extensionsfolder>|Reference an assembly or directory containing a design time tool (Short form: -t).| diff --git a/docs/fsharp/language-reference/generics/constraints.md b/docs/fsharp/language-reference/generics/constraints.md index 474fc7bdbe34d..0aa7683b52a7f 100644 --- a/docs/fsharp/language-reference/generics/constraints.md +++ b/docs/fsharp/language-reference/generics/constraints.md @@ -20,7 +20,8 @@ There are several different constraints you can apply to limit the types that ca |Constraint|Syntax|Description| |----------|------|-----------| |Type Constraint|*type-parameter* :> *type*|The provided type must be equal to or derived from the type specified, or, if the type is an interface, the provided type must implement the interface.| -|Null Constraint|*type-parameter* : null|The provided type must support the null literal. This includes all .NET object types but not F# list, tuple, function, class, record, or union types.| +|Null Constraint|*type-parameter* : null|The provided type must support the null value. This includes all .NET object types but not F# list, tuple, function, class, record, or union types.| +|Not Null Constraint|*type-parameter* : not null|The provided type must not support the null value. This disallows both `null` annotated types and types which have null as their representation value (such as the option type or types defined with AllowNullLiteral attribute). This generic constraint does allow value types, since those can never be null.| |Explicit Member Constraint|[(]*type-parameter* [or ... or *type-parameter*)] : (*member-signature*)|At least one of the type arguments provided must have a member that has the specified signature; not intended for common use. Members must be either explicitly defined on the type or part of an implicit type extension to be valid targets for an Explicit Member Constraint.| |Constructor Constraint|*type-parameter* : ( new : unit -> 'a )|The provided type must have a parameterless constructor.| |Value Type Constraint|*type-parameter* : struct|The provided type must be a .NET value type.| @@ -54,6 +55,10 @@ type Class2<'T when 'T :> System.IComparable> = type Class3<'T when 'T : null> = class end +// Not Null constraint +type Class4<'T when 'T : not null> = + class end + // Member constraint with instance member type Class5<'T when 'T : (member Method1 : 'T -> int)> = class end diff --git a/docs/fsharp/language-reference/pattern-matching.md b/docs/fsharp/language-reference/pattern-matching.md index 5535213a35d39..4ac2d0e7c6a87 100644 --- a/docs/fsharp/language-reference/pattern-matching.md +++ b/docs/fsharp/language-reference/pattern-matching.md @@ -210,6 +210,24 @@ The following example uses the null pattern and the variable pattern. [!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet4817.fs)] +Null pattern is also recommended for the F# 9 [nullability capabilities](./values/null-values.md#null-values-starting-with-f-9): + +```fsharp +let len (str: string | null) = + match str with + | null -> -1 + | s -> s.Length +``` + +Similarly, you can use new dedicated nullability related [patterns](./active-patterns.md): + +```fsharp +let let str = // str is inferred to be `string | null` + match str with + | Null -> -1 + | NonNull (s: string) -> s.Length +``` + ## Nameof pattern The `nameof` pattern matches against a string when its value is equal to the expression that follows the `nameof` keyword. for example: diff --git a/docs/fsharp/language-reference/values/null-values.md b/docs/fsharp/language-reference/values/null-values.md index f5187e754e22e..ff99f5a7ec3d7 100644 --- a/docs/fsharp/language-reference/values/null-values.md +++ b/docs/fsharp/language-reference/values/null-values.md @@ -7,7 +7,7 @@ ms.date: 08/15/2020 This topic describes how the null value is used in F#. -## Null Value +## Null Values Prior To F# 9 The null value is not normally used in F# for values or variables. However, null appears as an abnormal value in certain situations. If a type is defined in F#, null is not permitted as a regular value unless the [AllowNullLiteral](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-core-allownullliteralattribute.html#Value) attribute is applied to the type. If a type is defined in some other .NET language, null is a possible value, and when you are interoperating with such types, your F# code might encounter null values. @@ -31,6 +31,73 @@ You can use the following code to check if an arbitrary value is null. [!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-1/snippet703.fs)] +## Null Values starting with F# 9 + +In F# 9, extra capabilities are added to the language to deal with reference types which can have `null` as a value. Those are off by default - to turn them on, the following property must be put in your project file: + +```xml +enable +``` + +This passes the `--checknulls+` [flag](../compiler-options.md) to the F# compiler and sets a `NULLABLE` [preprocessor directive](../compiler-directives.md#nullable-directive) for the build. + +To explicitly opt-in into nullability, a type declaration has to be suffixed with the new syntax: + +```fsharp +type | null +``` + +The bar symbol `|` has the meaning of a logical OR in the syntax, building a union of two disjoint sets of types: the underlying type, and the nullable reference. This is the same syntactical symbol which is used for declaring multiple cases of an F# discriminated union: `type AB = A | B` carries the meaning of either `A`, or `B`. + +The nullable annotation `| null` can be used at all places where a reference type would be normally used: + +- Fields of union types, record types and custom types. +- Type aliases to existing types. +- Type applications of a generic type. +- Explicit type annotations to let bindings, parameters or return types. +- Type annotations to object-programming constructs like members, properties or fields. + +```fsharp +type AB = A | B +type AbNull = AB | null + +type RecordField = { X: string | null } +type TupleField = string * string | null + +type NestedGenerics = { Z : List | null> | null } +``` + +The bar symbol `|` does have other usages in F# which might lead to syntactical ambiguities. In such cases, parentheses are needed around the null-annotated type: + +```fsharp +// Unexpected symbol '|' (directly before 'null') in member definition +type DUField = N of string | null +``` + +Wrapping the same type into a pair of `( )` parentheses fixes the issue: + +```fsharp +type DUField = N of (string | null) +``` + +When used in pattern matching, `|` is used to separate different pattern matching clauses. + +```fsharp +match x with +| ?: string | null -> ... +``` + +This snippet is actually equivalent to code first doing a type test against the `string` type, and then having a separate clause for handling null: + +```fsharp +match x with +| ?: string +| null -> ... +``` + +> [!IMPORTANT] +> The extra null related capabilities were added to the language for the interoperability purposes. Using `| null` in F# type modeling is not considered idiomatic for denoting missing information - for that purpose, use options (as described above). Read more about null-related [conventions](../../style-guide/conventions.md#nulls-and-default-values) in the style guide. + ## See also - [Values](index.md) diff --git a/docs/fsharp/style-guide/component-design-guidelines.md b/docs/fsharp/style-guide/component-design-guidelines.md index f8ab19b497e16..ad0a369492aba 100644 --- a/docs/fsharp/style-guide/component-design-guidelines.md +++ b/docs/fsharp/style-guide/component-design-guidelines.md @@ -693,11 +693,51 @@ let checkNonNull argName (arg: obj) = | null -> nullArg argName | _ -> () -let checkNonNull` argName (arg: obj) = +let checkNonNull' argName (arg: obj) = if isNull arg then nullArg argName else () ``` +Starting with F# 9, you can leverage the new `| null` [syntax](../language-reference/values/null-values.md#null-values-starting-with-f-9) to make the compiler indicate possible null values and where they need handling: + +```fsharp +let checkNonNull argName (arg: obj | null) = + match arg with + | null -> nullArg argName + | _ -> () + +let checkNonNull' argName (arg: obj | null) = + if isNull arg then nullArg argName + else () +``` + +In F# 9, the compiler emits a warning when it detects that a possible null value is not handled: + +```fsharp +let printLineLength (s: string) = + printfn "%i" s.Length + +let readLineFromStream (sr: System.IO.StreamReader) = + // `ReadLine` may return null here - when the stream is finished + let line = sr.ReadLine() + // nullness warning: The types 'string' and 'string | null' + // do not have equivalent nullability + printLineLength line +``` + +These warnings should be addressed using F# [null pattern](../language-reference/pattern-matching.md#null-pattern) in matching: + +```fsharp +let printLineLength (s: string) = + printfn "%i" s.Length + +let readLineFromStream (sr: System.IO.StreamReader) = + let line = sr.ReadLine() + match line with + | null -> () + | s -> printLineLength s +``` + #### Avoid using tuples as return values Instead, prefer returning a named type holding the aggregate data, or using out parameters to return multiple values. Although tuples and struct tuples exist in .NET (including C# language support for struct tuples), they will most often not provide the ideal and expected API for .NET developers. diff --git a/docs/fsharp/style-guide/conventions.md b/docs/fsharp/style-guide/conventions.md index 61658bebff99a..ab4df74e63819 100644 --- a/docs/fsharp/style-guide/conventions.md +++ b/docs/fsharp/style-guide/conventions.md @@ -687,6 +687,54 @@ module Array = For legacy reasons some string functions in FSharp.Core still treat nulls as empty strings and do not fail on null arguments. However do not take this as guidance, and do not adopt coding patterns that attribute any semantic meaning to "null". +### Leverage F# 9 null syntax at the API boundaries + +F# 9 adds [syntax](../language-reference/values/null-values.md#null-values-starting-with-f-9) to explicitly state that a value can be null. It's designed to be used on the API boundaries, to make the compiler indicate the places where null handling is missing. + +Here is an example of the valid usage of the syntax: + +```fsharp +type CustomType(m1, m2) = + member _.M1 = m1 + member _.M2 = m2 + + override this.Equals(obj: obj | null) = + match obj with + | :? CustomType as other -> this.M1 = other.M1 && this.M2 = other.M2 + | _ -> false + + override this.GetHashCode() = + hash (this.M1, this.M2) +``` + +**Avoid** propagating nulls further down your F# code: + +```fsharp +let getLineFromStream (stream: System.IO.StreamReader) : string | null = + stream.ReadLine() +``` + +**Instead**, use idiomatic F# means (e.g., options): + +```fsharp +let getLineFromStream (stream: System.IO.StreamReader) = + stream.ReadLine() |> Option.ofObj +``` + +For raising null related exceptions you can use special `nullArgCheck` and `nonNull` functions. They're handy also because in case the value is not null, they [shadow](../language-reference/functions/index.md#scope) the argument with its sanitized value - the further code cannot access possible null pointers anymore. + +```fsharp +let inline processNullableList list = + let list = nullArgCheck (nameof list) list // throws `ArgumentNullException` + // 'list' is safe to use from now on + list |> List.distinct + +let inline processNullableList' list = + let list = nonNull list // throws `NullReferenceException` + // 'list' is safe to use from now on + list |> List.distinct +``` + ## Object programming F# has full support for objects and object-oriented (OO) concepts. Although many OO concepts are powerful and useful, not all of them are ideal to use. The following lists offer guidance on categories of OO features at a high level.