System.Collections.Specialized.NameObjectCollectionBase Class

Summary

Provides the abstract base class for a sorted collection of associated String keys and Object values that can be accessed either with the key or with the index.

C# Syntax:

[Serializable] public abstract class NameObjectCollectionBase : ICollection, IEnumerable, ISerializable, IDeserializationCallback

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 NameObjectCollectionBase, but derived classes can create their own synchronized versions of the NameObjectCollectionBase using the NameObjectCollectionBase.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.

The underlying structure for this class is a hashtable.

The capacity is the number of key-and-value pairs that the NameObjectCollectionBase instance can contain. The default initial capacity is zero. The capacity is automatically increased as required.

The hash code provider dispenses hash codes for keys in the NameObjectCollectionBase instance. The default hash code provider is the CaseInsensitiveHashCodeProvider.

The comparer determines whether two keys are equal. The default comparer is the CaseInsensitiveComparer.

null is allowed as a key or as a value.

The NameObjectCollectionBase.BaseGet method does not distinguish between null which is returned because the specified key is not found and null which is returned because the value associated with the key is null.

System.Collections.Specialized Namespace | Hashtable | NameValueCollection | String

System.Collections.Specialized.NameObjectCollectionBase Member List:

Public Properties

Count	Read-only Gets the number of key-and-value pairs contained in the NameObjectCollectionBase instance.
Keys	Read-only Gets a NameObjectCollectionBase.KeysCollection instance that contains all the keys in the NameObjectCollectionBase instance.

Public Methods

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 NameObjectCollectionBase.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetObjectData	Implements the ISerializable interface and returns the data needed to serialize the NameObjectCollectionBase instance.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
OnDeserialization	Implements the ISerializable interface and raises the deserialization event when the deserialization is complete.
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	Overloaded: .ctor() Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the NameObjectCollectionBase class that is empty.
ctor #2	Overloaded: .ctor(int capacity) Initializes a new instance of the NameObjectCollectionBase class that is empty and has the specified initial capacity.
ctor #3	Overloaded: .ctor(IHashCodeProvider hashProvider, IComparer comparer) Initializes a new instance of the NameObjectCollectionBase class that is empty and uses the specified hash code provider and the specified comparer.
ctor #4	Overloaded: .ctor(SerializationInfo info, StreamingContext context) Initializes a new instance of the NameObjectCollectionBase class that is serializable and uses the specified SerializationInfo and StreamingContext.
ctor #5	Overloaded: .ctor(int capacity, IHashCodeProvider hashProvider, IComparer comparer) Initializes a new instance of the NameObjectCollectionBase class that is empty, has the specified initial capacity and uses the specified case-insensitive hash code provider and the specified case-insensitive comparer.

Protected Properties

IsReadOnly

Read-write Gets or sets a value indicating whether the NameObjectCollectionBase instance is read-only.

Protected Methods

BaseAdd	Adds an entry with the specified key and value into the NameObjectCollectionBase instance.
BaseClear	Removes all entries from the NameObjectCollectionBase instance.
BaseGet	Overloaded: BaseGet(int index) Gets the value of the entry at the specified index of the NameObjectCollectionBase instance.
BaseGet	Overloaded: BaseGet(string name) Gets the value of the first entry with the specified key from the NameObjectCollectionBase instance.
BaseGetAllKeys	Returns a String array that contains all the keys in the NameObjectCollectionBase instance.
BaseGetAllValues	Overloaded: BaseGetAllValues() Returns an Object array that contains all the values in the NameObjectCollectionBase instance.
BaseGetAllValues	Overloaded: BaseGetAllValues(Type type) Returns an array of the specified type that contains all the values in the NameObjectCollectionBase instance.
BaseGetKey	Gets the key of the entry at the specified index of the NameObjectCollectionBase instance.
BaseHasKeys	Gets a value indicating whether the NameObjectCollectionBase instance contains entries whose keys are not null.
BaseRemove	Removes the entries with the specified key from the NameObjectCollectionBase instance.
BaseRemoveAt	Removes the entry at the specified index of the NameObjectCollectionBase instance.
BaseSet	Overloaded: BaseSet(int index, object value) Sets the value of the entry at the specified index of the NameObjectCollectionBase instance.
BaseSet	Overloaded: BaseSet(string name, object value) Sets the value of the first entry with the specified key in the NameObjectCollectionBase instance, if found; otherwise, adds an entry with the specified key and value into the NameObjectCollectionBase instance.
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 NameObjectCollectionBase to a compatible one-dimensional Array, starting at the specified index of the target array.

