Nullable<T> Struct
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Represents a value type that can be assigned null.
generic <typename T>
where T : value classpublic value class Nullablepublic struct Nullable<T> where T : struct[System.Serializable]
public struct Nullable<T> where T : structtype Nullable<'T (requires 'T : struct)> = struct[<System.Serializable>]
type Nullable<'T (requires 'T : struct)> = structPublic Structure Nullable(Of T)Type Parameters
- T
The underlying value type of the Nullable<T> generic type.
- Inheritance
- Attributes
Examples
The following code example defines three rows of a table in the Microsoft Pubs sample database. The table contains two columns that are not nullable and two columns that are nullable.
using namespace System;
// Define the "titleAuthor" table of the Microsoft "pubs" database.
value struct titleAuthor
{
public:
// Author ID; format ###-##-####
String^ au_id;
// Title ID; format AA####
String^ title_id;
// Author ORD is nullable.
Nullable<short> au_ord;
// Royalty Percent is nullable.
Nullable<int> royaltyper;
// Display the values of the titleAuthor array elements.
static void Display(String^ dspTitle,
array<titleAuthor>^ dspAllTitleAuthors)
{
Console::WriteLine("*** {0} ***", dspTitle);
for each (titleAuthor dspTA in dspAllTitleAuthors) {
Console::WriteLine("Author ID ... {0}", dspTA.au_id);
Console::WriteLine("Title ID .... {0}", dspTA.title_id);
Console::WriteLine("Author ORD .. {0}", dspTA.au_ord.HasValue ?
dspTA.au_ord.Value : -1);
Console::WriteLine("Royalty % ... {0}", dspTA.royaltyper.HasValue ?
dspTA.royaltyper.Value : 0);
Console::WriteLine();
}
}
};
void main()
{
// Declare and initialize the titleAuthor array.
array<titleAuthor>^ ta = gcnew array<titleAuthor>(3);
ta[0].au_id = "712-32-1176";
ta[0].title_id = "PS3333";
ta[0].au_ord = 1;
ta[0].royaltyper = 100;
ta[1].au_id = "213-46-8915";
ta[1].title_id = "BU1032";
// ta[1].au_ord = nullptr;
// ta[1].royaltyper = nullptr;
ta[2].au_id = "672-71-3249";
ta[2].title_id = "TC7777";
// ta[2].au_ord = nullptr;
ta[2].royaltyper = 40;
// Display the values of the array elements, and
// display a legend.
titleAuthor::Display("Title Authors Table", ta);
Console::WriteLine("Legend:");
Console::WriteLine("An Author ORD of -1 means no value is defined.");
Console::WriteLine("A Royalty % of 0 means no value is defined.");
}
// The example displays the following output:
// *** Title Authors Table ***
// Author ID ... 712-32-1176
// Title ID .... PS3333
// Author ORD .. 1
// Royalty % ... 100
//
// Author ID ... 213-46-8915
// Title ID .... BU1032
// Author ORD .. -1
// Royalty % ... 0
//
// Author ID ... 672-71-3249
// Title ID .... TC7777
// Author ORD .. -1
// Royalty % ... 40
//
// Legend:
// An Author ORD of -1 means no value is defined.
// A Royalty % of 0 means no value is defined.
using System;
class Sample
{
// Define the "titleAuthor" table of the Microsoft "pubs" database.
public struct titleAuthor
{
// Author ID; format ###-##-####
public string au_id;
// Title ID; format AA####
public string title_id;
// Author ORD is nullable.
public short? au_ord;
// Royalty Percent is nullable.
public int? royaltyper;
}
public static void Main()
{
// Declare and initialize the titleAuthor array.
titleAuthor[] ta = new titleAuthor[3];
ta[0].au_id = "712-32-1176";
ta[0].title_id = "PS3333";
ta[0].au_ord = 1;
ta[0].royaltyper = 100;
ta[1].au_id = "213-46-8915";
ta[1].title_id = "BU1032";
ta[1].au_ord = null;
ta[1].royaltyper = null;
ta[2].au_id = "672-71-3249";
ta[2].title_id = "TC7777";
ta[2].au_ord = null;
ta[2].royaltyper = 40;
// Display the values of the titleAuthor array elements, and
// display a legend.
Display("Title Authors Table", ta);
Console.WriteLine("Legend:");
Console.WriteLine("An Author ORD of -1 means no value is defined.");
Console.WriteLine("A Royalty % of 0 means no value is defined.");
}
// Display the values of the titleAuthor array elements.
public static void Display(string dspTitle,
titleAuthor[] dspAllTitleAuthors)
{
Console.WriteLine("*** {0} ***", dspTitle);
foreach (titleAuthor dspTA in dspAllTitleAuthors) {
Console.WriteLine("Author ID ... {0}", dspTA.au_id);
Console.WriteLine("Title ID .... {0}", dspTA.title_id);
Console.WriteLine("Author ORD .. {0}", dspTA.au_ord ?? -1);
Console.WriteLine("Royalty % ... {0}", dspTA.royaltyper ?? 0);
Console.WriteLine();
}
}
}
// The example displays the following output:
// *** Title Authors Table ***
// Author ID ... 712-32-1176
// Title ID .... PS3333
// Author ORD .. 1
// Royalty % ... 100
//
// Author ID ... 213-46-8915
// Title ID .... BU1032
// Author ORD .. -1
// Royalty % ... 0
//
// Author ID ... 672-71-3249
// Title ID .... TC7777
// Author ORD .. -1
// Royalty % ... 40
//
// Legend:
// An Author ORD of -1 means no value is defined.
// A Royalty % of 0 means no value is defined.
open System
// Define the "titleAuthor" table of the Microsoft "pubs" database.
type titleAuthor =
struct
// Author ID format ###-##-####
val mutable au_id: string
// Title ID format AA####
val mutable title_id: string
// Author ORD is nullable.
val mutable au_ord: Nullable<int16>
// Royalty Percent is nullable.
val mutable royaltyper: Nullable<int>
end
// Display the values of the titleAuthor array elements.
let display dspTitle (dspAllTitleAuthors: #seq<titleAuthor>) =
printfn $"*** {dspTitle} ***"
for dspTA in dspAllTitleAuthors do
printfn $"Author ID ... {dspTA.au_id}"
printfn $"Title ID .... {dspTA.title_id}"
printfn $"Author ORD .. {dspTA.au_ord.GetValueOrDefault -1s}"
printfn $"Royalty %% ... {dspTA.royaltyper.GetValueOrDefault -1}\n"
// Declare and initialize the titleAuthor array.
let ta = Array.zeroCreate<titleAuthor> 3
ta[0].au_id <- "712-32-1176"
ta[0].title_id <- "PS3333"
ta[0].au_ord <- Nullable 1s
ta[0].royaltyper <- Nullable 100
ta[1].au_id <- "213-46-8915"
ta[1].title_id <- "BU1032"
ta[1].au_ord <- Nullable()
ta[1].royaltyper <- Nullable()
ta[2].au_id <- "672-71-3249"
ta[2].title_id <- "TC7777"
ta[2].au_ord <- Nullable()
ta[2].royaltyper <- Nullable 40
// Display the values of the titleAuthor array elements, and
// display a legend.
display "Title Authors Table" ta
printfn "Legend:"
printfn "An Author ORD of -1 means no value is defined."
printfn "A Royalty %% of 0 means no value is defined."
// The example displays the following output:
// *** Title Authors Table ***
// Author ID ... 712-32-1176
// Title ID .... PS3333
// Author ORD .. 1
// Royalty % ... 100
//
// Author ID ... 213-46-8915
// Title ID .... BU1032
// Author ORD .. -1
// Royalty % ... 0
//
// Author ID ... 672-71-3249
// Title ID .... TC7777
// Author ORD .. -1
// Royalty % ... 40
//
// Legend:
// An Author ORD of -1 means no value is defined.
// A Royalty % of 0 means no value is defined.
Class Sample
' Define the "titleAuthor" table of the Microsoft "pubs" database.
Public Structure titleAuthor
' Author ID; format ###-##-####
Public au_id As String
' Title ID; format AA####
Public title_id As String
' Author ORD is nullable.
Public au_ord As Nullable(Of Short)
' Royalty Percent is nullable.
Public royaltyper As Nullable(Of Integer)
End Structure
Public Shared Sub Main()
' Declare and initialize the titleAuthor array.
Dim ta(2) As titleAuthor
ta(0).au_id = "712-32-1176"
ta(0).title_id = "PS3333"
ta(0).au_ord = 1
ta(0).royaltyper = 100
ta(1).au_id = "213-46-8915"
ta(1).title_id = "BU1032"
ta(1).au_ord = Nothing
ta(1).royaltyper = Nothing
ta(2).au_id = "672-71-3249"
ta(2).title_id = "TC7777"
ta(2).au_ord = Nothing
ta(2).royaltyper = 40
' Display the values of the titleAuthor array elements, and
' display a legend.
Display("Title Authors Table", ta)
Console.WriteLine("Legend:")
Console.WriteLine("An Author ORD of -1 means no value is defined.")
Console.WriteLine("A Royalty % of 0 means no value is defined.")
End Sub
' Display the values of the titleAuthor array elements.
Public Shared Sub Display(ByVal dspTitle As String, _
ByVal dspAllTitleAuthors() As titleAuthor)
Console.WriteLine("*** {0} ***", dspTitle)
Dim dspTA As titleAuthor
For Each dspTA In dspAllTitleAuthors
Console.WriteLine("Author ID ... {0}", dspTA.au_id)
Console.WriteLine("Title ID .... {0}", dspTA.title_id)
Console.WriteLine("Author ORD .. {0}", dspTA.au_ord.GetValueOrDefault(-1))
Console.WriteLine("Royalty % ... {0}", dspTA.royaltyper.GetValueOrDefault(0))
Console.WriteLine()
Next
End Sub
End Class
'This example displays the following output:
' *** Title Authors Table ***
' Author ID ... 712-32-1176
' Title ID .... PS3333
' Author ORD .. 1
' Royalty % ... 100
'
' Author ID ... 213-46-8915
' Title ID .... BU1032
' Author ORD .. -1
' Royalty % ... 0
'
' Author ID ... 672-71-3249
' Title ID .... TC7777
' Author ORD .. -1
' Royalty % ... 40
'
' Legend:
' An Author ORD of -1 means no value is defined.
' A Royalty % of 0 means no value is defined.
Remarks
A type is said to be nullable if it can be assigned a value or can be assigned null, which means the type has no value whatsoever. By default, all reference types, such as String, are nullable, but all value types, such as Int32, are not.
In C# and Visual Basic, you mark a value type as nullable by using the ? notation after the value type. For example, int? in C# or Integer? in Visual Basic declares an integer value type that can be assigned null.
The Nullable<T> structure supports using only a value type as a nullable type because reference types are nullable by design.
The Nullable class provides complementary support for the Nullable<T> structure. The Nullable class supports obtaining the underlying type of a nullable type, and comparison and equality operations on pairs of nullable types whose underlying value type does not support generic comparison and equality operations.
Fundamental Properties
The two fundamental members of the Nullable<T> structure are the HasValue and Value properties. If the HasValue property for a Nullable<T> object is true, the value of the object can be accessed with the Value property. If the HasValue property is false, the value of the object is undefined and an attempt to access the Value property throws an InvalidOperationException.
Boxing and Unboxing
When a nullable type is boxed, the common language runtime automatically boxes the underlying value of the Nullable<T> object, not the Nullable<T> object itself. That is, if the HasValue property is true, the contents of the Value property is boxed. When the underlying value of a nullable type is unboxed, the common language runtime creates a new Nullable<T> structure initialized to the underlying value.
If the HasValue property of a nullable type is false, the result of a boxing operation is null. Consequently, if a boxed nullable type is passed to a method that expects an object argument, that method must be prepared to handle the case where the argument is null. When null is unboxed into a nullable type, the common language runtime creates a new Nullable<T> structure and initializes its HasValue property to false.
.NET Framework 4.5.1 and Windows Runtime Components
Starting with the .NET Framework 4.5.1, you can include a Nullable<T> type as a member of a structure exported in a WinMD library. Previously, this was not supported.
Constructors
| Nullable<T>(T) |
Initializes a new instance of the Nullable<T> structure to the specified value. |
Properties
| HasValue |
Gets a value indicating whether the current Nullable<T> object has a valid value of its underlying type. |
| Value |
Gets the value of the current Nullable<T> object if it has been assigned a valid underlying value. |
Methods
| Equals(Object) |
Indicates whether the current Nullable<T> object is equal to a specified object. |
| GetHashCode() |
Retrieves the hash code of the object returned by the Value property. |
| GetValueOrDefault() |
Retrieves the value of the current Nullable<T> object, or the default value of the underlying type. |
| GetValueOrDefault(T) |
Retrieves the value of the current Nullable<T> object, or the specified default value. |
| ToString() |
Returns the text representation of the value of the current Nullable<T> object. |
Operators
| Explicit(Nullable<T> to T) |
Defines an explicit conversion of a Nullable<T> instance to its underlying value. |
| Implicit(T to Nullable<T>) |
Creates a new Nullable<T> object initialized to a specified value. |