Skip to content

Commit be915bc

Browse files
BillWagnerBillWagner
committed
fix links
1 parent 58123df commit be915bc

File tree

1 file changed

+257
-1
lines changed

1 file changed

+257
-1
lines changed

Diff for: ‎standard/types.md

+257-1
Original file line numberDiff line numberDiff line change
@@ -720,7 +720,263 @@ An *unmanaged_type* is any type that isn’t a *reference_type*, a *type_paramet
720720
- `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `char`, `float`, `double`, `decimal`, or `bool`.
721721
- Any *enum_type*.
722722
- Any user-defined *struct_type* that is not a constructed type and contains instance fields of *unmanaged_type*s only.
723-
- In unsafe code ([§22.2](unsafe-code.md#222-unsafe-contexts)), any *pointer_type* ([§22.3](unsafe-code.md#223-pointer-types)).
723+
- In unsafe code ([§23.2](unsafe-code.md#232-unsafe-contexts)), any *pointer_type* ([§23.3](unsafe-code.md#233-pointer-types)).
724+
725+
## 8.9 Reference Types and nullability
726+
727+
### 8.9.1 General
728+
729+
A *nullable reference type* is denoted by appending a *nullable_type_annotation* (`?`) to a non-nullable reference type. There is no semantic difference between a non-nullable reference type and its corresponding nullable type, both can either be a reference to an object or `null`. The presence or absence of the *nullable_type_annotation* declares whether an expression is intended to permit null values or not. A compiler may provide diagnostics when an expression is not used according to that intent. The null state of an expression is defined in [§8.9.5](types.md#895-nullabilities-and-null-states). An identity conversion exists among a nullable reference type and its corresponding non-nullable reference type ([§10.2.2](conversions.md#1022-identity-conversion)).
730+
731+
There are two forms of nullability for reference types:
732+
733+
- *nullable*: A *nullable-reference-type* can be assigned `null`. Its default null state is *maybe-null*.
734+
- *non-nullable*: A *non-nullable reference* should not be assigned a `null` value. Its default null state is *not-null*.
735+
736+
> *Note:* The types `R` and `R?` are represented by the same underlying type, `R`. A variable of that underlying type can either contain a reference to an object or be the value `null`, which indicates “no reference.” *end note*
737+
738+
The syntactic distinction between a *nullable reference type* and its corresponding *non-nullable reference type* enables a compiler to generate diagnostics. A compiler must allow the *nullable_type_annotation* as defined in [§8.2.1](types.md#821-general). The diagnostics must be limited to warnings. Neither the presence or absence of nullable annotations, nor the state of the nullable context can change the compile time or runtime behavior of a program except for changes in any diagnostic messages generated at compile time.
739+
740+
### 8.9.2 Non-nullable reference types
741+
742+
A ***non-nullable reference type*** is a reference type of the form `T`, where `T` is the name of the type. The default null-state of a non-nullable variable is *not-null*. Warnings may be generated when an expression that is *maybe-null* is used where a *not-null* value is required.
743+
744+
### 8.9.3 Nullable reference types
745+
746+
A reference type of the form `T?` (such as `string?`) is a ***nullable reference type***. The default null-state of a nullable variable is *maybe null*. The annotation `?` indicates the intent that variables of this type are nullable. The compiler can recognize these intents to issue warnings. When the nullable annotation context is disabled, using this annotation can generate a warning.
747+
748+
### 8.9.4 Nullable context
749+
750+
#### 8.9.4.1 General
751+
752+
Every line of source code has a ***nullable context***. The annotations and warnings flags for the nullable context control nullable annotations ([§8.9.4.3](types.md#8943-nullable-annotations)) and nullable warnings ([§8.9.4.4](types.md#8944-nullable-warnings)), respectively. Each flag can be *enabled* or *disabled*. The compiler can use static flow analysis to determine the null state of any reference variable. A reference variable’s null state ([§8.9.5](types.md#895-nullabilities-and-null-states)) is either *not null*, *maybe null*, or *maybe default*.
753+
754+
The nullable context may be specified within source code via nullable directives ([§6.5.9](lexical-structure.md#659-nullable-directive)) and/or via some implementation-specific mechanism external to the source code. If both approaches are used, nullable directives supersede the settings made via an external mechanism.
755+
756+
The default state of the nullable context is implementation defined.
757+
758+
Throughout this specification, all C# code that does not contain nullable directives, or about which no statement is made regarding the current nullable context state, shall be assumed to have been compiled using a nullable context where both annotations and warnings are enabled.
759+
760+
> *Note:* A nullable context where both flags are disabled matches the previous standard behavior for reference types. *end note*
761+
762+
#### 8.9.4.2 Nullable disable
763+
764+
When both the warning and annotations flags are disabled, the nullable context is *disabled*.
765+
766+
When the nullable context is ***disabled***:
767+
768+
- No warning shall be generated when a variable of an unannotated reference type is initialized with, or assigned a value of, `null`.
769+
- No warning shall be generated when a variable of a reference type that possibly has the null value.
770+
- For any reference type `T`, the annotation `?` in `T?` generates a message and the type `T?` is the same as `T`.
771+
- For any type parameter constraint `where T : C?`, the annotation `?` in `C?` generates a message and the type `C?` is the same as `C`.
772+
- For any type parameter constraint `where T : U?`, the annotation `?` in `U?` generates a message and the type `U?` is the same as `U`.
773+
- The generic constraint `class?` generates a warning message. The type parameter must be a reference type.
774+
> *Note*: This message is characterized as “informational” rather than “warning,” so as not to confuse it with the state of the nullable warning setting, which is unrelated. *end note*
775+
- The null-forgiving operator `!` ([§12.8.9](expressions.md#1289-null-forgiving-expressions)) has no effect.
776+
777+
> *Example*:
778+
>
779+
> <!-- Example: {template:"code-in-main-without-using", name:"NullableAnnotationContext1", ignoredWarnings:["CS0219","CS8632"], expectedException:"NullReferenceException"} -->
780+
> ```csharp
781+
> #nullable disable annotations
782+
> string? s1 = null; // Informational message; ? is ignored
783+
> string s2 = null; // OK; null initialization of a reference
784+
> s2 = null; // OK; null assignment to a reference
785+
> char c1 = s2[1]; // OK; no warning on dereference of a possible null;
786+
> // throws NullReferenceException
787+
> c1 = s2![1]; // OK; ! is ignored
788+
> ```
789+
>
790+
> *end example*
791+
792+
#### 8.9.4.3 Nullable annotations
793+
794+
When the warning flag is disabled and the annotations flag is enabled, the nullable context is *annotations*.
795+
796+
When the nullable context is ***annotations***:
797+
798+
- For any reference type `T`, the annotation `?` in `T?` indicates that `T?` a nullable type, whereas the unannotated `T` is non-nullable.
799+
- No diagnostic warnings related to nullability are generated.
800+
- The null-forgiving operator `!` ([§12.8.9](expressions.md#1289-null-forgiving-expressions)) may alter the analyzed null state of its operand and what compile time diagnostic warnings are produced.
801+
802+
> *Example*:
803+
>
804+
> <!-- Example: {template:"code-in-main-without-using", name:"NullableAnnotationContext2", ignoredWarnings:["CS0219"], expectedException:"NullReferenceException"} -->
805+
> ```csharp
806+
> #nullable disable warnings
807+
> #nullable enable annotations
808+
> string? s1 = null; // OK; ? makes s2 nullable
809+
> string s2 = null; // OK; warnings are disabled
810+
> s2 = null; // OK; warnings are disabled
811+
> char c1 = s2[1]; // OK; warnings are disabled; throws NullReferenceException
812+
> c1 = s2![1]; // No warnings
813+
> ```
814+
>
815+
> *end example*
816+
817+
#### 8.9.4.4 Nullable warnings
818+
819+
When the warning flag is enabled and the annotations flag is disabled, the nullable context is *warnings*.
820+
821+
When the nullable context is ***warnings***, a compiler can generate diagnostics in the following cases:
822+
823+
- A reference variable that has been determined to be *maybe null*, is dereferenced.
824+
- A reference variable of a non-nullable type is assigned to an expression that is *maybe null*.
825+
- The `?` is used to note a nullable reference type.
826+
- The null-forgiving operator `!` ([§12.8.9](expressions.md#1289-null-forgiving-expressions)) is used to set the null state of its operand to *not null*.
827+
828+
> *Example*:
829+
>
830+
> <!-- Example: {template:"code-in-main-without-using", name:"NullableAnnotationContext3", ignoredWarnings:["CS0219"], expectedWarnings:["CS8632", "CS8602"], expectedException:"NullReferenceException"} -->
831+
> ```csharp
832+
> #nullable disable annotations
833+
> #nullable enable warnings
834+
> string? s1 = null; // OK; ? makes s2 nullable
835+
> string s2 = null; // OK; null-state of s2 is "maybe null"
836+
> s2 = null; // OK; null-state of s2 is "maybe null"
837+
> char c1 = s2[1]; // Warning; dereference of a possible null;
838+
> // throws NullReferenceException
839+
> c1 = s2![1]; // The warning is suppressed
840+
> ```
841+
>
842+
> *end example*
843+
844+
#### 8.9.4.5 Nullable enable
845+
846+
When both the warning flag and the annotations flag are enabled, the nullable context is *enabled*.
847+
848+
When the nullable context is ***enabled***:
849+
850+
- For any reference type `T`, the annotation `?` in `T?` makes `T?` a nullable type, whereas the unannotated `T` is non-nullable.
851+
- The compiler can use static flow analysis to determine the null state of any reference variable. When nullable warnings are enabled, a reference variable’s null state ([§8.9.5](types.md#895-nullabilities-and-null-states)) is either *not null*, *maybe null*, or *maybe default* and
852+
- The null-forgiving operator `!` ([§12.8.9](expressions.md#1289-null-forgiving-expressions)) sets the null state of its operand to *not null*.
853+
- The compiler can issue a warning if the nullability of a type parameter doesn’t match the nullability of its corresponding type argument.
854+
855+
### 8.9.5 Nullabilities and null states
856+
857+
A compiler is not required to perform any static analysis nor is it required to generate any diagnostic warnings related to nullability.
858+
859+
**The remainder of this subclause is conditionally normative.**
860+
861+
A compiler that generates diagnostic warnings conforms to these rules.
862+
863+
Every expression has one of three ***null state***s:
864+
865+
- *maybe null*: The value of the expression may evaluate to null.
866+
- *maybe default*: The value of the expression may evaluate to the default value for that type.
867+
- *not null*: The value of the expression isn’t null.
868+
869+
The ***default null state*** of an expression is determined by its type, and the state of the annotations flag when it is declared:
870+
871+
- The default null state of a nullable reference type is:
872+
- Maybe null when its declaration is in text where the annotations flag is enabled.
873+
- Not null when its declaration is in text where the annotations flag is disabled.
874+
- The default null state of a non-nullable reference type is not null.
875+
876+
> *Note:* The *maybe default* state is used with unconstrained type parameters when the type is a non-nullable type, such as `string` and the expression `default(T)` is the null value. Because null is not in the domain for the non-nullable type, the state is maybe default. *end note*
877+
878+
A diagnostic can be produced when a variable ([§9.2.1](variables.md#921-general)) of a non-nullable reference type is initialized or assigned to an expression that is maybe null when that variable is declared in text where the annotation flag is enabled.
879+
880+
> *Example*: Consider the following method where a parameter is nullable and that value is assigned to a non-nullable type:
881+
>
882+
> <!-- Example: {template:"code-in-class-lib", name:"NullableAssignment", expectedWarnings:["CS8600"]} -->
883+
> ```csharp
884+
> #nullable enable
885+
> public class C
886+
> {
887+
> public void M(string? p)
888+
> {
889+
> // Assignment of maybe null value to non-nullable variable
890+
> string s = p;
891+
> }
892+
> }
893+
> ```
894+
>
895+
> The compiler may issue a warning where the parameter that might be null is assigned to a variable that should not be null. If the parameter is null-checked before assignment, the compiler may use that in its nullable state analysis and not issue a warning:
896+
>
897+
> <!-- Example: {template:"code-in-class-lib", name:"NullChecked"} -->
898+
> ```csharp
899+
> #nullable enable
900+
> public class C
901+
> {
902+
> public void M(string? p)
903+
> {
904+
> if (p != null)
905+
> {
906+
> string s = p;
907+
> // Use s
908+
> }
909+
> }
910+
> }
911+
> ```
912+
>
913+
> *end example*
914+
915+
The compiler can update the null state of a variable as part of its analysis.
916+
917+
> *Example*: The compiler may choose to update the state based on any statements in your program:
918+
>
919+
> <!-- Example: {template:"code-in-class-lib", name:"UpdateStates", expectedWarnings:["CS8602","CS8602"]} -->
920+
> ```csharp
921+
> #nullable enable
922+
> public void M(string? p)
923+
> {
924+
> // p is maybe-null
925+
> int length = p.Length;
926+
>
927+
> // p is not null.
928+
> string s = p;
929+
>
930+
> if (s != null)
931+
> {
932+
> int l2 = s.Length;
933+
> }
934+
> // s is maybe null
935+
> int l3 = s.Length;
936+
> }
937+
> ```
938+
>
939+
> In the previous example, the compiler may decide that after the statement `int length = p.Length;`, the null-state of `p` is not-null. If it were null, that statement would have thrown a `NullReferenceException`. This is similar to the behavior if the code had been preceded by `if (p == null) throw NullReferenceException();` except that the code as written may produce a warning, the purpose of which is to warn that an exception may be thrown implicitly.
940+
941+
Later in the method, the code checks that `s` is not a null reference. The null-state of `s` can change to maybe null after the null-checked block closes. The compiler can infer that `s` is maybe null because the code was written to assume that it might have been null. Generally, when the code contains a null check, the compiler may infer that the value might have been null.*end example*
942+
<!-- markdownlint-disable MD028 -->
943+
944+
<!-- markdownlint-enable MD028 -->
945+
> *Example*: The compiler can treat a property ([§15.7](classes.md#157-properties)) as either a variable with state, or as independent get and set accessors ([§15.7.3](classes.md#1573-accessors)). In other words, a compiler can choose whether writing to a property changes the null state of reading the property, or if reading a property changes the null state of that property.
946+
>
947+
> <!-- Example: {template:"standalone-console", name:"NullPropertyAnalysis"} -->
948+
> ```csharp
949+
> class Test
950+
> {
951+
> private string? _field;
952+
> public string? DisappearingProperty
953+
> {
954+
> get
955+
> {
956+
> string tmp = _field;
957+
> _field = null;
958+
> return tmp;
959+
> }
960+
> set
961+
> {
962+
> _field = value;
963+
> }
964+
> }
965+
>
966+
> static void Main()
967+
> {
968+
> var t = new Test();
969+
> if (t.DisappearingProperty != null)
970+
> {
971+
> int len = t.DisappearingProperty.Length;
972+
> }
973+
> }
974+
> }
975+
> ```
976+
>
977+
> In the previous example, the backing field for the `DisappearingProperty` is set to null when it is read. However, a compiler may assume that reading a property doesn’t change the null state of that expression. *end example*
978+
979+
***End of conditionally normative text***
724980
725981
726982
## 8.9 Reference Types and nullability

0 commit comments

Comments
 (0)