System.Collections.Specialized.StringCollection Class

Summary

Represents a collection of strings.

C# Syntax:

[Serializable] public class StringCollection : 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 StringCollection, but derived classes can create their own synchronized versions of the StringCollection using the StringCollection.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.

Duplicate strings are allowed in StringCollection.

String comparisons are case-sensitive.

Indexes in this collection are zero-based.

System.Collections.Specialized Namespace

System.Collections.Specialized.StringCollection Member List:

Public Constructors

ctor #1

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

Public Properties

Count	Read-only Gets the number of strings contained in the StringCollection.
IsReadOnly	Read-only Gets a value indicating whether the StringCollection is read-only.
IsSynchronized	Read-only Gets a value indicating whether access to the StringCollection 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 StringCollection.

Public Methods

Add	Adds a string to the end of the StringCollection.
AddRange	Copies the elements of a string array to the end of the StringCollection.
Clear	Removes all the strings from the StringCollection.
Contains	Determines whether the specified string is in the StringCollection.
CopyTo	Copies the entire StringCollection values to a one-dimensional array of strings, 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.
GetEnumerator	Returns a StringEnumerator that can iterate through the StringCollection.
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.
IndexOf	Searches for the specified string and returns the zero-based index of the first occurrence within the StringCollection.
Insert	Inserts a string into the StringCollection at the specified index.
Remove	Removes the first occurrence of a specific string from the StringCollection.
RemoveAt	Removes the string at the specified index of the StringCollection.
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 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.

Explicit Interface Implementations 

ICollection.CopyTo	Copies the entire StringCollection to a compatible one-dimensional Array, starting at the specified index of the target array.
IEnumerable.GetEnumerator	Returns a IEnumerator that can iterate through the StringCollection.
IList.Add	Adds an object to the end of the StringCollection.
IList.Contains	Determines whether an element is in the StringCollection.
IList.IndexOf	Searches for the specified Object and returns the zero-based index of the first occurrence within the entire StringCollection.
IList.Insert	Inserts an element into the StringCollection at the specified index.
IList.Remove	Removes the first occurrence of a specific object from the StringCollection.

Hierarchy:

• System.Object
• System.Collections.Specialized.StringCollection

System.Collections.Specialized.StringCollection Member Details

Summary:

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

C# Syntax:

public StringCollection();

Return to top

Summary

Gets the number of strings contained in the StringCollection.

C# Syntax:

public int Count {get;}

Implements:

ICollection.Count

Return to top

Summary

Gets a value indicating whether the StringCollection is read-only.

C# Syntax:

public bool IsReadOnly {get;}

StringCollection implements the StringCollection.IsReadOnly property because it is required by the IList interface.

A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created.

A StringCollection instance is always writable.

Return to top

Summary

Gets a value indicating whether access to the StringCollection is synchronized (thread-safe).

C# Syntax:

public bool IsSynchronized {get;}

Implements:

ICollection.IsSynchronized

StringCollection implements the StringCollection.IsSynchronized property because it is required by the ICollection interface.

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 StringCollection.SyncRoot during the entire enumeration:

              StringCollection myCollection = new StringCollection();
               lock( myCollection.SyncRoot ) {
               foreach ( Object item in myCollection ) {
               // Insert your code here.
               }
              }
            

Return to top

Summary

Gets or sets the element at the specified index.

C# Syntax:

public string this[int index] {get; set;}

index

The zero-based index of the entry to get or set. The zero-based index of the entry to get or set.

Exceptions

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

This property provides the ability to access a specific element in the collection by using the following syntax: myCollection[index] .

Return to top

Summary

Gets an object that can be used to synchronize access to the StringCollection.

C# Syntax:

public object SyncRoot {get;}

Implements:

ICollection.SyncRoot

Derived classes can provide their own synchronized version of the StringCollection using the StringCollection.SyncRoot property. The synchronizing code must perform operations on the StringCollection.SyncRoot of the StringCollection, not directly on the StringCollection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the StringCollection object.

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 StringCollection.SyncRoot during the entire enumeration:

              StringCollection myCollection = new StringCollection();
               lock( myCollection.SyncRoot ) {
               foreach ( Object item in myCollection ) {
               // Insert your code here.
               }
              }
            

Return to top

Summary

Adds a string to the end of the StringCollection.

C# Syntax:

public int Add(    string value );

value

The string to add to the end of the StringCollection.

Return Value:

The zero-based index at which the new element is inserted.

Duplicate strings are allowed in StringCollection.

Return to top

Summary

Copies the elements of a string array to the end of the StringCollection.

C# Syntax:

public void AddRange(    string[] value );

value

An array of strings to add to the end of the StringCollection.

Exceptions

Exception Type	Condition
ArgumentNullException	value is null.

Duplicate strings are allowed in StringCollection.

The array itself can not be null but it can contain elements that are null.

Return to top

Summary

Removes all the strings from the StringCollection.

C# Syntax:

public void Clear();

Implements:

IList.Clear

StringCollection.Count is set to zero.

Return to top

Summary

Determines whether the specified string is in the StringCollection.

C# Syntax:

public bool Contains(    string value );

value

The string to locate in the StringCollection.

Return Value:

true if value is found in the StringCollection; otherwise, false.

The StringCollection.Contains method can confirm the existence of a string before performing further operations.

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

This method determines equality by calling Object.Equals. String comparisons are case-sensitive.

Return to top

Summary

Copies the entire StringCollection values to a one-dimensional array of strings, starting at the specified index of the target array.

C# Syntax:

public void CopyTo(    string[] array,    int index );

array

The one-dimensional array of strings that is the destination of the elements copied from StringCollection. The Array must have zero-based indexing. The one-dimensional array of strings that is the destination of the elements copied from StringCollection. 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 StringCollection is greater than the available space from index to the end of the destination array.
InvalidCastException	The type of the source StringCollection cannot be cast automatically to the type of the destination array.

