System.Collections.CollectionBase Class

Summary

Provides the abstract base class for a strongly typed collection.

C# Syntax:

[Serializable] public abstract class CollectionBase : IList, ICollection, IEnumerable

Public static (non-instance) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

This implementation does not provide a synchronized (thread-safe) wrapper for a CollectionBase, but derived classes can create their own synchronized versions of the CollectionBase using the CollectionBase.System.Collections.ICollection.SyncRoot property.

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.

A CollectionBase instance is always modifiable. See ReadOnlyCollectionBase for a read-only version of this class.

Notes to implementors: This base class is provided to make it easier for implementers to create a strongly typed custom collection. Implementers should extend this base class instead of creating their own.

System.Collections Namespace | ArrayList | IList | ReadOnlyCollectionBase

System.Collections.CollectionBase Member List:

Public Properties

Count

Read-only Gets the number of elements contained in the CollectionBase instance.

Public Methods

Clear	Removes all objects from the CollectionBase instance.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetEnumerator	Returns an enumerator that can iterate through the CollectionBase instance.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
RemoveAt	Removes the element at the specified index of the CollectionBase instance.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.

Protected Constructors

ctor #1

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

Protected Properties

InnerList	Read-only Gets an ArrayList containing the list of elements in the CollectionBase instance.
List	Read-only Gets an IList containing the list of elements in the CollectionBase instance.

Protected Methods

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.
OnClear	Performs additional custom processes when clearing the contents of the CollectionBase instance.
OnClearComplete	Performs additional custom processes after clearing the contents of the CollectionBase instance.
OnInsert	Performs additional custom processes before inserting a new element into the CollectionBase instance.
OnInsertComplete	Performs additional custom processes after inserting a new element into the CollectionBase instance.
OnRemove	Performs additional custom processes when removing an element from the CollectionBase instance.
OnRemoveComplete	Performs additional custom processes after removing an element from the CollectionBase instance.
OnSet	Performs additional custom processes before setting a value in the CollectionBase instance.
OnSetComplete	Performs additional custom processes after setting a value in the CollectionBase instance.
OnValidate	Performs additional custom processes when validating a value.

Explicit Interface Implementations 

ICollection.CopyTo	Copies the entire CollectionBase to a compatible one-dimensional Array, starting at the specified index of the target array.
IList.Add	Adds an object to the end of the CollectionBase.
IList.Contains	Determines whether the CollectionBase contains a specific element.
IList.IndexOf	Searches for the specified Object and returns the zero-based index of the first occurrence within the entire CollectionBase.
IList.Insert	Inserts an element into the CollectionBase at the specified index.
IList.Remove	Removes the first occurrence of a specific object from the CollectionBase.

Hierarchy:

• System.Object
• System.Collections.CollectionBase
  • System.CodeDom.CodeAttributeArgumentCollection
  • System.CodeDom.CodeAttributeDeclarationCollection
  • System.CodeDom.CodeCatchClauseCollection
  • System.CodeDom.CodeCommentStatementCollection
  • System.CodeDom.CodeExpressionCollection
  • System.CodeDom.CodeNamespaceCollection
  • System.CodeDom.CodeParameterDeclarationExpressionCollection
  • System.CodeDom.CodeStatementCollection
  • System.CodeDom.CodeTypeDeclarationCollection
  • System.CodeDom.CodeTypeMemberCollection
  • System.CodeDom.CodeTypeReferenceCollection
  • System.CodeDom.Compiler.CompilerErrorCollection
  • System.Xml.Schema.XmlSchemaObjectCollection
  • System.Xml.Serialization.XmlAnyElementAttributes
  • System.Xml.Serialization.XmlArrayItemAttributes
  • System.Xml.Serialization.XmlElementAttributes

System.Collections.CollectionBase Member Details

Summary:

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:

protected CollectionBase();

Return to top

Summary

Gets the number of elements contained in the CollectionBase instance.

C# Syntax:

public int Count {get;}

Implements:

ICollection.Count

Return to top

Summary

Gets an ArrayList containing the list of elements in the CollectionBase instance.

C# Syntax:

protected ArrayList InnerList {get;}

The On* methods are invoked only on the instance returned by the CollectionBase.List property, but not on the instance returned by the CollectionBase.InnerList property.

Return to top

Summary

Gets an IList containing the list of elements in the CollectionBase instance.

C# Syntax:

protected IList List {get;}

The On* methods are invoked only on the instance returned by the CollectionBase.List property, but not on the instance returned by the CollectionBase.InnerList property.

Return to top

Summary

Removes all objects from the CollectionBase instance.

C# Syntax:

public void Clear();

Implements:

IList.Clear

CollectionBase.Count is set to zero.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~CollectionBase();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Returns an enumerator that can iterate through the CollectionBase instance.

C# Syntax:

public IEnumerator GetEnumerator();

Return Value:

An IEnumerator for the CollectionBase instance.

Implements:

IEnumerable.GetEnumerator

Enumerators only allow reading the data in the collection. Enumerators cannot be used to modify the underlying collection.

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.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Performs additional custom processes when clearing the contents of the CollectionBase instance.

C# Syntax:

protected virtual void OnClear();

The default implementation of this method is intended to be overridden by a derived class to perform some action before the collection is cleared.

The On* methods are invoked only on the instance returned by the CollectionBase.List property, but not on the instance returned by the CollectionBase.InnerList property.

Notes to implementors:

This method allows implementers to define processes that must be performed before deleting all the elements from the underlying ArrayList. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.

CollectionBase.OnClear is invoked before the standard Clear behavior, whereas CollectionBase.OnClearComplete is invoked after the standard Clear behavior.

For example, implementers can exempt certain elements from deletion by a global Clear.

Return to top

Summary

Performs additional custom processes after clearing the contents of the CollectionBase instance.

C# Syntax:

protected virtual void OnClearComplete();

The default implementation of this method is intended to be overridden by a derived class to perform some action after the collection is cleared.

The On* methods are invoked only on the instance returned by the CollectionBase.List property, but not on the instance returned by the CollectionBase.InnerList property.

Notes to implementors:

This method allows implementers to define processes that must be performed after deleting all the elements from the underlying ArrayList. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.

CollectionBase.OnClear is invoked before the standard Clear behavior, whereas CollectionBase.OnClearComplete is invoked after the standard Clear behavior.

Return to top

Summary

Performs additional custom processes before inserting a new element into the CollectionBase instance.

C# Syntax:

protected virtual void OnInsert(    int index,    object value );

index

The zero-based index at which to insert value.

value

The new value of the element at index.

The default implementation of this method is intended to be overridden by a derived class to perform some action before the specified element is inserted.

The On* methods are invoked only on the instance returned by the CollectionBase.List property, but not on the instance returned by the CollectionBase.InnerList property.

Notes to implementors:

This method allows implementers to define processes that must be performed before inserting the element into the underlying ArrayList. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.

CollectionBase.OnInsert is invoked before the standard Insert behavior, whereas CollectionBase.OnInsertComplete is invoked after the standard Insert behavior.

For example, implementers can restrict which types of objects can be inserted into the ArrayList.

Return to top

Summary

Performs additional custom processes after inserting a new element into the CollectionBase instance.

C# Syntax:

protected virtual void OnInsertComplete(    int index,    object value );

index

The zero-based index at which to insert value.

value

The new value of the element at index.

The default implementation of this method is intended to be overridden by a derived class to perform some action after the specified element is inserted.

The On* methods are invoked only on the instance returned by the CollectionBase.List property, but not on the instance returned by the CollectionBase.InnerList property.

Notes to implementors:

This method allows implementers to define processes that must be performed after inserting the element into the underlying ArrayList. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.

CollectionBase.OnInsert is invoked before the standard Insert behavior, whereas CollectionBase.OnInsertComplete is invoked after the standard Insert behavior.

Return to top

Summary

Performs additional custom processes when removing an element from the CollectionBase instance.

C# Syntax:

protected virtual void OnRemove(    int index,    object value );

index

The zero-based index at which value can be found.

value

The value of the element to remove from index.

The default implementation of this method is intended to be overridden by a derived class to perform some action before the specified element is removed.

The On* methods are invoked only on the instance returned by the CollectionBase.List property, but not on the instance returned by the CollectionBase.InnerList property.

Notes to implementors:

This method allows implementers to define processes that must be performed before removing the element from the underlying ArrayList. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.

CollectionBase.OnRemove is invoked before the standard Remove behavior, whereas CollectionBase.OnRemoveComplete is invoked after the standard Remove behavior.

For example, implementers can prevent removal of elements by always throwing an exception in CollectionBase.OnRemove.

Return to top

Summary

Performs additional custom processes after removing an element from the CollectionBase instance.

C# Syntax:

protected virtual void OnRemoveComplete(    int index,    object value );

index

The zero-based index at which value can be found.

value

The value of the element to remove from index.

The default implementation of this method is intended to be overridden by a derived class to perform some action after the specified element is removed.

The On* methods are invoked only on the instance returned by the CollectionBase.List property, but not on the instance returned by the CollectionBase.InnerList property.

Notes to implementors:

This method allows implementers to define processes that must be performed after removing the element from the underlying ArrayList. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.

CollectionBase.OnRemove is invoked before the standard Remove behavior, whereas CollectionBase.OnRemoveComplete is invoked after the standard Remove behavior.

Return to top

Summary

Performs additional custom processes before setting a value in the CollectionBase instance.

C# Syntax:

protected virtual void OnSet(    int index,    object oldValue,    object newValue );

index

The zero-based index at which oldValue can be found.

oldValue

The value to replace with newValue.

newValue

The new value of the element at index.

The default implementation of this method is intended to be overridden by a derived class to perform some action before the specified element is set.

The On* methods are invoked only on the instance returned by the CollectionBase.List property, but not on the instance returned by the CollectionBase.InnerList property.

Notes to implementors:

This method allows implementers to define processes that must be performed before setting the specified element in the underlying ArrayList. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.

CollectionBase.OnSet is invoked before the standard Set behavior, whereas CollectionBase.OnSetComplete is invoked after the standard Set behavior.

For example, implementers can restrict which values can be overwritten by performing a check inside CollectionBase.OnSet.

Return to top

Summary

Performs additional custom processes after setting a value in the CollectionBase instance.

C# Syntax:

protected virtual void OnSetComplete(    int index,    object oldValue,    object newValue );

index

The zero-based index at which oldValue can be found.

oldValue

The value to replace with newValue.

newValue

The new value of the element at index.

The default implementation of this method is intended to be overridden by a derived class to perform some action after the specified element is set.

The On* methods are invoked only on the instance returned by the CollectionBase.List property, but not on the instance returned by the CollectionBase.InnerList property.

Notes to implementors:

This method allows implementers to define processes that must be performed after setting the specified element in the underlying ArrayList. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.

CollectionBase.OnSet is invoked before the standard Set behavior, whereas CollectionBase.OnSetComplete is invoked after the standard Set behavior.

Return to top

Summary

Performs additional custom processes when validating a value.

C# Syntax:

protected virtual void OnValidate(    object value );

value

The object to validate.

The default implementation of this method determines whether value is null, and, if so, throws ArgumentNullException. It is intended to be overridden by a derived class to perform additional action when the specified element is validated.

The On* methods are invoked only on the instance returned by the CollectionBase.List property, but not on the instance returned by the CollectionBase.InnerList property.

Notes to implementors:

This method allows implementers to define processes that must be performed when executing the standard behavior of the underlying ArrayList. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.

CollectionBase.OnValidate can be used to impose restrictions on the type of objects that are accepted into the collection. The default implementation prevents null from being added to or removed from the underlying ArrayList.

Return to top

Summary