Hierarchy:

• System.Object
• System.Collections.Specialized.NameObjectCollectionBase
  • System.Collections.Specialized.NameValueCollection

System.Collections.Specialized.NameObjectCollectionBase Member Details

Summary

Initializes a new instance of the NameObjectCollectionBase class that is empty.

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

C# Syntax:

protected NameObjectCollectionBase();

The capacity is the number of key-and-value pairs that the NameObjectCollectionBase instance can contain. The default initial capacity is zero. The capacity is automatically increased as required.

The hash code provider dispenses hash codes for keys in the NameObjectCollectionBase instance. The default hash code provider is the CaseInsensitiveHashCodeProvider.

The comparer determines whether two keys are equal. The default comparer is the CaseInsensitiveComparer.

Return to top

Summary

Initializes a new instance of the NameObjectCollectionBase class that is empty and has the specified initial capacity.

C# Syntax:

protected NameObjectCollectionBase(    int capacity );

capacity

The approximate number of entries that the NameObjectCollectionBase instance can initially contain.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	capacity is less than zero.

The capacity is the number of key-and-value pairs that the NameObjectCollectionBase instance can contain. Specifying the initial capacity eliminates the need to perform a number of resizing operations while entries are added to the NameObjectCollectionBase instance. The capacity is automatically increased as required.

The hash code provider dispenses hash codes for keys in the NameObjectCollectionBase instance. The default hash code provider is the CaseInsensitiveHashCodeProvider.

The comparer determines whether two keys are equal. The default comparer is the CaseInsensitiveComparer.

Return to top

Summary

Initializes a new instance of the NameObjectCollectionBase class that is empty and uses the specified hash code provider and the specified comparer.

C# Syntax:

protected NameObjectCollectionBase(    IHashCodeProvider hashProvider,    IComparer comparer );

hashProvider

The IHashCodeProvider that will supply the hash codes for all keys in the NameObjectCollectionBase instance. The IHashCodeProvider that will supply the hash codes for all keys in the NameObjectCollectionBase instance.

comparer

The IComparer to use to determine whether two keys are equal. The IComparer to use to determine whether two keys are equal.

The capacity is the number of key-and-value pairs that the NameObjectCollectionBase instance can contain. The default initial capacity is zero. The capacity is automatically increased as required.

The hash code provider dispenses hash codes for keys in the NameObjectCollectionBase instance. The default hash code provider is the CaseInsensitiveHashCodeProvider.

The comparer determines whether two keys are equal. The default comparer is the CaseInsensitiveComparer.

Return to top

Summary

Initializes a new instance of the NameObjectCollectionBase class that is serializable and uses the specified SerializationInfo and StreamingContext.

C# Syntax:

protected NameObjectCollectionBase(    SerializationInfo info,    StreamingContext context );

info

A SerializationInfo object that contains the information required to serialize the new NameObjectCollectionBase instance.

context

A StreamingContext object that contains the source and destination of the serialized stream associated with the new NameObjectCollectionBase instance.

Return to top

Summary

Initializes a new instance of the NameObjectCollectionBase class that is empty, has the specified initial capacity and uses the specified case-insensitive hash code provider and the specified case-insensitive comparer.

C# Syntax:

protected NameObjectCollectionBase(    int capacity,    IHashCodeProvider hashProvider,    IComparer comparer );

capacity