The specified array must be of a compatible type.

The elements are copied to the Array in the same order in which the enumerator of the StringCollection iterates through the StringCollection.

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:

~StringCollection();

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

Return to top

Summary

Returns a StringEnumerator that can iterate through the StringCollection.

C# Syntax:

public StringEnumerator GetEnumerator();

Return Value:

A StringEnumerator for the StringCollection.

Enumerators are intended to be used only to read data in the collection. Enumerators cannot be used to modify the underlying collection.

The enumerator does not have exclusive access to the collection.

When an enumerator is created, it takes a snapshot of the current state of the collection. If changes are made to the collection, such as adding, modifying or deleting elements, the snapshot gets out of sync and the enumerator throws an InvalidOperationException. Two enumerators created from the same collection at the same time can have different snapshots of the collection.

The enumerator is in an invalid state if it is positioned before the first element in the collection or after the last element in the collection. Whenever the enumerator is in an invalid state, calling IEnumerator.Current throws an exception.

Initially, the enumerator is positioned before the first element in the collection. IEnumerator.Reset also brings the enumerator back to this position. Therefore, after an enumerator is created or after a IEnumerator.Reset, IEnumerator.MoveNext must be called 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.

After the end of the collection is passed, the enumerator is again in an invalid state and calling IEnumerator.MoveNext returns false. Calling IEnumerator.Current throws an exception if the last call to IEnumerator.MoveNext returned false.

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

Summary

Searches for the specified string and returns the zero-based index of the first occurrence within the StringCollection.

C# Syntax:

public int IndexOf(    string value );

value

The string to locate.

Return Value:

The zero-based index of the first occurrence of value in the StringCollection, if found; otherwise, -1.

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

This method determines equality by calling Object.Equals. String comparisons are case-sensitive.

Return to top

Summary

Inserts a string into the StringCollection at the specified index.

C# Syntax:

public void Insert(    int index,    string value );

index

The zero-based index at which value is inserted.

value

The string to insert.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	index is less than zero. -or- index greater than StringCollection.Count.

Duplicate strings are allowed in StringCollection.

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

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

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

Removes the first occurrence of a specific string from the StringCollection.

C# Syntax:

public void Remove(    string value );

value

The string to remove from the StringCollection.

Duplicate strings are allowed in StringCollection. Only the first occurrence is removed. To remove all occurrences of the specified string, use RemoveAt(IndexOf(value)) repeatedly while StringCollection.IndexOf does not return -1.

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

This method determines equality by calling Object.Equals. String comparisons are case-sensitive.

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

Removes the string at the specified index of the StringCollection.

C# Syntax:

public void RemoveAt(    int index );

index

The zero-based index of the string to remove.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	index is less than zero. -or- index is equal to or greater than StringCollection.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 StringCollection 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 StringCollection. 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 StringCollection is greater than the available space from index to the end of the destination array.
InvalidCastException	The type of the source StringCollection 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

Returns a IEnumerator that can iterate through the StringCollection.

C# Syntax:

IEnumerator IEnumerable.GetEnumerator();

Return Value:

A IEnumerator for the StringCollection.

Implements:

IEnumerable.GetEnumerator

Enumerators are intended to be used only to read data in the collection. Enumerators cannot be used to modify the underlying collection.

The enumerator does not have exclusive access to the collection.

When an enumerator is created, it takes a snapshot of the current state of the collection. If changes are made to the collection, such as adding, modifying or deleting elements, the snapshot gets out of sync and the enumerator throws an InvalidOperationException. Two enumerators created from the same collection at the same time can have different snapshots of the collection.

The enumerator is in an invalid state if it is positioned before the first element in the collection or after the last element in the collection. Whenever the enumerator is in an invalid state, calling IEnumerator.Current throws an exception.

Initially, the enumerator is positioned before the first element in the collection. IEnumerator.Reset also brings the enumerator back to this position. Therefore, after an enumerator is created or after a IEnumerator.Reset, IEnumerator.MoveNext must be called 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.

After the end of the collection is passed, the enumerator is again in an invalid state and calling IEnumerator.MoveNext returns false. Calling IEnumerator.Current throws an exception if the last call to IEnumerator.MoveNext returned false.

Return to top

Summary

Adds an object to the end of the StringCollection.

C# Syntax:

int IList.Add(    object value );

value

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

Return Value:

The StringCollection index at which the value has been added.

Exceptions

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

Implements:

IList.Add

If StringCollection.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 StringCollection.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 StringCollection.Count.

Return to top

Summary

Determines whether an element is in the StringCollection.

C# Syntax:

bool IList.Contains(    object value );

value

The Object to locate in the StringCollection.The element to locate can be null. The Object to locate in the StringCollection.The element to locate can be null.

Return Value:

true if value is found in the StringCollection; otherwise, false.

Implements:

IList.Contains

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

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 StringCollection.

C# Syntax:

int IList.IndexOf(    object value );

value

The Object to locate in the StringCollection.

Return Value:

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

Implements:

IList.IndexOf

The StringCollection is searched forward starting at the first element and ending at the last element.

This method performs a linear search. On average, this is an O(n /2) operation, where n is StringCollection.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 StringCollection 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. The Object to insert.

Exceptions

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

Implements:

IList.Insert

If StringCollection.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 StringCollection.Count, value is added to the end of StringCollection.

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 StringCollection.

C# Syntax:

void IList.Remove(    object value );

value

The Object to remove from the StringCollection.

Exceptions

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

Implements:

IList.Remove

This method performs a linear search; therefore, the average execution time is proportional to StringCollection.Count. That is, this method is an O(n) operation, where n is StringCollection.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