netcore/System.Private.CoreLib/shared/System/Diagnostics/CodeAnalysis/NullableAttributes.cs

   1 // Licensed to the .NET Foundation under one or more agreements.
   2 // The .NET Foundation licenses this file to you under the MIT license.
   3 // See the LICENSE file in the project root for more information.
   4
   5 namespace System.Diagnostics.CodeAnalysis
   6 {
   7     /// <summary>Specifies that null is allowed as an input even if the corresponding type disallows it.</summary>
   8     [AttributeUsage(AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property, Inherited = false)]
   9 #if INTERNAL_NULLABLE_ATTRIBUTES
  10     internal
  11 #else
  12     public
  13 #endif
  14         sealed class AllowNullAttribute : Attribute { }
  15
  16     /// <summary>Specifies that null is disallowed as an input even if the corresponding type allows it.</summary>
  17     [AttributeUsage(AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property, Inherited = false)]
  18 #if INTERNAL_NULLABLE_ATTRIBUTES
  19     internal
  20 #else
  21     public
  22 #endif
  23         sealed class DisallowNullAttribute : Attribute { }
  24
  25     /// <summary>Specifies that an output may be null even if the corresponding type disallows it.</summary>
  26     [AttributeUsage(AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property | AttributeTargets.ReturnValue, Inherited = false)]
  27 #if INTERNAL_NULLABLE_ATTRIBUTES
  28     internal
  29 #else
  30     public
  31 #endif
  32         sealed class MaybeNullAttribute : Attribute { }
  33
  34     /// <summary>Specifies that an output will not be null even if the corresponding type allows it.</summary>
  35     [AttributeUsage(AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property | AttributeTargets.ReturnValue, Inherited = false)]
  36 #if INTERNAL_NULLABLE_ATTRIBUTES
  37     internal
  38 #else
  39     public
  40 #endif
  41         sealed class NotNullAttribute : Attribute { }
  42
  43     /// <summary>Specifies that when a method returns <see cref="ReturnValue"/>, the parameter may be null even if the corresponding type disallows it.</summary>
  44     [AttributeUsage(AttributeTargets.Parameter, Inherited = false)]
  45 #if INTERNAL_NULLABLE_ATTRIBUTES
  46     internal
  47 #else
  48     public
  49 #endif
  50         sealed class MaybeNullWhenAttribute : Attribute
  51     {
  52         /// <summary>Initializes the attribute with the specified return value condition.</summary>
  53         /// <param name="returnValue">
  54         /// The return value condition. If the method returns this value, the associated parameter may be null.
  55         /// </param>
  56         public MaybeNullWhenAttribute(bool returnValue) => ReturnValue = returnValue;
  57
  58         /// <summary>Gets the return value condition.</summary>
  59         public bool ReturnValue { get; }
  60     }
  61
  62     /// <summary>Specifies that when a method returns <see cref="ReturnValue"/>, the parameter will not be null even if the corresponding type allows it.</summary>
  63     [AttributeUsage(AttributeTargets.Parameter, Inherited = false)]
  64 #if INTERNAL_NULLABLE_ATTRIBUTES
  65     internal
  66 #else
  67     public
  68 #endif
  69         sealed class NotNullWhenAttribute : Attribute
  70     {
  71         /// <summary>Initializes the attribute with the specified return value condition.</summary>
  72         /// <param name="returnValue">
  73         /// The return value condition. If the method returns this value, the associated parameter will not be null.
  74         /// </param>
  75         public NotNullWhenAttribute(bool returnValue) => ReturnValue = returnValue;
  76
  77         /// <summary>Gets the return value condition.</summary>
  78         public bool ReturnValue { get; }
  79     }
  80
  81     /// <summary>Specifies that the output will be non-null if the named parameter is non-null.</summary>
  82     [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property | AttributeTargets.ReturnValue, AllowMultiple = true, Inherited = false)]
  83 #if INTERNAL_NULLABLE_ATTRIBUTES
  84     internal
  85 #else
  86     public
  87 #endif
  88         sealed class NotNullIfNotNullAttribute : Attribute
  89     {
  90         /// <summary>Initializes the attribute with the associated parameter name.</summary>
  91         /// <param name="parameterName">
  92         /// The associated parameter name.  The output will be non-null if the argument to the parameter specified is non-null.
  93         /// </param>
  94         public NotNullIfNotNullAttribute(string parameterName) => ParameterName = parameterName;
  95
  96         /// <summary>Gets the associated parameter name.</summary>
  97         public string ParameterName { get; }
  98     }
  99
 100     /// <summary>Applied to a method that will never return under any circumstance.</summary>
 101     [AttributeUsage(AttributeTargets.Method, Inherited = false)]
 102 #if INTERNAL_NULLABLE_ATTRIBUTES
 103     internal
 104 #else
 105     public
 106 #endif
 107         sealed class DoesNotReturnAttribute : Attribute { }
 108
 109     /// <summary>Specifies that the method will not return if the associated Boolean parameter is passed the specified value.</summary>
 110     [AttributeUsage(AttributeTargets.Parameter, Inherited = false)]
 111 #if INTERNAL_NULLABLE_ATTRIBUTES
 112     internal
 113 #else
 114     public
 115 #endif
 116         sealed class DoesNotReturnIfAttribute : Attribute
 117     {
 118         /// <summary>Initializes the attribute with the specified parameter value.</summary>
 119         /// <param name="parameterValue">
 120         /// The condition parameter value. Code after the method will be considered unreachable by diagnostics if the argument to
 121         /// the associated parameter matches this value.
 122         /// </param>
 123         public DoesNotReturnIfAttribute(bool parameterValue) => ParameterValue = parameterValue;
 124
 125         /// <summary>Gets the condition parameter value.</summary>
 126         public bool ParameterValue { get; }
 127     }
 128 }