Arrays (C++ Component Extensions)

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

The Platform::Array<T> type in C++/CX, or the array keyword in C++/CLI, declares an array of a specified type and initial value.

The array must be declared by using the handle-to-object (^) modifier after the closing angle bracket (>) in the declaration.

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

Unlike standard C++, subscripting is not a synonym for pointer arithmetic and is not commutative.

For more information about arrays, see:

Arrays are members of the Platform namespace. Arrays can be only one-dimensional.

Syntax

The first example of the syntax uses the ref new aggregate keyword to allocate an array. The second example declares a local array.

  
      [qualifiers]  
      [  
      Platform::  
      ]  
      Array<  
      [qualifiers]  
      array-type  
      [,rank]  
      >^  
      identifier = ref new[Platform::]Array<initialization-type> [{initialization-list [,...]}]  
  
[qualifiers][Platform::]Array<[qualifiers]array-type[,rank]>^identifier = {initialization-list [,...]}  

qualifiers [optional]
One or more of these storage class specifiers: mutable, volatile, const, extern, static.

array-type
The type of the array variable. Valid types are Windows Runtime classes and fundamental types, ref classes and structs, value classes and structs, and native pointers (type``*).

rank [optional]
The number of dimensions of the array. Must be 1.

identifier
The name of the array variable.

initialization-type
The type of the values that initialize the array. Typically, array-type and initialization-type are the same type. However, the types can be different if there is a conversion from initialization-type to array-type—for example, if initialization-type is derived from array-type.

initialization-list [optional]
A comma-delimited list of values in curly brackets that initialize the elements of the array. For example, if rank-size-list were (3), which declares a one-dimensional array of 3 elements, initialization list could be {1,2,3}.

Remarks

You can detect at compile time whether a type is a reference-counted array with __is_ref_array(``type``). For more information, see Compiler Support for Type Traits.

Requirements

Compiler option: /ZW

Examples

The following example creates a one-dimensional array that has 100 elements.

  
      // cwr_array.cpp  
// compile with: /ZW  
using namespace Platform;  
ref class MyClass {};  
int main() {  
   // one-dimensional array  
   Array<MyClass^>^ My1DArray = ref new Array<MyClass^>(100);  
   My1DArray[99] = ref new MyClass();  
}  

Syntax

The first example of the syntax uses the gcnew keyword to allocate an array. The second example declares a local array.

  
      [qualifiers]  
      [  
      cli::  
      ]  
      array<  
      [qualifiers]  
      array-type [,rank] >^identifier = gcnew[cli::]array<initialization-type[,rank]>(rank-size-list[,...]) [{initialization-list [,...]}]  
  
[qualifiers][cli::]array<[qualifiers]array-type [,rank] >^identifier = {initialization-list [,...]}  

qualifiers [optional]
One or more of these storage class specifiers: mutable, volatile, const, extern, static.

array-type
The type of the array variable. Valid types are Windows Runtime classes and fundamental types, ref classes and structs, value classes and structs, native pointers (type``*), and native POD (plain old data) types.

rank [optional]
The number of dimensions of the array. The default is 1; the maximum is 32. Each dimension of the array is itself an array.

identifier
The name of the array variable.

initialization-type
The type of the values that initialize the array. Typically, array-type and initialization-type are the same type. However, the types can be different if there is a conversion from initialization-type to array-type—for example, if initialization-type is derived from array-type.

rank-size-list
A comma-delimited list of the size of each dimension in the array. Alternatively, if the initialization-list parameter is specified, the compiler can deduce the size of each dimension and rank-size-list can be omitted. For more information, see How to: Create Multidimension Arrays.

initialization-list [optional]
A comma-delimited list of values in curly brackets that initialize the elements of the array. Or a comma-delimited list of nested initialization-list items that initialize the elements in a multi-dimensional array.

For example, if rank-size-list were (3), which declares a one-dimensional array of 3 elements, initialization list could be {1,2,3}. If rank-size-list were (3,2,4), which declares a three-dimensional array of 3 elements in the first dimension, 2 elements in the second, and 4 elements in the third, initialization-list could be {{1,2,3},{0,0},{-5,10,-21,99}}.)

Remarks

array is in the Platform, default, and cli Namespaces namespace.

Like standard C++, the indices of an array are zero-based, and an array is subscripted by using square brackets ([]). Unlike standard C++, the indices of a multi-dimensional array are specified in a list of indices for each dimension instead of a set of square-bracket ([]) operators for each dimension. For example, identifier[index1, index2] instead of identifier[index1][ index2].

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

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

When you allocate 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 (C++/CLI).

At compile time, you can detect whether a type is a common language runtime (CLR) array with__is_ref_array(``type``). For more information, see Compiler Support for Type Traits.

Requirements

Compiler option: /clr

Examples

The following example creates a one-dimensional array that has 100 elements, and a three-dimensional array that has 3 elements in the first dimension, 5 elements in the second, and 6 elements in the third.

// 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();  
}  

Component Extensions for Runtime Platforms

Show: