nullptr

nullptr indicates that an object handle, interior pointer, or native pointer type does not point to an object. nullptr is only valid when compiling with /clr (Common Language Runtime Compilation).

You cannot initialize handles to zero; only nullptr can be used. Assignment of constant 0 to an object handle will produce a boxed Int32 and a cast to Object^.

nullptr can be used in the initialization of the following pointer types:

• Native pointer:

• Managed handle:

• Managed interior pointer:

nullptr can be used for reference checking before using a pointer.

nullptr can be used anywhere a handle or a native pointer can be used. nullptr can also be used as an argument for functions.

// mcpp_nullptr.cpp
// compile with: /clr
value class V {};
ref class G {};
void f(System::Object ^) {}

int main() {
   int *pN = nullptr;
   G ^pG = nullptr;
   V ^pV1 = nullptr;
   interior_ptr<V> pV2 = nullptr;

   if (pN == nullptr) {}
   if (pG == nullptr) {}
   if (pV1 == nullptr) {}
   if (pV2 == nullptr) {}

   f(nullptr);   // calls f(System::Object ^)
}

nullptr is equivalent to Nothing in Visual Basic and null in C#. Function calls among languages that use these null mechanisms for error checking should be interpreted correctly.

nullptr is not a type and is not supported for use with:

• sizeof

• typeid

• typeobj

• throw nullptr (although throw (Object ^)nullptr; will work)

Example

The following sample shows that nullptr and zero can be used interchangeably on native pointers.

// mcpp_nullptr_1.cpp
// compile with: /clr
class MyClass {
public:
   int i;
};

int main() {
   MyClass * pMyClass = nullptr;
   if ( pMyClass == nullptr)
      System::Console::WriteLine("pMyClass == nullptr");

   if ( pMyClass == 0)
      System::Console::WriteLine("pMyClass == 0");

   pMyClass = 0;
   if ( pMyClass == nullptr)
      System::Console::WriteLine("pMyClass == nullptr");

   if ( pMyClass == 0)
      System::Console::WriteLine("pMyClass == 0");
}

pMyClass == nullptr
pMyClass == 0
pMyClass == nullptr
pMyClass == 0

The following example shows that nullptris interpreted as a handle to any type or a native pointer to any type. In case of function overloading with handles to different types, an ambiguity error will be generated. The nullptr would have to be explicitly cast to a type.

// mcpp_nullptr_2.cpp
// compile with: /clr /LD
void f(int *){}
void f(int ^){}

void f_null() {
   f(nullptr);   // C2668
   // try one of the following lines instead
   f((int *) nullptr);
   f((int ^) nullptr);
}

The following sample shows that casting nullptr is allowed and returns a pointer or handle to the cast type that contains the nullptr value.

// mcpp_nullptr_3.cpp
// compile with: /clr /LD
using namespace System;
template <typename T> 
void f(T) {}   // C2036 cannot deduce template type because nullptr can be any type

int main() {
   f((Object ^) nullptr);   // T = Object^, call f(Object ^)

   // Delete the following line to resolve.
   f(nullptr);

   f(0);   // T = int, call f(int)
}

The following sample shows that nullptr can be used as a function parameter.

// mcpp_nullptr_4.cpp
// compile with: /clr
using namespace System;
void f(Object ^ x) {
   Console::WriteLine("test");
}

int main() {
   f(nullptr);
}

test

The following sample shows that when handles are declared and not explicitly initialized, they are default initialized to nullptr.

// mcpp_nullptr_5.cpp
// compile with: /clr
using namespace System;
ref class MyClass {
public:
   void Test() {
      MyClass ^pMyClass;   // gc type
      if (pMyClass == nullptr)
         Console::WriteLine("NULL");
   }
};

int main() {
   MyClass ^ x = gcnew MyClass();
   x -> Test();
}

NULL

The following sample shows that nullptr can be assigned to a native pointer when compiling with /clr.

// mcpp_nullptr_6.cpp
// compile with: /clr
int main() {
   int * i = 0;
   int * j = nullptr;
}

Requirements

Compiler option: /clr

See Also

Concepts

Language Features for Targeting the CLR