System.Array Class

public abstract class Array : ICloneable, ICollection, IEnumerable, IList

Base Types

Object
  Array

This type implements ICloneable, ICollection, IEnumerable, and IList.

Assembly

mscorlib

Library

BCL

Summary

Serves as the base class for arrays. Provides methods for creating, copying, manipulating, searching, and sorting arrays.

Description

This class is intended to be used as a base class by language implementations that support arrays. Only the system can derive from this type: derived classes of Array are not to be created by the developer.

[Note: An array is a collection of identically typed data elements that are accessed and referenced by sets of integral indices.

The rank of an array is the number of dimensions in the array. Each dimension has its own set of indices. An array with a rank greater than one can have a different lower bound and a different number of elements for each dimension. Multidimensional arrays (i.e. arrays with a rank greater than one) are processed in row-major order.

The lower bound of a dimension is the starting index of that dimension.

The length of an array is the total number of elements contained in all of its dimensions.

A vector is a one-dimensional array with a lower bound of '0'.

If the implementer creates a derived class of Array, expected Array behavior cannot be guaranteed. For information on array-like objects with increased functionality, see the IList and IList<T> interfaces. For more information regarding the use of arrays versus the use of collections, see Partition V of the CLI Specification.

]

Every specific Array type has three instance methods defined on it. While some programming languages allow direct access to these methods, they are primarily intended to be called by the output of compilers based on language syntax that deals with arrays.

• Get: Takes as many Int32 arguments as the array has dimensions and returns the value stored at the given index. It throws a IndexOutOfRangeException exception for invalid indices.

• Set: Takes as many Int32 arguments as the array has dimensions, plus one additional argument (the last argument) which has the same type as an array element. It stores the final value in the specified index of the array. It throws a IndexOutOfRangeException exception for invalid indices.

• Address: Takes as many Int32 arguments as the array has dimensions and returns the address of the element at the given index. It throws a IndexOutOfRangeException exception for invalid indices.

In addition, every specific Array type has a constructor on it that takes as many non-negative Int32 arguments as the array has dimensions. The arguments specify the number of elements in each dimension, and a lower bound of 0. Thus, a two-dimensional array of Int32 objects would have a constructor that could be called with (2, 4) as its arguments to create an array of eight zeros with the first dimension indexed with 0 and 1 and the second dimension indexed with 0, 1, 2, and 3.

For all specific array types except vectors (i.e. those permitted to have non-zero lower bounds and those with more than one dimension) there is an additional constructor. It takes twice as many arguments as the array has dimensions. The arguments are considered in pairs, with the first of the pair specifying the lower bound for that dimension and the second specifying the total number of elements in that dimension. Thus, a two-dimensional array of Int32 objects would also have a constructor that could be called with (-1, 2, 1, 3) as its arguments, specifying an array of 6 zeros, with the first dimension indexed by -1 and 0, and the second dimension indexed by 1, 2, and 3.

Enumeration over an array occurs in ascending row-major order, starting from the first element. (For example, a 2x3 array is traversed in the order [0,0], [0,1], [0,2], [1,0], [1,1], and [1,2].)

Parallel implementation of methods taking a System.Predicate argument are not permitted.

See Also

System Namespace

Members

Array Constructors

Array Constructor

Array Methods

Array.AsReadOnly<T> Method
Array.BinarySearch(System.Array, int, int, System.Object, System.Collections.IComparer) Method
Array.BinarySearch(System.Array, System.Object, System.Collections.IComparer) Method
Array.BinarySearch(System.Array, int, int, System.Object) Method
Array.BinarySearch(System.Array, System.Object) Method
Array.BinarySearch<T>(T[], T) Method
Array.BinarySearch<T>(T[], T, System.Collections.Generic.IComparer<T>) Method
Array.BinarySearch<T>(T[], int, int, T) Method
Array.BinarySearch<T>(T[], int, int, T, System.Collections.Generic.IComparer<T>) Method
Array.Clear Method
Array.Clone Method
Array.ConvertAll<T,U> Method
Array.Copy(System.Array, System.Array, int) Method
Array.Copy(System.Array, int, System.Array, int, int) Method
Array.CopyTo Method
Array.CreateInstance(System.Type, int[]) Method
Array.CreateInstance(System.Type, int, int, int) Method
Array.CreateInstance(System.Type, int, int) Method
Array.CreateInstance(System.Type, int) Method
Array.CreateInstance(System.Type, int[], int[]) Method
Array.Exists<T> Method
Array.Find<T> Method
Array.FindAll<T> Method
Array.FindIndex<T>(T[], System.Predicate<T>) Method
Array.FindIndex<T>(T[], int, System.Predicate<T>) Method
Array.FindIndex<T>(T[], int, int, System.Predicate<T>) Method
Array.FindLast<T> Method
Array.FindLastIndex<T>(T[], System.Predicate<T>) Method
Array.FindLastIndex<T>(T[], int, System.Predicate<T>) Method
Array.FindLastIndex<T>(T[], int, int, System.Predicate<T>) Method
Array.ForEach<T> Method
Array.GetEnumerator Method
Array.GetLength Method
Array.GetLowerBound Method
Array.GetUpperBound Method
Array.GetValue(int[]) Method
Array.GetValue(int) Method
Array.GetValue(int, int) Method
Array.GetValue(int, int, int) Method
Array.IndexOf(System.Array, System.Object, int, int) Method
Array.IndexOf(System.Array, System.Object, int) Method
Array.IndexOf(System.Array, System.Object) Method
Array.IndexOf<T>(T[], T, int, int) Method
Array.IndexOf<T>(T[], T, int) Method
Array.IndexOf<T>(T[], T) Method
Array.Initialize Method
Array.LastIndexOf(System.Array, System.Object, int, int) Method
Array.LastIndexOf(System.Array, System.Object, int) Method
Array.LastIndexOf(System.Array, System.Object) Method
Array.LastIndexOf<T>(T[], T, int, int) Method
Array.LastIndexOf<T>(T[], T, int) Method
Array.LastIndexOf<T>(T[], T) Method
Array.Resize<T> Method
Array.Reverse(System.Array, int, int) Method
Array.Reverse(System.Array) Method
Array.SetValue(System.Object, int) Method
Array.SetValue(System.Object, int, int) Method
Array.SetValue(System.Object, int, int, int) Method
Array.SetValue(System.Object, int[]) Method
Array.Sort(System.Array, System.Array, int, int, System.Collections.IComparer) Method
Array.Sort(System.Array, int, int, System.Collections.IComparer) Method
Array.Sort(System.Array, System.Array, System.Collections.IComparer) Method
Array.Sort(System.Array, System.Collections.IComparer) Method
Array.Sort(System.Array, System.Array, int, int) Method
Array.Sort(System.Array) Method
Array.Sort(System.Array, System.Array) Method
Array.Sort(System.Array, int, int) Method
Array.Sort<K,V>(K[], V[], int, int, System.Collections.Generic.IComparer<K>) Method
Array.Sort<K,V>(K[], V[], System.Collections.Generic.IComparer<K>) Method
Array.Sort<K,V>(K[], V[], int, int) Method
Array.Sort<K,V>(K[], V[]) Method
Array.Sort<T>(T[], int, int, System.Collections.Generic.IComparer<T>) Method
Array.Sort<T>(T[], System.Collections.Generic.IComparer<T>) Method
Array.Sort<T>(T[], System.Comparison<T>) Method
Array.Sort<T>(T[]) Method
Array.Sort<T>(T[], int, int) Method
Array.System.Collections.IList.Add Method
Array.System.Collections.IList.Clear Method
Array.System.Collections.IList.Contains Method
Array.System.Collections.IList.IndexOf Method
Array.System.Collections.IList.Insert Method
Array.System.Collections.IList.Remove Method
Array.System.Collections.IList.RemoveAt Method
Array.TrueForAll<T> Method

