[Serializable] |
An ArrayList can safely support multiple readers concurrently, as long as the collection is not modified. To guarantee the thread safety of the ArrayList, all operations must be done through the wrapper returned by the ArrayList.Synchronized method.
Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads.
Indexes in this collection are zero-based.
using System;
using System.Collections;
public class SamplesArrayList {
public static void Main() {
// Creates and initializes a new ArrayList.
ArrayList myAL = new ArrayList();
myAL.Add("Hello");
myAL.Add("World");
myAL.Add("!");
// Displays the properties and values of the ArrayList.
Console.WriteLine( "myAL" );
Console.WriteLine( "\tCount: {0}", myAL.Count );
Console.WriteLine( "\tCapacity: {0}", myAL.Capacity );
Console.Write( "\tValues:" );
PrintValues( myAL );
}
public static void PrintValues( IEnumerable myList ) {
System.Collections.IEnumerator myEnumerator = myList.GetEnumerator();
while ( myEnumerator.MoveNext() )
Console.Write( "\t{0}", myEnumerator.Current );
Console.WriteLine();
}
}
/*
This code produces the following output.
myAL
Count: 3
Capacity: 16
Values: Hello World !
*/
| ctor #1 | Overloaded:.ctor()Default constructor. This constructor is called by derived class constructors to initialize state in this type.Initializes a new instance of the ArrayList class that is empty and has the default initial capacity. |
| ctor #2 | Overloaded:.ctor(ICollection c) Initializes a new instance of the ArrayList class that contains elements copied from the specified collection and that has the same initial capacity as the number of elements copied. |
| ctor #3 | Overloaded:.ctor(int capacity) Initializes a new instance of the ArrayList class that is empty and has the specified initial capacity. |
| Capacity | Read-write Gets or sets the number of elements that the ArrayList can contain. |
| Count | Read-only Gets the number of elements actually contained in the ArrayList. |
| IsFixedSize | Read-only Gets a value indicating whether the ArrayList has a fixed size. |
| IsReadOnly | Read-only Gets a value indicating whether the ArrayList is read-only. |
| IsSynchronized | Read-only Gets a value indicating whether access to the ArrayList is synchronized (thread-safe). |
| Item | Read-write Gets or sets the element at the specified index. |
| SyncRoot | Read-only Gets an object that can be used to synchronize access to the ArrayList. |
| Adapter | Creates an ArrayList wrapper for a specific IList. |
| Add | Adds an object to the end of the ArrayList. |
| AddRange | Adds the elements of an ICollection to the end of the ArrayList. |
| BinarySearch | Overloaded:BinarySearch(object value) Searches the entire sorted ArrayList for an element using the default comparer and returns the zero-based index of the element. |
| BinarySearch | Overloaded:BinarySearch(object value, IComparer comparer) Searches the entire sorted ArrayList for an element using the specified comparer and returns the zero-based index of the element. |
| BinarySearch | Overloaded:BinarySearch(int index, int count, object value, IComparer comparer) Searches a section of the sorted ArrayList for an element using the specified comparer and returns the zero-based index of the element. |
| Clear | Removes all elements from the ArrayList. |
| Clone | Creates a shallow copy of the ArrayList. |
| Contains | Determines whether an element is in the ArrayList. |
| CopyTo | Overloaded:CopyTo(Array array) Copies the entire ArrayList to a compatible one-dimensional Array, starting at the beginning of the target array. |
| CopyTo | Overloaded:CopyTo(Array array, int arrayIndex) Copies the entire ArrayList to a compatible one-dimensional Array, starting at the specified index of the target array. |
| CopyTo | Overloaded:CopyTo(int index, Array array, int arrayIndex, int count) Copies a range of elements from the ArrayList to a compatible one-dimensional Array, starting at the specified index of the target array. |
| Equals (inherited from System.Object) |
See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects. |
| FixedSize | Overloaded:FixedSize(ArrayList list) Returns an ArrayList wrapper with a fixed size. |
| FixedSize | Overloaded:FixedSize(IList list) Returns an IList wrapper with a fixed size. |
| GetEnumerator | Overloaded:GetEnumerator() Returns an enumerator for the entire ArrayList. |
| GetEnumerator | Overloaded:GetEnumerator(int index, int count) Returns an enumerator for a section of the ArrayList. |
| GetHashCode (inherited from System.Object) |
See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects. |
| GetRange | Returns an ArrayList which represents a subset of the elements in the source ArrayList. |
| GetType (inherited from System.Object) |
See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects. |
| IndexOf | Overloaded:IndexOf(object value) Searches for the specified Object and returns the zero-based index of the first occurrence within the entire ArrayList. |
| IndexOf | Overloaded:IndexOf(object value, int startIndex) Searches for the specified Object and returns the zero-based index of the first occurrence within the section of the ArrayList that extends from the specified index to the last element. |
| IndexOf | Overloaded:IndexOf(object value, int startIndex, int count) Searches for the specified Object and returns the zero-based index of the first occurrence within the section of the ArrayList that starts at the specified index and contains the specified number of elements. |
| Insert | Inserts an element into the ArrayList at the specified index. |
| InsertRange | Inserts the elements of a collection into the ArrayList at the specified index. |
| LastIndexOf | Overloaded:LastIndexOf(object value) Searches for the specified Object and returns the zero-based index of the last occurrence within the entire ArrayList. |
| LastIndexOf | Overloaded:LastIndexOf(object value, int startIndex) Searches for the specified Object and returns the zero-based index of the last occurrence within the section of the ArrayList that extends from the first element to the specified index. |
| LastIndexOf | Overloaded:LastIndexOf(object value, int startIndex, int count) Searches for the specified Object and returns the zero-based index of the last occurrence within the section of the ArrayList that contains the specified number of elements and ends at the specified index. |
| ReadOnly | Overloaded:ReadOnly(ArrayList list) Returns a read-only ArrayList wrapper. |
| ReadOnly | Overloaded:ReadOnly(IList list) Returns a read-only IList wrapper. |
| Remove | Removes the first occurrence of a specific object from the ArrayList. |
| RemoveAt | Removes the element at the specified index of the ArrayList. |
| RemoveRange | Removes a range of elements from the ArrayList. |
| Repeat | Returns an ArrayList whose elements are copies of the specified value. |
| Reverse | Overloaded:Reverse() Reverses the order of the elements in the entire ArrayList. |
| Reverse | Overloaded:Reverse(int index, int count) Reverses the order of the elements in the specified range. |
| SetRange | Copies the elements of a collection over a range of elements in the ArrayList. |
| Sort | Overloaded:Sort() Sorts the elements in the entire ArrayList using the IComparable implementation of each element. |
| Sort | Overloaded:Sort(IComparer comparer) Sorts the elements in the entire ArrayList using the specified comparer. |
| Sort | Overloaded:Sort(int index, int count, IComparer comparer) Sorts the elements in a section of ArrayList using the specified comparer. |
| Synchronized | Overloaded:Synchronized(ArrayList list) Returns an ArrayList wrapper that is synchronized (thread-safe). |
| Synchronized | Overloaded:Synchronized(IList list) Returns an IList wrapper that is synchronized (thread-safe). |
| ToArray | Overloaded:ToArray() Copies the elements of the ArrayList to a new Object array. |
| ToArray | Overloaded:ToArray(Type type) Copies the elements of the ArrayList to a new array of the specified type. |
| ToString (inherited from System.Object) |
See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects. |
| TrimToSize | Sets the capacity to the actual number of elements in the ArrayList. |
| Finalize (inherited from System.Object) |
See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects. |
| MemberwiseClone (inherited from System.Object) |
See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects. |
Hierarchy:
public ArrayList(); |
If the number of elements added to the list reaches the current capacity, the capacity is automatically doubled.
public ArrayList( |
c
| Exception Type | Condition |
|---|---|
| ArgumentNullException | c is null. |
The elements are copied onto the ArrayList in the same order they are read by the IEnumerator of the ICollection.
public ArrayList( |
capacity
| Exception Type | Condition |
|---|---|
| ArgumentOutOfRangeException | capacity is less than zero. |
If the number of elements added to the list reaches the current capacity, the capacity is automatically doubled. Therefore, if the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the ArrayList.
public virtual int Capacity {get; set;}
|
| Exception Type | Condition |
|---|---|
| ArgumentOutOfRangeException | ArrayList.Capacity is set to a value that is less than ArrayList.Count. |
ArrayList.Capacity is always greater than or equal to ArrayList.Count. If ArrayList.Count exceeds ArrayList.Capacity while adding elements, the capacity of the list is doubled by automatically reallocating the internal array.
When the value of ArrayList.Capacity is set explicitly, the internal array is also reallocated to accommodate the specified capacity. If ArrayList.Capacity is explicitly set to zero, the common language runtime sets it to the default capacity instead. The default capacity is 16.
public virtual int Count {get;}
|
ArrayList.Count is always less than or equal to ArrayList.Capacity. If ArrayList.Count exceeds ArrayList.Capacity while adding elements, the capacity of the list is doubled by automatically reallocating the internal array before copying the old elements and adding the new elements.
public virtual bool IsFixedSize {get;}
|
using System;
using System.Collections;
public class SamplesArrayList {
public static void Main() {
// Creates and initializes a new ArrayList.
ArrayList myAL = new ArrayList();
myAL.Add( "The" );
myAL.Add( "quick" );
myAL.Add( "brown" );
myAL.Add( "fox" );
myAL.Add( "jumped" );
myAL.Add( "over" );
myAL.Add( "the" );
myAL.Add( "lazy" );
myAL.Add( "dog" );
// Create a fixed-size wrapper around the ArrayList.
ArrayList myFixedSizeAL = ArrayList.FixedSize( myAL );
// Display whether the ArrayLists have a fixed size or not.
Console.WriteLine( "myAL {0}.", myAL.IsFixedSize ? "has a fixed size" : "does not have a fixed size" );
Console.WriteLine( "myFixedSizeAL {0}.", myFixedSizeAL.IsFixedSize ? "has a fixed size" : "does not have a fixed size" );
Console.WriteLine();
// Display both ArrayLists.
Console.WriteLine( "Initially," );
Console.Write( "Standard :" );
PrintValues( myAL, ' ' );
Console.Write( "Fixed size:" );
PrintValues( myFixedSizeAL, ' ' );
// Sort is allowed in the fixed-size ArrayList.
myFixedSizeAL.Sort();
// Display both ArrayLists.
Console.WriteLine( "After Sort," );
Console.Write( "Standard :" );
PrintValues( myAL, ' ' );
Console.Write( "Fixed size:" );
PrintValues( myFixedSizeAL, ' ' );
// Reverse is allowed in the fixed-size ArrayList.
myFixedSizeAL.Reverse();
// Display both ArrayLists.
Console.WriteLine( "After Reverse," );
Console.Write( "Standard :" );
PrintValues( myAL, ' ' );
Console.Write( "Fixed size:" );
PrintValues( myFixedSizeAL, ' ' );
// Add an element to the standard ArrayList.
myAL.Add( "AddMe" );
// Display both ArrayLists.
Console.WriteLine( "After adding to the standard ArrayList," );
Console.Write( "Standard :" );
PrintValues( myAL, ' ' );
Console.Write( "Fixed size:" );
PrintValues( myFixedSizeAL, ' ' );
Console.WriteLine();
// Adding or inserting elements to the fixed-size ArrayList throws an exception.
try {
myFixedSizeAL.Add( "AddMe2" );
} catch ( Exception myException ) {
Console.WriteLine("Exception: " + myException.ToString());
}
try {
myFixedSizeAL.Insert( 3, "InsertMe" );
} catch ( Exception myException ) {
Console.WriteLine("Exception: " + myException.ToString());
}
}
public static void PrintValues( IEnumerable myList, char mySeparator ) {
System.Collections.IEnumerator myEnumerator = myList.GetEnumerator();
while ( myEnumerator.MoveNext() )
Console.Write( "{0}{1}", mySeparator, myEnumerator.Current );
Console.WriteLine();
}
}
/*
This code produces the following output.
myAL does not have a fixed size.
myFixedSizeAL has a fixed size.
Initially,
Standard : The quick brown fox jumped over the lazy dog
Fixed size: The quick brown fox jumped over the lazy dog
After Sort,
Standard : brown dog fox jumped lazy over quick the The
Fixed size: brown dog fox jumped lazy over quick the The
After Reverse,
Standard : The the quick over lazy jumped fox dog brown
Fixed size: The the quick over lazy jumped fox dog brown
After adding to the standard ArrayList,
Standard : The the quick over lazy jumped fox dog brown AddMe
Fixed size: The the quick over lazy jumped fox dog brown AddMe
Exception: System.NotSupportedException: Collection was of a fixed size.
at System.Collections.FixedSizeArrayList.Add(Object obj)
at SamplesArrayList.Main()
Exception: System.NotSupportedException: Collection was of a fixed size.
at System.Collections.FixedSizeArrayList.Insert(Int32 index, Object obj)
at SamplesArrayList.Main()
*/
public virtual bool IsReadOnly {get;}
|
using System;
using System.Collections;
public class SamplesArrayList {
public static void Main() {
// Inserts code to create and initialize a new ArrayList.
ArrayList myAL = new ArrayList();
// Creates a read-only copy of the ArrayList.
ArrayList myReadOnlyAL = ArrayList.ReadOnly( myAL );
// Displays whether the ArrayList is read-only or writable.
Console.WriteLine( "myAL is {0}.", myAL.IsReadOnly ? "read only" : "writable" );
Console.WriteLine( "myReadOnlyAL is {0}.", myReadOnlyAL.IsReadOnly ? "read only" : "writable" );
// Adding to a read-only copy causes an exception.
try {
myReadOnlyAL.Add("Boo!");
} catch ( Exception myException ) {
Console.WriteLine("Exception: " + myException.ToString());
}
}
}
/*
This code produces the following output.
myAL is writable.
myReadOnlyAL is read only.
Exception: System.NotSupportedException: Collection is read-only.
at System.Collections.ReadOnlyArrayList.Add(Object obj)
at SamplesArrayList.Main()
*/
public virtual bool IsSynchronized {get;}
|
Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads.
The following code example shows how to lock the collection using the ArrayList.SyncRoot during the entire enumeration:
ArrayList myCollection = new ArrayList();
lock( myCollection.SyncRoot ) {
foreach ( Object item in myCollection ) {
// Insert your code here.
}
}
using System;
using System.Collections;
public class SamplesArrayList {
public static void Main() {
// Creates and initializes a new ArrayList.
ArrayList myAL = new ArrayList();
myAL.Add( "The" );
myAL.Add( "quick" );
myAL.Add( "brown" );
myAL.Add( "fox" );
// Creates a synchronized wrapper around the ArrayList.
ArrayList mySyncdAL = ArrayList.Synchronized( myAL );
// Displays the sychronization status of both ArrayLists.
Console.WriteLine( "myAL is {0}.", myAL.IsSynchronized ? "synchronized" : "not synchronized" );
Console.WriteLine( "mySyncdAL is {0}.", mySyncdAL.IsSynchronized ? "synchronized" : "not synchronized" );
}
}
/*
This code produces the following output.
myAL is not synchronized.
mySyncdAL is synchronized.
*/
public virtual object this[int index] {get; set;}
|
index
| Exception Type | Condition |
|---|---|
| ArgumentOutOfRangeException | index is less than zero. -or- index is equal to or greater than ArrayList.Count. |
myCollection[index]
.
public virtual object SyncRoot {get;}
|
Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads.
The following code example shows how to lock the collection using the ArrayList.SyncRoot during the entire enumeration:
ArrayList myCollection = new ArrayList();
lock( myCollection.SyncRoot ) {
foreach ( Object item in myCollection ) {
// Insert your code here.
}
}
list
| Exception Type | Condition |
|---|---|
| ArgumentNullException | list is null. |
The ArrayList class provides generic ArrayList.Reverse, ArrayList.BinarySearch and ArrayList.Sort methods. This wrapper can be a means to use those methods on IList; however, performing these generic operations through the wrapper might be less efficient than operations applied directly on the IList.
value
| Exception Type | Condition |
|---|---|
| NotSupportedException | The ArrayList is read-only. -or- The ArrayList has a fixed size. |
If ArrayList.Count is less than ArrayList.Capacity, this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(n) operation, where n is ArrayList.Count.
using System;
using System.Collections;
public class SamplesArrayList {
public static void Main() {
// Creates and initializes a new ArrayList.
ArrayList myAL = new ArrayList();
myAL.Add( "The" );
myAL.Add( "quick" );
myAL.Add( "brown" );
myAL.Add( "fox" );
// Creates and initializes a new Queue.
Queue myQueue = new Queue();
myQueue.Enqueue( "jumped" );
myQueue.Enqueue( "over" );
myQueue.Enqueue( "the" );
myQueue.Enqueue( "lazy" );
myQueue.Enqueue( "dog" );
// Displays the ArrayList and the Queue.
Console.WriteLine( "The ArrayList initially contains the following:" );
PrintValues( myAL, '\t' );
Console.WriteLine( "The Queue initially contains the following:" );
PrintValues( myQueue, '\t' );
// Copies the Queue elements to the end of the ArrayList.
myAL.AddRange( myQueue );
// Displays the ArrayList.
Console.WriteLine( "The ArrayList now contains the following:" );
PrintValues( myAL, '\t' );
}
public static void PrintValues( IEnumerable myList, char mySeparator ) {
System.Collections.IEnumerator myEnumerator = myList.GetEnumerator();
while ( myEnumerator.MoveNext() )
Console.Write( "{0}{1}", mySeparator, myEnumerator.Current );
Console.WriteLine();
}
}
/*
This code produces the following output.
The ArrayList initially contains the following:
The quick brown fox
The Queue initially contains the following:
jumped over the lazy dog
The ArrayList now contains the following:
The quick brown fox jumped over the lazy dog
*/
public virtual void AddRange( |
c
| Exception Type | Condition |
|---|---|
| ArgumentNullException | c is null. |
| NotSupportedException | The ArrayList is read-only. -or- The ArrayList has a fixed size. |
If the ArrayList can accommodate the new elements without increasing the ArrayList.Capacity, this method is an O(n) operation, where n is the number of elements to be added. If the capacity needs to be increased to accommodate the new elements, this method becomes an O(n + m) operation, where n is the number of elements to be added and m is ArrayList.Count.
using System;
using System.Collections;
public class SamplesArrayList {
public static void Main() {
// Creates and initializes a new ArrayList.
ArrayList myAL = new ArrayList();
myAL.Add( "The" );
myAL.Add( "quick" );
myAL.Add( "brown" );
myAL.Add( "fox" );
// Creates and initializes a new Queue.
Queue myQueue = new Queue();
myQueue.Enqueue( "jumped" );
myQueue.Enqueue( "over" );
myQueue.Enqueue( "the" );
myQueue.Enqueue( "lazy" );
myQueue.Enqueue( "dog" );
// Displays the ArrayList and the Queue.
Console.WriteLine( "The ArrayList initially contains the following:" );
PrintValues( myAL, '\t' );
Console.WriteLine( "The Queue initially contains the following:" );
PrintValues( myQueue, '\t' );
// Copies the Queue elements to the end of the ArrayList.
myAL.AddRange( myQueue );
// Displays the ArrayList.
Console.WriteLine( "The ArrayList now contains the following:" );
PrintValues( myAL, '\t' );
}
public static void PrintValues( IEnumerable myList, char mySeparator ) {
System.Collections.IEnumerator myEnumerator = myList.GetEnumerator();
while ( myEnumerator.MoveNext() )
Console.Write( "{0}{1}", mySeparator, myEnumerator.Current );
Console.WriteLine();
}
}
/*
This code produces the following output.
The ArrayList initially contains the following:
The quick brown fox
The Queue initially contains the following:
jumped over the lazy dog
The ArrayList now contains the following:
The quick brown fox jumped over the lazy dog
*/
value
| Exception Type | Condition |
|---|---|
| ArgumentException | Neither value nor the elements of ArrayList implement the IComparable interface. -or- value is not of the same type as the elements of the ArrayList. |
Comparing null with any type is allowed and does not generate an exception when using IComparable. When sorting, null is considered to be less than any other object.
If the ArrayList contains more than one element with the same value, the method returns only the index of the first occurrence.
If the ArrayList does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the ArrayList, this index should be used as the insertion point to maintain the sort order.
This method is an O(log
using System;
using System.Collections;
public class SamplesArrayList {
public static void Main() {
// Creates and initializes a new ArrayList.
ArrayList myAL = new ArrayList();
for ( int i = 0; i <= 4; i++ )
myAL.Add( i*2 );
// Displays the ArrayList.
Console.WriteLine( "The Int32 ArrayList contains the following:" );
PrintValues( myAL );
// Locates a specific object that does not exist in the ArrayList.
Object myObjectOdd = 3;
FindMyObject( myAL, myObjectOdd );
// Locates an object that exists in the ArrayList.
Object myObjectEven = 6;
FindMyObject( myAL, myObjectEven );
}
public static void FindMyObject( ArrayList myList, Object myObject ) {
int myIndex=myList.BinarySearch( myObject );
if ( myIndex < 0 )
Console.WriteLine( "The object to search for ({0}) is not found. The next larger object is at index {1}.", myObject, ~myIndex );
else
Console.WriteLine( "The object to search for ({0}) is at index {1}.", myObject, myIndex );
}
public static void PrintValues( IEnumerable myList ) {
System.Collections.IEnumerator myEnumerator = myList.GetEnumerator();
while ( myEnumerator.MoveNext() )
Console.Write( "\t{0}", myEnumerator.Current );
Console.WriteLine();
}
}
/*
This code produces the following output.
The Int32 ArrayList contains the following:
0 2 4 6 8
The object to search for (3) is not found. The next larger object is at index 2.
The object to search for (6) is at index 3.
*/
value
comparer
-or-
null to use the default comparer that is the IComparable implementation of each element.
The IComparer implementation to use when comparing elements.-or-
null to use the default comparer that is the IComparable implementation of each element.
| Exception Type | Condition |
|---|---|
| ArgumentException | comparer is null and neither value nor the elements of ArrayList implement the IComparable interface. -or- comparer is null and value is not of the same type as the elements of the ArrayList. |
If comparer is provided, the elements of the ArrayList are compared to the specified value using the specified IComparer implementation. If the ArrayList is not already sorted according to the sort order defined by comparer, the result might be incorrect.
If comparer is null, the comparison is done using the IComparable implementation provided by the element itself or by the specified value. If the ArrayList is not already sorted according to the IComparable implementation, the result might be incorrect.
Comparing null with any type is allowed and does not generate an exception when using IComparable. When sorting, null is considered to be less than any other object.
If the ArrayList contains more than one element with the same value, the method returns only the index of the first occurrence.
If the ArrayList does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the ArrayList, this index should be used as the insertion point to maintain the sort order.
This method is an O(log
public virtual int BinarySearch( |
index
count
value
comparer
-or-
null to use the default comparer that is the IComparable implementation of each element.
The IComparer implementation to use when comparing elements.-or-
null to use the default comparer that is the IComparable implementation of each element.
| Exception Type | Condition |
|---|---|
| ArgumentException | index and count do not denote a valid range in the ArrayList. -or- comparer is null and neither value nor the elements of ArrayList implement the IComparable interface. -or- comparer is null and value is not of the same type as the elements of the ArrayList. |
| ArgumentOutOfRangeException | index is less than zero. -or- count is less than zero. |
If comparer is provided, the elements of the ArrayList are compared to the specified value using the specified IComparer implementation. If the ArrayList is not already sorted according to the sort order defined by comparer, the result might be incorrect.
If comparer is null, the comparison is done using the IComparable implementation provided by the element itself or by the specified value. If the ArrayList is not already sorted according to the IComparable implementation, the result might be incorrect.
Comparing null with any type is allowed and does not generate an exception when using IComparable. When sorting, null is considered to be less than any other object.
If the ArrayList contains more than one element with the same value, the method returns only the index of the first occurrence.
If the ArrayList does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the ArrayList, this index should be used as the insertion point to maintain the sort order.
This method is an O(log
public virtual void Clear(); |
| Exception Type | Condition |
|---|---|
| NotSupportedException | The ArrayList is read-only. -or- The ArrayList has a fixed size. |
using System;
using System.Collections;
public class SamplesArrayList {
public static void Main() {
// Creates and initializes a new ArrayList.
ArrayList myAL = new ArrayList();
myAL.Add( "The" );
myAL.Add( "quick" );
myAL.Add( "brown" );
myAL.Add( "fox" );
myAL.Add( "jumped" );
// Displays the count, capacity and values of the ArrayList.
Console.WriteLine( "Initially," );
Console.WriteLine( " Count : {0}", myAL.Count );
Console.WriteLine( " Capacity : {0}", myAL.Capacity );
Console.Write( " Values:" );
PrintValues( myAL );
// Trim the ArrayList.
myAL.TrimToSize();
// Displays the count, capacity and values of the ArrayList.
Console.WriteLine( "After TrimToSize," );
Console.WriteLine( " Count : {0}", myAL.Count );
Console.WriteLine( " Capacity : {0}", myAL.Capacity );
Console.Write( " Values:" );
PrintValues( myAL );
// Clear the ArrayList.
myAL.Clear();
// Displays the count, capacity and values of the ArrayList.
Console.WriteLine( "After Clear," );
Console.WriteLine( " Count : {0}", myAL.Count );
Console.WriteLine( " Capacity : {0}", myAL.Capacity );
Console.Write( " Values:" );
PrintValues( myAL );
// Trim the ArrayList again.
myAL.TrimToSize();
// Displays the count, capacity and values of the ArrayList.
Console.WriteLine( "After the second TrimToSize," );
Console.WriteLine( " Count : {0}", myAL.Count );
Console.WriteLine( " Capacity : {0}", myAL.Capacity );
Console.Write( " Values:" );
PrintValues( myAL );
}
public static void PrintValues( IEnumerable myList ) {
System.Collections.IEnumerator myEnumerator = myList.GetEnumerator();
while ( myEnumerator.MoveNext() )
Console.Write( "\t{0}", myEnumerator.Current );
Console.WriteLine();
}
}
/*
This code produces the following output.
Initially,
Count : 5
Capacity : 16
Values: The quick brown fox jumped
After TrimToSize,
Count : 5
Capacity : 5
Values: The quick brown fox jumped
After Clear,
Count : 0
Capacity : 5
Values:
After the second TrimToSize,
Count : 0
Capacity : 16
Values:
*/
public virtual object Clone(); |
In contrast, a deep copy of a collection copies the elements and everything directly or indirectly referenced by the elements.
item
This method determines equality by calling Object.Equals.
public virtual void CopyTo( |
array
| Exception Type | Condition |
|---|---|
| ArgumentNullException | array is null. |
| ArgumentException | array is multidimensional. -or- The number of elements in the source ArrayList is greater than the number of elements that the destination array can contain. |
| InvalidCastException | The type of the source ArrayList cannot be cast automatically to the type of the destination array. |
This method uses Array.Copy to copy the elements.
The elements are copied to the Array in the same order in which the enumerator iterates through the ArrayList.
using System;
using System.Collections;
public class SamplesArrayList {
public static void Main() {
// Creates and initializes the source ArrayList.
ArrayList mySourceList = new ArrayList();
mySourceList.Add( "three" );
mySourceList.Add( "napping" );
mySourceList.Add( "cats" );
mySourceList.Add( "in" );
mySourceList.Add( "the" );
mySourceList.Add( "barn" );
// Creates and initializes the one-dimensional target Array.
Array myTargetArray=Array.CreateInstance( typeof(String), 15 );
myTargetArray.SetValue( "The", 0 );
myTargetArray.SetValue( "quick", 1 );
myTargetArray.SetValue( "brown", 2 );
myTargetArray.SetValue( "fox", 3 );
myTargetArray.SetValue( "jumped", 4 );
myTargetArray.SetValue( "over", 5 );
myTargetArray.SetValue( "the", 6 );
myTargetArray.SetValue( "lazy", 7 );
myTargetArray.SetValue( "dog", 8 );
// Displays the values of the target Array.
Console.WriteLine( "The target Array contains the following (before and after copying):" );
PrintValues( myTargetArray, ' ' );
// Copies the second element from the source ArrayList to the target ArrayList starting at index 7.
mySourceList.CopyTo( 1, myTargetArray, 7, 1 );
// Displays the values of the target Array.
PrintValues( myTargetArray, ' ' );
// Copies the entire source ArrayList to the target ArrayList starting at index 6.
mySourceList.CopyTo( myTargetArray, 6 );
// Displays the values of the target Array.
PrintValues( myTargetArray, ' ' );
// Copies the entire source ArrayList to the target ArrayList starting at index 0.
mySourceList.CopyTo( myTargetArray );
// Displays the values of the target Array.
PrintValues( myTargetArray, ' ' );
}
public static void PrintValues( Array myArr, char mySeparator ) {
System.Collections.IEnumerator myEnumerator = myArr.GetEnumerator();
int i = 0;
int cols = myArr.GetLength( myArr.Rank - 1 );
while ( myEnumerator.MoveNext() ) {
if ( i < cols ) {
i++;
} else {
Console.WriteLine();
i = 1;
}
Console.Write( "{0}{1}", mySeparator, myEnumerator.Current );
}
Console.WriteLine();
}
}
/*
This code produces the following output.
The target Array contains the following (before and after copying):
The quick brown fox jumped over the lazy dog
The quick brown fox jumped over the napping dog
The quick brown fox jumped over three napping cats in the barn
three napping cats in the barn three napping cats in the barn
*/
array
arrayIndex
| Exception Type | Condition |
|---|---|
| ArgumentNullException | array is null. |
| ArgumentOutOfRangeException | arrayIndex is less than zero. |
| ArgumentException | array is multidimensional. -or- arrayIndex is equal to or greater than the length of array. -or- The number of elements in the source ArrayList is greater than the available space from arrayIndex to the end of the destination array. |
| InvalidCastException | The type of the source ArrayList cannot be cast automatically to the type of the destination array. |
This method uses Array.Copy to copy the elements.
using System;
using System.Collections;
public class SamplesArrayList {
public static void Main() {
// Creates and initializes the source ArrayList.
ArrayList mySourceList = new ArrayList();
mySourceList.Add( "three" );
mySourceList.Add( "napping" );
mySourceList.Add( "cats" );
mySourceList.Add( "in" );
mySourceList.Add( "the" );
mySourceList.Add( "barn" );
// Creates and initializes the one-dimensional target Array.
Array myTargetArray=Array.CreateInstance( typeof(String), 15 );
myTargetArray.SetValue( "The", 0 );
myTargetArray.SetValue( "quick", 1 );
myTargetArray.SetValue( "brown", 2 );
myTargetArray.SetValue( "fox", 3 );
myTargetArray.SetValue( "jumped", 4 );
myTargetArray.SetValue( "over", 5 );
myTargetArray.SetValue( "the", 6 );
myTargetArray.SetValue( "lazy", 7 );
myTargetArray.SetValue( "dog", 8 );
// Displays the values of the target Array.
Console.WriteLine( "The target Array contains the following (before and after copying):" );
PrintValues( myTargetArray, ' ' );
// Copies the second element from the source ArrayList to the target ArrayList, starting at index 7.
mySourceList.CopyTo( 1, myTargetArray, 7, 1 );
// Displays the values of the target Array.
PrintValues( myTargetArray, ' ' );
// Copies the entire source ArrayList to the target ArrayList, starting at index 6.
mySourceList.CopyTo( myTargetArray, 6 );
// Displays the values of the target Array.
PrintValues( myTargetArray, ' ' );
// Copies the entire source ArrayList to the target ArrayList, starting at index 0.
mySourceList.CopyTo( myTargetArray );
// Displays the values of the target Array.
PrintValues( myTargetArray, ' ' );
}
public static void PrintValues( Array myArr, char mySeparator ) {
System.Collections.IEnumerator myEnumerator = myArr.GetEnumerator();
int i = 0;
int cols = myArr.GetLength( myArr.Rank - 1 );
while ( myEnumerator.MoveNext() ) {
if ( i < cols ) {
i++;
} else {
Console.WriteLine();
i = 1;
}
Console.Write( "{0}{1}", mySeparator, myEnumerator.Current );
}
Console.WriteLine();
}
}
/*
This code produces the following output.
The target Array contains the following (before and after copying):
The quick brown fox jumped over the lazy dog
The quick brown fox jumped over the napping dog
The quick brown fox jumped over three napping cats in the barn
three napping cats in the barn three napping cats in the barn
*/
index
array
arrayIndex
count
| Exception Type | Condition |
|---|---|
| ArgumentNullException | array is null. |
| ArgumentOutOfRangeException | index is less than zero. -or- arrayIndex is less than zero. -or- count is less than zero. |
| ArgumentException | array is multidimensional. -or- index is equal to or greater than the ArrayList.Count of the source ArrayList. -or- arrayIndex is equal to or greater than the length of array. -or- The number of elements in the source ArrayList is greater than the available space from arrayIndex to the end of the destination array. |
| InvalidCastException | The type of the source ArrayList cannot be cast automatically to the type of the destination array. |
using System;
using System.Collections;
public class SamplesArrayList {
public static void Main() {
// Creates and initializes the source ArrayList.
ArrayList mySourceList = new ArrayList();
mySourceList.Add( "three" );
mySourceList.Add( "napping" );
mySourceList.Add( "cats" );
mySourceList.Add( "in" );
mySourceList.Add( "the" );
mySourceList.Add( "barn" );
// Creates and initializes the one-dimensional target Array.
Array myTargetArray=Array.CreateInstance( typeof(String), 15 );
myTargetArray.SetValue( "The", 0 );
myTargetArray.SetValue( "quick", 1 );
myTargetArray.SetValue( "brown", 2 );
myTargetArray.SetValue( "fox", 3 );
myTargetArray.SetValue( "jumped", 4 );
myTargetArray.SetValue( "over", 5 );
myTargetArray.SetValue( "the", 6 );
myTargetArray.SetValue( "lazy", 7 );
myTargetArray.SetValue( "dog", 8 );
// Displays the values of the target Array.
Console.WriteLine( "The target Array contains the following (before and after copying):" );
PrintValues( myTargetArray, ' ' );
// Copies the second element from the source ArrayList to the target ArrayList, starting at index 7.
mySourceList.CopyTo( 1, myTargetArray, 7, 1 );
// Displays the values of the target Array.
PrintValues( myTargetArray, ' ' );
// Copies the entire source ArrayList to the target ArrayList, starting at index 6.
mySourceList.CopyTo( myTargetArray, 6 );
// Displays the values of the target Array.
PrintValues( myTargetArray, ' ' );
// Copies the entire source ArrayList to the target ArrayList, starting at index 0.
mySourceList.CopyTo( myTargetArray );
// Displays the values of the target Array.
PrintValues( myTargetArray, ' ' );
}
public static void PrintValues( Array myArr, char mySeparator ) {
System.Collections.IEnumerator myEnumerator = myArr.GetEnumerator();
int i = 0;
int cols = myArr.GetLength( myArr.Rank - 1 );
while ( myEnumerator.MoveNext() ) {
if ( i < cols ) {
i++;
} else {
Console.WriteLine();
i = 1;
}
Console.Write( "{0}{1}", mySeparator, myEnumerator.Current );
}
Console.WriteLine();
}
}
/*
This code produces the following output.
The target Array contains the following (before and after copying):
The quick brown fox jumped over the lazy dog
The quick brown fox jumped over the napping dog
The quick brown fox jumped over three napping cats in the barn
three napping cats in the barn three napping cats in the barn
*/
~ArrayList(); |
list
| Exception Type | Condition |
|---|---|
| ArgumentNullException | list is null. |
using System;
using System.Collections;
public class SamplesArrayList {
public static void Main() {
// Creates and initializes a new ArrayList.
ArrayList myAL = new ArrayList();
myAL.Add( "The" );
myAL.Add( "quick" );
myAL.Add( "brown" );
myAL.Add( "fox" );
myAL.Add( "jumped" );
myAL.Add( "over" );
myAL.Add( "the" );
myAL.Add( "lazy" );
myAL.Add( "dog" );
// Create a fixed-size wrapper around the ArrayList.
ArrayList myFixedSizeAL = ArrayList.FixedSize( myAL );
// Display whether the ArrayLists have a fixed size or not.
Console.WriteLine( "myAL {0}.", myAL.IsFixedSize ? "has a fixed size" : "does not have a fixed size" );
Console.WriteLine( "myFixedSizeAL {0}.", myFixedSizeAL.IsFixedSize ? "has a fixed size" : "does not have a fixed size" );
Console.WriteLine();
// Display both ArrayLists.
Console.WriteLine( "Initially," );
Console.Write( "Standard :" );
PrintValues( myAL, ' ' );
Console.Write( "Fixed size:" );
PrintValues( myFixedSizeAL, ' ' );
// Sort is allowed in the fixed-size ArrayList.
myFixedSizeAL.Sort();
// Display both ArrayLists.
Console.WriteLine( "After Sort," );
Console.Write( "Standard :" );
PrintValues( myAL, ' ' );
Console.Write( "Fixed size:" );
PrintValues( myFixedSizeAL, ' ' );
// Reverse is allowed in the fixed-size ArrayList.
myFixedSizeAL.Reverse();
// Display both ArrayLists.
Console.WriteLine( "After Reverse," );
Console.Write( "Standard :" );
PrintValues( myAL, ' ' );
Console.Write( "Fixed size:" );
PrintValues( myFixedSizeAL, ' ' );
// Add an element to the standard ArrayList.
myAL.Add( "AddMe" );
// Display both ArrayLists.
Console.WriteLine( "After adding to the standard ArrayList," );
Console.Write( "Standard :" );
PrintValues( myAL, ' ' );
Console.Write( "Fixed size:" );
PrintValues( myFixedSizeAL, ' ' );
Console.WriteLine();
// Adding or inserting elements to the fixed-size ArrayList throws an exception.
try {
myFixedSizeAL.Add( "AddMe2" );
} catch ( Exception myException ) {
Console.WriteLine("Exception: " + myException.ToString());
}
try {
myFixedSizeAL.Insert( 3, "InsertMe" );
} catch ( Exception myException ) {
Console.WriteLine("Exception: " + myException.ToString());
}
}
public static void PrintValues( IEnumerable myList, char mySeparator ) {
System.Collections.IEnumerator myEnumerator = myList.GetEnumerator();
while ( myEnumerator.MoveNext() )
Console.Write( "{0}{1}", mySeparator, myEnumerator.Current );
Console.WriteLine();
}
}
/*
This code produces the following output.
myAL does not have a fixed size.
myFixedSizeAL has a fixed size.
Initially,
Standard : The quick brown fox jumped over the lazy dog
Fixed size: The quick brown fox jumped over the lazy dog
After Sort,
Standard : brown dog fox jumped lazy over quick the The
Fixed size: brown dog fox jumped lazy over quick the The
After Reverse,
Standard : The the quick over lazy jumped fox dog brown
Fixed size: The the quick over lazy jumped fox dog brown
After adding to the standard ArrayList,
Standard : The the quick over lazy jumped fox dog brown AddMe
Fixed size: The the quick over lazy jumped fox dog brown AddMe
Exception: System.NotSupportedException: Collection was of a fixed size.
at System.Collections.FixedSizeArrayList.Add(Object obj)
at SamplesArrayList.Main()
Exception: System.NotSupportedException: Collection was of a fixed size.
at System.Collections.FixedSizeArrayList.Insert(Int32 index, Object obj)
at SamplesArrayList.Main()
*/
list
| Exception Type | Condition |
|---|---|
| ArgumentNullException | list is null. |
public virtual IEnumerator GetEnumerator(); |
Initially, the enumerator is positioned before the first element in the collection. IEnumerator.Reset also brings the enumerator back to this position. At this position, calling IEnumerator.Current throws an exception. Therefore, you must call IEnumerator.MoveNext to advance the enumerator to the first element of the collection before reading the value of IEnumerator.Current.
IEnumerator.Current returns the same object until either IEnumerator.MoveNext or IEnumerator.Reset is called. IEnumerator.MoveNext sets IEnumerator.Current to the next element.
After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling IEnumerator.MoveNext returns false. If the last call to IEnumerator.MoveNext returned false, calling IEnumerator.Current throws an exception. To set IEnumerator.Current to the first element of the collection again, you can call IEnumerator.Reset followed by 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 the next call to IEnumerator.MoveNext or IEnumerator.Reset throws an InvalidOperationException. If the collection is modified between IEnumerator.MoveNext and IEnumerator.Current, IEnumerator.Current will return the element that it is set to, even if the enumerator is already invalidated.
The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads.
public virtual IEnumerator GetEnumerator( |
index
count
| Exception Type | Condition |
|---|---|
| ArgumentOutOfRangeException | index is less than zero. -or- count is less than zero. |
| ArgumentException | index and count do not specify a valid range in the ArrayList. |
Initially, the enumerator is positioned before the first element in the collection. IEnumerator.Reset also brings the enumerator back to this position. At this position, calling IEnumerator.Current throws an exception. Therefore, you must call IEnumerator.MoveNext to advance the enumerator to the first element of the collection before reading the value of IEnumerator.Current.
IEnumerator.Current returns the same object until either IEnumerator.MoveNext or IEnumerator.Reset is called. IEnumerator.MoveNext sets IEnumerator.Current to the next element.
After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling IEnumerator.MoveNext returns false. If the last call to IEnumerator.MoveNext returned false, calling IEnumerator.Current throws an exception. To set IEnumerator.Current to the first element of the collection again, you can call IEnumerator.Reset followed by 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 the next call to IEnumerator.MoveNext or IEnumerator.Reset throws an InvalidOperationException. If the collection is modified between IEnumerator.MoveNext and IEnumerator.Current, IEnumerator.Current will return the element that it is set to, even if the enumerator is already invalidated.
The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads.
public virtual int GetHashCode(); |