Nullable(T) Structure
TOC
Collapse the table of content
Expand the table of content

Nullable(Of T) Structure

 

Represents a value type that can be assigned null.

Namespace:   System
Assembly:  mscorlib (in mscorlib.dll)

<SerializableAttribute>
Public Structure Nullable(Of T As Structure)

Type Parameters

T

The underlying value type of the Nullable(Of T) generic type.

NameDescription
System_CAPS_pubmethodNullable(Of T)(T)

Initializes a new instance of the Nullable(Of T) structure to the specified value.

NameDescription
System_CAPS_pubpropertyHasValue

Gets a value indicating whether the current Nullable(Of T) object has a valid value of its underlying type.

System_CAPS_pubpropertyValue

Gets the value of the current Nullable(Of T) object if it has been assigned a valid underlying value.

NameDescription
System_CAPS_pubmethodEquals(Object)

Indicates whether the current Nullable(Of T) object is equal to a specified object.(Overrides ValueType.Equals(Object).)

System_CAPS_pubmethodGetHashCode()

Retrieves the hash code of the object returned by the Value property.(Overrides ValueType.GetHashCode().)

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethodGetValueOrDefault()

Retrieves the value of the current Nullable(Of T) object, or the object's default value.

System_CAPS_pubmethodGetValueOrDefault(T)

Retrieves the value of the current Nullable(Of T) object, or the specified default value.

System_CAPS_pubmethodToString()

Returns the text representation of the value of the current Nullable(Of T) object.(Overrides ValueType.ToString().)

NameDescription
System_CAPS_puboperatorSystem_CAPS_staticNarrowing(Nullable(Of T) to T)

Defines an explicit conversion of a Nullable(Of T) instance to its underlying value.

System_CAPS_puboperatorSystem_CAPS_staticWidening(T to Nullable(Of T))

Creates a new Nullable(Of T) object initialized to a specified value.

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(Of 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(Of 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.

The two fundamental members of the Nullable(Of T) structure are the HasValue and Value properties. If the HasValue property for a Nullable(Of 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.

When a nullable type is boxed, the common language runtime automatically boxes the underlying value of the Nullable(Of T) object, not the Nullable(Of 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(Of 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(Of T) structure and initializes its HasValue property to false.

Starting with the .NET Framework 4.5.1, you can include a Nullable(Of T) type as a member of a structure exported in a WinMD library. Previously, this was not supported.

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.

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.

Universal Windows Platform
Available since 4.5
.NET Framework
Available since 2.0
Portable Class Library
Supported in: portable .NET platforms
Silverlight
Available since 2.0
Windows Phone Silverlight
Available since 7.0
Windows Phone
Available since 8.1

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
Show:
© 2016 Microsoft