Array Properties

Array.IsFixedSize Property
Array.IsReadOnly Property
Array.IsSynchronized Property
Array.Length Property
Array.LongLength Property
Array.Rank Property
Array.SyncRoot Property
Array.System.Collections.ICollection.Count Property
Array.System.Collections.IList.Item Property

Constructs a new instance of the Array class.

See Also

System.Array Class, System Namespace

array

The array to wrap in a read-only IList<T> wrapper.

Return Value

A read-only IList<T> wrapper around the specified array.

Exceptions

Exception Type	Condition
ArgumentNullException	array is null .

Description

[Note: To prevent any modifications to the array, expose the array only through this wrapper.]

The returned IList<T> has the same enumeration order as the array it wraps.

A collection that is read-only is simply a collection with a wrapper that prevents modifying the underlying array; therefore, if changes are made to the underlying array, the read-only collection reflects those changes.

See Also

System.Array Class, System Namespace

Searches the specified section of the specified one-dimensional Array for the specified value, using the specified IComparer implementation.

Parameters

array

A Array to search.

index

A Int32 that contains the index at which searching starts.

length

A Int32 that contains the number of elements to search, beginning with index .

value

A Object for which to search.

comparer

The IComparer implementation to use when comparing elements. Specify a null reference to use the IComparable implementation of each element.

Return Value

A Int32 with one of the following values based on the result of the search operation.

Return Value	Description
The index of value in the array.	value was found.
The bitwise complement of the index of the first element that is larger than value.	value was not found, and at least one array element in the range of index to index + length - 1 was greater than value.
The bitwise complement of (index + length).	value was not found, and value was greater than all array elements in the range of index to index + length- 1.

[Note: If value is not found, the caller can take the bitwise complement of the return value to determine the index of array where value would be found in the range of index to index + length - 1 if array is already sorted.]

Exceptions

Exception Type	Condition
ArgumentNullException	array is null .
RankException	array has more than one dimension.
ArgumentOutOfRangeException	index is less than array.GetLowerBound(0) . -or- length is less than zero.
ArgumentException	index + length is greater than array.GetLowerBound(0) + array.Length . -or- array.UpperBound == System.Int32.MaxValue.
InvalidOperationException	comparer is null , and both value and at least one element of array do not implement the IComparable interface.

Description

value is compared to each element of array using comparer until an element with a value greater than or equal to value is found. If comparer is null , the IComparable interface of the element being compared - or of value if the element being compared does not implement the interface -- is used. If value does not implement the IComparable interface and is compared to an element that does not implement the IComparable interface, a InvalidOperationException exception is thrown. If array is not already sorted, correct results are not guaranteed.

[Note: A null reference can be compared with any type; therefore, comparisons with a null reference do not generate exceptions.]

Example

This example demonstrates the System.Array.BinarySearch(System.Array,System.Object) method.

using System;
class BinarySearchExample {
  public static void Main() {    
    int[] intAry = { 0, 2, 4, 6, 8 };
    Console.WriteLine( "The indices and elements of the array are: ");
    for ( int i = 0; i < intAry.Length; i++ )
      Console.Write("[{0}]: {1, -5}", i, intAry[i]);
    Console.WriteLine();
    SearchFor( intAry, 3 );
    SearchFor( intAry, 6 );
    SearchFor( intAry, 9 );
  }
  public static void SearchFor( Array ar, Object value ) {
    int i = Array.BinarySearch( ar, 0, ar.Length, value, null );
    Console.WriteLine();
    if ( i > 0 ) {
      Console.Write( "The object searched for, {0}, was found ", value );
      Console.WriteLine( "at index {1}.", value, i );
    }
    else if ( ~i == ar.Length ) {
      Console.Write( "The object searched for, {0}, was ", value );
      Console.Write( "not found,\nand no object in the array had " );
      Console.WriteLine( "greater value. " );
    }
    else {
      Console.Write( "The object searched for, {0}, was ", value );
      Console.Write( "not found.\nThe next larger object is at " );
      Console.WriteLine( "index {0}.", ~i );
    }
  }
}
   

The output is

The indices and elements of the array are:

[0]:0 [1]:2 [2]:4 [3]:6 [4]:8

The object searched for, 3, was not found.

The next larger object is at index 2.

The object searched for, 6, was found at index 3.

The object searched for, 9, was not found,

and no object in the array had greater value.

See Also