Removes the element at the specified index of the CollectionBase instance.

C# Syntax:

public void RemoveAt(    int index );

index

The zero-based index of the element to remove.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	index is less than zero. -or- index is equal to or greater than CollectionBase.Count.

Implements:

IList.RemoveAt

In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hashtable.

Return to top

Summary

Copies the entire CollectionBase to a compatible one-dimensional Array, starting at the specified index of the target array.

C# Syntax:

void ICollection.CopyTo(    Array array,    int index );

array

The one-dimensional Array that is the destination of the elements copied from CollectionBase. The Array must have zero-based indexing.

index

The zero-based index in array at which copying begins.

Exceptions

Exception Type	Condition
ArgumentNullException	array is null.
ArgumentOutOfRangeException	index is less than zero.
ArgumentException	array is multidimensional. -or- index is equal to or greater than the length of array. -or- The number of elements in the source CollectionBase is greater than the available space from index to the end of the destination array.
InvalidCastException	The type of the source CollectionBase cannot be cast automatically to the type of the destination array.

Implements:

ICollection.CopyTo

The specified array must be of a compatible type.

This method uses Array.Copy to copy the elements.

Return to top

Summary

Adds an object to the end of the CollectionBase.

C# Syntax:

int IList.Add(    object value );

value

The Object to be added to the end of the CollectionBase.

Return Value:

The CollectionBase index at which the value has been added.

Exceptions

Exception Type	Condition
NotSupportedException	The CollectionBase is read-only. -or- The CollectionBase has a fixed size.

Implements:

IList.Add

If CollectionBase.Count already equals the capacity, the capacity of the list is doubled by automatically reallocating the internal array and copying the existing elements to the new array before the new element is added.

If CollectionBase.Count is less than the 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 CollectionBase.Count.

Return to top

Summary

Determines whether the CollectionBase contains a specific element.

C# Syntax:

bool IList.Contains(    object value );

value

The Object to locate in the CollectionBase.

Return Value:

true if the CollectionBase contains the specified value; otherwise, false.

Implements:

IList.Contains

This method performs a linear search. On average, this is an O(n /2) operation, where n is CollectionBase.Count. The longest search is an O(n) operation.

This method determines equality by calling Object.Equals.

Return to top

Summary

Searches for the specified Object and returns the zero-based index of the first occurrence within the entire CollectionBase.

C# Syntax:

int IList.IndexOf(    object value );

value

The Object to locate in the CollectionBase.

Return Value:

The zero-based index of the first occurrence of value within the entire CollectionBase, if found; otherwise, -1.

Implements:

IList.IndexOf

This method performs a linear search. On average, this is an O(n /2) operation, where n is CollectionBase.Count. The longest search is an O(n) operation.

This method determines equality by calling Object.Equals.

Return to top

Summary

Inserts an element into the CollectionBase at the specified index.

C# Syntax:

void IList.Insert(    int index,    object value );

index

The zero-based index at which value should be inserted.

value

The Object to insert.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	index is less than zero. -or- index is greater than CollectionBase.Count.
NotSupportedException	The CollectionBase is read-only. -or- The CollectionBase has a fixed size.

Implements:

IList.Insert

If CollectionBase.Count already equals the capacity, the capacity of the list is doubled by automatically reallocating the internal array before the new element is inserted.

If index is equal to CollectionBase.Count, value is added to the end of CollectionBase.

In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accomodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hashtable.

Return to top

Summary

Removes the first occurrence of a specific object from the CollectionBase.

C# Syntax:

void IList.Remove(    object value );

value

The Object to remove from the CollectionBase.

Exceptions

Exception Type	Condition
NotSupportedException	The CollectionBase is read-only. -or- The CollectionBase has a fixed size.

Implements:

IList.Remove

This method performs a linear search; therefore, the average execution time is proportional to CollectionBase.Count. That is, this method is an O(n) operation, where n is CollectionBase.Count.

This method determines equality by calling Object.Equals.

In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hashtable.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Top of page