array (Visual C+)

The array keyword lets you create a dynamic array that is allocated on the common language runtime heap.

[qualifiers] [cli::]array<[qualifiers]type1[, dimension]>^var = 
gcnew [cli::]array<type2[, dimension]>(val[,val...])

Parameters

• dimension [optional]
  The number of dimensions of the array. The default is 1. The maximum is 32.

• qualifiers [optional]
  A storage class specifier. Valid keywords for qualifier are: mutable, volatile, const, extern, and static.

• val
  A comma-separated list of the size of your array or an aggregate initializer.

  There should be one size val for each dimension. For more information, see Multidimension Arrays.

• type1
  The type of the array variable. Valid types are managed reference types (type**^), managed value types (type), and native pointers (type***). A tracking handle is always required after the closing angle bracket (>) in the declaration.

• type2
  The type of the values initializing the array. Commonly, type1 and type2 will be the same types. However, it is possible for the types to be different, as long as there is a conversion from type2 to type1. For example, if type2 is derived from type1.

  Like type1, valid types are managed reference types, managed value types, and native pointers. However, a tracking handle is not allowed after the closing angle bracket (>).

• var
  The name of the array variable.

Remarks

The number of elements of the array is not part of the type. A single array variable can refer to arrays of different sizes.

Like standard C++, the indices of a managed array are zero-based, and a managed array is subscripted using ordinary C++ array brackets. Unlike standard C++, subscripting is not a synonym for pointer arithmetic and is not commutative.

A managed array is itself a managed object. It is actually a pointer into the common language runtime heap. As a managed object, it has the same restrictions as a managed class. Most notably, the element type cannot be a native C++ class that is not a POD type.

array is in the cli namespace. See cli Namespace for more information.

All managed arrays inherit from System::Array. Any method or property of System::Array can be applied directly to the array variable.

When allocating an array whose element type is pointer-to a managed class, the elements are 0-initialized.

When allocating an array whose element type is a value type V, the default constructor for V is applied to each array element. For more information, see .NET Framework Equivalents to C++ Native Types.

You can detect at compile time if a type is a CLR array with __is_ref_array(type). For more information, see Compiler Support for Type Traits.

For more information on arrays, see

• Array Covariance

• How to: Create Single-Dimension Arrays

• How to: Create Multidimension Arrays

• How to: Create Arrays of Managed Arrays (Jagged Arrays)

• How to: Make Typedefs for Managed Arrays

• How to: Use Managed Arrays as Template Type Parameters

• ... (Variable Argument Lists)

• How to: Sort Arrays

• How to: Sort Arrays Using Custom Criteria

Example

// clr_array.cpp
// compile with: /clr
ref class MyClass {};
int main() {
   // one-dimensional array
   array<MyClass ^> ^ My1DArray = gcnew array<MyClass ^>(100);
   My1DArray[99] = gcnew MyClass();

   // three-dimensional array
   array<MyClass ^, 3> ^ My3DArray = gcnew array<MyClass ^, 3>(3, 5, 6);
   My3DArray[0,0,0] = gcnew MyClass();
}

Requirements

Compiler option: /clr

See Also

Concepts

Language Features for Targeting the CLR

Change History

Date	History	Reason
December 2008	Improved example.	Customer feedback.