System.Array Class, System Namespace

Searches the specified one-dimensional Array for the specified value, using the specified IComparer implementation.

Parameters

array

A Array to search.

value

A Object for which to search.

comparer

The IComparer implementation to use when comparing elements. Specify a null reference to use the IComparable implementation of each element.

Return Value

A Int32 with one of the following values based on the result of the search operation.

Return Value	Description
The index of value in the array.	value was found.
The bitwise complement of the index of the first element that is larger than value.	value was not found, and at least one array element was greater than value.
The bitwise complement of (array.GetLowerBound(0) + array.Length).	value was not found, and value was greater than all array elements.

[Note: If value is not found, the caller can take the bitwise complement of the return value to determine the index where value would be found in array if it is already sorted.]

Exceptions

Exception Type	Condition
ArgumentNullException	array is null .
RankException	array has more than one dimension.
InvalidOperationException	comparer is null , and both value and at least one element of array do not implement the IComparable interface.

Description

This version of System.Array.BinarySearch(System.Array,System.Object) is equivalent to System.Array.BinarySearch(System.Array,System.Object)(array, array.GetLowerBound(0), array.Length, value, comparer).

value is compared to each element of array using comparer until an element with a value greater than or equal to value is found. If comparer is null , the IComparable interface of the element being compared - or of value if the element being compared does not implement the interface - is used. If value does not implement the IComparable interface and is compared to an element that does not implement the IComparable interface, a InvalidOperationException exception is thrown. If array is not already sorted, correct results are not guaranteed.

[Note: A null reference can be compared with any type; therefore, comparisons with a null reference do not generate exceptions.]

See Also

System.Array Class, System Namespace

Searches the specified section of the specified one-dimensional Array for the specified value.

Parameters

array

A Array to search.

index

A Int32 that contains the index at which searching starts.

length

A Int32 that contains the number of elements to search, beginning with index .

value

A Object for which to search.

Return Value

A Int32 with one of the following values based on the result of the search operation.

Return Value	Description
The index of value in the array.	value was found.
The bitwise complement of the index of the first element that is larger than value.	value was not found, and at least one array element in the range of index to index + length - 1 was greater than value.
The bitwise complement of (index + length).	value was not found, and value was greater than all array elements in the range of index to index + length- 1.

[Note: If value is not found, the caller can take the bitwise complement of the return value to determine the index of the array where value would be found in the range of index to index + length - 1 if array is already sorted.]

Exceptions

Exception Type	Condition
ArgumentNullException	array is null .
RankException	array has more than one dimension.
ArgumentOutOfRangeException	index < array.GetLowerBound(0). -or- length < 0.
ArgumentException	index and length do not specify a valid range in array (i.e. index + length > array.GetLowerBound(0) + array.Length). -or- array.UpperBound == System.Int32.MaxValue.
InvalidOperationException	Either value or at least one element of array does not implement the IComparable interface.

Description

This version of System.Array.BinarySearch(System.Array,System.Object) is equivalent to System.Array.BinarySearch(System.Array,System.Object)(array, array.GetLowerBound(0), array.Length, value, null ).

value is compared to each element of array using the IComparable interface of the element being compared - or of value if the element being compared does not implement the interface - until an element with a value greater than or equal to value is found. If value does not implement the IComparable interface and is compared to an element that does not implement the IComparable interface, a InvalidOperationException exception is thrown. If array is not already sorted, correct results are not guaranteed.

[Note: A null reference can be compared with any type; therefore, comparisons with a null reference do not generate exceptions.]

See Also

System.Array Class, System Namespace

Searches the specified one-dimensional Array for the specified object.

Parameters

array

A Array to search for an object.

value

A Object for which to search.

Return Value

A Int32 with one of the following values based on the result of the search operation.

Return Value	Description
The index of value in the array.	value was found.
The bitwise complement of the index of the first element that is larger than value.	value was not found and the value of at least one element of array was greater than value.
The bitwise complement of (array.GetLowerBound(0) + array.Length).	value was not found, and value was greater than the value of all array elements.

[Note: If value is not found, the caller can take the bitwise complement of the return value to determine the index where value would be found in array if it is sorted already.]

Exceptions

Exception Type	Condition
ArgumentNullException	array is null .
RankException	array has more than one dimension.
InvalidOperationException	Both value and at least one element of array do not implement the IComparable interface.

Description

This version of System.Array.BinarySearch(System.Array,System.Object) is equivalent to System.Array.BinarySearch(System.Array,System.Object)(array, array.GetLowerBound(0), array.Length, value, null ).

value is compared to each element of array using the IComparable interface of the element being compared - or of value if the element being compared does not implement the interface - until an element with a value greater than or equal to value is found. If value does not implement the IComparable interface and is compared to an element that does not implement the IComparable interface, a InvalidOperationException exception is thrown. If array is not already sorted, correct results are not guaranteed.

[Note: A null reference can be compared with any type; therefore, comparisons with a null reference do not generate exceptions.]

See Also

System.Array Class, System Namespace

Searches an entire one-dimensional sorted array for a specific element, using the IComparable<T> or IComparable interface implemented by each element of the array and by the specified object.

Parameters

array

The one-dimensional array to search.

value

The object for which to search.

Return Value

One of the following values based on the result of the search operation:

Return Value	Description
A non-negative index of value in the array.	value was found.
A negative value, which is the bitwise complement of the index of the first element that is larger than value.	value was not found and the value of at least one element of array was greater than value.
A negative value, which is the bitwise complement of one more than the index of the final element.	value was not found, and value was greater than the value of all array elements.

Exceptions

Exception Type	Condition
ArgumentNullException	array is null .
InvalidOperationException	Neither value nor the elements of the array implement the IComparable<T> or IComparable interfaces.

Description

Either value or every element of array must implement the IComparable<T> or IComparable interface, which is used for comparisons. The elements of array must already be sorted in increasing value according to the sort order defined by the IComparable<T> or IComparable implementation; otherwise, the behavior is unspecified

Duplicate elements are allowed. If the array contains more than one element equal to value, the method returns the index of only one of the occurrences, but not necessarily the first one.

[Note: null can always be compared with any other reference type; therefore, comparisons with null do not generate an exception.]

See Also

System.Array Class, System Namespace

Searches an entire one-dimensional sorted array for a value using the specified IComparer<T> interface.

Parameters

array

The one-dimensional array to search.

value

The object for which to search.

comparer

The implementation to use when comparing elements.

-or-

null to use the IComparable<T> or IComparable implementation of each element.

Return Value

One of the following values based on the result of the search operation:

Return Value	Description
A non-negative index of value in the array.	value was found.
A negative value, which is the bitwise complement of the index of the first element that is larger than value.	value was not found and the value of at least one element of array was greater than value.
A negative value, which is the bitwise complement of one more than the index of the final element.	value was not found, and value was greater than the value of all array elements.

Exceptions

Exception Type	Condition
ArgumentNullException	array is null .
InvalidOperationException	comparer is null , and neither value nor the elements of the array implement the IComparable<T> or IComparable interface.

Description

The comparer customizes how the elements are compared.

The elements of array must already be sorted in increasing value according to the sort order defined by comparer; otherwise, the behavior is unspecified

If comparer is not null , the elements of array are compared to the specified value using the specified System.Collections.Generic.IComparer implementation.

If comparer is null , the default comparer is used.

Duplicate elements are allowed. If the array contains more than one element equal to value, the method returns the index of only one of the occurrences, but not necessarily the first one.

[Note: null can always be compared with any other reference type; therefore, comparisons with null do not generate an exception.]

See Also

System.Array Class, System Namespace

Searches a range of elements in a one-dimensional sorted array for a value, using the IComparable interface implemented by each element of the array and by the specified value.

Parameters

array

The one-dimensional array to search.

index

The starting index of the range to search.

length

The length of the range to search.

value

The object for which to search.

Return Value

One of the following values based on the result of the search operation:

Return Value	Description
A non-negative index of value in the array.	value was found.
A negative value, which is the bitwise complement of the index of the first element that is larger than value.	value was not found and the value of at least one element of array was greater than value.
A negative value, which is the bitwise complement of one more than the index of the final element.	value was not found, and value was greater than the value of all array elements.

Exceptions

Exception Type	Condition
ArgumentException	index + length is greater than array.Length .
ArgumentNullException	array is null .
ArgumentOutOfRangeException	index is less than zero -or- length is less than zero.
InvalidOperationException	Neither value nor the elements of the array implement the IComparable<T> or IComparable interface.

Description

Either value or every element of array must implement the IComparable interface, which is used for comparisons. The elements of array must already be sorted in increasing value according to the sort order defined by the IComparable<T> or IComparable implementation; otherwise, the behavior is unspecified

Duplicate elements are allowed. If the array contains more than one element equal to value, the method returns the index of only one of the occurrences, but not necessarily the first one.

[Note: null can always be compared with any other reference type; therefore, comparisons with null do not generate an exception.]

See Also

System.Array Class, System Namespace

Searches a range of elements in a one-dimensional sorted array for a value, using the specified IComparer<T> interface.

Parameters

array

The one-dimensional array to search.

index

The starting index of the range to search.

length

The length of the range to search.

value

The object for which to search.

comparer

The implementation to use when comparing elements.

-or-

null to use the IComparable<T> or IComparable implementation of each element.

Return Value

One of the following values based on the result of the search operation:

Return Value	Description
A non-negative index of value in the array.	value was found.
A negative value, which is the bitwise complement of the index of the first element that is larger than value.	value was not found and the value of at least one element of array was greater than value.
A negative value, which is the bitwise complement of one more than the index of the final element.	value was not found, and value was greater than the value of all array elements.

Exceptions

Exception Type	Condition
ArgumentException	index and length do not specify a valid range in array.
ArgumentNullException	array is null .
ArgumentOutOfRangeException	index is less than zero -or- length is less than zero.
InvalidOperationException	comparer is null , and neither value nor the elements of the array implement the IComparable<T> or IComparable interface.

Description

The comparer customizes how the elements are compared.

The elements of array must already be sorted in increasing value according to the sort order defined by comparer; otherwise, the behavior is unspecified.

If comparer is not null , the elements of array are compared to the specified value using the specified IComparer<T> implementation.

If comparer is null , the comparison is done using the IComparable<T> or System.IComparable implementation provided by the element itself or by the specified value.

Duplicate elements are allowed. If the array contains more than one element equal to value, the method returns the index of only one of the occurrences, but not necessarily the first one.

[Note: null can always be compared with any other reference type; therefore, comparisons with null do not generate an exception.]

See Also

System.Array Class, System Namespace

Sets the specified range of elements in the specified Array to zero, false, or to a null reference, depending on the element type.

Parameters

array

The Array to clear.

index

A Int32 that contains the index at which clearing starts.

length

A Int32 that contains the number of elements to clear, beginning with index.

Exceptions

Exception Type	Condition
ArgumentNullException	array is null .
ArgumentOutOfRangeException	index < array.GetLowerBound(0). length < 0. index and length do not specify a valid range in array (i.e. index + length > array.GetLowerBound(0) + array.Length ).

Description

Reference-type elements will be set to null . Value-type elements will be set to zero, except for Boolean elements, which will be set to false .

See Also

System.Array Class, System Namespace

Returns a Object that is a copy of the current instance.

Return Value

A Object that is a copy of the current instance.

Description

[Note: This method is implemented to support the ICloneable interface.]

[Behaviors: Each of the elements of the current instance is copied to the clone. If the elements are reference types, the references are copied. If the elements are value-types, the values are copied. The clone is of the same type as the current instance.]

[Default: As described above.]

[Overrides: Override this method to return a clone of an array.]

[Usage: Use this method to obtain the clone of an array.]

Example

This example demonstrates the System.Array.Clone method.

using System;
public class ArrayCloneExample {
  public static void Main() {
    int[] intAryOrig = { 3, 4, 5 };
    //must explicitly convert clones object into an array
    int[] intAryClone = (int[]) intAryOrig.Clone();
    Console.Write( "The elements of the first  array are: " );
    foreach( int i in intAryOrig )
      Console.Write( "{0,3}", i );
    Console.WriteLine();
    Console.Write( "The elements of the cloned array are: " );
    foreach( int i in intAryClone )
      Console.Write( "{0,3}", i );
    Console.WriteLine();
    //Clear the values of the original array.
    Array.Clear( intAryOrig, 0, 3 );
    Console.WriteLine( "After clearing the first array," );
    Console.Write( "The elements of the first  array are: " );
    foreach( int i in intAryOrig )
      Console.Write( "{0,3}", i );
    Console.WriteLine();
    Console.Write( "The elements of the cloned array are: " );
    foreach( int i in intAryClone )
      Console.Write( "{0,3}", i );
  }
}
   

The output is

The elements of the first array are: 3 4 5

The elements of the cloned array are: 3 4 5

After clearing the first array,

The elements of the first array are: 0 0 0

The elements of the cloned array are: 3 4 5

See Also

System.Array Class, System Namespace

array

The one-dimensional array to convert.

converter

A Converter<T,U> that converts each element from one type to another type.

Return Value

A new array of the target type containing the converted elements from array.

Exceptions

Exception Type	Condition
ArgumentNullException	array is null or converter is null .

Description

The Converter<T,U> is a delegate that converts an array element to the target type. The elements of array are individually passed to this converter, and the converted elements are saved in the new array. The source array remains unchanged.

See Also

System.Array Class, System Namespace

sourceArray

A Array that contains the data to copy.

destinationArray

A Array that receives the data.

length

A Int32 designating the number of elements to copy, starting with the first element and proceeding in order.

Exceptions

Exception Type	Condition
ArgumentNullException	sourceArray or destinationArray is null .
RankException	sourceArray and destinationArray have different ranks.
ArrayTypeMismatchException	The elements in both arrays are built-in types, and converting from the type of the elements of sourceArray into the type of the elements in destinationArray requires a narrowing conversion. -or- Both arrays are built-in types, and one array is a value-type array and the other an array of interface type not implemented by that value-type. -or- Both arrays are user-defined value types and are not of the same type.
InvalidCastException	At least one of the elements in sourceArray is not assignment-compatible with the type of destinationArray.
ArgumentOutOfRangeException	length < 0.
ArgumentException	length > sourceArray.Length. -or- length > destinationArray.Length.

Description

This version of System.Array.Copy(System.Array,System.Array,System.Int32) is equivalent to System.Array.Copy(System.Array,System.Array,System.Int32) (sourceArray, sourceArray.GetLowerBound(0), destinationArray, destinationArray.GetLowerBound(0), length).

If sourceArray and destinationArray are of different types, System.Array.Copy(System.Array,System.Array,System.Int32) performs widening conversions on the elements of sourceArray as necessary before storing the information in destinationArray. Value types will be boxed when being converted to a Object. If the necessary conversion is a narrowing conversion, a ArrayTypeMismatchException exception is thrown. [Note: For information regarding valid conversions performed by this method, see Convert.]

If an exception is thrown while copying, the state of destinationArray is undefined.

If sourceArray and destinationArray are the same array, System.Array.Copy(System.Array,System.Array,System.Int32) copies the source elements safely to their destination, as if the copy were done through an intermediate array.

Example

This example demonstrates the System.Array.Copy(System.Array,System.Array,System.Int32) method.

using System;
public class ArrayCopyExample {
   public static void Main() {
      int[] intAryOrig = new int[3];
      double[] dAryCopy = new double[3];
      for ( int i = 0; i < intAryOrig.Length; i++ )
         intAryOrig[i] = i+3;
      //copy the first 2 elements of the source into the destination
      Array.Copy( intAryOrig, dAryCopy, 2);
      Console.Write( "The elements of the first array are: " );
      for ( int i = 0; i < intAryOrig.Length; i++ ) 
         Console.Write( "{0,3}", intAryOrig[i] );
      Console.WriteLine();
      Console.Write( "The elements of the copied array are: " );
      for ( int i = 0; i < dAryCopy.Length; i++ ) 
         Console.Write( "{0,3}", dAryCopy[i] );
   }
}
   

The output is

The elements of the first array are: 3 4 5

The elements of the copied array are: 3 4 0

See Also

System.Array Class, System Namespace

sourceArray

The Array that contains the data to copy.

sourceIndex

A Int32 that contains the index in sourceArray from which copying begins.

destinationArray

The Array that receives the data.

destinationIndex

A Int32 that contains the index in destinationArray at which storing begins.

length

A Int32 that contains the number of elements to copy.

Exceptions

Exception Type	Condition
ArgumentNullException	sourceArray or destinationArray is null .
RankException	sourceArray and destinationArray have different ranks.
ArrayTypeMismatchException	The elements in both arrays are built-in types, and converting from the type of the elements of sourceArray into the type of the elements in destinationArray requires a narrowing conversion. -or- Both arrays are built-in types, and one array is a value-type array and the other an array of interface type not implemented by that value-type. -or- Both arrays are user-defined value types and are not of the same type.
InvalidCastException	At least one element in sourceArray is assignment-incompatible with the type of destinationArray.
ArgumentOutOfRangeException	sourceIndex < sourceArray.GetLowerBound(0). -or- destinationIndex < destinationArray.GetLowerBound(0). -or- length < 0.
ArgumentException	(sourceIndex + length ) > (sourceArray.GetLowerBound(0) + sourceArray.Length). (destinationIndex + length ) > ( destinationArray.GetLowerBound(0) + destinationArray.Length).

Description

If sourceArray and destinationArray are of different types, System.Array.Copy(System.Array,System.Array,System.Int32) performs widening conversions on the elements of sourceArray as necessary before storing the information in destinationArray. Value types will be boxed when being converted to a Object. If the necessary conversion is a narrowing conversion, a ArrayTypeMismatchException exception is thrown. [Note: For information regarding valid conversions performed by this method, see Convert .]

If an exception is thrown while copying, the state of destinationArray is undefined.

If sourceArray and destinationArray are the same array, System.Array.Copy(System.Array,System.Array,System.Int32) copies the source elements safely to their destination as if the copy were done through an intermediate array.

Example

This example demonstrates the System.Array.Copy(System.Array,System.Array,System.Int32) method.

using System;
class ArrayCopyExample {
   public static void Main() {
      int[] intAry = { 0, 10, 20, 30, 40, 50 };
      Console.Write( "The elements of the array are: " );
      foreach ( int i in intAry )
         Console.Write( "{0,3}", i );
      Console.WriteLine();
      Array.Copy( intAry, 2, intAry, 0, 4 );
      Console.WriteLine( "After copying elements 2 through 5 into elements 0 through 4" );
      Console.Write( "The elements of the array are: " );
      foreach ( int i in intAry )
         Console.Write( "{0,3}", i );
      Console.WriteLine();     
   }
}
   

The output is

The elements of the array are: 0 10 20 30 40 50

After copying elements 2 through 5 into elements 0 through 4

The elements of the array are: 20 30 40 50 40 50

See Also

System.Array Class, System Namespace

array

A one-dimensional Array that is the destination of the elements copied from the current instance.

index

A Int32 that contains the index in array at which copying begins.

Exceptions

Exception Type	Condition
ArgumentNullException	array is null .
RankException	The current instance has more than one dimension.
ArgumentOutOfRangeException	index < array.GetLowerBound(0) .
ArgumentException	array has more than one dimension. -or- ( index + Length of the current instance) > (array.GetLowerBound(0) + array.Length ). -or- The number of elements in the current instance is greater than the available space from index to the end of array.
ArrayTypeMismatchException	The element type of the current instance is not assignment-compatible with the element type of array.

Description

index is the array index in the destination array at which copying begins.

[Note: This method is implemented to support the ICollection interface. If implementing ICollection is not explicitly required, use System.Array.Copy(System.Array,System.Array,System.Int32) to avoid an extra indirection.

If this method throws an exception while copying, the state of array is undefined.

]

[Behaviors: As described above.]

[Default: As described above.]

[Overrides: Override this method to copy elements of the current instance to a specified array.]

[Usage: Use this method to copy elements of the current instance to a specified array.]

Example

The following example shows how to copy the elements of one Array into another.

using System;

public class ArrayCopyToExample
{
   public static void Main()
   {
      Array aryOne = Array.CreateInstance(typeof(Object), 3);
      aryOne.SetValue("one", 0);
      aryOne.SetValue("two", 1);
      aryOne.SetValue("three", 2);

      Array aryTwo = Array.CreateInstance(typeof(Object), 5);
      for (int i=0; i < aryTwo.Length; i++)
         aryTwo.SetValue(i, i);

      Console.WriteLine("The contents of the first array are:");
      foreach (object o in aryOne)
         Console.Write("{0} ", o);
      Console.WriteLine();
      Console.WriteLine("The original contents of the second array are:");
      foreach (object o in aryTwo)
         Console.Write("{0} ", o);
      Console.WriteLine();
      
      aryOne.CopyTo(aryTwo, 1);

      Console.WriteLine("The new contents of the second array are:");
      foreach( object o in aryTwo)
         Console.Write("{0} ", o);
   }
}

The output is

The contents of the first array are:

one two three

The original contents of the second array are:

0 1 2 3 4

The new contents of the second array are:

0 one two three 4

See Also

System.Array Class, System Namespace

Creates a zero-based, multidimensional array of the specified Type and dimension lengths.

Parameters

elementType

The Type of the elements contained in the new Array instance.

lengths

A one-dimensional array of Int32 objects that contains the size of each dimension of the new Array instance.

Return Value

A new zero-based, multidimensional Array instance of the specified Type with the specified length for each dimension. The System.Array.Rank of the new instance is equal to lengths.Length.

Exceptions

Exception Type	Condition
ArgumentNullException	elementType or lengths is null .
ArgumentException	elementType is not a valid Type. -or- lengths.Length = 0.
ArgumentOutOfRangeException	A value in lengths is less than zero.

Description

The number of elements in lengths is required to equal the number of dimensions in the new Array instance. Each element of lengths specifies the length of the corresponding dimension in the new instance.

Reference-type elements will be set to null . Value-type elements will be set to zero, except for Boolean elements, which will be set to false .

[Note: Unlike most classes, Array provides the System.Array.CreateInstance(System.Type,System.Int32) method, instead of public constructors, to allow for late bound access.]

Example

The following example shows how to create and initialize a multidimensional Array.

using System;

public class CreateMultiDimArrayExample
{
   public static void Main()
   {
      int i, j, k;
      int[] indexAry = {2, 4, 5};
      Array ary = Array.CreateInstance( typeof(int), indexAry );
      for( i = ary.GetLowerBound(0); i <= ary.GetUpperBound(0); i++ )
      {
         for( j = ary.GetLowerBound(1); j <= ary.GetUpperBound(1); j++ )
         {
            for( k = ary.GetLowerBound(2); k <= ary.GetUpperBound(2); k++ )
            {
               ary.SetValue( (100*i + 10*j + k), i, j, k );
            }
         }
      }
      Console.WriteLine("The elements of the array are:");
      for( i = ary.GetLowerBound(0); i <= ary.GetUpperBound(0); i++)
      {
         for( j = ary.GetLowerBound(1); j <= ary.GetUpperBound(1); j++)
         {
             for( k = ary.GetLowerBound(2); k <= ary.GetUpperBound(2); k++ )
            {
               Console.Write("{0, 3} ", ary.GetValue(i, j, k));
            }
            Console.WriteLine();
         }
         Console.WriteLine();
      }
   }
}
   

The output is

The elements of the array are:
  0   1   2   3   4
 10  11  12  13  14
 20  21  22  23  24
 30  31  32  33  34

100 101 102 103 104
110 111 112 113 114
120 121 122 123 124
130 131 132 133 134 

Library

ExtendedArray

See Also

System.Array Class, System Namespace

Creates a zero-based, three-dimensional array of the specified Type and dimension lengths.

Parameters

elementType

The Type of the elements contained in the new Array instance.

length1

A Int32 that contains the number of elements contained in the first dimension of the new Array instance.

length2

A Int32 that contains the number of elements contained in the second dimension of the new Array instance.

length3

A Int32 that contains the number of elements contained in the third dimension of the new Array instance.

Return Value

A new zero-based, three-dimensional Array instance of elementType objects with the size length1 for the first dimension, length2 for the second, and length3 for the third.

Exceptions

Exception Type	Condition
ArgumentNullException	elementType is null .
ArgumentException	elementType is not a valid Type.
ArgumentOutOfRangeException	length1 < 0. -or- length2 < 0. -or- length3 < 0.

Description

Reference-type elements will be set to null . Value-type elements will be set to zero, except for Boolean elements, which will be set to false .

[Note: Unlike most classes, Array provides the System.Array.CreateInstance(System.Type,System.Int32) method, instead of public constructors, to allow for late bound access.]

Example

The following example shows how to create and initialize a three-dimensional Array.

using System;

public class Create3DArrayExample
{
   public static void Main()
   {
      int i, j, k;
      Array ary = Array.CreateInstance( typeof(int), 2, 4, 3 );
      for( i = ary.GetLowerBound(0); i <= ary.GetUpperBound(0); i++ )
      {
         for( j = ary.GetLowerBound(1); j <= ary.GetUpperBound(1); j++ )
         {
            for( k = ary.GetLowerBound(2); k <= ary.GetUpperBound(2); k++ )
            {
               ary.SetValue( (100*i + 10*j + k), i, j, k );
            }
         }
      }
      Console.WriteLine("The elements of the array are:");
      for( i = ary.GetLowerBound(0); i <= ary.GetUpperBound(0); i++)
      {
         for( j = ary.GetLowerBound(1); j <= ary.GetUpperBound(1); j++)
         {
             for( k = ary.GetLowerBound(2); k <= ary.GetUpperBound(2); k++ )
            {
               Console.Write("{0, 3} ", ary.GetValue(i, j, k));
            }
            Console.WriteLine();
         }
         Console.WriteLine();
      }
   }
}
   

The output is

The elements of the array are:
  0   1   2
 10  11  12
 20  21  22
 30  31  32

100 101 102
110 111 112
120 121 122
130 131 132
 

Library

ExtendedArray

See Also

System.Array Class, System Namespace

Creates a zero-based, two-dimensional array of the specified Type and dimension lengths.

Parameters

elementType

The Type of the elements contained in the new Array instance.

length1

A Int32 that contains the number of elements contained in the first dimension of the new Array instance.

length2

A Int32 that contains the number of elements contained in the second dimension of the new Array instance.

Return Value

A new zero-indexed, two-dimensional Array instance of elementType objects with the size length1 for the first dimension and length2 for the second.

Exceptions

Exception Type	Condition
ArgumentNullException	elementType is null .
ArgumentException	elementType is not a valid Type.
ArgumentOutOfRangeException	length1 < 0. -or- length2 < 0.

Description

Reference-type elements will be set to null . Value-type elements will be set to zero, except for Boolean elements, which will be set to false .

[Note: Unlike most classes, Array provides the System.Array.CreateInstance(System.Type,System.Int32) method, instead of public constructors, to allow for late bound access.]

Example

The following example shows how to create and initialize a two-dimensional Array.

using System;

public class Create2DArrayExample
{
   public static void Main()
   {
      int i, j;
      Array ary = Array.CreateInstance( typeof(int), 5, 3 );
      for( i = ary.GetLowerBound(0); i <= ary.GetUpperBound(0); i++ )
      {
         for( j = ary.GetLowerBound(1); j <= ary.GetUpperBound(1); j++ )
         {
            ary.SetValue( (10*i + j), i, j );
         }
      }
      Console.WriteLine("The elements of the array are:");
      for( i = ary.GetLowerBound(0); i <= ary.GetUpperBound(0); i++)
      {
         for( j = ary.GetLowerBound(1); j <= ary.GetUpperBound(1); j++)
         {
            Console.Write("{0, 2} ", ary.GetValue(i, j));
         }
         Console.WriteLine();
      }
   }
} 
  

The output is

The elements of the array are:
 0  1  2
10 11 12
20 21 22
30 31 32
40 41 42
 

Library

ExtendedArray

See Also

System.Array Class, System Namespace

elementType

The Type of the elements contained in the new Array instance.

length

A Int32 that contains the number of elements contained in the new Array instance.

Return Value

A zero-based, one-dimensional Array object containing length elements of type elementType.

Exceptions

Exception Type	Condition
ArgumentNullException	elementType is null .
ArgumentException	elementType is not a valid Type.
ArgumentOutOfRangeException	length < 0.

Description

Reference-type elements will be set to null . Value-type elements will be set to zero, except for Boolean elements, which will be set to false .

[Note: Unlike most classes, Array provides the System.Array.CreateInstance(System.Type,System.Int32) method, instead of public constructors, to allow for late bound access.]

Example

The following example shows how to create and initialize a one-dimensional Array.

using System;

public class ArrayCreateInstanceExample
{

   public static void Main()
   {

      Array intAry = Array.CreateInstance(typeof(int),5);
      for (int i=intAry.GetLowerBound(0);i<=intAry.GetUpperBound(0);i++)
         intAry.SetValue(i*3,i);
      Console.Write("The values of the array are:");
      foreach (int i in intAry)
         Console.Write("{0} ",i);
   
   }

}
   

The output is

The values of the array are: 0 3 6 9 12

See Also

System.Array Class, System Namespace

Creates a multidimensional array whose element type is the specified Type, and dimension lengths and lower bounds, as specified.

Parameters

elementType

The Type of the elements contained in the new Array instance.

lengths

A one-dimensional array of Int32 objects that contains the size of each dimension of the new Array instance.

lowerBounds

A one-dimensional array of Int32 objects that contains the lower bound of each dimension of the new Array instance.

Return Value

A new multidimensional Array whose element type is the specified Type and with the specified length and lower bound for each dimension.

Exceptions

Exception Type	Condition
ArgumentNullException	elementType, lengths, or lowerBounds is null .
ArgumentException	elementType is not a valid Type. -or- lengths.Length = 0. -or- lengths and lowerBounds do not contain the same number of elements.
ArgumentOutOfRangeException	A value in lengths is less than zero.

Description

The lengths and lowerBounds are required to have the same number of elements. The number of elements in lengths equals the number of dimensions in the new Array instance

Each element of lengths specifies the length of the corresponding dimension in the new Array instance.

Each element of lowerBounds specifies the lower bound of the corresponding dimension in the new Array instance.

Reference-type elements will be set to null . Value-type elements will be set to zero, except for Boolean elements, which will be set to false .

[Note: Unlike most classes, Array provides the System.Array.CreateInstance(System.Type,System.Int32) method, instead of public constructors, to allow for late bound access.]

Example

The following example shows how to create and initialize a multidimensional Array with specified low bounds.

using System;

public class MultiDimNonZeroBoundExample
{
   public static void Main()
   {
      int i, j, k;
      int[] indexAry = {4, 2, 3};
      int[] lowboundAry = {3, 2, 1};
      Array ary = Array.CreateInstance( typeof(int), indexAry, lowboundAry );
      for( i = ary.GetLowerBound(0); i <= ary.GetUpperBound(0); i++ )
      {
         for( j = ary.GetLowerBound(1); j <= ary.GetUpperBound(1); j++ )
         {
            for( k = ary.GetLowerBound(2); k <= ary.GetUpperBound(2); k++ )
            {
               ary.SetValue( (100*i + 10*j + k), i, j, k );
            }
         }
      }
      Console.WriteLine("The elements of the array are:");
      for( i = ary.GetLowerBound(0); i <= ary.GetUpperBound(0); i++)
      {
         for( j = ary.GetLowerBound(1); j <= ary.GetUpperBound(1); j++)
         {
             for( k = ary.GetLowerBound(2); k <= ary.GetUpperBound(2); k++ )
            {
               Console.Write("{0, 3} ", ary.GetValue(i, j, k));
            }
            Console.WriteLine();
         }
         Console.WriteLine();
      }
   }
}
   

The output is

The elements of the array are:
321 322 323
331 332 333

421 422 423
431 432 433

521 522 523
531 532 533

621 622 623
631 632 633

Library

ExtendedArray

See Also

System.Array Class, System Namespace

System.Array Class, System Namespace

System.Array Class, System Namespace

System.Array Class, System Namespace

System.Array Class, System Namespace

System.Array Class, System Namespace

System.Array Class, System Namespace

System.Array Class, System Namespace

System.Array Class, System Namespace

System.Array Class, System Namespace

System.Array Class, System Namespace

System.Array Class, System Namespace

Returns a IEnumerator for the current instance.

Return Value

A IEnumerator for the current instance.

Description

A IEnumerator grants read-access to the elements of a Array.

[Note: This method is implemented to support the IEnumerator interface. For more information regarding the use of an enumerator, see IEnumerator.]

[Behaviors: Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection.

Initially, the enumerator is positioned before the first element of the current instance. System.Collections.IEnumerator.Reset returns the enumerator to this position. Therefore, after an enumerator is created or after a System.Collections.IEnumerator.Reset, System.Collections.IEnumerator.MoveNext is required to be called to advance the enumerator to the first element of the collection before reading the value of System.Collections.IEnumerator.Current.

System.Collections.IEnumerator.Current returns the same object until either System.Collections.IEnumerator.MoveNext or System.Collections.IEnumerator.Reset is called. System.Collections.IEnumerator.MoveNext sets System.Collections.IEnumerator.Current to the next element.

If System.Collections.IEnumerator.MoveNext passes the end of the collection, the enumerator is positioned after the last element in the collection and System.Collections.IEnumerator.MoveNext returns false. When the enumerator is at this position, subsequent calls toSystem.Collections.IEnumerator.MoveNext also return false . If the last call to System.Collections.IEnumerator.MoveNext returned false , System.Collections.IEnumerator.Current is unspecified. To set System.Collections.IEnumerator.Current to the first element of the collection again, you can call System.Collections.IEnumerator.Reset followed by System.Collections.IEnumerator.MoveNext.

An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and its behavior is undefined.

The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization.

]

[Default: Multidimensional arrays will be processed in Row-major form.

[Note: For some multidimensional Array objects, it can be desirable for an enumerator to process them in Column-major form.]

]

[Overrides: Override this method to provide read-access to the current instance.]

[Usage: Use this method to iterate over the elements of the current instance.]

Example

This example demonstrates the System.Array.GetEnumerator method.

using System;
using System.Collections;
public class ArrayGetEnumerator {
   public static void Main() {
      string[,] strAry = {{"1","one"}, {"2", "two"}, {"3", "three"}};
      Console.Write( "The elements of the array are: " );
      IEnumerator sEnum = strAry.GetEnumerator();
      while ( sEnum.MoveNext() )
         Console.Write( " {0}", sEnum.Current );
   }
}
   

The output is

The elements of the array are: 1 one 2 two 3 three

See Also

System.Array Class, System Namespace

System.Array Class, System Namespace

dimension

A Int32 that contains the zero-based dimension of the current instance whose lower bound is to be determined.

Return Value

A Int32 that contains the lower bound of the specified dimension in the current instance.

Exceptions

Exception Type	Condition
IndexOutOfRangeException	dimension < 0. -or- dimension is equal to or greater than the System.Array.Rank property of the current instance.

Description

[Note: For example, System.Array.GetLowerBound(System.Int32) (0) returns the lower bound of the first dimension of the current instance, and System.Array.GetLowerBound(System.Int32)(System.Array.Rank - 1) returns the lower bound of the last dimension of the current instance.]

Library

RuntimeInfrastructure

See Also

System.Array Class, System Namespace

dimension

A Int32 that contains the zero-based dimension of the current instance whose upper bound is to be determined.

Return Value

A Int32 that contains the upper bound of the specified dimension in the current instance.

Exceptions

Exception Type	Condition
IndexOutOfRangeException	dimension < 0. -or- dimension is equal to or greater than the System.Array.Rank property of the current instance.

Description

[Note: For example, System.Array.GetUpperBound(System.Int32) (0) returns the upper bound of the first dimension of the current instance, and System.Array.GetUpperBound(System.Int32)(System.Array.Rank - 1) r