The approximate number of entries that the NameObjectCollectionBase instance can initially contain.

hashProvider

The case-insensitive IHashCodeProvider that will supply the hash codes for all keys in the NameObjectCollectionBase instance. The case-insensitive IHashCodeProvider that will supply the hash codes for all keys in the NameObjectCollectionBase instance.

comparer

The case-insensitive IComparer to use to determine whether two keys are equal. The case-insensitive IComparer to use to determine whether two keys are equal.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	capacity is less than zero.

The capacity is the number of key-and-value pairs that the NameObjectCollectionBase instance can contain. Specifying the initial capacity eliminates the need to perform a number of resizing operations while entries are added to the NameObjectCollectionBase instance. The capacity is automatically increased as required.

The hash code provider dispenses hash codes for keys in the NameObjectCollectionBase instance. The default hash code provider is the CaseInsensitiveHashCodeProvider.

The comparer determines whether two keys are equal. The default comparer is the CaseInsensitiveComparer.

Return to top

Summary

Gets the number of key-and-value pairs contained in the NameObjectCollectionBase instance.

C# Syntax:

public virtual int Count {get;}

Implements:

ICollection.Count

Return to top

Summary

Gets or sets a value indicating whether the NameObjectCollectionBase instance is read-only.

C# Syntax:

protected bool IsReadOnly {get; set;}

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

Return to top

Summary

Gets a NameObjectCollectionBase.KeysCollection instance that contains all the keys in the NameObjectCollectionBase instance.

C# Syntax:

public virtual NameObjectCollectionBase.KeysCollection Keys {get;}

Return to top

Summary

Adds an entry with the specified key and value into the NameObjectCollectionBase instance.

C# Syntax:

protected void BaseAdd(    string name,    object value );

name

The String key of the entry to add. The key can be null. The String key of the entry to add. The key can be null.

value

The Object value of the entry to add. The value can be null. The Object value of the entry to add. The value can be null.

Exceptions

Exception Type	Condition
NotSupportedException	The collection is read-only.

Return to top

Summary

Removes all entries from the NameObjectCollectionBase instance.

C# Syntax:

protected void BaseClear();

Exceptions

Exception Type	Condition
NotSupportedException	The collection is read-only.

NameObjectCollectionBase.Count is set to zero.

Return to top

Summary

Gets the value of the entry at the specified index of the NameObjectCollectionBase instance.

C# Syntax:

protected object BaseGet(    int index );

index

The zero-based index of the value to get.

Return Value:

An Object that represents the value of the entry at the specified index.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	index is outside the valid range of indexes for the collection.

Return to top

Summary

Gets the value of the first entry with the specified key from the NameObjectCollectionBase instance.

C# Syntax:

protected object BaseGet(    string name );

name

The String key of the entry to get. The key can be null. The String key of the entry to get. The key can be null.

Return Value:

An Object that represents the value of the first entry with the specified key, if found; otherwise, null.

If the collection contains multiple entries with the specified key, this method returns only the first entry. To get the values of subsequent entries with the same key, use the enumerator to iterate through the collection and compare the keys. This method returns null in the following cases: 1) if the specified key is not found; and 2) if the specified key is found and its associated value is null. This method does not distinguish between the two cases.

Return to top

Summary

Returns a String array that contains all the keys in the NameObjectCollectionBase instance.

C# Syntax:

protected string[] BaseGetAllKeys();

Return Value:

A String array that contains all the keys in the NameObjectCollectionBase instance.

Return to top

Summary

Returns an Object array that contains all the values in the NameObjectCollectionBase instance.

C# Syntax:

protected object[] BaseGetAllValues();

Return Value:

An Object array that contains all the values in the NameObjectCollectionBase instance.

Return to top

Summary

Returns an array of the specified type that contains all the values in the NameObjectCollectionBase instance.

C# Syntax:

protected object[] BaseGetAllValues(    Type type );

type

A Type that represents the type of array to return.

Return Value:

