__box

  • Article

Note

This topic applies only to version 1 of Managed Extensions for C++. This syntax should only be used to maintain version 1 code. See Implicit Boxing for information on using the equivalent functionality in the new syntax.

Creates a managed copy of a __value class object.

__box(value-class identifier)

Remarks

The __box keyword is used to create a managed object (derived from System::ValueType) from an existing __value class object. When the __box keyword is applied to a __value class:

  • A managed object is allocated on the common language runtime heap.

  • The current value of the __value class object is bit-wise copied into the managed object.

  • The address of the new managed object is returned.

This process is known as boxing. This enables any __value class object to be used in generic routines that work for any managed object because the managed object indirectly inherits from System::Object (since System::ValueType inherits from System::Object).

Note

The newly created boxed object is a copy of the __value class object. Therefore, modifications to the value of the boxed object do not affect the contents of the __value class object.

Example

Here's is an example that does boxing and unboxing:

// keyword__box.cpp
// compile with: /clr:oldSyntax
#using < mscorlib.dll >
using namespace System;

int main() {
  Int32 i = 1;
  System::Object* obj = __box(i);
  Int32 j = *dynamic_cast<__box Int32*>(obj);
}

In the following example, an unmanaged value type (V) is boxed and passed as a managed parameter to the Positive function.

// keyword__box2.cpp
// compile with: /clr:oldSyntax
#using <mscorlib.dll>
using namespace System;

__value struct V {
   int i;
};
void Positive(Object*) {}   // expects a managed class

int main() {
   V v={10};   // allocate and initialize
   Console::WriteLine(v.i);

   // copy to the common language runtime heap
   __box V* pBoxedV = __box(v);
   Positive(pBoxedV);   // treat as a managed class

   pBoxedV->i = 20;   // update the boxed version
   Console::WriteLine(pBoxedV->i);
}

10
20