An array of the specified type that contains all the values in the NameObjectCollectionBase instance.

Exceptions

Exception Type	Condition
ArgumentNullException	type is null.
ArgumentException	type is not a valid Type.

Return to top

Summary

Gets the key of the entry at the specified index of the NameObjectCollectionBase instance.

C# Syntax:

protected string BaseGetKey(    int index );

index

The zero-based index of the key to get.

Return Value:

A String that represents the key of the entry at the specified index.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	index is outside the valid range of indexes for the collection.

Return to top

Summary

Gets a value indicating whether the NameObjectCollectionBase instance contains entries whose keys are not null.

C# Syntax:

protected bool BaseHasKeys();

Return Value:

true if the NameObjectCollectionBase instance contains entries whose keys are not null; otherwise, false.

Return to top

Summary

Removes the entries with the specified key from the NameObjectCollectionBase instance.

C# Syntax:

protected void BaseRemove(    string name );

name

The String key of the entries to remove. The key can be null. The String key of the entries to remove. The key can be null.

Exceptions

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

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 entry at the specified index of the NameObjectCollectionBase instance.

C# Syntax:

protected void BaseRemoveAt(    int index );

index

The zero-based index of the entry to remove.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	index is outside the valid range of indexes for the collection.
NotSupportedException	The collection is read-only. -or- The collection has a fixed size.

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

Sets the value of the entry at the specified index of the NameObjectCollectionBase instance.

C# Syntax:

protected void BaseSet(    int index,    object value );

index

The zero-based index of the entry to set.

value

The Object that represents the new value of the entry to set. The value can be null. The Object that represents the new value of the entry to set. The value can be null.

Exceptions

Exception Type	Condition
NotSupportedException	The collection is read-only.
ArgumentOutOfRangeException	index is outside the valid range of indexes for the collection.

Return to top

Summary

Sets the value of the first entry with the specified key in the NameObjectCollectionBase instance, if found; otherwise, adds an entry with the specified key and value into the NameObjectCollectionBase instance.

C# Syntax:

protected void BaseSet(    string name,    object value );

name

The String key of the entry to set. The key can be null. The String key of the entry to set. The key can be null.

value

The Object that represents the new value of the entry to set. The value can be null. The Object that represents the new value of the entry to set. The value can be null.

Exceptions

Exception Type	Condition
NotSupportedException	The collection is read-only.

If the collection contains multiple entries with the specified key, this method sets only the first entry. To set the values of subsequent entries with the same key, use the enumerator to iterate through the collection and compare the keys.

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:

~NameObjectCollectionBase();

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

C# Syntax:

public IEnumerator GetEnumerator();

Return Value:

An IEnumerator for the NameObjectCollectionBase instance.

Implements:

IEnumerable.GetEnumerator

This enumerator returns the keys of the collection as strings.

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

Summary

Implements the ISerializable interface and returns the data needed to serialize the NameObjectCollectionBase instance.

C# Syntax:

public virtual void GetObjectData(    SerializationInfo info,    StreamingContext context );

info

A SerializationInfo object that contains the information required to serialize the NameObjectCollectionBase instance.

context

A StreamingContext object that contains the source and destination of the serialized stream associated with the NameObjectCollectionBase instance.

Exceptions

Exception Type	Condition
ArgumentNullException	info is null.

Implements:

ISerializable.GetObjectData

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

Implements the ISerializable interface and raises the deserialization event when the deserialization is complete.

C# Syntax:

public virtual void OnDeserialization(    object sender );

sender

The source of the deserialization event.

Exceptions

Exception Type	Condition
SerializationException	The SerializationInfo object associated with the current NameObjectCollectionBase instance is invalid.

Implements:

IDeserializationCallback.OnDeserialization

Return to top

Summary

Copies the entire NameObjectCollectionBase 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 NameObjectCollectionBase. 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 NameObjectCollectionBase is greater than the available space from index to the end of the destination array.
InvalidCastException	The type of the source NameObjectCollectionBase 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

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